@algolia/wizard 0.46.0 → 0.48.0-rc.141.344

package/docs/algolia-sdk/README.md

@@ -20,14 +20,20 @@ Always install the **latest stable** within the major (use a caret range like `^
 
 - Use a **search-only API key** in any browser/client code. It is safe to expose.
   NEVER ship an admin or any write-capable key to the client.
-- Read the Application ID and search-only key from **public env vars**, never hardcode
-  them inline.
+- Import the Application ID and search-only key from the project's shared client-side
+  config module as plain exported constants. They are public, safe to commit — never read
+  them from an env var or `.env*` file, and never hardcode them elsewhere.
 - Instantiate the search client **once, outside your components**, and pass a stable
   reference. Do not inline `algoliasearch(...)` as a prop value — it breaks the
   client cache and causes re-renders.
 - For InstantSearch, import the client from `algoliasearch/lite` (smaller bundle and
   correct types — see `instantsearch-setup.md`).
 - Always enable **Insights** on the InstantSearch root with `insights: true`. Without it there are no click/conversion events, so many Algolia features will not work as expected.
+- Vendor CSS must be **global**: import an InstantSearch theme from a JS/TS module or the
+  app's global stylesheet and keep `.ais-*` overrides in a global block. In a scoped style
+  block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`) or a CSS Module, scoping
+  rewrites the selectors, the widget's runtime DOM carries no scope attribute, and the
+  styling silently does nothing while the build passes.
 
 ## Files
 

package/docs/algolia-sdk/instantsearch-setup-js.md

@@ -20,10 +20,18 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## Vanilla (`instantsearch.js` v4)
 
+Use the `autocomplete` widget for the results panel. It owns focus, blur, outside-click
+dismissal, Up/Down navigation with wrap-around, Enter/Escape/Tab, and the combobox ARIA
+(`combobox`, `aria-expanded`, `aria-activedescendant`) — add no open/close logic or ARIA
+roles of your own.
+
+Needs `instantsearch.js` **4.110.0+**. If an older 4.x is pinned, upgrade within `^4`
+rather than switching widgets.
+
 ```js
 import { liteClient as algoliasearch } from 'algoliasearch/lite'
 import instantsearch from 'instantsearch.js'
-import { searchBox, hits } from 'instantsearch.js/es/widgets'
+import { autocomplete } from 'instantsearch.js/es/widgets'
 import {
   ALGOLIA_APP_ID,
   ALGOLIA_SEARCH_API_KEY,
@@ -39,24 +47,128 @@ const search = instantsearch({
 })
 
 search.addWidgets([
-  searchBox({ container: '#searchbox' }),
-  hits({ container: '#hits' }),
+  autocomplete({
+    container: '#autocomplete',
+    placeholder: 'Search...',
+    indices: [
+      {
+        indexName: ALGOLIA_INDEX_NAME,
+        getURL: (item) => `/products/${item.handle}`,
+        templates: {
+          item({ item, onSelect }, { html, components }) {
+            return html`<div onClick=${onSelect}>
+              ${components.Highlight({ hit: item, attribute: 'title' })}
+            </div>`
+          },
+          noResults(_, { html }) {
+            return html`<span>No results</span>`
+          },
+        },
+      },
+    ],
+  }),
 ])
 
 search.start()
 ```
 
