@magicx-eng/ai-autocomplete-vanilla 0.32.1 → 0.33.0

package/README.md

@@ -602,7 +602,7 @@ unsub();
 
 > **Option icons.** An option may carry an icon: `icon_svg` is inline SVG markup and `icon` its name. The built-in dropdown draws the SVG before the option's text, in the text color, and hides it while the row shows its loading skeleton. When rendering options yourself, pass `icon_svg` through the exported `sanitizeOptionIconSvg` before inserting it — it reduces the markup to plain vector drawing and returns `null` for anything else — and use `optionLabel(option)` for the text — it is the option's `text` alone; `icon` is the icon's name and is never shown as text, even when `icon_svg` is missing or fails to draw. A picked option's `icon` / `icon_svg` are copied onto its completed parameter, and the chip in the input draws the glyph before its text. Both surfaces can be switched off: `showOptionIcons: false` renders option rows as text only and `showChipIcons: false` renders chips as text only; either way the icon element is omitted rather than hidden.
 
-> **Option pictures and counts.** An option may also carry `image_url` — a picture of the best-matching catalog item offering it — and `item_count`, how many items offer it (each is present only when the server includes it; when it includes counts, the options also arrive ordered by them, most items first; a starting state carries pictures but no counts). The built-in dropdown draws the picture as a square thumbnail before the option's text (in place of its `icon_svg`, so a row never leads with two visuals) and the count as a muted label at the row's trailing edge (`"12 items"`); a skeleton row keeps the tile's placeholder fill and hides the count. The unit word after the number is a token: set `--aia-option-count-unit: "sneakers"` to name what is being counted, `--aia-option-count-unit-one: "sneaker"` for a count of 1 (it falls back to the plural token), or `--aia-option-count-unit: ""` for the number alone. When rendering options yourself, pass `image_url` through the exported `optionImageSrc` before using it as an `<img src>` — it returns the URL only when it is `http(s)` and `null` otherwise — and `formatOptionCount(option.item_count)` gives the number the built-in rows print (`null` when there is no count); `optionCountLabel(count, unit?)` appends a unit for a dropdown that prints the word itself (`"item"` / `"items"` by default; one word, a `{ one, other }` pair, or `""` for none). Both surfaces can be switched off: `showOptionImages: false` renders rows without pictures (an option's icon then draws instead) and `showOptionCounts: false` hides the counts. A picked option's `image_url` is copied onto its completed parameter too, and the chip in the input draws it as a small rounded tile before its text, in place of the icon; `showChipImages: false` renders chips without pictures (the icon then draws instead). The tile is sized by `--aia-option-image-size` (40px), rounded by `--aia-option-image-radius` (12px), spaced by `--aia-option-image-gap` (12px) and filled by `--aia-option-image-bg` (default: `--aia-skeleton-bg`) while its picture loads; the count reads `--aia-option-count-font-size` (12px), `--aia-option-count-color` and `--aia-option-count-opacity` (0.6); the chip's tile reads `--aia-chip-image-size` (1.25em of the chip's font), `--aia-chip-image-radius` (4px) and `--aia-chip-image-bg` (default: `--aia-skeleton-bg`).
+> **Option pictures and counts.** An option may also carry `image_url` — a picture of the best-matching catalog item offering it — and `item_count`, how many items offer it (each is present only when the server includes it; when it includes counts, the options also arrive ordered by them, most items first; a starting state carries pictures but no counts). The built-in dropdown draws the picture as a square thumbnail before the option's text (in place of its `icon_svg`, so a row never leads with two visuals) and the count as a muted label at the row's trailing edge (`"12 items"`); a skeleton row keeps the tile's placeholder fill and hides the count. The unit word after the number is a token: set `--aia-option-count-unit: "sneakers"` to name what is being counted, `--aia-option-count-unit-one: "sneaker"` for a count of 1 (it falls back to the plural token), or `--aia-option-count-unit: ""` for the number alone. When rendering options yourself, pass `image_url` through the exported `optionImageSrc` before using it as an `<img src>` — it returns the URL only when it is `http(s)` and `null` otherwise — and `formatOptionCount(option.item_count)` gives the number the built-in rows print (`null` when there is no count); `optionCountLabel(count, unit?)` appends a unit for a dropdown that prints the word itself (`"item"` / `"items"` by default; one word, a `{ one, other }` pair, or `""` for none). Both surfaces can be switched off: `showOptionImages: false` renders rows without pictures (an option's icon then draws instead) and `showOptionCounts: false` hides the counts. A picked option's `image_url` is copied onto its completed parameter too, and the chip in the input draws it as a small rounded tile before its text, in place of the icon; `showChipImages: false` renders chips without pictures (the icon then draws instead). The tile is sized by `--aia-option-image-size` (40px), rounded by `--aia-option-image-radius` (12px), spaced by `--aia-option-image-gap` (12px) and filled by `--aia-option-image-bg` (default: `--aia-skeleton-bg`) while its picture loads; in a grid with pictures, an icon row draws its glyph at `--aia-option-tile-icon-size` (1.5em) so it holds the picture column; the count reads `--aia-option-count-font-size` (12px), `--aia-option-count-color` and `--aia-option-count-opacity` (0.6); the chip's tile reads `--aia-chip-image-size` (1.25em of the chip's font), `--aia-chip-image-radius` (4px) and `--aia-chip-image-bg` (default: `--aia-skeleton-bg`).
 
 ### State shape (`CoreState`)
 
@@ -647,6 +647,7 @@ unsub();
 | `removeLastParam()` | Remove the last completed param from state. The text stays in the input as plain text. |
 | `clearNewParamId()` | Clear shimmer animation state. |
 | `reset()` | Clear all state, re-fetch initial suggestions, and start a new session (rotates `session_id`). Call this after handling submit. |
+| `recordSubmit(result)` | Record a submit from a button you render. Enter and the built-in button are recorded for you; call this once per submit from your own button. |
 | `setValue(text)` | Set text (controlled mode). |
 | `setCompletedParams(params)` | Set completed params (controlled mode). |
 | `setMode(mode)` | Switch color mode at runtime. |
@@ -982,6 +983,12 @@ const ac = new AIAutocomplete(container, {
 });
 ```
 
+### Visitor id and submits
+
+Pass `visitorId` to tie searches to what the same visitor does later: a UUID v4 you keep across page loads (for example a first-party cookie), or a function that returns one. A function is called only when the id is needed, so it is safe to create the id lazily inside it.
+
+Submits from Enter and from the built-in submit button are recorded for you. If you render your own submit button (Tier 2 or 3), call `recordSubmit(result)` from it, once per submit, with the result you pass to your own submit handler.
+
 ## Option Overrides
 
 Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `type` and is a function of the phrase the user has typed for that parameter:

package/dist/index.d.mts

@@ -109,6 +109,8 @@ interface AutocompleteResponse {
     meta: {
         request_id: string;
         request_at: string;
+        /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
+        funnel_telemetry?: boolean;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -880,6 +882,16 @@ interface CoreOptions {
      * parameters and options to them.
      */
     additionalContext?: Record<string, unknown>;
+    /**
+     * Stable id for this visitor, kept by the host across page loads (e.g. a
+     * first-party cookie). Rides on funnel telemetry so searches can be joined
+     * to what the visitor does afterwards. Must be a UUID v4; omit to send none.
+     *
+     * A function is called only once the server has switched funnel telemetry
+     * on, so a host that creates the id lazily (sets a cookie) creates nothing
+     * while it is off.
+     */
+    visitorId?: string | (() => string | undefined);
     columns?: number;
     /** Where pills render in "full" mode. Default: "dropdown". Ignored in "dropdown" mode (always in dropdown). */
     pillPlacement?: "inline" | "dropdown" | "hidden";
@@ -1064,6 +1076,19 @@ declare class AIAutocomplete {
     private subscriberCount;
     private emitter;
     private sessionId;
+    /** The /suggest request whose response is on screen; telemetry echoes it. */
+    private lastRequestId;
+    /** Session that already sent `search_started`, so it fires once per session. */
+    private searchStartedSessionId;
+    /**
+     * The server's funnel-telemetry switch, from the latest response's meta.
+     * `null` until a response says; no funnel event goes out before that.
+     */
+    private funnelTelemetry;
+    /** A `search_started` that happened before any response said whether to send it. */
+    private pendingSearchStarted;
+    /** What the last `impression` showed, so an identical response doesn't resend it. */
+    private lastImpressionKey;
     private readonly emitSubmit;
     private readonly emitError;
     constructor(container: HTMLElement, opts?: CoreOptions);
@@ -1174,6 +1199,12 @@ declare class AIAutocomplete {
      * highlight the keyboard has since moved elsewhere is left alone.
      */
     clearHighlight(index: number): void;
+    /**
+     * Records a submit in telemetry. The SDK does this itself when it runs the
+     * submit (Enter, or Tier 1's button); call it only from a submit path you
+     * own — a button you render — so each submit is counted once.
+     */
+    recordSubmit(result: AutocompleteResult): void;
     /**
      * Announce a product selection. The rendered cards call this on activation;
      * headless consumers rendering their own strip call it themselves.
@@ -1252,7 +1283,13 @@ declare class AIAutocomplete {
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
+    private resolveVisitorId;
     private resolveSource;
+    /**
+     * Records what a response put on screen: pills and their options in display
+     * order, and the product cards. Positions are 1-based array order.
+     */
+    private fireImpression;
     private fireTelemetry;
     private setupContainer;
     private buildAndRenderFull;

package/dist/index.d.ts

@@ -109,6 +109,8 @@ interface AutocompleteResponse {
     meta: {
         request_id: string;
         request_at: string;
+        /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
+        funnel_telemetry?: boolean;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -880,6 +882,16 @@ interface CoreOptions {
      * parameters and options to them.
      */
     additionalContext?: Record<string, unknown>;
+    /**
+     * Stable id for this visitor, kept by the host across page loads (e.g. a
+     * first-party cookie). Rides on funnel telemetry so searches can be joined
+     * to what the visitor does afterwards. Must be a UUID v4; omit to send none.
+     *
+     * A function is called only once the server has switched funnel telemetry
+     * on, so a host that creates the id lazily (sets a cookie) creates nothing
+     * while it is off.
+     */
+    visitorId?: string | (() => string | undefined);
     columns?: number;
     /** Where pills render in "full" mode. Default: "dropdown". Ignored in "dropdown" mode (always in dropdown). */
     pillPlacement?: "inline" | "dropdown" | "hidden";
@@ -1064,6 +1076,19 @@ declare class AIAutocomplete {
     private subscriberCount;
     private emitter;
     private sessionId;
+    /** The /suggest request whose response is on screen; telemetry echoes it. */
+    private lastRequestId;
+    /** Session that already sent `search_started`, so it fires once per session. */
+    private searchStartedSessionId;
+    /**
+     * The server's funnel-telemetry switch, from the latest response's meta.
+     * `null` until a response says; no funnel event goes out before that.
+     */
+    private funnelTelemetry;
+    /** A `search_started` that happened before any response said whether to send it. */
+    private pendingSearchStarted;
+    /** What the last `impression` showed, so an identical response doesn't resend it. */
+    private lastImpressionKey;
     private readonly emitSubmit;
     private readonly emitError;
     constructor(container: HTMLElement, opts?: CoreOptions);
@@ -1174,6 +1199,12 @@ declare class AIAutocomplete {
      * highlight the keyboard has since moved elsewhere is left alone.
      */
     clearHighlight(index: number): void;
+    /**
+     * Records a submit in telemetry. The SDK does this itself when it runs the
+     * submit (Enter, or Tier 1's button); call it only from a submit path you
+     * own — a button you render — so each submit is counted once.
+     */
+    recordSubmit(result: AutocompleteResult): void;
     /**
      * Announce a product selection. The rendered cards call this on activation;
      * headless consumers rendering their own strip call it themselves.
@@ -1252,7 +1283,13 @@ declare class AIAutocomplete {
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
+    private resolveVisitorId;
     private resolveSource;
+    /**
+     * Records what a response put on screen: pills and their options in display
+     * order, and the product cards. Positions are 1-based array order.
+     */
+    private fireImpression;
     private fireTelemetry;
     private setupContainer;
     private buildAndRenderFull;