@magicx-eng/ai-autocomplete-react 0.43.1 → 0.44.0

package/README.md

@@ -367,6 +367,7 @@ function App() {
 | `productImageFallback?` | `"image" \| "initial"` | `"image"` | Fallback for a missing or blank product image URL, or an image load error. `"image"` shows the placeholder pictogram; `"initial"` shows the title initial. A working image still takes priority. See [Product strip](#product-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. |
+| `onProductAddToCart?` | `(product: Product) => void \| PromiseLike<unknown>` | — | When set, every card that isn't sold out shows an add-to-cart button; pressing it calls this instead of `onProductSelect`. Return a promise to show progress. See [Product strip](#product-strip). |
 | `resetOnSubmit?` | `boolean` | `true` | Clear the input and start a new session after `onSubmit` runs. Set to `false` to keep the query in place — e.g. when `onSubmit` navigates away — and call the handle's `reset()` yourself. |
 | `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()`. |
@@ -614,6 +615,32 @@ type Product = {
   itself change the query. Removing the config restores the server's items at
   once.
 
+**Add to cart.** Pass `onProductAddToCart` and every card that isn't sold out
+(`available: false`) shows a round cart button over the bottom-right corner of
+its image (in the list layout, at the right end of the row). Leave it unset and
+no card has one. The SDK never touches a cart: pressing the button calls your
+handler with the card's `Product`, and does not fire `onProductSelect`,
+navigate or close the panel.
+
+```tsx
+<AIAutocomplete
+  onSubmit={handleSubmit}
+  onProductAddToCart={(product) => cart.add(product.id)}
+/>
+```
+
+Return a promise to have the button show progress. While it is pending the
+button carries `data-aia-cart-state="adding"` (and `aria-busy="true"`), dims
+and ignores further presses; once it resolves the cart turns into a check
+(`data-aia-cart-state="added"`) for 1.5 seconds. A rejection puts the button
+back at rest — show your own error. A handler that returns nothing goes
+straight to "added". The button is labelled "Add to cart: {title}" in the
+widget language, reachable by Tab and pressed with Enter or Space. Theme it
+with `--aia-product-cart-size` (28px), `--aia-product-cart-bg` and
+`--aia-product-cart-color`; its focus ring uses `--aia-product-focus-ring`.
+The button is a `[data-aia-product-cart]` element, and a card that has one
+carries `data-aia-product-has-cart`.
+
 **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
 intercepted (`preventDefault`) and emits `onProductSelect` instead.
@@ -631,10 +658,10 @@ 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: `useAIAutocomplete()` takes `showProducts`,
-`products`, `productImageFallback` 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.
+`products`, `productImageFallback`, `onProductSelect` and `onProductAddToCart`,
+and the strip renders inside `<AIAutocompleteDropdown />` via `dropdownProps`.
+Tier 3 consumers read `products` (and `customFields`) from the hook and call
+`selectProduct(product)` and `addProductToCart(product)` from their own cards.
 
 #### Custom submit button
 
@@ -732,6 +759,7 @@ The headless hook for Tier 2 and Tier 3. Accepts the same options as `<AIAutocom
 | `reset` | `() => void` | Clear all state, re-fetch, and start a new session (rotates `session_id`). Call this after handling submit. |
 | `recordSubmit` | `(result: AutocompleteResult) => void` | Record a submit from a button you render. Enter is recorded for you; call this once per button submit. |
 | `selectProduct` | `(product: Product) => void` | Announce a product selection (fires `onProductSelect`). The built-in dropdown calls this for you; hand-rolled strips call it themselves. Never navigates. |
+| `addProductToCart` | `(product: Product) => Promise<void>` | Add a product through `onProductAddToCart`. The built-in dropdown's cart buttons call this for you; hand-rolled strips call it themselves. Resolves when the handler's promise settles and rejects with its error; does nothing without a handler. |
 
 **Input forwarding (custom inputs)** — call these instead of spreading `inputProps` when your input isn't a `<textarea>` (contentEditable / rich-text editors):
 
@@ -747,7 +775,7 @@ The headless hook for Tier 2 and Tier 3. Accepts the same options as `<AIAutocom
 | Field | Type | Description |
 |---|---|---|
 | `inputProps` | `object` | Spread onto a `<textarea>`. Includes `value`, `placeholder`, `onChange`, `onKeyDown`, and ARIA attributes. |
-| `dropdownProps` | `AIAutocompleteDropdownProps` | Spread onto `<AIAutocompleteDropdown />`. Carries the options, `activeIndex`, `onSelect` / `onHighlight`, pills, open state, `optionsPosition`, and the product strip's `products` / `productImageFallback` / `onProductSelect` / `onProductFocusChange` — read these directly to render your own dropdown in Tier 3. |
+| `dropdownProps` | `AIAutocompleteDropdownProps` | Spread onto `<AIAutocompleteDropdown />`. Carries the options, `activeIndex`, `onSelect` / `onHighlight`, pills, open state, `optionsPosition`, and the product strip's `products` / `productImageFallback` / `onProductSelect` / `onProductAddToCart` (only when the hook has one) / `onProductFocusChange` — read these directly to render your own dropdown in Tier 3. |
 
 ### `<AIAutocompleteDropdown />`
 
@@ -770,6 +798,7 @@ The dropdown component for Tier 2. Spread `dropdownProps` from the hook (and add
 | `products?` | `Product[]` | Product cards to render below the options grid. Empty renders no strip. |
 | `productImageFallback?` | `"image" \| "initial"` | Default: `"image"`. Fallback for a missing or blank product image URL, or an image load error. `"image"` shows the placeholder pictogram; `"initial"` shows the title initial. A working image still takes priority. See [Product strip](#product-strip). Forwarded by the hook in `dropdownProps`. |
 | `onProductSelect?` | `(product: Product) => void` | Called when a card is activated. |
+| `onProductAddToCart?` | `(product: Product) => void \| PromiseLike<unknown>` | When set, every card that isn't sold out draws an add-to-cart button whose press calls this. See [Product strip](#product-strip). |
 | `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. |
 

package/dist/index.d.mts

@@ -177,6 +177,18 @@ interface AIAutocompleteProps {
      * browser (so cmd-click still opens a tab) and don't fire this.
      */
     onProductSelect?: (product: Product) => void;
+    /**
+     * Adds a product to the cart from its card. When set, every card that isn't
+     * sold out (`available: false`) shows an add-to-cart button in the bottom
+     * right corner of its image; when unset, no card has one. Pressing the button
+     * calls this, not `onProductSelect`, and the panel stays open. The SDK never
+     * touches a cart itself.
+     *
+     * Return a promise to have the button show progress: it carries
+     * `data-aia-cart-state="adding"` until the promise settles, then `"added"`
+     * for a moment if it resolved. A rejection puts the button back at rest.
+     */
+    onProductAddToCart?: (product: Product) => void | PromiseLike<unknown>;
     /**
      * Custom submit button. Pass any ReactNode to replace the default button.
      * Pass `null` to render no button. Default (`undefined`) renders the built-in
@@ -337,6 +349,18 @@ interface UseAIAutocompleteOptions {
      * browser (so cmd-click still opens a tab) and don't fire this.
      */
     onProductSelect?: (product: Product) => void;
+    /**
+     * Adds a product to the cart from its card. When set, every card that isn't
+     * sold out (`available: false`) shows an add-to-cart button in the bottom
+     * right corner of its image; when unset, no card has one. Pressing the button
+     * calls this, not `onProductSelect`, and the panel stays open. The SDK never
+     * touches a cart itself.
+     *
+     * Return a promise to have the button show progress: it carries
+     * `data-aia-cart-state="adding"` until the promise settles, then `"added"`
+     * for a moment if it resolved. A rejection puts the button back at rest.
+     */
+    onProductAddToCart?: (product: Product) => void | PromiseLike<unknown>;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -431,6 +455,13 @@ interface UseAIAutocompleteReturn {
      * never navigates.
      */
     selectProduct: (product: Product) => void;
+    /**
+     * Add a product to the cart through `onProductAddToCart`. The built-in
+     * dropdown's cart buttons call this for you; hand-rolled strips call it
+     * themselves. Resolves once the handler's promise settles and rejects with
+     * its error. Without a handler it does nothing.
+     */
+    addProductToCart: (product: Product) => Promise<void>;
     /** Tier 1 helper: forward plain-text input to the core (autocapitalize handled). */
     handleTextChange: (value: string) => void;
     /** Tier 1 helper: forward keyboard events to the core. */
@@ -557,6 +588,14 @@ interface AIAutocompleteDropdownProps {
     products?: Product[];
     /** Called when a product card is activated. Provided by `dropdownProps` from the hook. */
     onProductSelect?: (product: Product) => void;
+    /**
+     * Called when a card's add-to-cart button is pressed. When set, every card
+     * that isn't sold out draws the button; when unset, none do. Provided by
+     * `dropdownProps` from the hook when `onProductAddToCart` is set. Return a
+     * promise to have the button show `data-aia-cart-state="adding"`, then
+     * `"added"` for a moment once it resolves.
+     */
+    onProductAddToCart?: (product: Product) => void | PromiseLike<unknown>;
     /** How the product strip lays its cards out — see the Tier 1 prop of the same name. Default: `"row"`. */
     productsLayout?: ProductsLayout;
     /**
@@ -617,8 +656,8 @@ interface AIAutocompleteDropdownProps {
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, onUnhighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, showOptionImages, showOptionCounts, skipDisabled, activeSelected, isLoading, skeletonExiting, isInputEmpty, language, products, onProductSelect, onProductFocusChange, productsLayout, productImageFallback, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, onUnhighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, showOptionImages, showOptionCounts, skipDisabled, activeSelected, isLoading, skeletonExiting, isInputEmpty, language, products, onProductSelect, onProductAddToCart, onProductFocusChange, productsLayout, productImageFallback, 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, language, currency, productId, visitorId, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showOptionImages, showOptionCounts, showSkipButton, showProducts, productImageFallback, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, mapProducts, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, language, currency, productId, visitorId, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showOptionImages, showOptionCounts, showSkipButton, showProducts, productImageFallback, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, mapProducts, onProductSelect, onProductAddToCart, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };

package/dist/index.d.ts

@@ -177,6 +177,18 @@ interface AIAutocompleteProps {
      * browser (so cmd-click still opens a tab) and don't fire this.
      */
     onProductSelect?: (product: Product) => void;
+    /**
+     * Adds a product to the cart from its card. When set, every card that isn't
+     * sold out (`available: false`) shows an add-to-cart button in the bottom
+     * right corner of its image; when unset, no card has one. Pressing the button
+     * calls this, not `onProductSelect`, and the panel stays open. The SDK never
+     * touches a cart itself.
+     *
+     * Return a promise to have the button show progress: it carries
+     * `data-aia-cart-state="adding"` until the promise settles, then `"added"`
+     * for a moment if it resolved. A rejection puts the button back at rest.
+     */
+    onProductAddToCart?: (product: Product) => void | PromiseLike<unknown>;
     /**
      * Custom submit button. Pass any ReactNode to replace the default button.
      * Pass `null` to render no button. Default (`undefined`) renders the built-in
@@ -337,6 +349,18 @@ interface UseAIAutocompleteOptions {
      * browser (so cmd-click still opens a tab) and don't fire this.
      */
     onProductSelect?: (product: Product) => void;
+    /**
+     * Adds a product to the cart from its card. When set, every card that isn't
+     * sold out (`available: false`) shows an add-to-cart button in the bottom
+     * right corner of its image; when unset, no card has one. Pressing the button
+     * calls this, not `onProductSelect`, and the panel stays open. The SDK never
+     * touches a cart itself.
+     *
+     * Return a promise to have the button show progress: it carries
+     * `data-aia-cart-state="adding"` until the promise settles, then `"added"`
+     * for a moment if it resolved. A rejection puts the button back at rest.
+     */
+    onProductAddToCart?: (product: Product) => void | PromiseLike<unknown>;
     value?: string;
     completedParams?: CompletedParamState[];
     onChange?: (value: string) => void;
@@ -431,6 +455,13 @@ interface UseAIAutocompleteReturn {
      * never navigates.
      */
     selectProduct: (product: Product) => void;
+    /**
+     * Add a product to the cart through `onProductAddToCart`. The built-in
+     * dropdown's cart buttons call this for you; hand-rolled strips call it
+     * themselves. Resolves once the handler's promise settles and rejects with
+     * its error. Without a handler it does nothing.
+     */
+    addProductToCart: (product: Product) => Promise<void>;
     /** Tier 1 helper: forward plain-text input to the core (autocapitalize handled). */
     handleTextChange: (value: string) => void;
     /** Tier 1 helper: forward keyboard events to the core. */
@@ -557,6 +588,14 @@ interface AIAutocompleteDropdownProps {
     products?: Product[];
     /** Called when a product card is activated. Provided by `dropdownProps` from the hook. */
     onProductSelect?: (product: Product) => void;
+    /**
+     * Called when a card's add-to-cart button is pressed. When set, every card
+     * that isn't sold out draws the button; when unset, none do. Provided by
+     * `dropdownProps` from the hook when `onProductAddToCart` is set. Return a
+     * promise to have the button show `data-aia-cart-state="adding"`, then
+     * `"added"` for a moment once it resolves.
+     */
+    onProductAddToCart?: (product: Product) => void | PromiseLike<unknown>;
     /** How the product strip lays its cards out — see the Tier 1 prop of the same name. Default: `"row"`. */
     productsLayout?: ProductsLayout;
     /**
@@ -617,8 +656,8 @@ interface AIAutocompleteDropdownProps {
 
 declare const AIAutocomplete: react.ForwardRefExoticComponent<AIAutocompleteProps & react.RefAttributes<AIAutocompleteHandle>>;
 
-declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, onUnhighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, showOptionImages, showOptionCounts, skipDisabled, activeSelected, isLoading, skeletonExiting, isInputEmpty, language, products, onProductSelect, onProductFocusChange, productsLayout, productImageFallback, formatType, dateView, selectedDateIso, selectedDateRange, dateRangeStart, onPreviousMonth, onNextMonth, optionsPosition, mode, }: AIAutocompleteDropdownProps): react_jsx_runtime.JSX.Element;
+declare function AIAutocompleteDropdown({ suggestions, activeIndex, onSelect, onHighlight, onUnhighlight, isOpen, id, className, pills, onPillClick, showPills, onSkip, showSkipButton, showOptionIcons, showOptionImages, showOptionCounts, skipDisabled, activeSelected, isLoading, skeletonExiting, isInputEmpty, language, products, onProductSelect, onProductAddToCart, onProductFocusChange, productsLayout, productImageFallback, 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, language, currency, productId, visitorId, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showOptionImages, showOptionCounts, showSkipButton, showProducts, productImageFallback, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, mapProducts, onProductSelect, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
+declare function useAIAutocomplete({ onSubmit, onResult, onError, optionOverrides, maskCompletedText, apiConfig, additionalContext, language, currency, productId, visitorId, columns, dropdownTrigger, optionsPosition, closeDropdownOnBlur, showNonTappableOptions, showOptionIcons, showOptionImages, showOptionCounts, showSkipButton, showProducts, productImageFallback, onFocus, onBlur, value: controlledValue, completedParams: controlledParams, onChange: onChangeProp, onParamsChange, products, mapProducts, onProductSelect, onProductAddToCart, source, setCursor, }: UseAIAutocompleteOptions): UseAIAutocompleteReturn;
 
 export { AIAutocomplete, AIAutocompleteDropdown, type AIAutocompleteDropdownProps, type AIAutocompleteHandle, type AIAutocompleteProps, type UseAIAutocompleteOptions, type UseAIAutocompleteReturn, useAIAutocomplete };