docs: write "what is autocomplete"?

packages/autocomplete-plugin-algolia-insights/src/createAlgoliaInsightsPlugin.ts

@@ -12,7 +12,7 @@ import {
   AlgoliaInsightsHit,
   InsightsApi,
   InsightsClient,
-  OnHighlightParams,
+  OnActiveParams,
   OnItemsChangeParams,
   OnSelectParams,
 } from './types';
@@ -59,7 +59,7 @@ export type CreateAlgoliaInsightsPluginParams = {
   /**
    * Hook to send an Insights event when an item is active.
    */
-  onActive?(params: OnHighlightParams): void;
+  onActive?(params: OnActiveParams): void;
 };
 
 export function createAlgoliaInsightsPlugin({

packages/autocomplete-plugin-algolia-insights/src/types/EventParams.ts

@@ -15,7 +15,7 @@ export type OnSelectParams = {
   event: any;
 };
 
-export type OnHighlightParams = OnSelectParams;
+export type OnActiveParams = OnSelectParams;
 
 export type OnItemsChangeParams = {
   insights: InsightsApi;

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,20 @@
+---
+id: basic-options
+title: Basic configuration options
+---
+
+:::note Draft
+
+This page needs to cover:
+
+- There are only two required params to create an autocomplete:
+  - You need to provide a selector for the **container** you want autocomplete to appear in.
+  - You need to define where to get the items to display using **getSources** (or a **plug-in** which provides **getSources**). Check our **Sources** core concept for more information.
+- Beyond this, there are many parameters you can use to customize the experience and help you with development. Here are some commonly used ones:
+  - Use **placeholder** to define the text that appears in the input when a user hasn’t typed anything.
+  - Use **autoFocus** to focus on the search box when the page is loaded and **openOnFocus** to display items as soon as a user selects the autocomplete (without typing anything).
+  - Use the **onStateChange** hook to call a function whenever the state changes (see our **State** core concept for more info).
+  - Use **`debug: true`** to keep the autocomplete panel with items open, even when the blur event occurs. (This is only meant to be used during development. See our **Debugging guide** for more info.)
+- Check out the **API reference** for a full list of params.
+
+:::

packages/website/docs/context.md

@@ -1,10 +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.
 
+:::note Draft
+
+This page needs to cover:
+
+- You can use **context** to store and access data in the **state**. You can think of it as a global variable.
+- For example, you can use **context** to store data regarding the number of hits from an Algolia response, and then use this when creating **templates** in your sources. Without storing this value in the **context**, you wouldn’t have access to it in the templates.
+- Like all setters, **setContext** expects an object that it will merge with the previous context object.
+  - Code snippet (including setContext and using context.nbHits in a template)
+- **Plugins** can also store their API in **context**
+
+:::
+
 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`.
 
 The following example stores the number of hits from an Algolia response to display it in the templates.

packages/website/docs/createAlgoliaInsightsPlugin.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/creating-multi-source-autocompletes.md

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

packages/website/docs/getting-started.md

@@ -3,6 +3,24 @@ id: getting-started
 title: Getting Started
 ---
 
+:::note Draft
+
+This page needs to cover:
+
+- These docs provide a few ways to learn how to use Autocomplete:
+  - Read about **Core Concepts**—here you can learn more about underlying principles, like **Sources** and **State**.
+  - Follow our **Guides** to understand how to build common UX patterns.
+  - Refer to **API reference**.
+  - [Maybe v2] Play in the **Playground** where you can select components of your autocomplete and we provide you with the code.
+- Keep reading for a simple sample implementation
+- Installation
+  - JS
+  - Core
+- A basic example
+  - Commented code snippet on a basic example (only using query-suggestions plug-in) with resulting UI and links to various **Core Concepts.**
+
+:::
+
 This page is an overview of the Autocomplete documentation and related resources.
 
 Autocomplete is a JavaScript library for **building autocomplete search experiences**.
@@ -17,3 +35,43 @@ Autocomplete is a JavaScript library for **building autocomplete search experien
 - Plugs easily to Algolia's realtime search engine
 
 ## What is Autocomplete
+
+## Installation
+
+Autocomplete is available on the [npm](https://www.npmjs.com/) registry.
+
+### JavaScript
+
+```bash
+yarn add @algolia/autocomplete-js@alpha
+# or
+npm install @algolia/autocomplete-js@alpha
+```
+
+If you do not wish to use a package manager, you can use standalone endpoints:
+
+```html
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-js@alpha"></script>
+
+<!-- unpkg -->
+<script src="https://unpkg.com/@algolia/autocomplete-js@alpha"></script>
+```
+
+### Headless
+
+```bash
+yarn add @algolia/autocomplete-core@alpha
+# or
+npm install @algolia/autocomplete-core@alpha
+```
+
+If you do not wish to use a package manager, you can use standalone endpoints:
+
+```html
+<!-- jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-core@alpha"></script>
+
+<!-- unpkg -->
+<script src="https://unpkg.com/@algolia/autocomplete-core@alpha"></script>
+```

packages/website/docs/help.md

@@ -0,0 +1,14 @@
+---
+id: help
+title: Help and Discussion
+---
+
+<!-- prettier-ignore -->
+:::note Draft
+This page needs to cover:
+
+- Ask questions and discuss with other community members on [GitHub](https://github.com/algolia/autocomplete.js/discussions/new)
+- Request a feature to add to Autocomplete on [GitHub](https://github.com/algolia/autocomplete.js/discussions/new)
+- Report a bug on [GitHub](https://github.com/algolia/autocomplete.js/issues/new?template=Bug_report.md)
+
+:::

packages/website/docs/introduction.md

@@ -0,0 +1,40 @@
+---
+id: introduction
+title: What is Autocomplete?
+---
+
+Autocomplete is an open-source, production-ready JavaScript library for building autocomplete experiences.
+
+A user types into an input, and the autocomplete "completes" their thought by providing full terms or results: this is the very base of an autocomplete experience.
+
+For example, try typing the letter "s" in the search box on the top right of this site. You can directly navigate to documentation on concepts like "**s**ources" and "**s**tate". If you continue typing, say "st", the results update. You see pages having to do with "**st**ate," "getting **st**arted," and "**st**atic sources."
+
+**Autocomplete is now a ubiquitous part of most search experiences.** Search providers like Google, e-commerce sites like Amazon, and messaging apps like Slack all offer autocomplete experiences on mobile and desktop.
+
+While the search experience on this site displays links to pages, autocomplete experiences frequently show completed search terms. If you start a search by typing the letter "j" into Google, it suggests search terms like "javascript", "jest", "jsonlines", etc. Selecting one of these lands you on the search results page for the term.
+
+This experience minimizes typing, which is particularly impactful on mobile. It enables users to find what they're looking for quicker. It also exposes them to searches, products, or pages they may not have thought of but are interested in anyway.
+
+You may have already used Autocomplete-powered UIs. The [Algolia](https://www.algolia.com/doc/), [React Native](https://reactnative.dev/), [Tailwind CSS](https://tailwindcss.com/docs), and other documentation websites use Autocomplete via the [Algolia DocSearch](https://docsearch.algolia.com/) project. This library is flexible enough to power more than just documentation search though. **It's designed to help you build interactive and accessible autocomplete experiences, regardless of your use case.**
+
+## What this library provides
+
+Autocomplete is a JavaScript library that lets you quickly build autocomplete experiences. All you need to get started is:
+- A container to inject the experience into
+- Data to fill the autocomplete with
+
+The data that populates the autocomplete results are called [`sources`](/docs/sources). You can use whatever you want in your sources: a static set of searches terms, search results from an external source like an [Algolia](https://www.algolia.com/doc/guides/getting-started/what-is-algolia/) index, recent searches, and much more.
+
+By configuring just those two required parameters (`container` and `getSources`) you can have an interactive autocomplete experience. **The library creates an input and provides the interactivity and accessibility attributes, but you're in full control of the DOM elements to output.**
+
+You don't have to display just suggested search terms, you can display links for actual results themselves (rather than links to results pages) or even display "actions" that a user can take from within an autocomplete. For example, you could let your users turn dark mode on, directly from an autocomplete, if they begin to type "darkmode".
+
+You can also display different data types (such as suggested search terms, product results, and actions) differently. The format of each data type and layout is customizable and up to you.
+
+## What this library doesn't provide
+
+Contrary to [Algolia InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/), Autocomplete doesn't provide a library of ready-made UI widgets. You're in control of the full rendering of your autocomplete experience, and the library provides everything you need to make it functional and accessible.
+
+Also, you're in charge of providing the collection of items to display. You can easily plug Algolia results with the [`autocomplete-algolia-preset`](getAlgoliaHits) if you want, but you're free to use Autocomplete with any data sources you want.
+
+Ready to learn more? Move on to [Getting Started](/docs/getting-started) to see a basic example in action.