docs: merge docs-1 into next (#433)

Co-authored-by: François Chalifour <[email protected]>
Co-authored-by: Sarah Dayan <[email protected]>
Co-authored-by: Maria Elisabeth Schreiber <[email protected]>

Author: 3 people

packages/autocomplete-js/src/autocomplete.ts

@@ -143,6 +143,7 @@ export function autocomplete<TItem extends BaseItem>(
       propGetters,
       state: lastStateRef.current,
     };
+
     const render =
       (!getItemsCount(state) &&
         !hasEmptySourceTemplateRef.current &&

packages/website/docs/api.md

@@ -1,4 +1,8 @@
 ---
 id: api
-title: API
+title: Introduction
 ---
+
+import Draft from './partials/draft.md'
+
+<Draft />

packages/website/docs/basic-options.md

@@ -0,0 +1,58 @@
+---
+id: basic-options
+title: Basic configuration options
+---
+
+Everything you need to create fantastic autocomplete experiences.
+
+We've built Autocomplete to give you unlimited flexibility while freeing you from having to think about things like keyboard navigation, accessibility, or UI state. **The library offers a wide variety of APIs to let you fully customize the behavior and rendering of your autocomplete.**
+
+Yet, only two parameters are required to create an autocomplete:
+- The **container** you want your autocomplete to go in.
+- The **sources** from which to get the items to display (see more in [**Sources**](sources)).
+
+```js title="JavaScript"
+import { autocomplete } from '@algolia/autocomplete-js';
+
+autocomplete({
+  container: '#autocomplete',
+  getSources() {
+    return [
+      {
+        getItems({ query }) {
+          return [
+            { label: 'Twitter', url: 'https://twitter.com' },
+            { label: 'GitHub', url: 'https://github.com' },
+          ].filter(({ label }) =>
+            label.toLowerCase().includes(query.toLowerCase())
+          );
+        },
+        getItemUrl({ item }) {
+          return item.url;
+        },
+        templates: {
+          item({ item }) {
+            return item.label;
+          },
+        },
+      },
+    ];
+  },
+});
+```
+
+The `container` options refers to where to inject the autocomplete in your HTML. It can be a [CSS selector](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) or an [Element](https://developer.mozilla.org/docs/Web/API/HTMLElement). Make sure to provide a container (e.g., a `div`), not an `input`. Autocomplete generates a fully accessible search box for you.
+
+```html title="HTML"
+<div id="autocomplete"></div>
+```
+
+This is all you need to build a [fully functional, accessible, keyboard-navigable autocomplete](https://codesandbox.io/s/vigilant-dew-g2ezl).
+
+Now, this is a great start, but **you can go much further**. Here are some of the options you'll probably want to use next:
+- Use [`placeholder`](autocomplete-js#placeholder) to define the text that appears in the input before the user types anything.
+- Use [`autoFocus`](autocomplete-js#autofocus) to focus on the search box on page load, and [`openOnFocus`](autocomplete-js#openonfocus) to display items as soon as a user selects the autocomplete, even without typing.
+- Use the [`onStateChange`](autocomplete-js#onstatechange) lifecycle hook to execute code whenever the state changes.
+- Use [`debug: true`](autocomplete-js#debug) to keep the autocomplete panel open even when the blur event occurs (see [**Debugging**](debugging)).
+
+For a full list of all available parameters, check out the [API reference](autocomplete-js).

packages/website/docs/context.md

@@ -1,16 +1,22 @@
 ---
 id: context
-title: Context
+title: Accessing data with Context
 ---
 
-The autocomplete context allows to store data in the state to use in different lifecycle hooks.
+The Context lets you store data and access it in different lifecycle hooks.
 
-You can use this API to access data in the templates that you would otherwise have access only in `getSources` for instance. The `setContext` setters expects an object that will be merged with the previous context. You can then read the context in `state.context`.
+Sometimes you need to store arbitrary data so you can access it later in your autocomplete. For example, when retrieving hits from Algolia, you may want to reuse the total number of retrieved hits in a template.
 
-The following example stores the number of hits from an Algolia response to display it in the templates.
+Autocomplete lets you store data using its Context API and access it anywhere from the [state](/docs/state).
+
+## Usage
+
+Context exposes a `setContext` function, which takes an object and merges it with the existing context. You can then access the context in `state.context`.
+
+The following example stores the number of hits from an Algolia response, making it accessible everywhere in your autocomplete.
 
 ```js
-const autocomplete = createAutocomplete({
+autocomplete({
   // ...
   getSources({ query, setContext }) {
     return getAlgoliaResults({
@@ -21,15 +27,13 @@ const autocomplete = createAutocomplete({
           query,
         },
       ],
-    }).then((results) => {
-      const productsResults = results[0];
-
+    }).then(([products]) => {
       setContext({
-        nbProducts: productsResults.nbHits,
+        nbProducts: products.nbHits,
       });
 
-      // You can now use `state.context.nbProducts` anywhere you have access to
-      // the state.
+      // You can now use `state.context.nbProducts`
+      // anywhere where you have access to `state`.
 
       return [
         // ...
@@ -38,3 +42,48 @@ const autocomplete = createAutocomplete({
   },
 });
 ```
+
+Context can be handy when developing [Autocomplete plugins](/docs/plugins). It avoids polluting the global namespace while still being able to pass data around across different lifecycle hooks.
+
+```js
+function createAutocompletePlugin() {
+  return {
+    // ...
+    subscribe({ setContext }) {
+      setContext({
+        autocompletePlugin: {
+          // ...
+        },
+      });
+    },
+  };
+}
+```
+
+## Reference
+
+The `setContext` function is accessible on your `autocomplete` instance.
+
+It's also provided in:
+- [`getSources`](createAutocomplete#getsources)
+- [`onInput`](createAutocomplete#oninput)
+- [`onSubmit`](createAutocomplete#onsubmit)
+- [`onReset`](createAutocomplete#onreset)
+- [`source.onActive`](sources#onactive)
+- [`source.onSelect`](sources#onselect)
+- [`source.getItems`](sources#getitems)
+- `plugin.subscribe`
+
+The `context` object is available on the [`state`](/docs/state) object.
+
+### `setContext`
+
+> `(value: Record<string, unknown>) => void`
+
+The function to pass data to to store it in the context.
+
+### `context`
+
+> `Record<string, unknown>`
+
+The context to read data from.

packages/website/docs/controlled-mode.md

@@ -0,0 +1,86 @@
+---
+id: createAlgoliaInsightsPlugin
+---
+
+## Example
+
+```ts
+import algoliasearch from 'algoliasearch/lite';
+import { autocomplete } from '@algolia/autocomplete-js';
+import { createAlgoliaInsightsPlugin } from '@algolia/autocomplete-plugin-algolia-insights';
+import insightsClient from 'search-insights';
+
+const appId = 'latency';
+const apiKey = '6be0576ff61c053d5f9a3225e2a90f76';
+const searchClient = algoliasearch(appId, apiKey);
+insightsClient('init', { appId, apiKey });
+
+const algoliaInsightsPlugin = createAlgoliaInsightsPlugin({ insightsClient });
+
+autocomplete({
+  container: '#autocomplete',
+  plugins: [algoliaInsightsPlugin],
+});
+```
+
+## Import
+
+```ts
+import { createAlgoliaInsightsPlugin } from '@algolia/autocomplete-plugin-algolia-insights';
+```
+
+## Params
+
+### `insightsClient`
+
+> `InsightsClient` | required
+
+The initialized Search Insights client.
+
+### `onItemsChange`
+
+> `(params: OnItemsChangeParams) => void`
+
+Hook to send an Insights event when the items change.
+
+This hook is debounced every 400ms to better reflect when items are acknowledged by the user.
+
+```ts
+type OnItemsChangeParams = {
+  insights: InsightsApi;
+  insightsEvents: ViewedObjectIDsParams[];
+  state: AutocompleteState<any>;
+};
+```
+
+### `onSelect`
+
+> `(params: OnSelectParams) => void`
+
+Hook to send an Insights event when an item is selected.
+
+```ts
+type OnSelectParams = {
+  insights: InsightsApi;
+  insightsEvents: ClickedObjectIDsAfterSearchParams[];
+  item: AlgoliaInsightsHit;
+  state: AutocompleteState<any>;
+  event: any;
+};
+```
+
+### `onActive`
+
+> `(params: OnActiveParams) => void`
+
+Hook to send an Insights event when an item is active.
+
+```ts
+type OnActiveParams = {
+  insights: InsightsApi;
+  insightsEvents: ClickedObjectIDsAfterSearchParams[];
+  item: AlgoliaInsightsHit;
+  state: AutocompleteState<any>;
+  event: any;
+};
+```

packages/website/docs/createAlgoliaInsightsPlugin.md

@@ -0,0 +1,4 @@
+---
+id: creating-multi-source-autocompletes
+title: Creating multi-source autocompletes
+---