@algolia/wizard 0.42.0 → 0.43.0-rc.141.298

package/dist/main.js

@@ -3472,7 +3472,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.42.0",
+  version: "0.43.0-rc.141.298",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -4132,6 +4132,7 @@ function searchInstructions(input) {
   return [
     "Implement an in-app Algolia search experience.",
     `Build the search UI for ${input.searchUiTarget}.`,
+    "This step is search UI only \u2014 the index is already populated. Do not create or modify ingestion scripts, rake/manage/CLI tasks, migrations, seeders, or any other data-loading code, even if you notice the data looks incomplete.",
     ...doc ? [
       "Follow the Algolia SDK reference below for client setup, search UI wiring, and Insights instrumentation \u2014 Insights is required, not optional; prefer the reference over prior knowledge:",
       doc
@@ -4139,9 +4140,12 @@ function searchInstructions(input) {
       "No bundled Algolia SDK reference exists for this stack, so rely on the project's own conventions and Algolia's official client for its language. Do not invent APIs \u2014 keep to the documented search endpoint and its parameters."
     ],
     `Create the search experience as its own component in a new file, following the project's existing component conventions (location, naming, styling approach). Do not write it inline into an existing file.`,
-    `Import and render that new component from ${input.searchLocation ? `"${input.searchLocation}"` : "the best shared, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app \u2014 at least a working search input and results list against the target index.`,
+    `Import and render that new component from ${input.searchLocation ? `"${input.searchLocation}"` : "the best shared, always-rendered layout location (e.g. a header/nav component)"} so it is reachable across the app \u2014 at least a working search input and results panel against the target index.`,
     "If a search box already exists, replace its usage with an import and render of your new component; remove the old implementation.",
     "When rendering results with an existing shared component (e.g. a card), import and reuse that component rather than inlining its markup \u2014 inlining silently drops the styles and behavior its own file provides.",
+    "Results appear as a dropdown panel, not a permanently visible list: show it only while the input is focused and has a non-empty query, and close it on Escape, on blur, and on an outside click. If the SDK reference above documents an Autocomplete widget for this stack, it already provides all of that (open/close, arrow-key navigation, combobox ARIA, Insights events) \u2014 use it as-is and do not add your own open/close logic or ARIA roles on top of it. Only build this by hand when the reference has no such widget for this stack, or says it is headless; then also handle Up/Down arrows over the results and Enter to select.",
+    "Meet WCAG AA contrast (4.5:1 body text, 3:1 large text/icons) between the panel's text and its own background, and give both the input and the active result a focus indicator that is visible against whatever sits behind it. Style the panel through the widget's own class and CSS-variable overrides (or, if building by hand, the app's existing theme tokens) \u2014 never assume a light surface or reuse the surrounding page's colors unchanged inside the panel.",
+    "The panel takes its width from the input by default, so a small input makes it unreadably narrow: give it a minimum width of 320px independent of the input, and keep it anchored to the input edge it opens from so widening it does not push it off-screen.",
     `Define ${SEARCH_CONFIG_APP_ID}, ${SEARCH_CONFIG_SEARCH_KEY}, and ${SEARCH_CONFIG_INDEX_NAME} as exported constants in a module that fits this project's existing conventions for shared client-side config \u2014 reuse an existing one if it already holds config like this, or add a small new one otherwise. These are PUBLIC values, safe to commit and expose client-side: never read them from an environment variable or a .env* file, and never hardcode them anywhere except in that one module (import them wherever the search client needs them).`,
     `Set ${SEARCH_CONFIG_APP_ID} to "${input.appId}" and ${SEARCH_CONFIG_INDEX_NAME} to "${input.targetIndex}".`,
     input.searchKey ? `Set ${SEARCH_CONFIG_SEARCH_KEY} to "${input.searchKey}".` : `A real search-only key could not be provisioned${input.searchKeyError ? ` (${input.searchKeyError})` : ""} \u2014 set ${SEARCH_CONFIG_SEARCH_KEY} to the placeholder "${SEARCH_KEY_PLACEHOLDER}" and add a prominent TODO for the developer to fill in a real one.`,

package/docs/algolia-sdk/README.md

@@ -20,8 +20,10 @@ 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, where they are plain exported constants. They are public values, safe to
+  commit — do not read them from an env var or `.env*` file, and never hardcode them
+  inline anywhere else.
 - 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.

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

@@ -20,10 +20,19 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## Vanilla (`instantsearch.js` v4)
 
+Use the `autocomplete` widget for the results panel. It already manages focus, blur,
+outside-click dismissal, Up/Down arrow navigation with wrap-around, Enter/Escape/Tab, and
+the combobox ARIA (`combobox`, `aria-expanded`, `aria-activedescendant`), so do not add
+your own open/close logic or ARIA roles around it.
+
+The `autocomplete` export needs `instantsearch.js` **4.110.0 or newer**. If the project
+pins an older 4.x, upgrade within the major (`^4`) rather than reaching for a different
+widget.
+
 ```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,13 +48,74 @@ const search = instantsearch({
 })
 
 search.addWidgets([
-  searchBox({ container: '#searchbox' }),
-  hits({ container: '#hits' }),
+  autocomplete({
+    container: '#autocomplete',
+    placeholder: 'Search...',
+    indices: [
+      {
+        indexName: ALGOLIA_INDEX_NAME,
+        templates: {
+          item({ item, onSelect }, { html, components }) {
+            return html`<div onClick=${onSelect}>
+              ${components.Highlight({ hit: item, attribute: 'name' })}
+            </div>`
+          },
+        },
+      },
+    ],
+  }),
 ])
 
 search.start()
 ```
 
+`indices[].getURL` and `.getQuery` are optional — only pass `getURL` if the app has a real
+per-item page to link to; don't invent one. Leave `showQuerySuggestions`,
+`showPromptSuggestions`, `showRecent`, and `aiMode` unset — each depends on an index or
+feature (query suggestions, recent-search storage, AI chat) this project doesn't have.
+
+### Styling the panel
+
+The widget ships no CSS of its own. Install `instantsearch.css` and import a theme once,
+then layer the app's own look on top:
+
+```js
+import 'instantsearch.css/themes/satellite.css'
+```
+
+The theme defines its palette as `--ais-*` custom properties on `:root`, and the colors
+are **RGB triplets consumed through `rgba()`**, not CSS colors — override them with
+triplets or every widget color breaks:
+
+```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 own classes (`.ais-Autocomplete`,
+`.ais-AutocompletePanel`, `.ais-AutocompleteInput`, `.ais-AutocompleteIndexList`,
+`.ais-AutocompleteIndexItem`), or `cssClasses` / `indices[].cssClasses` to add your own
+class names to those elements.
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the width of the
+input container — a small input yields an unreadably narrow panel. Give it a minimum
+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 switches to detached (fullscreen) mode and renders
+no panel, so panel width rules only apply above that breakpoint. Change the breakpoint
+with `detachedMediaQuery` or `--ais-autocomplete-detached-media-query`; pass `''` to
+disable detached mode.
+
 ## Insights (click analytics) — always enable it
 
 The `insights` option turns on the Insights middleware (`instantsearch.js` v4.55+),
@@ -90,27 +160,19 @@ 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`, the `autocomplete` widget sends `view` and `click` events itself:
+`view` when results render, `click` from the result element's own click handler. Its item
+template receives `{ item, onSelect }` and **no `sendEvent`** — there is nothing to wire,
+and nothing to send events from. Call `onSelect` for the widget's own selection behavior
+(closing the panel, recording 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
-      >`
-    },
-  },
-})
-```
+The `hits` and `infiniteHits` widgets behave the same way. Only a custom `item` template
+there needs explicit wiring, and only when its click target is your own element — that
+template 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) that happen away from the
+results panel, so wire them at the real action, in a component that has a `sendEvent` of
+its own:
 
 ```js
 sendEvent('conversion', hit, 'Product Added To Cart', {

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

@@ -20,9 +20,18 @@ const searchClient = algoliasearch(ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY)
 
 ## React (`react-instantsearch` v7)
 
+Use the `Autocomplete` widget for the results panel. It already manages focus, blur,
+outside-click dismissal, Up/Down arrow navigation with wrap-around, Enter/Escape/Tab, and
+the combobox ARIA (`combobox` on the input, `aria-expanded`, `aria-activedescendant`), so
+do not add your own open/close logic or ARIA roles around it.
+
+The `Autocomplete` export needs `react-instantsearch` **7.18.0 or newer**. If the project
+pins an older 7.x, upgrade within the major (`^7`) rather than reaching for a different
+widget.
+
 ```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 +47,69 @@ export function Search() {
       indexName={ALGOLIA_INDEX_NAME}
       insights={true}
     >
-      <SearchBox />
-      <Hits />
+      <Autocomplete
+        placeholder="Search..."
+        indices={[
+          {
+            indexName: ALGOLIA_INDEX_NAME,
+            itemComponent: ({ item, onSelect }) => (
+              <div onClick={onSelect}>{item.name}</div>
+            ),
+          },
+        ]}
+      />
     </InstantSearch>
   )
 }
 ```
 
+`indices[].getURL` and `.getQuery` are optional — only pass `getURL` if the app has a real
+per-item page to link to; don't invent one. Leave `showQuerySuggestions`,
+`showPromptSuggestions`, `showRecent`, and `aiMode` unset — each depends on an index or
+feature (query suggestions, recent-search storage, AI chat) this project doesn't have.
+
+### Styling the panel
+
+The widget ships no CSS of its own. Install `instantsearch.css` and import a theme once,
+then layer the app's own look on top:
+
+```tsx
+import 'instantsearch.css/themes/satellite.css'
+```
+
+The theme defines its palette as `--ais-*` custom properties on `:root`, and the colors
+are **RGB triplets consumed through `rgba()`**, not CSS colors — override them with
+triplets or every widget color breaks:
+
+```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 own classes (`.ais-Autocomplete`,
+`.ais-AutocompletePanel`, `.ais-AutocompleteInput`, `.ais-AutocompleteIndexList`,
+`.ais-AutocompleteIndexItem`), or the `classNames` / `indices[].classNames` props to add
+your own class names to those elements.
+
+The theme's panel is `position: absolute; width: 100%`, so it inherits the width of the
+input container — a small input yields an unreadably narrow panel. Give it a minimum
+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 switches to detached (fullscreen) mode and renders
+no panel, so panel width rules only apply above that breakpoint. Change the breakpoint
+with `detachedMediaQuery` or `--ais-autocomplete-detached-media-query`; pass `''` to
+disable detached mode.
+
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
 
 ## Insights (click analytics) — always enable it
@@ -63,7 +128,13 @@ case, install `search-insights` from npm and pass its default export as
 ```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
@@ -83,8 +154,14 @@ 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` and `click` events itself: `view`
+when results render, `click` from the result element's own click handler. Its
+`itemComponent` receives `{ item, onSelect, onApply }` and **no `sendEvent`** — there is
+nothing to wire, and nothing to send events from. Call `onSelect` for the widget's own
+selection behavior (closing the panel, recording 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. `ais-autocomplete` is headless: its default
+slot only provides `currentRefinement`, `indices`, and `refine` — it renders nothing and
+handles no focus, blur, keyboard, or ARIA itself. You must build all of it: keep the panel
+closed until the input is focused and has a query, close it on Escape, blur, or an outside
+click, move an active-option highlight with the Up/Down arrows and select it with Enter,
+carry the combobox ARIA on the input, and send 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,73 @@ 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"` belongs on the `input`, not on a wrapper — with `aria-controls`
+  pointing at the popup's `id` and `aria-activedescendant` at the active option's `id`.
+  Keep focus on the input while the arrows move the highlight.
+- The element carrying `role="listbox"` must be the direct parent of the
+  `role="option"` elements. A `ul` nested inside a `listbox` div, or options nested one
+  level deeper, breaks the accessibility tree.
+- `v-show`, not `v-if`, so the `aria-activedescendant` target stays in the DOM.
+- `@mousedown.prevent` on an option, not `@click` — selection has to 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 page chrome, so the panel closes. Don't add a
+  `document` click listener on top — it fights `@mousedown.prevent` on the options.
+- `.is-active` needs a visible style, not just `aria-selected`: the panel is the only
+  focus feedback a keyboard user gets, since focus never leaves the input.
+
+The panel is your own markup here, so it has no widget theme to inherit from: give
+`.search-panel` its own background from the app's theme tokens (never transparent over
+page content), text that clears 4.5:1 against that background, `position: absolute` with
+`min-width: 320px` anchored to the input edge it opens from, and a `max-height` with
+`overflow-y: auto`.
+
+`ais-autocomplete`'s `indices` slot prop supports federated search across multiple
+indices; this project has only one, so `indices[0]` is always the one to read.
+
 Register the widgets via the InstantSearch Vue plugin in your app entry:
 
 ```js
@@ -85,19 +198,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` events fire
+on their own when results render. `click` does not, because 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, does send `view` and `click` itself.
+Only a custom `item` slot there needs wiring, and only when its click target is your own
+element — 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.42.0",
+  "version": "0.43.0-rc.141.298",
   "description": "Magically implement Algolia functionality in your codebase",
   "type": "module",
   "engines": {