+### Match entity schema
+
+Ensure the attributes you map into the component match the entity. 'title' above is an example.
+
+### Navigation is `getURL`'s job, not the template's
+
+- `indices[].getURL` — `(item) => string`, a route that already exists; don't invent one.
+  It navigates on click **and** on Enter over a highlighted item, and records the click
+  event.
+- The `item` template renders content only: **no `<a>`, no `href`, no click handler of
+  your own, never `stopPropagation`.** The widget's `<li>` owns the click — it sends the
+  Insights `click`, closes the panel, clears the active option.
+- `getSearchPageURL` sends Enter with nothing highlighted to a full results page; pass it
+  only if the app has one. `.getQuery` is optional.
+- TypeScript: type records through the generic, not casts inside templates —
+  `type ProductHit = Hit<{ title: string; handle: string }>` (`Hit` from
+  `instantsearch.js`), then `autocomplete<ProductHit>({ ... })` types `item`, `getURL`,
+  and the templates.
+
+### Styling the panel
+
+The widget ships no CSS. Install `instantsearch.css` and import a theme once, from the
+component's own JS/TS module or the app's global stylesheet:
+
+```js
+import 'instantsearch.css/themes/satellite.css'
+```
+
+The theme and your `.ais-*` overrides must be **global**: never a CSS `@import` inside a
+framework-scoped style block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`) or
+a CSS Module.
+Use `<style is:global>` (Astro), an unscoped block or `:deep()` (Vue), or plain global CSS.
+
+The theme ships a dark palette behind `:root[data-theme=dark], .dark`: in a dark app set
+`data-theme="dark"` on `<html>` or render under a `.dark` ancestor, then adjust.
+
+Palette lives in `--ais-*` custom properties on `:root` as **RGB triplets consumed through
+`rgba()`**, override with triplets only:
+
+```css
+:root {
+  --ais-background-color-rgb: 24, 24, 27; /* not #18181b */
+  --ais-text-color-rgb: 244, 244, 245;
+  --ais-primary-color-rgb: 129, 140, 248;
+}
+```
+
+Everything else is plain CSS against the widget's classes, or `cssClasses` /
+`indices[].cssClasses` to add your own names to the same elements. Who owns what:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't size the
+  widget from the input.
+- `.ais-AutocompleteForm` — visible frame: background, border, radius, focus ring
+  (`:focus-within`). The input's pill goes here.
+- `.ais-AutocompleteInput` — text only; theme sets `border: 0`, `background: none`,
+  `width: 100%`. A border or width here leaves the form's frame drawn around it and
+  changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`), `.ais-AutocompletePanelLayout` — dropdown surface
+  and its scroll container.
+- `.ais-AutocompleteIndex`, `-IndexHeader`, `-IndexList`, `-IndexItem`, `-IndexNoResults`
+  — one index's results; the active item carries `aria-selected="true"`.
+- `.ais-AutocompleteItemWrapper`, `-ItemContent`, `-ItemIcon` — inside one result.
+- `.ais-AutocompleteSubmitButton`, `-ClearButton`, `-LoadingIndicator`, `-Label` — form
+  controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the input
+container's width — a small input yields an unreadably narrow panel. Give it a min-width
+and anchor it to the edge it opens from, or it grows off-screen:
+
+```css
+.ais-AutocompletePanel {
+  min-width: 320px;
+  left: 0; /* right: 0; left: auto for an input aligned to the right */
+}
+```
+
+Below `(max-width: 680px)` the widget goes detached (fullscreen): the inline form becomes
+a `.ais-AutocompleteDetachedSearchButton`, form and results move into an overlay
+(`.ais-AutocompleteDetachedOverlay`, `.ais-AutocompleteDetachedContainer`,
+`.ais-AutocompleteDetachedFormContainer`). So panel-width rules apply only above that
+breakpoint, and styling the inline form leaves the mobile trigger button on the theme's
+look unless you style it too. Change it with `detachedMediaQuery` or
+`--ais-autocomplete-detached-media-query`; pass `''` to disable detached mode entirely.
+
 ## Insights (click analytics) — always enable it
 
 The `insights` option turns on the Insights middleware (`instantsearch.js` v4.55+),
 which adds `clickAnalytics: true` to every query and keeps the `userToken` in sync
 between search and event calls. Never set `clickAnalytics` or `userToken` on the `configure` widget by hand.
 
