@magicx-eng/ai-autocomplete-angular 0.5.8 → 0.7.0

package/README.md

@@ -306,6 +306,7 @@ Standalone-first apps don't need this — import the components/directive direct
 | `autoFocus` | `boolean` | `true` | Focus the input on mount. Set to `false` to leave focus to the consumer. |
 | `value` | `string` | — | Controlled text value. Pair with `(valueChange)` or use `[(value)]`. |
 | `completedParams` | `CompletedParamState[]` | — | Controlled completed params. Pair with `(completedParamsChange)` or use `[(completedParams)]`. |
+| `products` | `ProductsConfig` | — | Opt-in product strip — see [Product strip](#product-strip). Bind a stable reference (a component field, not an inline object literal). Omit it and nothing about the dropdown changes. |
 | `submitButton` | `TemplateRef<unknown> \| null` | — | Custom submit button. Pass a `<ng-template>` 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. |
 
 | Output | Payload | Description |
@@ -316,6 +317,7 @@ Standalone-first apps don't need this — import the components/directive direct
 | `completedParamsChange` | `CompletedParamState[]` | Two-way binding partner for `[completedParams]`. |
 | `focused` | `void` | The input gained focus. |
 | `blurred` | `void` | The input lost focus. |
+| `productSelect` | `Product` | A product card was activated. The SDK never navigates. |
 
 **Imperative methods** (via `@ViewChild`):
 
@@ -326,6 +328,112 @@ Standalone-first apps don't need this — import the components/directive direct
 | `reset()` | Clear all state, re-fetch, and start a new session (rotates `session_id`). |
 | `setMode(mode)` | Switch color mode at runtime. |
 
+#### 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 { Component } from "@angular/core";
+import type { Product, ProductsConfig } from "@magicx-eng/ai-autocomplete-angular";
+
+@Component({
+  template: `<ai-autocomplete
+    [apiConfig]="apiConfig"
+    [products]="products"
+    (productSelect)="openProduct($event)"
+    (submitted)="onSubmit($event)"
+  ></ai-autocomplete>`,
+})
+export class SearchComponent {
+  // A component field, not an inline object literal: a new reference on each
+  // change-detection pass reads as a swapped integration and clears the
+  // current cards (the same rule `apiConfig` and `optionOverrides` follow).
+  products: ProductsConfig = {
+    // You own the request entirely — auth headers, GraphQL body, locale
+    // prefixes. Honour the signal: the SDK aborts it as soon as a newer query
+    // supersedes this one.
+    fetch: (query, signal) =>
+      fetch(`/api/products?q=${encodeURIComponent(query)}`, { signal }).then((r) => r.json()),
+
+    // Pure mapping, kept out of `fetch` so you can unit-test it without a
+    // network.
+    transform: (raw): Product[] =>
+      (raw as ApiResponse).items.map((item) => ({
+        id: item.id,
+        title: item.title,
+        url: item.url,
+        imageUrl: item.image?.src ?? null,   // null renders the placeholder tile
+        price: formatMoney(item.price),      // you know the currency
+        vendor: item.brand,
+      })),
+
+    limit: 8,   // applied by the SDK, after transform
+  };
+
+  // Selection emits — the SDK never navigates.
+  openProduct(product: Product): void {
+    this.router.navigateByUrl(product.url);
+  }
+}
+```
+
+`Product` is exactly six fields; only `id`, `title` and `url` are required:
+
+```ts
+type Product = {
+  id: string;
+  title: string;
+  url: string;
+  imageUrl?: string | null;
+  price?: string;
+  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.
+- **Empty queries never reach you.** On mount and after `reset()` the strip
+  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 `errored` output, 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 option list.
+  `dropdownTrigger` (`manual` / `hidden`) still gates the panel as before.
+
+**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 `(productSelect)` 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]`
+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.
+
+Swapping `[products]` for a different config (or `undefined`) clears the current
+cards; the strip repopulates on the *next* `/suggest` request rather than
+immediately, since the product search rides that one scheduler.
+
+Tier 2 gets the same thing: pass `products` / `onProductSelect` to the
+`AIAutocompleteController` and `<ai-autocomplete-dropdown>` renders the strip.
+Tier 3 consumers subscribe to `products$` and call
+`controller.selectProduct(product)` from their own cards.
+
 #### Custom submit button
 
 ```html
@@ -407,7 +515,7 @@ ac.destroy();
 
 #### Constructor options
 
-Accepts the same shape as `<ai-autocomplete>`'s inputs (`apiConfig`, `optionOverrides`, `columns`, `dropdownTrigger`, `optionsPosition`, `closeDropdownOnBlur`, `showNonTappableOptions`), plus event callbacks (`onSubmit`, `onError`, `onChange`, `onParamsChange`, `onFocus`, `onBlur`) and controlled-mode initial values (`value`, `completedParams`).
+Accepts the same shape as `<ai-autocomplete>`'s inputs (`apiConfig`, `optionOverrides`, `columns`, `dropdownTrigger`, `optionsPosition`, `closeDropdownOnBlur`, `showNonTappableOptions`, `products`), plus event callbacks (`onSubmit`, `onError`, `onChange`, `onParamsChange`, `onFocus`, `onBlur`, `onProductSelect`) and controlled-mode initial values (`value`, `completedParams`).
 
 #### State observables
 
@@ -415,10 +523,12 @@ Accepts the same shape as `<ai-autocomplete>`'s inputs (`apiConfig`, `optionOver
 |---|---|---|
 | `text$` | `Observable<string>` | Editor's plain-text content. |
 | `completedParams$` | `Observable<CompletedParamState[]>` | Bold completed params currently in the editor. |
+| `skippedParams$` | `Observable<SkippedParamState[]>` | Suggestions the user dismissed with <kbd>→</kbd>. Nothing renders them — pass them to `buildSubmitResult` for a hand-rolled submit. |
 | `suggestionPills$` | `Observable<Suggestion[]>` | Actionable suggestion pills (first item is the active pill). |
 | `segments$` | `Observable<Segment[]>` | Text + completed-param segments for rendering the editor body. |
 | `newParamId$` | `Observable<string \| null>` | ID of the most-recently-promoted param (drives shimmer animation). |
 | `suggestions$` | `Observable<Suggestion[]>` | All suggestions from the server (including non-actionable ones). |
+| `products$` | `Observable<Product[]>` | Results of the latest product search. Always empty unless `products` is configured — see [Product strip](#product-strip). |
 | `activeIndex$` | `Observable<number>` | Currently highlighted dropdown option index. `-1` = none. |
 | `isLoading$` | `Observable<boolean>` | UI-visible loading flag (suppressed during selection animation and re-edit). |
 | `isReady$` | `Observable<boolean>` | Server-reported "query is complete" flag. |
@@ -440,6 +550,7 @@ Every observable is gated by `distinctUntilChanged` + `shareReplay({ bufferSize:
 |---|---|
 | `reset()` | Clear all state, rotate `session_id`, and re-fetch. Call after submit. |
 | `selectOption(option)` | Pick a dropdown option (or replace the re-edited param if in re-edit mode). |
+| `selectProduct(product)` | Announce a product selection (fires `onProductSelect`). `<ai-autocomplete-dropdown>` calls this for you; hand-rolled strips call it themselves. Never navigates. |
 | `setActivePill(index)` | Promote the pill at `index` to active. |
 | `removeLastParam()` | Drop the last completed param's "completed" status. |
 | `clearNewParamId()` | Clear the shimmer-animation state. |
@@ -492,7 +603,7 @@ The dropdown component for Tier 2:
 | `mode` | `"light" \| "dark" \| "auto"` | — | Color mode for a **standalone** dropdown — self-scopes the SDK tokens so no `.magicx-aia` wrapper is needed. `"auto"` follows `prefers-color-scheme`. Leave unset when nested inside a `.magicx-aia` ancestor (e.g. Tier 1). |
 | `className` | `string` | — | Extra CSS class applied to the dropdown root. |
 
-Placement (`optionsPosition`) is read from the controller's options via `dropdown$` — set it once on the controller, not on the dropdown. All actions (option selection, hover, pill clicks) are forwarded to the controller — no outputs to wire.
+Placement (`optionsPosition`) is read from the controller's options via `dropdown$` — set it once on the controller, not on the dropdown. The [product strip](#product-strip) comes from there too: configure `products` on the controller and the dropdown renders the cards. All actions (option selection, hover, pill clicks, product activation) are forwarded to the controller — no outputs to wire.
 
 ### `AutocompleteResult`
 
@@ -500,7 +611,19 @@ Placement (`optionsPosition`) is read from the controller's options via `dropdow
 |---|---|---|
 | `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[]` | Filled parameter values. |
+| `completed_params` | `CompletedParam[]` | 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 }
+```
+
+Tier 2 consumers who build their own submit payload get the raw skips from the controller (`skippedParams$`, or `getState().skippedParams`) and can fold them in the same way with the exported `buildSubmitResult(text, completedParams, skippedParams)`.
+
+> **Reading `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. `buildSubmitResult` applies the rule for you; to apply it elsewhere (say, a "you skipped X" badge), use the exported `withSkippedParams(completedParams, skippedParams)`.
 
 ---
 
@@ -531,6 +654,21 @@ Override on the host element (via `class`). All defaults use `:where()` (zero sp
 | `--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. |
 | `--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 masked text in cached pills/options. |
 | `--aia-footer-chip-bg` | `--aia-surface` at 65% | `--aia-surface` at 65% | Fill behind the footer's keyboard hint and AI-Autocomplete badge. The option list scrolls under the footer, so this keeps both legible over the row passing behind them. `transparent` on the glass surface. |
 
@@ -558,7 +696,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; }`.