@magicx-eng/ai-autocomplete-react 0.18.1 → 0.19.0

package/README.md

@@ -18,7 +18,8 @@ A React/TypeScript SDK that provides a guided AI-powered autocomplete experience
 - **Client-side filtering** — instant substring filtering on every keystroke
 - **Datepicker** — date parameters are answered with a calendar instead of an option list. Click a day or navigate with the arrow keys; the date is committed the way it would be written — `Tuesday` for a date inside the next week, `March 23` for one later this year, `March 23 2027` for another year. Tapping a committed date re-opens the calendar on the month that text names now — for a weekday name, that is the next such day, not the one originally picked. A parameter whose options are written as spans (`September 11 - October 13`) gets the same calendar answered in two clicks, committed as one range.
 - **Option overrides** — supply the options for a parameter yourself: a fixed list, a computed one, or one fetched from your own search endpoint as the user types
-- **Product strip (opt-in)** — plug in any platform's product search and the dropdown renders a horizontal row of product cards below the options; the SDK owns the UI, your integration owns only `fetch` and `transform`
+- **Product strip** — the dropdown renders a horizontal row of product cards below the options, filled by default with the items the `/suggest` response reports as matching the query; plug in your own product search instead with `products`, or turn the strip off with `showProducts={false}`
+- **Catalog report** — every response says which of the query's constraints the catalog applied, which it had to drop, and how many items are left, on `customFields` / `custom_fields`
 - **Controlled & uncontrolled** — works out of the box or integrates with external state
 - **Ref forwarding** — imperative `focus()`, `blur()`, `reset()`, and `setMode()` via ref
 - **Accessible** — ARIA combobox 1.2 pattern with `role="listbox"`, `aria-activedescendant`
