@algolia/wizard 0.43.0-rc.141.298 → 0.43.0-rc.141.299

package/dist/main.js

@@ -3472,7 +3472,7 @@ async function runAnalysis(mode, extraInstructions = []) {
 // package.json
 var package_default = {
   name: "@algolia/wizard",
-  version: "0.43.0-rc.141.298",
+  version: "0.43.0-rc.141.299",
   description: "Magically implement Algolia functionality in your codebase",
   type: "module",
   engines: {
@@ -4143,8 +4143,11 @@ function searchInstructions(input) {
     `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.",
+    "Results appear as a dropdown panel, not a permanently visible list. If the SDK reference above documents an Autocomplete widget for this stack, it already owns that behavior \u2014 when the panel opens and closes, Escape, blur, outside click, arrow-key navigation, combobox ARIA, Insights events \u2014 so use it as-is and add no open/close logic, query gating, or ARIA roles of your own, even if it opens on focus before anything is typed. Only build this by hand when the reference has no such widget for this stack, or says it is headless; then show the panel only while the input is focused and has a non-empty query, close it on Escape, on blur, and on an outside click, and move an active-result highlight with Up/Down arrows with Enter to select.",
+    "Let the widget own result selection: where the hits have a detail page, pass its per-index URL option (getURL or the flavor's equivalent) so it navigates on click and on Enter with a result highlighted, and keep your item template or item component to content only \u2014 no anchor, no href, no click handler of your own, no stopPropagation. The widget's own result element is what sends the Insights click event, closes the panel, and clears the active option; wrapping a result in your own link swallows all three while still navigating, so it looks correct and silently loses click analytics.",
+    "Render the zero-results state through the widget's own no-results template or component, so a query that matches nothing shows a message rather than an empty panel.",
     "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.",
+    "A vendor theme stylesheet, and any CSS you write against vendor class names, must be global: import the theme from the component's own script module or the app's global stylesheet, and put the overrides in a global block (Astro's <style is:global>, an unscoped Vue block, a plain global CSS file). Never route either through a framework-scoped style block or a CSS Module \u2014 scoping rewrites the vendor selectors, and the widget builds its DOM at runtime with no scope attribute on it, so not one rule matches: the styling silently does nothing and the build still passes.",
     "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}".`,

package/docs/algolia-sdk/README.md

@@ -30,6 +30,11 @@ Always install the **latest stable** within the major (use a caret range like `^
 - 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 has to be **global** CSS: import an InstantSearch theme from a JS/TS module
+  or the app's global stylesheet, and keep `.ais-*` overrides in a global block. Inside a
+  framework-scoped style block (Astro `<style>`, Vue `<style scoped>`, Svelte `<style>`) or
+  a CSS Module, scoping rewrites the selectors, the widget's runtime DOM never carries the
+  scope attribute, and the styling silently does nothing while the build still passes.
 
 ## Files
 

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

@@ -54,12 +54,16 @@ search.addWidgets([
     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: 'name' })}
             </div>`
           },
+          noResults(_, { html }) {
+            return html`<span>No results</span>`
+          },
         },
       },
     ],
@@ -69,20 +73,62 @@ search.addWidgets([
 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`,
+### Navigation is `getURL`'s job, not the template's
+
+Where the hits have a detail page, pass `indices[].getURL` — `(item) => string`, a route
+that already exists; don't invent one. The widget then navigates on click **and** on Enter
+over a keyboard-highlighted item, and records the click event on the way out. Without it,
+Enter on a highlighted result does nothing.
+
+The `item` template renders content only: **no `<a>`, no `href`, no click handler of your
+own, and never `stopPropagation`.** The widget's own `<li>` owns the click — it sends the
+Insights `click` event, closes the panel, and clears the active option. Wrapping the
+template in an anchor swallows all three: the link still navigates, so it looks correct,
+while click analytics never fire and the panel stays open behind the new page.
+
+Give every index a `templates.noResults` — without it the panel renders an empty box on a
+query that matches nothing.
+
+`getSearchPageURL` sends Enter with no result highlighted to a full search-results page;
+pass it only if the app has one. `.getQuery` is optional. 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.
 
+In TypeScript, type the records through the widget's generic instead of casting inside the
+templates:
+
+```ts
+import type { Hit } from 'instantsearch.js'
+
+type ProductHit = Hit<{ title: string; handle: string }>
+
+autocomplete<ProductHit>({
+  /* item, getURL, and the templates are all typed from ProductHit */
+})
+```
+
 ### 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:
+from the component's own JS/TS module or from the app's global stylesheet:
 
 ```js
 import 'instantsearch.css/themes/satellite.css'
 ```
 
+**Never import the theme as a CSS `@import` inside a framework-scoped style block** — an
+Astro `<style>`, a Vue `<style scoped>`, a Svelte `<style>`, a CSS Module. Scoping
+rewrites every selector in the imported theme
+(`.ais-AutocompleteInput[data-astro-cid-abc123]`), and the widget renders its own DOM at
+runtime into an empty container, so none of those elements carry the scope attribute and
+not one theme rule matches. Nothing errors, the build passes, and the search UI renders
+unstyled. Your own overrides of `.ais-*` classes have the same problem: put them in global
+CSS (`<style is:global>` in Astro, an unscoped block or `:deep()` in Vue).
+
+The theme already ships a dark palette behind `:root[data-theme=dark], .dark`. In a dark
+app, set `data-theme="dark"` on `<html>` or render the widget under a `.dark` ancestor and
+adjust from there — don't redefine the light palette by hand.
+
 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:
@@ -95,10 +141,29 @@ triplets or every widget color breaks:
 }
 ```
 
-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.
+Everything else is plain CSS against the widget's own classes, or `cssClasses` /
+`indices[].cssClasses` to add your own class names to the same elements. Know which
+element owns what before writing a rule:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't try to size
+  the widget from the input.
+- `.ais-AutocompleteForm` — the visible frame: background, border, radius, and the focus
+  ring (`:focus-within`). Style the input's pill here.
+- `.ais-AutocompleteInput` — text only. The theme gives it `border: 0`,
+  `background: none`, `width: 100%`. A border or a fixed width here leaves the form's own
+  frame drawn around it and changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`) and `.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` — the
+  form's own controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+Don't style a class that isn't in that list: `.ais-SearchBox-*` belongs to the `searchBox`
+widget and does nothing here. To check the names against the installed version:
+`grep -o 'ais-Autocomplete[A-Za-z-]*' node_modules/instantsearch.css/themes/satellite.css | sort -u`.
 
 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
@@ -111,10 +176,14 @@ width and anchor it to the edge it opens from, or it grows off-screen:
 }
 ```
 
-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.
+Below `(max-width: 680px)` the widget switches to detached (fullscreen) mode: the inline
+form is replaced by a `.ais-AutocompleteDetachedSearchButton`, and the form and results
+move into an overlay (`.ais-AutocompleteDetachedOverlay`,
+`.ais-AutocompleteDetachedContainer`, `.ais-AutocompleteDetachedFormContainer`). So panel
+width rules only apply above that breakpoint, and styling the inline form leaves the
+mobile trigger button on the theme's own look unless you style it too. Change the
+breakpoint with `detachedMediaQuery` or `--ais-autocomplete-detached-media-query`; pass
+`''` to disable detached mode and keep the inline form at every width.
 
 ## Insights (click analytics) — always enable it
 
@@ -122,11 +191,16 @@ 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, do not pass `insightsClient`, and do not
+declare `window.aa`.
+
+Everything below this line is a **conditional fallback**. Apply one only when its stated
+condition actually holds in this project — a CSP you can point at, a user id the app
+already has. Where it doesn't hold, `insights: true` is the whole implementation.
 
-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
+If the project has a Content-Security-Policy that blocks jsDelivr, the CDN script cannot
+load. Only in that case, install `search-insights` from npm and pass its default export as
 `insightsClient` in the `insights` option:
 
 ```js

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

@@ -52,9 +52,11 @@ export function Search() {
         indices={[
           {
             indexName: ALGOLIA_INDEX_NAME,
+            getURL: (item) => `/products/${item.handle}`,
             itemComponent: ({ item, onSelect }) => (
               <div onClick={onSelect}>{item.name}</div>
             ),
+            noResultsComponent: () => <span>No results</span>,
           },
         ]}
       />
@@ -63,20 +65,63 @@ export function Search() {
 }
 ```
 
-`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`,
+### Navigation is `getURL`'s job, not the item component's
+
+Where the hits have a detail page, pass `indices[].getURL` — `(item) => string`, a route
+that already exists; don't invent one. The widget then navigates on click **and** on Enter
+over a keyboard-highlighted item, and records the click event on the way out. Without it,
+Enter on a highlighted result does nothing.
+
+`itemComponent` renders content only: **no `<a>`, no `href`, no `onClick` of your own
+beyond the `onSelect` it is handed, and never `stopPropagation`.** The widget's own `<li>`
+owns the click — it sends the Insights `click` event, closes the panel, and clears the
+active option. Wrapping the item in a link or a router `<Link>` swallows all three: the
+navigation still happens, so it looks correct, while click analytics never fire and the
+panel stays open behind the new page.
+
+Give every index a `noResultsComponent` — without it the panel renders an empty box on a
+query that matches nothing.
+
+`getSearchPageURL` sends Enter with no result highlighted to a full search-results page;
+pass it only if the app has one. `.getQuery` is optional. 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.
 
+In TypeScript, type the records through the component's generic instead of casting inside
+`itemComponent`:
+
+```tsx
+import type { Hit } from 'instantsearch.js'
+
+type ProductHit = Hit<{ title: string; handle: string }>
+
+export function Search() {
+  // item, getURL, and itemComponent are all typed from ProductHit
+  return <Autocomplete<ProductHit> indices={[]} />
+}
+```
+
 ### 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:
+from the component module or the app's global stylesheet:
 
 ```tsx
 import 'instantsearch.css/themes/satellite.css'
 ```
 
+**Never route the theme through scoped or module CSS** — a CSS Module, an Astro `<style>`,
+a Vue `<style scoped>`, a Svelte `<style>`, or any styled-components-style wrapper that
+rewrites selectors. Scoping renames every selector in the imported theme, and the widget
+renders its own DOM at runtime, so none of its elements match the rewritten names. Nothing
+errors, the build passes, and the search UI renders unstyled. Your own overrides of
+`.ais-*` classes have the same problem: keep them in a global stylesheet, or add your own
+class names through `classNames` and style those instead.
+
+The theme already ships a dark palette behind `:root[data-theme=dark], .dark`. In a dark
+app, set `data-theme="dark"` on `<html>` or render the widget under a `.dark` ancestor and
+adjust from there — don't redefine the light palette by hand.
+
 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:
@@ -89,10 +134,29 @@ triplets or every widget color breaks:
 }
 ```
 
-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.
+Everything else is plain CSS against the widget's own classes, or the `classNames` /
+`indices[].classNames` props to add your own class names to the same elements. Know which
+element owns what before writing a rule:
+
+- `.ais-Autocomplete` — root. Its **container** sets the widget's width; don't try to size
+  the widget from the input.
+- `.ais-AutocompleteForm` — the visible frame: background, border, radius, and the focus
+  ring (`:focus-within`). Style the input's pill here.
+- `.ais-AutocompleteInput` — text only. The theme gives it `border: 0`,
+  `background: none`, `width: 100%`. A border or a fixed width here leaves the form's own
+  frame drawn around it and changes no widths.
+- `.ais-AutocompletePanel` (+ `--open`) and `.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` — the
+  form's own controls.
+- `.ais-AutocompleteDetached*` — detached mode (below).
+
+Don't style a class that isn't in that list: `.ais-SearchBox-*` belongs to the `SearchBox`
+widget and does nothing here. To check the names against the installed version:
+`grep -o 'ais-Autocomplete[A-Za-z-]*' node_modules/instantsearch.css/themes/satellite.css | sort -u`.
 
 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
@@ -105,10 +169,14 @@ width and anchor it to the edge it opens from, or it grows off-screen:
 }
 ```
 
-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.
+Below `(max-width: 680px)` the widget switches to detached (fullscreen) mode: the inline
+form is replaced by a `.ais-AutocompleteDetachedSearchButton`, and the form and results
+move into an overlay (`.ais-AutocompleteDetachedOverlay`,
+`.ais-AutocompleteDetachedContainer`, `.ais-AutocompleteDetachedFormContainer`). So panel
+width rules only apply above that breakpoint, and styling the inline form leaves the
+mobile trigger button on the theme's own look unless you style it too. Change the
+breakpoint with `detachedMediaQuery` or `--ais-autocomplete-detached-media-query`; pass
+`''` to disable detached mode and keep the inline form at every width.
 
 Do not inline `searchClient={algoliasearch(...)}` — keep the stable reference above.
 
@@ -118,10 +186,16 @@ 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, do not pass `insightsClient`, and do not
+declare `window.aa`.
+
+Everything below this line is a **conditional fallback**. Apply one only when its stated
+condition actually holds in this project — a CSP you can point at, a user id the app
+already has. Where it doesn't hold, `insights={true}` is the whole implementation.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+If the project has a Content-Security-Policy that blocks jsDelivr, the CDN script cannot
+load. In that
 case, install `search-insights` from npm and pass its default export as
 `insightsClient`:
 

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

@@ -170,10 +170,14 @@ 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, do not pass `insightsClient`, and do not declare `window.aa`.
 
-If a Content-Security-Policy blocks jsDelivr, the CDN script cannot load. In that
+Everything below this line is a **conditional fallback**. Apply one only when its stated condition
+actually holds in this project — a CSP you can point at, a user id the app already has. Where it
+doesn't hold, `:insights="true"` is the whole implementation.
+
+If the project has a Content-Security-Policy that blocks jsDelivr, the CDN script cannot load. In that
 case, install `search-insights` from npm and pass its default export as
 `insightsClient`:
 

package/package.json

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