docs(parseAlgoliaHitReverseHighlight): rewrite guides (#479)

* docs(autocomplete-preset-algolia): add common note

* docs(parseAlgoliaHitReverseHighlight): rewrite guides

* docs(parseAlgoliaHitReverseHighlight): fix examples

* docs(parseAlgoliaHitReverseHighlight): fix params

* docs(parseAlgoliaHitReverseHighlight): fix examples

* docs(parseAlgoliaHitReverseHighlight): add descriptions

* docs(parseAlgoliaHitReverseHighlight): fix text

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

* docs(reverseHighlightHit): change examples

* fix: apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

Co-authored-by: François Chalifour <[email protected]>

Author: sarahdayan

packages/website/docs/parseAlgoliaHitReverseHighlight.md

@@ -2,16 +2,44 @@
 id: parseAlgoliaHitReverseHighlight
 ---
 
-Returns the highlighted parts of an Algolia hit.
+import PresetAlgoliaNote from './partials/preset-algolia/note.md'
 
-This is a common pattern for Query Suggestions.
+Returns the highlighted non-matching parts of an Algolia hit.
 
-## Example with a single string
+The `parseAlgoliaHitReverseHighlight` function lets you parse the non-highlighted parts of an Algolia hit. This is a common pattern for [Query Suggestions](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js/), where you want to highlight the differences between each suggestion.
+
+<PresetAlgoliaNote />
+
+## Installation
+
+First, you need to install the preset.
+
+```bash
+yarn add @algolia/autocomplete-preset-algolia@alpha
+# or
+npm install @algolia/autocomplete-preset-algolia@alpha
+```
+
+Then import it in your project:
 
 ```js
 import { parseAlgoliaHitReverseHighlight } from '@algolia/autocomplete-preset-algolia';
+```
+
+If you don't use a package manager, you can use a standalone endpoint:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-preset-algolia@alpha"></script>
+```
 
-// Fetch an Algolia hit
+## Examples
+
+### With a single string
+
+```js
+import { parseAlgoliaHitReverseHighlight } from '@algolia/autocomplete-preset-algolia';
+
+// An Algolia hit for query "lap"
 const hit = {
   name: 'Laptop',
   _highlightResult: {
@@ -20,20 +48,20 @@ const hit = {
     },
   },
 };
-const snippetParts = parseAlgoliaHitReverseHighlight({
+const reverseHighlightedParts = parseAlgoliaHitReverseHighlight({
   hit,
   attribute: 'name',
 });
 
-// => [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
+// [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
 ```
 
-## Example with nested attributes
+### With nested attributes
 
 ```js
 import { parseAlgoliaHitReverseHighlight } from '@algolia/autocomplete-preset-algolia';
 
-// Fetch an Algolia hit
+// An Algolia hit for query "lap"
 const hit = {
   name: {
     type: 'Laptop',
@@ -46,26 +74,30 @@ const hit = {
     },
   },
 };
-const snippetParts = parseAlgoliaHitReverseHighlight({
+const reverseHighlightedParts = parseAlgoliaHitReverseHighlight({
   hit,
   attribute: ['name', 'type'],
 });
 
-// => [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
+// [{ value: 'Lap', isHighlighted: false }, { value: 'top', isHighlighted: true }]
 ```
 
-# Reference
-
-## Params
+## Parameters
 
 ### `hit`
 
 > `AlgoliaHit` | required
 
-The Algolia hit to retrieve the attribute value from.
+The Algolia hit whose attribute to retrieve the reverse highlighted parts from.
 
 ### `attribute`
 
 > `string | string[]` | required
 
-The attribute to retrieve the highlight value from. You can use the array syntax to reference the nested attributes.
+The attribute to retrieve the reverse highlighted parts from. You can use the array syntax to reference nested attributes.
+
+## Returns
+
+> `ParsedAttribute[]`
+
+An array of the parsed attribute's parts.

packages/website/docs/reverseHighlightHit.md

@@ -2,36 +2,84 @@
 id: reverseHighlightHit
 ---
 
-Returns a virtual node with non-matching parts of an Algolia hit.
+Returns virtual nodes with highlighted non-matching parts of an Algolia hit.
 
-## Example
+ The `reverseHighlightHit` function lets you turn an Algolia hit into a virtual node with highlighted non-matching parts for a given attribute.
+
+## Examples
+
+### With a single string
+
+To determine what attribute to parse, you can pass it as a string.
 
 ```js
 import { reverseHighlightHit } from '@algolia/autocomplete-js';
 
-const hit = {}; // fetch an Algolia hit
-const highlightedValue = reverseHighlightHit({
+// An Algolia hit for query "zelda"
+const hit = {
+  query: 'zelda switch',
+  _highlightResult: {
+    query: {
+      value:
+        '__aa-highlight__zelda__/aa-highlight__ switch',
+    },
+  },
+};
+const reverseHighlightedValue = reverseHighlightHit({
   hit,
   attribute: 'query',
 });
 ```
 
-## Params
+### With nested attributes
+
+If you're referencing a nested attribute, you can use the array syntax.
+
+```js
+import { reverseHighlightHit } from '@algolia/autocomplete-js';
+
+// An Algolia hit for query "video"
+const hit = {
+  hierarchicalCategories: {
+    lvl1: 'Video games',
+  }
+  _highlightResult: {
+    hierarchicalCategories: {
+      lvl1: {
+        value:
+          '__aa-highlight__Video__/aa-highlight__ games',
+      },
+    },
+  },
+};
+const reverseHighlightedValue = reverseHighlightHit({
+  hit,
+  attribute: ['hierarchicalCategories', 'lvl1'],
+});
+```
+
+## Parameters
 
 ### `hit`
 
 > `AlgoliaHit` | required
 
-The Algolia hit to retrieve the attribute value from.
+The Algolia hit whose attribute to retrieve the highlighted parts from.
 
 ### `attribute`
 
-> `string` | required
+> `string | string[]` | required
 
-The attribute to retrieve the highlight value from.
+The attribute to retrieve the highlighted parts from. You can use the array syntax to reference nested attributes.
 
 ### `tagName`
 
 > `string` | defaults to `mark`
 
 The tag name of the virtual node.
+
+## Returns
+
+> `HighlightItemParams<THit>`
+
+Virtual nodes with the highlighted matching parts.