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

package/dist/index.d.ts

@@ -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 };