@@ -357,17 +358,85 @@ function App() {
 | `completedParams?` | `CompletedParamState[]` | — | Controlled completed params. |
 | `onChange?` | `(value: string) => void` | — | Called when text changes (controlled mode). |
 | `onParamsChange?` | `(params: CompletedParamState[]) => void` | — | Called when params change (controlled mode). |
-| `products?` | `ProductsConfig` | — | Opt-in product strip — see [Product strip](#product-strip). Omit it and nothing about the dropdown changes. |
+| `showProducts?` | `boolean` | `true` | Render the product strip below the options whenever there are products to show — see [Product strip](#product-strip). Set to `false` to render no strip. |
+| `products?` | `ProductsConfig` | — | Custom source for the product strip — see [Your own product search](#your-own-product-search-products). Omit it and the strip shows the items the `/suggest` response reports. |
 | `onProductSelect?` | `(product: Product) => void` | — | Called when a product card is activated. The SDK never navigates. |
 | `submitButton?` | `ReactNode` | — | Custom submit button. Pass any `ReactNode` to replace the default arrow button. Pass `null` to render no button. Clicks bubble up and trigger submit, so consumer-supplied buttons work without re-wiring `onClick`. |
 | `ref?` | `Ref<AIAutocompleteHandle>` | — | Imperative handle with `focus()`, `blur()`, `reset()`, and `setMode()`. |
 
 #### Product strip
 
-Opt in with `products` and the dropdown renders a horizontal row of product
-cards below the options grid. Every platform (Shopify today, others later) has
-its own search endpoint and its own response shape, so the SDK owns the UI and
-the integration owns only the fetching and the mapping.
+The dropdown renders a horizontal row of product cards below the options grid
+whenever it has products to show. By default those are the items the
+`/suggest` response itself reports as matching the query — no configuration,
+no extra request: the cards land in the same state update as the suggestions,
+so what the strip shows and what the pills offer always describe the same
+narrowing.
+
+```tsx
+<AIAutocomplete
+  onSubmit={handleSubmit}
+  // Selection emits — the SDK never navigates.
+  onProductSelect={(product) => product.url && router.push(product.url)}
+/>
+```
+
+Each server item becomes a `Product` with `id` (the item's stable id), `title`,
+`price` (the item's lowest price, verbatim as the catalog spells it — the
+currency is yours to add), `vendor`, `imageUrl`, and a **relative** `url` of
+`/products/{handle}` — the right link for a widget running on the storefront
+itself. An item the catalog has no handle for gets no `url`: its card is still
+activatable and still emits `onProductSelect`, it just has nothing for
+cmd-click to open. `productFromMatchedItem` / `productsFromCustomFields` are
+exported for a hand-rolled strip that wants the same mapping.
+
+Pass `showProducts={false}` to render no strip at all. The catalog report
+(below) stays readable either way.
+
+#### The catalog report (`customFields`)
+
+Every response that read the catalog also says what it did with the query. The
+hook returns it as `customFields`, and it rides on `AutocompleteResult` as
+`custom_fields`, so `onResult` on either tier carries it too:
+
+```tsx
+const { customFields } = useAIAutocomplete({ ... });
+
+// Or, on Tier 1:
+<AIAutocomplete onResult={(result) => setReport(result.custom_fields)} />
+
+{report && <p>{report.items.total} results</p>}
+{report?.dropped_filters.length > 0 && (
+  // e.g. { param: "Color", value: "Chartreuse", op: "eq" } — the shopper asked
+  // for a colour no item carries, so the results ignore it. Say so.
+  <p>No match for {report.dropped_filters.map((f) => f.value).join(", ")}</p>
+)}
+```
+
+- `applied_filters` / `dropped_filters` — the constraints the server read out
+  of the query as `{ param, value, op }` (`op` is one of `eq`, `ne`, `lt`,
+  `lte`, `gt`, `gte`), split into the ones the catalog answered and the ones it
+  could not (a parameter it does not have, a bound that is not a number, a
+  value no item carries). The items answer the applied set, so the dropped
+  list is what tells "87 black t-shirts" from "no black item, so here are
+  t-shirts". Both are always arrays.
+- `items.total` — how many items the applied filters left standing. It also
+  moves with the query's own words, so it drops as a typed word starts
+  matching a title. `items.matched` is the list the strip renders, capped by
+  the server; it is empty (with a non-zero `total`) when nothing narrowed the
+  catalog, where listing arbitrary items as matches would mislead.
+- `null` (no `custom_fields` key on the result) means the response carried no
+  report — no catalog was read for it (a product with no catalog, the starting
+  state, a response with no option-bearing parameter to offer). That is "no
+  news", not an empty catalog. The strip clears on such a response rather than
+  keeping an older query's items.
+
+#### Your own product search (`products`)
+
+To source the cards from your own search instead — a platform with its own
+endpoint and response shape — pass `products`. The SDK owns the UI; you own
+only the fetching and the mapping. The server's items are then not rendered
+(they stay readable on `customFields`).
 
 ```tsx
 import { AIAutocomplete, type Product } from "@magicx-eng/ai-autocomplete-react";
@@ -397,18 +466,17 @@ const products = {
 <AIAutocomplete
   onSubmit={handleSubmit}
   products={products}
-  // Selection emits — the SDK never navigates.
-  onProductSelect={(product) => router.push(product.url)}
+  onProductSelect={(product) => product.url && router.push(product.url)}
 />;
 ```
 
-`Product` is exactly six fields; only `id`, `title` and `url` are required:
+`Product` is exactly six fields; only `id` and `title` are required:
 
 ```ts
 type Product = {
   id: string;
   title: string;
-  url: string;
+  url?: string;               // absent = a card with no link (still activatable)
   imageUrl?: string | null;
   price?: string;
   vendor?: string;
@@ -432,13 +500,14 @@ type Product = {
   `dropdownTrigger` (`manual` / `hidden`) still gates the panel as before.
 - **Inline configs are safe.** `products={{ fetch, transform }}` written inline
   re-creates the object on every render; the hook forwards through a stable
-  proxy, so only turning the strip on or off reaches the core. Two deliberate
-  consequences: swapping one live config for another leaves the previous
-  integration's cards up until the next request replaces them (toggle
-  `products` off and back on to clear immediately), and turning the strip on
-  mid-session shows nothing until the next `/suggest` request fires — the
-  product search rides that one scheduler, and enabling the strip doesn't
-  itself change the query.
+  proxy, so only setting or removing the config reaches the core. Two
+  deliberate consequences: swapping one live config for another leaves the
+  previous integration's cards up until the next request replaces them
+  (remove `products` and set it again to clear immediately), and setting a
+  config mid-session shows nothing until the next `/suggest` request fires —
+  the product search rides that one scheduler, and configuring it doesn't
+  itself change the query. Removing the config restores the server's items at
+  once.
 
 **Selection and links.** Cards are real `<a href>` elements, so cmd/ctrl-click,
 middle-click and "copy link address" behave natively. A plain left click is
@@ -446,7 +515,7 @@ intercepted (`preventDefault`) and emits `onProductSelect` instead.
 
 `product.url` is used verbatim — the SDK trusts your `transform` output and
 does not sanitise it, so validate the URL there if the platform response isn't
-fully under your control. (Angular additionally runs its own `[href]`
+fully under your control. (Angular additionally runs its own `href`
 sanitiser, so unrecognised schemes like `myapp://…` are rewritten to
 `unsafe:…` in that package only.)
 
@@ -456,9 +525,10 @@ visible focus ring. Tabbing into the strip does not close the panel. The row
 scrolls horizontally by trackpad, wheel, touch and keyboard; the page never
 scrolls sideways and the scrollbar chrome is hidden in all engines.
 
-Tier 2 gets the same thing: pass `products` / `onProductSelect` to
-`useAIAutocomplete()` and the strip renders inside `<AIAutocompleteDropdown />`
-via `dropdownProps`. Tier 3 consumers read `products` from the hook and call
+Tier 2 gets the same thing: `useAIAutocomplete()` takes `showProducts`,
+`products` and `onProductSelect`, and the strip renders inside
+`<AIAutocompleteDropdown />` via `dropdownProps`. Tier 3 consumers read
+`products` (and `customFields`) from the hook and call
 `selectProduct(product)` from their own cards.
 
 #### Custom submit button
@@ -542,7 +612,8 @@ The headless hook for Tier 2 and Tier 3. Accepts the same options as `<AIAutocom
 | `isDropdownOpen` | `boolean` | Whether the dropdown should be visible. Drive your own dropdown's visibility with this in Tier 3. |
 | `placeholderText` | `string` | Suggested placeholder text for the current step. |
 | `error` | `Error \| null` | Last fetch error. |
-| `products` | `Product[]` | Results of the latest product search. Empty unless `products` is configured. Already spread into `dropdownProps` — read it directly only if you render your own strip. |
+| `products` | `Product[]` | What the product strip shows: the items the latest response reported as matching the query, or the results of a custom `products` search. Already spread into `dropdownProps` — read it directly only if you render your own strip. |
+| `customFields` | `CustomFieldsReport \| null` | The catalog report the latest response carried — applied and dropped filters, and the matching items' count and list — or `null` when it carried none. See [The catalog report](#the-catalog-report-customfields). |
 
 **Actions**
 
@@ -589,7 +660,7 @@ The dropdown component for Tier 2. Spread `dropdownProps` from the hook (and add
 | `pills?` | `Suggestion[]` | Pills to render inside the dropdown. |
 | `onPillClick?` | `(index: number) => void` | Called when a pill is clicked. |
 | `showPills?` | `boolean` | Whether to render pills. Default: `true`. |
-| `products?` | `Product[]` | Product cards to render below the options grid. Empty (the default) renders no strip. |
+| `products?` | `Product[]` | Product cards to render below the options grid. Empty renders no strip. |
 | `onProductSelect?` | `(product: Product) => void` | Called when a card is activated. |
 | `onProductFocusChange?` | `(focused: boolean) => void` | Called when focus enters/leaves the strip. Wired to `setFocused` by `dropdownProps` so a tabbed-to card doesn't close the panel. |
 | `isLoading?` | `boolean` | When `true`, the dropdown renders its pills + options as a skeleton: text masked, layout (count and widths) preserved, shimmer pulse animating. Falls back to a generic 3-bar placeholder when no pills/options are cached. |
@@ -605,6 +676,7 @@ The structured query as the SDK currently understands it. The same object is pas
 | `completed_params` | `CompletedParam[]` | Filled parameter values in query order, followed by any the user skipped (see below). |
 | `identified_params` | `IdentifiedParam[]` | Parameters the server recognised in the user's own words, as `{ type, value }` — e.g. `{ type: "due_date", value: "Friday" }` when the user typed "by Friday" instead of picking a date. They are not tokenized in `raw_query`, and they are tentative: each response replaces the set, and an entry drops out as soon as its text is edited away. |
 | `is_ready` | `boolean` | Whether the server considers the query complete enough to act on. |
+| `custom_fields?` | `CustomFieldsReport` | What catalog grounding did for the latest applied response, when it read a catalog at all — see [Product strip](#product-strip). `applied_filters` and `dropped_filters` list the query's constraints as `{ param, value, op }`; `items.total` is how many items the applied ones left standing and `items.matched` the ones the strip renders. Absent (no key) when the response carried no report. |
 
 #### Reading the query as it's built
 

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, DateRange, SkippedParamState, IdentifiedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, DATE_RANGE_META_END, DATE_RANGE_META_START, DateMonthView, DateRange, FormatType, IdentifiedParam, IdentifiedParamState, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, isoDate, monthLabel, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, DateRange, SkippedParamState, IdentifiedParamState, Segment, CustomFieldsReport } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DateMonthView, DateRange, ExpressedFilter, FilterOp, FormatType, IdentifiedParam, IdentifiedParamState, MatchedItem, MatchedItems, OptionOverrides, PRODUCT_PATH_PREFIX, Product, ProductsConfig, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, isoDate, monthLabel, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, productFromMatchedItem, productsFromCustomFields, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
 import * as react from 'react';
 import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -87,23 +87,33 @@ interface AIAutocompleteProps {
     onChange?: (value: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
     /**
-     * Opt-in product strip. When set, the dropdown renders a horizontal row of
-     * product cards below the options grid, fed by your own search endpoint on
-     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
-     * changes — no request, no markup, no layout shift.
+     * When true (default), the dropdown renders a horizontal row of product
+     * cards below the options grid whenever it has products to show: by default
+     * the items the `/suggest` response reports as matching the query, or the
+     * results of a custom `products` search. Set to false to render no strip
+     * and run no custom search.
+     */
+    showProducts?: boolean;
+    /**
+     * Custom source for the product strip. Omit it and the strip shows the
+     * items the `/suggest` response itself reports as matching the query, with
+     * no extra request. Set it and the dropdown is fed by your own search
+     * endpoint on the SDK's existing fetch cadence instead; the server's items
+     * are then not rendered.
      *
      * The object may be re-created on every render: the hook forwards calls
-     * through a stable proxy, so only toggling the strip on or off reaches the
-     * core.
+     * through a stable proxy, so only setting or removing the config reaches
+     * the core.
      *
      * Two consequences of that proxy, both deliberate:
      * - Swapping one live config for another (A → B, both defined) can't be told
      *   apart from a re-render, so A's cards stay on screen until the next
-     *   request replaces them. Toggle `products` off and back on to clear
+     *   request replaces them. Remove `products` and set it again to clear
      *   immediately.
-     * - Turning the strip on mid-session shows nothing until the next `/suggest`
-     *   request fires, because the product search rides that one scheduler and
-     *   enabling the strip doesn't itself change the query.
+     * - Setting a custom config mid-session shows nothing until the next
+     *   `/suggest` request fires, because the product search rides that one
+     *   scheduler and configuring it doesn't itself change the query. Removing
+     *   the config restores the server's items at once.
      */
     products?: ProductsConfig;
     /**
@@ -173,23 +183,33 @@ interface UseAIAutocompleteOptions {
     /** Called when the input loses focus. */
     onBlur?: () => void;
     /**
-     * Opt-in product strip. When set, the dropdown renders a horizontal row of
-     * product cards below the options grid, fed by your own search endpoint on
-     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
-     * changes — no request, no markup, no layout shift.
+     * When true (default), the dropdown renders a horizontal row of product
+     * cards below the options grid whenever it has products to show: by default
+     * the items the `/suggest` response reports as matching the query, or the
+     * results of a custom `products` search. Set to false to render no strip
+     * and run no custom search.
+     */
+    showProducts?: boolean;
+    /**
+     * Custom source for the product strip. Omit it and the strip shows the
+     * items the `/suggest` response itself reports as matching the query, with
+     * no extra request. Set it and the dropdown is fed by your own search
+     * endpoint on the SDK's existing fetch cadence instead; the server's items
+     * are then not rendered.
      *
      * The object may be re-created on every render: the hook forwards calls
-     * through a stable proxy, so only toggling the strip on or off reaches the
-     * core.
+     * through a stable proxy, so only setting or removing the config reaches
+     * the core.
      *
      * Two consequences of that proxy, both deliberate:
      * - Swapping one live config for another (A → B, both defined) can't be told
      *   apart from a re-render, so A's cards stay on screen until the next
-     *   request replaces them. Toggle `products` off and back on to clear
+     *   request replaces them. Remove `products` and set it again to clear
      *   immediately.
-     * - Turning the strip on mid-session shows nothing until the next `/suggest`
-     *   request fires, because the product search rides that one scheduler and
-     *   enabling the strip doesn't itself change the query.
+     * - Setting a custom config mid-session shows nothing until the next
+     *   `/suggest` request fires, because the product search rides that one
+     *   scheduler and configuring it doesn't itself change the query. Removing
+     *   the config restores the server's items at once.
      */
     products?: ProductsConfig;
     /**
@@ -258,11 +278,19 @@ interface UseAIAutocompleteReturn {
     listboxId: string;
     error: Error | null;
     /**
-     * Results of the latest product search. Always empty unless `products` is
-     * configured. Already spread into `dropdownProps` — read it directly only if
+     * What the product strip shows: the items the latest `/suggest` response
+     * reported as matching the query, or the results of a custom `products`
+     * search. Already spread into `dropdownProps` — read it directly only if
      * you render your own strip.
      */
     products: Product[];
+    /**
+     * The catalog grounding report the latest response carried, or null when it
+     * carried none: which of the query's constraints the catalog applied, which
+     * it dropped, and how many items (and which) the applied ones left
+     * standing. Null is "no news", not an empty catalog.
+     */
+    customFields: CustomFieldsReport | null;
     /**
      * Announce a product selection (fires `onProductSelect`). The built-in
      * dropdown calls this for you; hand-rolled strips call it themselves. The SDK
@@ -422,6 +450,6 @@ declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProp
 
 declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showSkipButton, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showSkipButton, showProducts, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, DateRange, SkippedParamState, IdentifiedParamState, Segment } from '@magicx-eng/ai-autocomplete-vanilla';
-export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, DATE_RANGE_META_END, DATE_RANGE_META_START, DateMonthView, DateRange, FormatType, IdentifiedParam, IdentifiedParamState, OptionOverrides, Product, ProductsConfig, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, isoDate, monthLabel, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
+import { AutocompleteResult, OptionOverrides, APIConfig, AppearanceMode, CompletedParamState, ProductsConfig, Product, Suggestion, SuggestionOption, FormatType, DateMonthView, DateRange, SkippedParamState, IdentifiedParamState, Segment, CustomFieldsReport } from '@magicx-eng/ai-autocomplete-vanilla';
+export { APIConfig, APIKeyConfig, AccessTokenConfig, AccessTokenResult, AppearanceMode, AutocompleteResult, CompletedParam, CompletedParamState, CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DateMonthView, DateRange, ExpressedFilter, FilterOp, FormatType, IdentifiedParam, IdentifiedParamState, MatchedItem, MatchedItems, OptionOverrides, PRODUCT_PATH_PREFIX, Product, ProductsConfig, Segment, SkippedParamState, SubmitResultExtras, Suggestion, SuggestionOption, TaskKind, WEEKDAY_LABELS, buildSubmitResult, cellDay, cellIso, dateCellMarks, formatDate, formatDateRange, isoDate, monthLabel, optionLabel, parseDate, parseLooseDate, parseLooseDateRange, productFromMatchedItem, productsFromCustomFields, sanitizeOptionIconSvg, selectedRangeFor, visibleDateRange, withSkippedParams } from '@magicx-eng/ai-autocomplete-vanilla';
 import * as react from 'react';
 import { ReactNode, KeyboardEvent, ChangeEvent } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -87,23 +87,33 @@ interface AIAutocompleteProps {
     onChange?: (value: string) => void;
     onParamsChange?: (params: CompletedParamState[]) => void;
     /**
-     * Opt-in product strip. When set, the dropdown renders a horizontal row of
-     * product cards below the options grid, fed by your own search endpoint on
-     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
-     * changes — no request, no markup, no layout shift.
+     * When true (default), the dropdown renders a horizontal row of product
+     * cards below the options grid whenever it has products to show: by default
+     * the items the `/suggest` response reports as matching the query, or the
+     * results of a custom `products` search. Set to false to render no strip
+     * and run no custom search.
+     */
+    showProducts?: boolean;
+    /**
+     * Custom source for the product strip. Omit it and the strip shows the
+     * items the `/suggest` response itself reports as matching the query, with
+     * no extra request. Set it and the dropdown is fed by your own search
+     * endpoint on the SDK's existing fetch cadence instead; the server's items
+     * are then not rendered.
      *
      * The object may be re-created on every render: the hook forwards calls
-     * through a stable proxy, so only toggling the strip on or off reaches the
-     * core.
+     * through a stable proxy, so only setting or removing the config reaches
+     * the core.
      *
      * Two consequences of that proxy, both deliberate:
      * - Swapping one live config for another (A → B, both defined) can't be told
      *   apart from a re-render, so A's cards stay on screen until the next
-     *   request replaces them. Toggle `products` off and back on to clear
+     *   request replaces them. Remove `products` and set it again to clear
      *   immediately.
-     * - Turning the strip on mid-session shows nothing until the next `/suggest`
-     *   request fires, because the product search rides that one scheduler and
-     *   enabling the strip doesn't itself change the query.
+     * - Setting a custom config mid-session shows nothing until the next
+     *   `/suggest` request fires, because the product search rides that one
+     *   scheduler and configuring it doesn't itself change the query. Removing
+     *   the config restores the server's items at once.
      */
     products?: ProductsConfig;
     /**
@@ -173,23 +183,33 @@ interface UseAIAutocompleteOptions {
     /** Called when the input loses focus. */
     onBlur?: () => void;
     /**
-     * Opt-in product strip. When set, the dropdown renders a horizontal row of
-     * product cards below the options grid, fed by your own search endpoint on
-     * the SDK's existing fetch cadence. Omit it and nothing about the dropdown
-     * changes — no request, no markup, no layout shift.
+     * When true (default), the dropdown renders a horizontal row of product
+     * cards below the options grid whenever it has products to show: by default
+     * the items the `/suggest` response reports as matching the query, or the
+     * results of a custom `products` search. Set to false to render no strip
+     * and run no custom search.
+     */
+    showProducts?: boolean;
+    /**
+     * Custom source for the product strip. Omit it and the strip shows the
+     * items the `/suggest` response itself reports as matching the query, with
+     * no extra request. Set it and the dropdown is fed by your own search
+     * endpoint on the SDK's existing fetch cadence instead; the server's items
+     * are then not rendered.
      *
      * The object may be re-created on every render: the hook forwards calls
-     * through a stable proxy, so only toggling the strip on or off reaches the
-     * core.
+     * through a stable proxy, so only setting or removing the config reaches
+     * the core.
      *
      * Two consequences of that proxy, both deliberate:
      * - Swapping one live config for another (A → B, both defined) can't be told
      *   apart from a re-render, so A's cards stay on screen until the next
-     *   request replaces them. Toggle `products` off and back on to clear
+     *   request replaces them. Remove `products` and set it again to clear
      *   immediately.
-     * - Turning the strip on mid-session shows nothing until the next `/suggest`
-     *   request fires, because the product search rides that one scheduler and
-     *   enabling the strip doesn't itself change the query.
+     * - Setting a custom config mid-session shows nothing until the next
+     *   `/suggest` request fires, because the product search rides that one
+     *   scheduler and configuring it doesn't itself change the query. Removing
+     *   the config restores the server's items at once.
      */
     products?: ProductsConfig;
     /**
@@ -258,11 +278,19 @@ interface UseAIAutocompleteReturn {
     listboxId: string;
     error: Error | null;
     /**
-     * Results of the latest product search. Always empty unless `products` is
-     * configured. Already spread into `dropdownProps` — read it directly only if
+     * What the product strip shows: the items the latest `/suggest` response
+     * reported as matching the query, or the results of a custom `products`
+     * search. Already spread into `dropdownProps` — read it directly only if
      * you render your own strip.
      */
     products: Product[];
+    /**
+     * The catalog grounding report the latest response carried, or null when it
+     * carried none: which of the query's constraints the catalog applied, which
+     * it dropped, and how many items (and which) the applied ones left
+     * standing. Null is "no news", not an empty catalog.
+     */
+    customFields: CustomFieldsReport | null;
     /**
      * Announce a product selection (fires `onProductSelect`). The built-in
      * dropdown calls this for you; hand-rolled strips call it themselves. The SDK
@@ -422,6 +450,6 @@ declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProp
 
 declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, skipDisabled, activeSelected, isLoading, isInputEmpty, products, onProductSelect, onProductFocusChange, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
 
-declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showSkipButton, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showSkipButton, showProducts, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };