@magicx-eng/ai-autocomplete-vanilla 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -147,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;
@@ -188,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;
@@ -289,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;
@@ -298,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[];
     /**
@@ -318,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;
@@ -328,6 +410,7 @@ declare class AIAutocomplete {
     private fetchController;
     private keyboardController;
     private pillsController;
+    private productsController;
     private reEdit;
     private modeController;
     private container;
@@ -336,6 +419,12 @@ declare class AIAutocomplete {
     private domRefs;
     private dropdownRefs;
     private timers;
+    /** One per instance — see {@link ConsumerBoundary}. Shared by the emitter, `subscribe()` and `optionOverrides`. */
+    private boundary;
+    /** Identity of the raw override record the wrapped copy below was built from. */
+    private rawOverrides;
+    private wrappedOverrides;
+    private subscriberCount;
     private emitter;
     private sessionId;
     private readonly emitSubmit;
@@ -351,15 +440,54 @@ declare class AIAutocomplete {
     setActivePill(index: number): void;
     removeLastParam(): void;
     /**
-     * Backspace inside a completed param: drop the param's "completed" status so
-     * it renders as plain (un-bold) text, AND remove one grapheme before the
-     * caret — same single-character delete a normal Backspace would do. The
-     * remaining text stays in the input so the user can continue editing what
-     * they had typed instead of losing the whole phrase.
+     * Locate the chip whose rendered text covers `offset`.
+     *
+     * Walks the derived `segments` — the exact thing the editor renders — rather
+     * than re-deriving param positions here. That keeps chip hit-testing in step
+     * with `deriveSegments` by construction (including params whose text repeats
+     * earlier in the input, and identified params that had to dodge completed
+     * coverage) instead of hand-mirroring its walk in a third place.
+     *
+     * Both chip kinds are returned: completed and identified render as visually
+     * identical chips, so both must behave atomically under Backspace. Re-edit
+     * remains completed-only — see `startEditingParamAtCaret`.
+     */
+    private findChipSpanAt;
+    /** Drop a located chip from whichever param array owns it. */
+    private withoutChip;
+    /**
+     * Backspace at the caret. A chip is atomic: the caret sits beside it, never
+     * within it, so the two positions mean different things.
+     *
+     * - Caret exactly at the chip's trailing edge (the position a Backspace over
+     *   the following space leaves you in): delete the WHOLE chip, the way a
+     *   chip-style token behaves. Collapses the space seam it leaves behind so
+     *   the surrounding words don't end up double-spaced.
+     * - Caret strictly inside the chip (only reachable by clicking into it):
+     *   drop the param so its text renders plain, and remove one grapheme — the
+     *   user keeps the phrase they had and can edit it by hand.
+     *
+     * Applies to both chip kinds. Completed and identified params render
+     * identically, so they must delete identically; only the array the param is
+     * dropped from differs.
      *
      * Returns true when a param was reconciled (caller should `preventDefault`).
      */
     removeParamAtCaret(offset: number): boolean;
+    /**
+     * ArrowLeft while the caret sits at a completed pill's trailing edge selects
+     * the pill rather than moving the caret into it: re-edit turns on, the pill
+     * renders highlighted, and the dropdown shows its cached options. The caret
+     * stays put at the trailing edge — it never enters the pill.
+     *
+     * Identified chips are excluded: they carry no cached options and are
+     * deliberately not re-editable (see `renderEditable`), even though Backspace
+     * treats them atomically like any other chip.
+     *
+     * Returns true when re-edit started (caller should `preventDefault` so the
+     * browser doesn't step the caret inside the `<strong>`).
+     */
+    startEditingParamAtCaret(offset: number): boolean;
     /**
      * Set the editor caret at the given plain-text offset. Uses the core's own
      * `domRefs.input` in "full" mode; falls back to the wrapper-provided
@@ -378,10 +506,25 @@ 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;
-    /** Subscribe to state changes. Listener receives the full (input + derived) shape. */
+    /**
+     * Subscribe to state changes. Listener receives the full (input + derived) shape.
+     *
+     * Consumer code, so it gets the same isolation as the `on*` events: a throw
+     * is contained and reported rather than unwinding into the `store.set` that
+     * triggered the notification. See {@link ConsumerBoundary}.
+     */
     subscribe(listener: (state: CoreState) => void): () => void;
     getState(): CoreState;
     get listboxId(): string;
@@ -399,6 +542,24 @@ declare class AIAutocomplete {
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
     private fireTelemetry;
+    /**
+     * `this.opts` with every `optionOverrides` entry wrapped in the instance's
+     * {@link ConsumerBoundary}.
+     *
+     * The derive layer calls these functions on the SDK's stack — from
+     * `getState()`, and from inside the store's notification drain — so an
+     * un-wrapped throw would unwind whatever internal operation triggered the
+     * derive and abort delivery of every queued notification with it, taking the
+     * instance down rather than just the override. Wrapped, a failed override
+     * answers `undefined` and each call site falls back to the server's options.
+     *
+     * Memoized on the raw record's identity so a swapped integration is
+     * re-wrapped while a stable one isn't re-wrapped on every derive. Note
+     * `update({ optionOverrides })` only becomes visible on the next store write
+     * — the derived layer memoizes on inputs identity, and `update` doesn't
+     * invalidate it for this key. Pre-existing, and unchanged by the wrapping.
+     */
+    private deriveOpts;
     private setupContainer;
     private buildAndRenderFull;
     private buildAndRenderDropdown;
@@ -603,4 +764,4 @@ declare function withSkippedParams(completed: CompletedParam[], skipped: Skipped
  */
 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 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 };
+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 };