@magicx-eng/ai-autocomplete-vanilla 0.6.0 → 0.8.0

package/README.md

@@ -87,6 +87,13 @@ const ac = new AIAutocomplete(container, {
   // Focus
   autoFocus: true,           // focus the input on mount (Tier 1 only)
 
+  // Product strip (opt-in). Omit it and nothing changes: no request, no markup.
+  products: {
+    fetch: (query, signal) => myPlatform.search(query, { signal }),
+    transform: (raw) => mapToProducts(raw),
+    limit: 8,
+  },
+
   // Custom submit button (Tier 1 only)
   // - undefined (default): renders the built-in arrow button
   // - null: no submit button at all
@@ -100,6 +107,7 @@ const ac = new AIAutocomplete(container, {
   onParamsChange: (params) => { ... },
   onFocus: () => { ... },
   onBlur: () => { ... },
+  onProductSelect: (product) => { ... },   // see "Product strip"
 
   // Controlled mode
   value: "initial text",
@@ -116,6 +124,7 @@ ac.reset();                    // Clear everything, re-fetch, and start a new se
 ac.destroy();                  // Remove DOM, listeners, timers
 ac.setMode("dark");            // Switch color mode
 ac.update({ animations: false, optionsPosition: "above" });
+ac.selectProduct(product);     // Emit onProductSelect (Tier 3 / custom strips)
 ```
 
 > **Tier 1 auto-resets** after both Enter key and built-in submit-button clicks — your `onSubmit` runs, then the SDK clears the input and starts a new session. You don't need to call `ac.reset()` yourself in Tier 1.
@@ -128,6 +137,109 @@ ac.update({ animations: false, optionsPosition: "above" });
 
 > **Caret placement after a completion** — whenever a completed param is added (by any means — option click, exact-match typing, or re-edit), the caret lands right after the trailing space following the bold so typing can continue immediately. A space is inserted if one wasn't already there.
 
+### 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.
+
+```ts
+import { AIAutocomplete, type Product } from "@magicx-eng/ai-autocomplete-vanilla";
+
+new AIAutocomplete(container, {
+  apiConfig: { apiKey: "..." },
+
+  products: {
+    // You own the request entirely — auth headers, GraphQL body, locale
+    // prefixes, whatever the platform needs. Honour the signal: the SDK aborts
+    // it as soon as a newer query supersedes this one.
+    fetch: (query, signal) =>
+      fetch("/api/2024-10/graphql.json", {
+        method: "POST",
+        headers: { "X-Shopify-Storefront-Access-Token": token },
+        body: JSON.stringify({ query: SEARCH_QUERY, variables: { q: query } }),
+        signal,
+      }).then((r) => r.json()),
+
+    // Pure mapping, kept out of `fetch` so you can unit-test it without a
+    // network. Fold it into `fetch` and return the array if you prefer.
+    transform: (raw) =>
+      raw.data.products.nodes.map((node) => ({
+        id: node.id,
+        title: node.title,
+        url: node.onlineStoreUrl,
+        imageUrl: node.featuredImage?.url ?? null,
+        price: formatMoney(node.priceRange.minVariantPrice),  // you know the currency
+        vendor: node.vendor,
+      })),
+
+    limit: 8,   // applied by the SDK, after transform
+  },
+
+  // Selection emits — the SDK never navigates.
+  onProductSelect: (product) => {
+    window.location.assign(product.url);   // …or add to cart, or fill the input
+  },
+});
+```
+
+`Product` is exactly six fields; only `id`, `title` and `url` are required:
+
+```ts
+type Product = {
+  id: string;
+  title: string;
+  url: string;
+  imageUrl?: string | null;   // null renders the placeholder tile
+  price?: string;             // pre-formatted by you
+  vendor?: string;
+};
+```
+
+**What the SDK guarantees**
+
+- **One fetch cadence.** The product search rides the same debounce, the same
+  `AbortController` and the same version guard as `/suggest` — there is no
+  second timer to drift out of step. A query that never triggers a suggestions
+  request (e.g. one still narrowing the current option list) doesn't trigger a
+  product search either.
+- **Empty queries never reach you.** On mount and after `reset()` the strip
+  simply clears.
+- **Out-of-order responses are dropped.** A slow response for an older query is
+  never rendered over a newer one.
+- **Failure is silent.** A rejected `fetch` or a throwing `transform` clears the
+  strip, logs once, and leaves the suggestions half untouched — no `error`
+  state, no `onError`, no effect on `isLoading`.
+- **The two halves are independent.** The panel opens if *either* has content,
+  so products keep it open when option filtering empties the list, and
+  suggestions render normally when there are no products. `dropdownTrigger`
+  (`manual` / `hidden`) still gates the panel as before — products don't
+  overrule an explicit opt-out of an auto-opening panel.
+
+**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 — the SDK
+never navigates on your behalf.
+
+`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]`
+sanitiser, so unrecognised schemes like `myapp://…` are rewritten to
+`unsafe:…` in that package only.)
+
+**Accessibility.** The strip is a `role="group"` labelled "Products"; each card
+is a `role="option"` in the tab order, activated with Enter or Space, with a
+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.
+
+`update({ products })` swaps the integration (and clears the current cards);
+`update({ products: undefined })` turns the strip off. Either way the strip
+repopulates on the *next* `/suggest` request rather than immediately — the
+product search rides that one scheduler, and changing the config doesn't itself
+change the query.
+
 #### Custom submit button
 
 ```ts
@@ -176,6 +288,8 @@ input.addEventListener("blur", () => ac.setFocused(false));
 
 Pills always render inside the dropdown in this mode. The library creates the dropdown DOM inside your container — you just provide the element and wire up your input's events.
 
+The [product strip](#product-strip) works here too: pass `products` / `onProductSelect` exactly as in Tier 1 and the strip renders inside the dropdown the library owns.
+
 > Focus/blur wiring is required when `dropdownTrigger` is `"auto"` (the default) — the dropdown only opens while the input is focused. Without `setFocused()`, the dropdown will never open.
 
 ---
@@ -244,6 +358,7 @@ unsub();
 | `isLoading` | `boolean` | Fetch in progress. The Tier 1 / Tier 2 renderers gate the loading skeleton additionally on `!inSelectionAnimation` and `!editingParam`. |
 | `inSelectionAnimation` | `boolean` | True for the 500 ms after a user-initiated option tap so the streak animation can finish before the dropdown switches to the loading skeleton. |
 | `editingParam` | `CompletedParamState \| null` | When non-null, the user is re-editing a bold completed param; cached options remain visible and the loading skeleton is suppressed. |
+| `products` | `Product[]` | Results of the latest product search (empty unless `products` is configured). See [Product strip](#product-strip) — Tier 3 consumers render their own cards and call `selectProduct(product)` to emit `onProductSelect`. |
 | `isReady` | `boolean` | Server indicates query is complete |
 | `error` | `Error \| null` | Last fetch error |
 
@@ -323,7 +438,19 @@ The object passed to `onSubmit`:
 |---|---|---|
 | `query` | `string` | Plain text as the user sees it. |
 | `raw_query` | `string` | Text with placeholder tokens (e.g. `"Create a {{TASK_1}}"`). |
-| `completed_params` | `CompletedParam[]` | Array of filled parameter values. |
+| `completed_params` | `CompletedParam[]` | Array of filled parameter values, followed by any the user skipped (see below). |
+
+#### Skipped parameters
+
+Pressing <kbd>→</kbd> at the end of the input dismisses the active pill. The dismissal is reported to the server — and included in `completed_params` here — as an entry with no placeholder and the sentinel text `"skipped"`:
+
+```ts
+{ placeholder: "", type: "goal", text: "skipped", kind: null }
+```
+
+Skipped entries are appended after the filled params (they have no position in the query) and are deduped by type. A skip is dropped if a param of the same type ends up filled anyway. Skipping the last available pill triggers an immediate request so the server can suggest something else; earlier skips ride along on the next request. `reset()` clears them.
+
+> **Reading `state.skippedParams` directly:** the array is append-only until `reset()`. The "drop a skip whose type got filled" rule is applied when the payload is built, not by pruning the array — so if the user skips `goal` and later fills one, the raw array still holds the `goal` entry. That's deliberate: the filter self-heals if they then delete that param's text, where pruning would discard the signal for good. Apply the same rule yourself with the exported `withSkippedParams(completedParams, skippedParams)`.
 
 ### Event Subscription
 
@@ -379,6 +506,21 @@ Override these on the container element. All built-in defaults use `:where()` (z
 | `--aia-scrollbar-thumb` | `rgba(0, 0, 0, 0.3)` | `rgba(0, 0, 0, 0.3)` | Color of the option list's scrollbar thumb (Firefox + WebKit). |
 | `--aia-streak-rgb` | `99, 102, 241` | `255, 255, 255` | Comma-separated RGB triplet used to tint the option-selection streak animation (consumed via `rgba(var(--aia-streak-rgb), …)`). |
 | `--aia-streak-glass-bg` | `rgba(99, 102, 241, 0.1)` | `rgba(255, 255, 255, 0.1)` | Background fill for the streak's glass-pill effect. |
+| `--aia-product-card-width` | `116px` | `116px` | Width of a product card in the strip. The media tile is square, so this also sets its height. |
+| `--aia-product-gap` | `8px` | `8px` | Gap between product cards. |
+| `--aia-product-bg` | `transparent` | `transparent` | Product card background. |
+| `--aia-product-bg-active` | `--aia-option-bg` | `--aia-option-bg` | Product card background on hover. |
+| `--aia-product-media-bg` | `--aia-skeleton-bg` | `--aia-skeleton-bg` | Fill behind the product image, and of the placeholder tile when a product has no image. |
+| `--aia-product-placeholder-color` | `--aia-option-color` | `--aia-option-color` | Glyph color of the no-image placeholder tile. |
+| `--aia-product-title-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product title text. Follows the option colors by default, so theming the panel moves suggestions and products together. |
+| `--aia-product-price-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product price text. |
+| `--aia-product-vendor-color` | `--aia-option-color` | `--aia-option-color` | Product vendor line. |
+| `--aia-product-focus-ring` | `--aia-option-color-selected` | `--aia-option-color-selected` | Focus ring drawn on a keyboard-focused card. |
+| `--aia-products-label-color` | `--aia-option-color` | `--aia-option-color` | "Products" section label. |
+| `--aia-product-title-font-size` | `12px` | `12px` | Product title font size. |
+| `--aia-product-price-font-size` | `11px` | `11px` | Product price font size. |
+| `--aia-product-vendor-font-size` | `10px` | `10px` | Product vendor font size. |
+| `--aia-products-label-font-size` | `11px` | `11px` | Section label font size. |
 | `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.25)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
 
 ### Per-mode Overrides
@@ -412,7 +554,11 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-pill]` | Each unfilled-suggestion pill |
 | `[data-aia-pillbar]` | Pill bar container inside the dropdown |
 | `[data-aia-option]` | Each suggestion option |
-| `[data-aia-dropdown]` | The dropdown root (listbox) |
+| `[data-aia-dropdown]` | The dropdown root (listbox). Carries `data-aia-has-products` while the product strip has cards. |
+| `[data-aia-products]` | Product strip section (label + row) |
+| `[data-aia-products-row]` | The horizontally scrolling row of cards |
+| `[data-aia-product]` | Each product card |
+| `[data-aia-product-placeholder]` | Media tile of a card whose product has no image |
 
 Completed params render as inline `<strong>` elements inside the editor. Override their weight with `[data-aia-input] strong { font-weight: 700; }` (the built-in style uses `:where()` so any consumer selector wins without `!important`).
 

package/dist/index.d.mts

@@ -78,6 +78,30 @@ interface CompletedParamState extends CompletedParam {
     options: SuggestionOption[];
     metadata?: Record<string, unknown>;
 }
+/**
+ * A suggestion the user dismissed with the skip key (→) instead of filling.
+ *
+ * Client-only bookkeeping. A skipped suggestion has no text in the input, so
+ * it can't live in `completedParams` — that array is reconciled against the
+ * input on every keystroke and anything missing from the text is dropped.
+ * Skipped entries are folded into the wire `completed_params` array (with
+ * `text: "skipped"`, no placeholder) only when a request or a submit result is
+ * built. See `withSkippedParams`.
+ *
+ * The array is append-only until `reset()` — a skip is filtered out at
+ * build time when a param of its type ended up filled, not pruned here.
+ * That's deliberate: the filter self-heals if the user later deletes that
+ * param's text (the skip reappears in the payload), where pruning would have
+ * discarded the signal permanently. Consumers reading this array directly
+ * should apply the same filter — `withSkippedParams` is exported for it.
+ */
+interface SkippedParamState {
+    id: string;
+    /** The skipped suggestion's `type` (e.g. "goal"). */
+    type: string;
+    /** The suggestion's display text at skip time. Introspection only — never sent. */
+    suggestionPlaceholder: string;
+}
 /**
  * Client-side state for an LLM-identified param. Tentative — replaced
  * wholesale from each response (latest wins) and dropped when its text no
@@ -123,6 +147,66 @@ interface AccessTokenResult {
 }
 type APIConfig = APIKeyConfig | AccessTokenConfig;
 type OptionOverrides = Record<string, (query: string) => SuggestionOption[]>;
+/**
+ * A single product card in the dropdown's product strip.
+ *
+ * Platform-agnostic on purpose: every integration (Shopify today, others
+ * later) maps its own search response onto exactly these fields, so the SDK
+ * renders one strip regardless of where the results came from. Only `id`,
+ * `title` and `url` are required — the card reflows when any of the rest is
+ * missing. Do NOT grow this shape casually; a new field is a new contract
+ * every integration has to satisfy.
+ */
+interface Product {
+    /** Stable identity — used as the render key, so it must be unique per result set. */
+    id: string;
+    title: string;
+    /** Destination for the card's `href`. Selection does not navigate; see `onProductSelect`. */
+    url: string;
+    /** Absent/null renders the placeholder tile — plenty of catalogues have no images. */
+    imageUrl?: string | null;
+    /** Pre-formatted by the integration, which is the side that knows the currency. */
+    price?: string;
+    vendor?: string;
+}
+/**
+ * Opt-in product-search wiring. Absent (the default) means the SDK never
+ * fetches and never renders a strip — behaviour is byte-for-byte what it was
+ * before products existed.
+ */
+interface ProductsConfig {
+    /**
+     * Runs the platform's product search. The integration owns the request
+     * entirely — auth headers, GraphQL body, locale prefixes, whatever the
+     * platform needs — and must honour `signal`: the SDK aborts it the moment a
+     * newer query supersedes this one.
+     *
+     * Called on the SDK's own fetch cadence (the same debounce that drives
+     * `/suggest`), never on a timer of its own, and never with an empty query.
+     */
+    fetch: (query: string, signal: AbortSignal) => Promise<unknown>;
+    /**
+     * Maps the platform's raw payload onto `Product[]`. Kept separate from
+     * `fetch` so integrations can unit-test the mapping without a network; fold
+     * it into `fetch` and return the mapped array if you prefer.
+     *
+     * A throw here is treated exactly like a rejected fetch: the strip clears,
+     * the suggestions half is untouched.
+     *
+     * The output is trusted: `Product.url` goes straight onto the card's `href`
+     * with no sanitisation, and modifier / middle clicks are deliberately left
+     * to the browser. If the platform response is not fully under your control,
+     * validate the URL inside `transform`.
+     *
+     * One cross-framework caveat: Angular's `[href]` binding runs its own URL
+     * sanitiser, so a scheme it doesn't recognise (`myapp://…`) is rewritten to
+     * `unsafe:myapp://…` there while vanilla and React emit it verbatim. Stick
+     * to http/https if the same integration has to serve all three packages.
+     */
+    transform: (raw: unknown) => Product[];
+    /** Optional cap the SDK applies after `transform`. */
+    limit?: number;
+}
 interface AutocompleteResult {
     query: string;
     raw_query: string;
@@ -142,6 +226,15 @@ interface CoreInputState {
      * override or overlap completed params.
      */
     identifiedParams: IdentifiedParamState[];
+    /**
+     * Suggestions the user dismissed with the skip key (→). Held apart from
+     * `completedParams` because they have no text in the input; folded into the
+     * wire `completed_params` array (as `text: "skipped"`) on every request and
+     * on the submit result. Append-only until `reset()` — see
+     * {@link SkippedParamState} for why skips of a since-filled type are
+     * filtered at build time rather than pruned here.
+     */
+    skippedParams: SkippedParamState[];
     /**
      * Open while the user has unresolved trailing text: anchored at the covered
      * offset where they started typing, snapshotting the actionable suggestions
@@ -155,6 +248,13 @@ interface CoreInputState {
         snapshot: Suggestion[];
     } | null;
     suggestions: Suggestion[];
+    /**
+     * Results of the latest product search, already transformed and capped by
+     * `opts.products.limit`. Always empty when `opts.products` is unconfigured.
+     * Cleared on an empty query and on a failed fetch/transform, so the strip
+     * never shows results belonging to an older query.
+     */
+    products: Product[];
     activeDropdownIndex: number;
     newParamId: string | null;
     isLoading: boolean;
@@ -256,6 +356,13 @@ interface CoreOptions {
      * arrow button. Clicks on the provided element bubble up and trigger submit.
      */
     submitButton?: HTMLElement | null;
+    /**
+     * Opt-in product strip. When set, the dropdown renders a horizontal row of
+     * product cards below the options grid, fed by the integration's 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.
+     */
+    products?: ProductsConfig;
     onSubmit?: (result: AutocompleteResult) => void;
     onError?: (error: Error) => void;
     onChange?: (text: string) => void;
@@ -265,6 +372,13 @@ interface CoreOptions {
     onFocus?: () => void;
     /** Called when the input loses focus (or `setFocused(false)` is called). */
     onBlur?: () => void;
+    /**
+     * Called when the user activates a product card. The SDK does NOT navigate —
+     * the integration decides what a selection means (open the PDP, add to cart,
+     * fill the input, …). Modifier / middle clicks are left to the browser so
+     * cmd-click and "copy link address" keep working, and don't fire this.
+     */
+    onProductSelect?: (product: Product) => void;
     value?: string;
     completedParams?: CompletedParamState[];
     /**
@@ -285,8 +399,9 @@ type AIAutocompleteEvents = {
     stateChange: [state: CoreState];
     focus: [];
     blur: [];
+    productSelect: [product: Product];
 };
-type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur">>;
+type CoreUpdateOptions = Partial<Omit<CoreOptions, "onSubmit" | "onError" | "onChange" | "onParamsChange" | "onStateChange" | "onFocus" | "onBlur" | "onProductSelect">>;
 declare class AIAutocomplete {
     private inputStore;
     private store;
@@ -295,6 +410,7 @@ declare class AIAutocomplete {
     private fetchController;
     private keyboardController;
     private pillsController;
+    private productsController;
     private reEdit;
     private modeController;
     private container;
@@ -345,6 +461,15 @@ declare class AIAutocomplete {
     handleCaretAfterInput(offset: number | null): void;
     handleCaretMove(offset: number | null): void;
     setActiveDropdownIndex(index: number): void;
+    /**
+     * Announce a product selection. The rendered cards call this on activation;
+     * headless consumers rendering their own strip call it themselves.
+     *
+     * Emitting is the entire behaviour — the SDK deliberately does not navigate
+     * to `product.url`, because only the integration knows whether a selection
+     * means "open the PDP", "add to cart" or "drop the title into the input".
+     */
+    selectProduct(product: Product): void;
     handleTextChange(value: string): void;
     handleKeyDown(e: KeyboardEvent): void;
     setFocused(focused: boolean): void;
@@ -393,6 +518,8 @@ declare class AIAutocomplete {
      * subscription early-returns on subsequent fires.
      */
     private maybeExitReEditOnNoMatch;
+    /** Fire an immediate (undebounced) fetch for the current text + params. */
+    private fetchNow;
     /**
      * When the user has typed text that exactly matches (case-insensitive) one
      * of the active suggestion's options, promote it to a completed param right
@@ -536,4 +663,36 @@ declare class ModeController {
     private detachListener;
 }
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type IdentifiedParam, type IdentifiedParamState, type InputItem, ModeController, type OptionOverrides, type RecentlySuggested, type RenderMode, type Segment, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset };
+/**
+ * Sentinel `text` marking a `completed_params` entry the user skipped (→)
+ * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
+ * marker, never user-entered content.
+ */
+declare const SKIPPED_PARAM_TEXT = "skipped";
+/**
+ * Folds skipped suggestions into a wire `completed_params` array so the server
+ * learns which parameters the user dismissed and can stop re-suggesting them.
+ *
+ * Skipped entries carry no placeholder: nothing was substituted into
+ * `raw_query`, so a `{{TYPE_N}}` token would point at text that doesn't exist.
+ * They're appended after the real params for the same reason — they have no
+ * position in the query.
+ *
+ * A skip is dropped when a param of the same type ends up filled anyway (the
+ * user skipped `goal`, then typed one): sending both would tell the server the
+ * parameter is simultaneously answered and declined.
+ */
+declare function withSkippedParams(completed: CompletedParam[], skipped: SkippedParamState[]): CompletedParam[];
+
+/**
+ * Builds the `AutocompleteResult` handed to `onSubmit`: the placeholder-
+ * tokenized raw query plus the completed params, with skipped suggestions
+ * folded in (see {@link withSkippedParams}).
+ *
+ * Shared by every submit path — vanilla Enter / submit button, the React Tier 1
+ * component, the Angular Tier 1 component — so they can't drift on what a
+ * result contains.
+ */
+declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[]): AutocompleteResult;
+
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type IdentifiedParam, type IdentifiedParamState, type InputItem, ModeController, type OptionOverrides, type Product, type ProductsConfig, type RecentlySuggested, type RenderMode, SKIPPED_PARAM_TEXT, type Segment, type SkippedParamState, type Store, type Suggestion, type SuggestionOption, type TaskKind, buildAttributionUrl, buildQuery, buildSubmitResult, createStore, cursorIsAtEnd, extractPlainText, getCursorOffset, getFooterHint, plainTextLength, previousGraphemeBoundary, renderEditableContent, setCursorOffset, withSkippedParams };