-Use `insights: true`. The middleware loads `search-insights` from the jsDelivr CDN
-itself; do not install the package or pass `insightsClient`.
+Use `insights: true` and nothing else. The middleware loads `search-insights` from the
+jsDelivr CDN itself; do not install the package, pass `insightsClient`, or declare
+`window.aa`.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
-case, install `search-insights` from npm and pass its default export as
+Only if the project has a Content-Security-Policy blocking jsDelivr (the CDN script then
+cannot load): install `search-insights` from npm and pass its default export as
 `insightsClient` in the `insights` option:
 
 ```js
@@ -74,9 +186,7 @@ manual `init` call is needed. Keep using the `insightsInitParams` option (for
 example `useCookie`) the same way as with the CDN path.
 
 The middleware sets an anonymous `userToken` itself, so events fire with no extra
-code. That token lives in memory only — a page reload starts a new one, which is
-enough for search→click attribution within a session but not across sessions, and not
-enough for Personalization to build a profile. To persist it in the first-party
+code. To persist it in the first-party
 `_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
 policy allows it:
 
@@ -90,27 +200,16 @@ insights: {
 
 ### Click and conversion events
 
-The `hits` and `infiniteHits` widgets send `view` and `click` events on their own. A
-custom `item` template whose click target is your own element gets `sendEvent` as the
-second argument:
+With `insights: true`, `autocomplete` sends `view` (on render) and `click` (from the
+result element's own handler) itself. Its item template gets `{ item, onSelect }` and
+**no `sendEvent`** — nothing to wire. Call `onSelect` for the widget's selection behavior
+(close the panel, record a recent search); the click event fires either way.
 
-```js
-hits({
-  container: '#hits',
-  templates: {
-    item(hit, { html, sendEvent }) {
-      return html`<a
-        href="${hit.url}"
-        onClick="${() => sendEvent('click', hit, 'Hit Clicked')}"
-        >${hit.name}</a
-      >`
-    },
-  },
-})
-```
+`hits` and `infiniteHits` behave the same; only a custom `item` template whose click
+target is your own element needs wiring — it gets `sendEvent` as the second argument.
 
-Conversions are business actions (add to cart, signup, booking), so wire them at the
-real action, not at render:
+Conversions are business actions (add to cart, signup, booking) away from the results
+panel: wire them at the real action, in a component with its own `sendEvent`:
 
 ```js
 sendEvent('conversion', hit, 'Product Added To Cart', {
@@ -161,14 +260,3 @@ import aa from 'search-insights'
 aa('setAuthenticatedUserToken', userId)
 aa('setAuthenticatedUserToken', undefined) // on logout
 ```
-
-## Frameworks without their own flavor
-
-Only React and Vue have a maintained InstantSearch wrapper. For any other
-framework — Angular, Svelte, Solid — drive `instantsearch.js` directly from a
-component, mounting widgets against element refs and calling `search.dispose()`
-on teardown.
-
-Do NOT install `angular-instantsearch` or a community `*-instantsearch` package:
-`angular-instantsearch` is deprecated and archived (last release v4.4.3, Sep 2024),
-is incompatible with Angular v13+, and receives no security fixes.

package/docs/algolia-sdk/instantsearch-setup-react.md

@@ -20,9 +20,17 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## React (`react-instantsearch` v7)
 
+Use the `Autocomplete` widget for the results panel. It owns focus, blur, outside-click
+dismissal, Up/Down navigation with wrap-around, Enter/Escape/Tab, and the combobox ARIA
+(`combobox` on the input, `aria-expanded`, `aria-activedescendant`) — add no open/close
+logic or ARIA roles of your own.
+
+Needs `react-instantsearch` **7.18.0+**. If an older 7.x is pinned, upgrade within `^7`
+rather than switching widgets.
+
 ```tsx
 import { liteClient as algoliasearch } from 'algoliasearch/lite'
-import { InstantSearch, SearchBox, Hits } from 'react-instantsearch'
+import { InstantSearch, Autocomplete } from 'react-instantsearch'
 import {
   ALGOLIA_APP_ID,
   ALGOLIA_SEARCH_API_KEY,
@@ -38,13 +46,109 @@ export function Search() {
       indexName={ALGOLIA_INDEX_NAME}
       insights={true}
     >
-      <SearchBox />
-      <Hits />
+      <Autocomplete
+        placeholder="Search..."
+        indices={[
+          {
+            indexName: ALGOLIA_INDEX_NAME,
+            getURL: (item) => `/products/${item.handle}`,
+            itemComponent: ({ item, onSelect }) => (
+              <div onClick={onSelect}>{item.title}</div>
+            ),
+            noResultsComponent: () => <span>No results</span>,
+          },
+        ]}
+      />
     </InstantSearch>
   )
 }
 ```
 
+### Match entity schema
+
+Ensure the attributes you map into the component match the entity. 'title' above is an example.
+
+### Navigation is `getURL`'s job, not the item component's
+
+- `indices[].getURL` — `(item) => string`, a route that already exists; don't invent one.
+  It navigates on click **and** on Enter over a highlighted item, and records the click
+  event.
+- `itemComponent` renders content only: **no `<a>`, no `href`, no `onClick` beyond the
+  `onSelect` it is handed, never `stopPropagation`.** The widget's `<li>` owns the click —
+  it sends the Insights `click`, closes the panel, clears the active option.
+- `getSearchPageURL` sends Enter with nothing highlighted to a full results page; pass it
+  only if the app has one. `.getQuery` is optional.
+- TypeScript: type records through the generic, not casts inside `itemComponent` —
+  `type ProductHit = Hit<{ title: string; handle: string }>` (`Hit` from
+  `instantsearch.js`), then `<Autocomplete<ProductHit> ... />` types `item`, `getURL`, and
+  `itemComponent`.
+
+### Styling the panel
+
+The widget ships no CSS. Install `instantsearch.css` and import a theme once, from the
+component module or the app's global stylesheet:
+
+```tsx
+import 'instantsearch.css/themes/satellite.css'
+```
+
+The theme and your `.ais-*` overrides must be **global**: never route either through a CSS
+Module, a scoped style block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`), or
+any styled-components-style wrapper that rewrites selectors. Keep them in a global
+stylesheet, or add your own class names via `classNames` and style those.
+
+The theme ships a dark palette behind `:root[data-theme=dark], .dark`: in a dark app set
+`data-theme="dark"` on `<html>` or render under a `.dark` ancestor, then adjust.
+
+Palette lives in `--ais-*` custom properties on `:root` as **RGB triplets consumed through
+`rgba()`**, override with triplets only:
+
+```css
+:root {
+  --ais-background-color-rgb: 24, 24, 27; /* not #18181b */
+  --ais-text-color-rgb: 244, 244, 245;
+  --ais-primary-color-rgb: 129, 140, 248;
+}
+```
+
+Everything else is plain CSS against the widget's classes, or the `classNames` /
+`indices[].classNames` props to add your own names to the same elements. Who owns what:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't size the
+  widget from the input.
+- `.ais-AutocompleteForm` — visible frame: background, border, radius, focus ring
+  (`:focus-within`). The input's pill goes here.
+- `.ais-AutocompleteInput` — text only; theme sets `border: 0`, `background: none`,
+  `width: 100%`. A border or width here leaves the form's frame drawn around it and
+  changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`), `.ais-AutocompletePanelLayout` — dropdown surface
+  and its scroll container.
+- `.ais-AutocompleteIndex`, `-IndexHeader`, `-IndexList`, `-IndexItem`, `-IndexNoResults`
+  — one index's results; the active item carries `aria-selected="true"`.
+- `.ais-AutocompleteItemWrapper`, `-ItemContent`, `-ItemIcon` — inside one result.
+- `.ais-AutocompleteSubmitButton`, `-ClearButton`, `-LoadingIndicator`, `-Label` — form
+  controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the input
+container's width — a small input yields an unreadably narrow panel. Give it a min-width
+and anchor it to the edge it opens from, or it grows off-screen:
+
+```css
+.ais-AutocompletePanel {
+  min-width: 320px;
+  left: 0; /* right: 0; left: auto for an input aligned to the right */
+}
+```
+
+Below `(max-width: 680px)` the widget goes detached (fullscreen): the inline form becomes
+a `.ais-AutocompleteDetachedSearchButton`, form and results move into an overlay
+(`.ais-AutocompleteDetachedOverlay`, `.ais-AutocompleteDetachedContainer`,
+`.ais-AutocompleteDetachedFormContainer`). So panel-width rules apply only above that
+breakpoint, and styling the inline form leaves the mobile trigger button on the theme's
+look unless you style it too. Change it with `detachedMediaQuery` or
+`--ais-autocomplete-detached-media-query`; pass `''` to disable detached mode entirely.
+
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
 
 ## Insights (click analytics) — always enable it
@@ -53,17 +157,24 @@ The `insights` prop turns on the Insights middleware, which adds
 `clickAnalytics: true` to every query and keeps the `userToken` in sync between search
 and event calls. Never set `clickAnalytics` or `userToken` on `<Configure>` by hand.
 
-Use `insights={true}`. The middleware loads `search-insights` from the jsDelivr CDN
-itself; do not install the package or pass `insightsClient`.
+Use `insights={true}` and nothing else. The middleware loads `search-insights` from the
+jsDelivr CDN itself; do not install the package, pass `insightsClient`, or declare
+`window.aa`.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
-case, install `search-insights` from npm and pass its default export as
+Only if the project has a Content-Security-Policy blocking jsDelivr (the CDN script then
+cannot load): install `search-insights` from npm and pass its default export as
 `insightsClient`:
 
 ```tsx
 import aa from 'search-insights'
 
-<InstantSearch insights={{ insightsClient: aa }} />
+export function Search() {
+  return (
+    <InstantSearch insights={{ insightsClient: aa }}>
+      {/* widgets */}
+    </InstantSearch>
+  )
+}
 ```
 
 The middleware calls `aa('init', ...)` itself with the app ID and search key, so no
@@ -71,9 +182,7 @@ manual `init` call is needed. Keep using the `insightsInitParams` option (for
 example `useCookie`) the same way as with the CDN path.
 
 The middleware sets an anonymous `userToken` itself, so events fire with no extra
-code. That token lives in memory only — a page reload starts a new one, which is
-enough for search→click attribution within a session but not across sessions, and not
-enough for Personalization to build a profile. To persist it in the first-party
+code. To persist it in the first-party
 `_ALGOLIA` cookie, switch to the object form — only where the app's cookie-consent
 policy allows it:
 
@@ -83,8 +192,13 @@ policy allows it:
 
 ### Click and conversion events
 
-`<Hits>` and `<InfiniteHits>` send `view` and `click` events on their own. Two cases
-need explicit wiring:
+With `insights={true}`, `<Autocomplete>` sends `view` (on render) and `click` (from the
+result element's own handler) itself. Its `itemComponent` receives
+`{ item, onSelect, onApply }` and **no `sendEvent`** — nothing to wire. Call `onSelect`
+for the widget's selection behavior (close the panel, record a recent search); the click
+event fires either way.
+
+`<Hits>` and `<InfiniteHits>` behave the same way. Two cases there need explicit wiring:
 
 - A custom `hitComponent` whose click target is your own element — it receives a
   `sendEvent` prop.

package/docs/algolia-sdk/instantsearch-setup-vue.md

@@ -20,19 +20,68 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## Vue (`vue-instantsearch` v4)
 
+Use `ais-autocomplete` for the query and results state. It is **headless**: its default
+slot provides only `currentRefinement`, `indices`, and `refine` — it renders nothing and
+handles no focus, blur, keyboard, or ARIA. Build all of it yourself: panel closed until
+the input is focused and has a query; close on Escape, blur, or outside click; active-option
+highlight on Up/Down with Enter to select; combobox ARIA on the input; click events via
+each index's `sendEvent`.
+
 ```vue
 <template>
-  <ais-instant-search
-    :search-client="searchClient"
-    :index-name="ALGOLIA_INDEX_NAME"
-    :insights="true"
-  >
-    <ais-search-box />
-    <ais-hits />
-  </ais-instant-search>
+  <div ref="containerRef" class="search" @focusout="onFocusOut">
+    <ais-instant-search
+      :search-client="searchClient"
+      :index-name="ALGOLIA_INDEX_NAME"
+      :insights="true"
+    >
+      <ais-autocomplete>
+        <template v-slot="{ currentRefinement, indices, refine }">
+          <input
+            type="search"
+            role="combobox"
+            aria-autocomplete="list"
+            aria-controls="search-panel"
+            :aria-expanded="isOpen(currentRefinement)"
+            :aria-activedescendant="
+              active >= 0 ? `search-option-${active}` : undefined
+            "
+            :value="currentRefinement"
+            @focus="open = true"
+            @input="onInput(refine, $event)"
+            @keydown.down.prevent="move(1, indices)"
+            @keydown.up.prevent="move(-1, indices)"
+            @keydown.enter.prevent="select(indices, active)"
+            @keydown.esc="close"
+          />
+          <ul
+            v-show="isOpen(currentRefinement)"
+            id="search-panel"
+            class="search-panel"
+            role="listbox"
+            aria-label="Search results"
+          >
+            <li
+              v-for="(hit, i) in indices[0]?.hits ?? []"
+              :id="`search-option-${i}`"
+              :key="hit.objectID"
+              role="option"
+              :aria-selected="i === active"
+              :class="{ 'is-active': i === active }"
+              @mousedown.prevent="select(indices, i)"
+              @mousemove="active = i"
+            >
+              <ais-highlight attribute="name" :hit="hit" />
+            </li>
+          </ul>
+        </template>
+      </ais-autocomplete>
+    </ais-instant-search>
+  </div>
 </template>
 
 <script setup>
+import { ref } from 'vue'
 import { liteClient as algoliasearch } from 'algoliasearch/lite'
 import {
   ALGOLIA_APP_ID,
@@ -41,9 +90,71 @@ import {
 } from '<the project's shared config module>'
 
 const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
+const open = ref(false)
+const active = ref(-1)
+const containerRef = ref(null)
+
+function isOpen(currentRefinement) {
+  return open.value && Boolean(currentRefinement)
+}
+
+function onInput(refine, event) {
+  open.value = true
+  active.value = -1
+  refine(event.currentTarget.value)
+}
+
+function move(delta, indices) {
+  const hits = indices[0]?.hits ?? []
+  if (!hits.length) return
+  open.value = true
+  const next = active.value + delta
+  active.value = next < 0 ? hits.length - 1 : next % hits.length
+}
+
+function select(indices, index) {
+  const hit = indices[0]?.hits?.[index]
+  if (!hit) return
+  indices[0].sendEvent('click', hit, 'Hit Clicked')
+  close()
+  // TODO: navigate to this hit's page, where the app has one
+}
+
+function close() {
+  open.value = false
+  active.value = -1
+}
+
+function onFocusOut(event) {
+  if (!containerRef.value?.contains(event.relatedTarget)) close()
+}
 </script>
 ```
 
+Details that break accessibility if changed:
+
+- `role="combobox"` on the `input`, not a wrapper — with `aria-controls` at the popup's
+  `id` and `aria-activedescendant` at the active option's `id`. Focus stays on the input
+  while the arrows move the highlight.
+- The `role="listbox"` element must be the direct parent of the `role="option"` elements;
+  a `ul` inside a `listbox` div, or options one level deeper, breaks the a11y tree.
+- `v-show`, not `v-if`, so the `aria-activedescendant` target stays in the DOM.
+- `@mousedown.prevent` on an option, not `@click` — selection must land before `focusout`
+  closes the panel.
+- `focusout` on the wrapper is the outside-click dismissal (`event.relatedTarget` is
+  `null` for a click on non-focusable chrome). Don't add a `document` click listener on
+  top — it fights `@mousedown.prevent`.
+- `.is-active` needs a visible style, not just `aria-selected` — it is a keyboard user's
+  only focus feedback, since focus never leaves the input.
+
+The panel is your own markup with no widget theme to inherit: give `.search-panel` a
+background from the app's theme tokens (never transparent over page content), text
+clearing 4.5:1 against it, `position: absolute` with `min-width: 320px` anchored to the
+input edge it opens from, and a `max-height` with `overflow-y: auto`.
+
+`indices` supports federated search across indices; this project has one, so `indices[0]`
+is always the one to read.
+
 Register the widgets via the InstantSearch Vue plugin in your app entry:
 
 ```js
@@ -57,12 +168,11 @@ The `insights` prop turns on the Insights middleware, which adds
 `clickAnalytics: true` to every query and keeps the `userToken` in sync between search
 and event calls. Never set `clickAnalytics` or `userToken` on `ais-configure` by hand.
 
-Use `:insights="true"`. The middleware loads `search-insights` from the jsDelivr CDN itself; do not install
-the package or pass `insightsClient`.
+Use `:insights="true"` and nothing else. The middleware loads `search-insights` from the
+jsDelivr CDN itself; do not install the package, pass `insightsClient`, or declare `window.aa`.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
-case, install `search-insights` from npm and pass its default export as
-`insightsClient`:
+Only if the project has a Content-Security-Policy blocking jsDelivr (the CDN script then cannot
+load): install `search-insights` from npm and pass its default export as `insightsClient`:
 
 ```js
 import aa from 'search-insights'
@@ -73,9 +183,7 @@ The middleware calls `aa('init', ...)` itself with the app ID and search key, so
 manual `init` call is needed.
 
 The middleware sets an anonymous `userToken` itself, so events fire with no extra
-code. That token lives in memory only — a page reload starts a new one, which is
-enough for search→click attribution within a session but not across sessions, and not
-enough for Personalization to build a profile. To persist it in the first-party
+code. To persist it in the first-party
 `_ALGOLIA` cookie, bind the object form — only where the app's cookie-consent policy
 allows it:
 
@@ -85,19 +193,18 @@ const insights = { insightsInitParams: { useCookie: true } } // then :insights="
 
 ### Click and conversion events
 
-`ais-hits` sends `view` and `click` events on its own. A custom `item` slot whose
-click target is your own element needs the slot's `sendEvent`:
+`ais-autocomplete` wraps the same connector as the other flavors, so `view` fires on its
+own when results render. `click` does not — the option markup is yours: call the index's
+`sendEvent` from your own option handler, as in the setup example above.
 
 ```vue
-<ais-hits>
-  <template v-slot:item="{ item, sendEvent }">
-    <a :href="item.url" @click="sendEvent('click', item, 'Hit Clicked')">
-      {{ item.name }}
-    </a>
-  </template>
-</ais-hits>
+<li @mousedown.prevent="indices[0].sendEvent('click', hit, 'Hit Clicked')">
 ```
 
+`ais-hits` (if the app also has a full results page) sends both itself; only a custom
+`item` slot whose click target is your own element needs wiring — that slot provides
+`sendEvent`.
+
 Conversions are business actions (add to cart, signup, booking), so wire them at the
 real action, not at render:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@algolia/wizard",
-  "version": "0.46.0",
+  "version": "0.48.0-rc.141.344",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {