@magicx-eng/ai-autocomplete-vanilla 0.20.2 → 0.22.0

package/dist/index.d.ts

@@ -74,12 +74,93 @@ interface AutocompleteResponse {
         input: InputItem[];
         suggestions: Suggestion[];
         is_ready?: boolean;
+        /**
+         * What catalog grounding did for this request. Absent whenever no
+         * catalog was read — see {@link CustomFieldsReport}.
+         */
+        custom_fields?: CustomFieldsReport;
     };
     meta: {
         request_id: string;
         request_at: string;
     };
 }
+/** Comparison an {@link ExpressedFilter} applies to its value. */
+type FilterOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
+/**
+ * One constraint the server read out of the query — a parameter, a value and
+ * how the two compare ("price", "100", "lt").
+ */
+interface ExpressedFilter {
+    param: string;
+    value: string;
+    op: FilterOp;
+}
+/**
+ * One catalog item the query narrowed down to, in the shape needed to render
+ * it. Only `source_id` and `title` are always present.
+ */
+interface MatchedItem {
+    /** Stable identity of the item within the catalog. */
+    source_id: string;
+    /** The item's id in the platform it was imported from, when it has one. */
+    origin_id?: string;
+    title: string;
+    /**
+     * The item's lowest price, verbatim as the catalog spells it ("131.00").
+     * Not formatted for display: the currency is the storefront's to add.
+     */
+    price?: string;
+    vendor?: string;
+    /**
+     * The platform's URL slug for the item, not a URL. The SDK builds a relative
+     * `/products/{handle}` link from it for the product strip, which is right for
+     * a widget running on the storefront itself.
+     */
+    handle?: string;
+    image_url?: string;
+}
+/** The items the applied filters left standing. */
+interface MatchedItems {
+    /**
+     * How many items the query narrowed the catalog to — `matched.length` at
+     * most, and larger when the list was capped. Also counts what the query's own
+     * words matched, so it drops as a typed word starts matching a title.
+     */
+    total: number;
+    /**
+     * The items themselves, capped by the server. Empty with a non-zero `total`
+     * when nothing narrowed the catalog: naming arbitrary items as matches would
+     * be worse than naming none.
+     */
+    matched: MatchedItem[];
+}
+/**
+ * What catalog grounding did for a request, as opposed to what it decided to
+ * ask next.
+ *
+ * Absent from a response whenever no catalog was read: a product with no
+ * catalog, a starting-state response, or a request whose suggestions offer no
+ * option-bearing parameter. Treat absence as "no news", not as an empty
+ * catalog.
+ *
+ * `applied_filters` and `dropped_filters` are what make `items` interpretable:
+ * the items answer the applied set, so without the dropped one "87 black
+ * t-shirts" and "no black item, so here are t-shirts" look identical. Both
+ * lists are always present, so a consumer reads `[]` rather than guarding a
+ * null.
+ */
+interface CustomFieldsReport {
+    /** Constraints the catalog read actually ran under. */
+    applied_filters: ExpressedFilter[];
+    /**
+     * Constraints the query expressed that the catalog could not answer — a
+     * parameter it does not have, a bound that is not a number, or a value no
+     * item carries. `items` were narrowed without them.
+     */
+    dropped_filters: ExpressedFilter[];
+    items: MatchedItems;
+}
 interface CompletedParamState extends CompletedParam {
     id: string;
     text: string;
@@ -205,19 +286,24 @@ type OptionOverrides = Record<string, OptionOverride>;
 /**
  * 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.
+ * Platform-agnostic on purpose: the server's matched items (the default
+ * source) and every custom integration (Shopify search today, others later)
+ * map onto exactly these fields, so the SDK renders one strip regardless of
+ * where the results came from. Only `id` and `title` 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 source 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;
+    /**
+     * Destination for the card's `href`. Absent, the card has no link — it is
+     * still activatable and still emits `onProductSelect`, but cmd-click and
+     * "copy link address" have nothing to open. Selection never navigates; 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. */
@@ -225,9 +311,13 @@ interface Product {
     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.
+ * Custom product-search wiring for the strip. Absent (the default), the strip
+ * shows the items the `/suggest` response itself reports as matching the query
+ * (`custom_fields.items`), with no extra request. Set it to source the cards
+ * from your own search instead: the server's items are then never rendered
+ * (they stay readable on `customFields`), and the SDK fetches through this
+ * config on its own cadence. To render no strip at all, set `showProducts`
+ * to false.
  */
 interface ProductsConfig {
     /**
@@ -289,6 +379,12 @@ interface AutocompleteResult {
     identified_params: IdentifiedParam[];
     /** Whether the server considers the query complete enough to act on. */
     is_ready: boolean;
+    /**
+     * What catalog grounding did for the latest applied response — the filters
+     * it applied and dropped, and the items they left standing. Present only
+     * when that response carried the block; see {@link CustomFieldsReport}.
+     */
+    custom_fields?: CustomFieldsReport;
 }
 
 /** A calendar month on screen. `month` is 0-based, matching `Date#getMonth`. */
@@ -458,12 +554,26 @@ interface CoreInputState {
     } | 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.
+     * What the product strip shows. By default the items the latest `/suggest`
+     * response reported as matching the query (`custom_fields.items.matched`,
+     * mapped onto `Product`), replaced on every response and empty when the
+     * response carried none — so the strip never shows items belonging to an
+     * older query. With `opts.products` configured, the results of the latest
+     * custom search instead, already transformed and capped by its `limit`,
+     * cleared on an empty query and on a failed fetch/transform. Always empty
+     * while `opts.showProducts` is false.
      */
     products: Product[];
+    /**
+     * The catalog grounding report the latest applied response carried, or null
+     * when it carried none. Replaced wholesale per response, so it always
+     * describes the suggestions on screen: which of the query's constraints the
+     * catalog applied, which it had to drop, and how many items (and which) the
+     * applied ones left standing. Null is "no news", not an empty catalog — a
+     * response reads no catalog when it has no option-bearing parameter to
+     * offer. See {@link CustomFieldsReport}.
+     */
+    customFields: CustomFieldsReport | null;
     /**
      * The consumer's {@link OptionSource} request for the pill on screen — the
      * active suggestion, or the completed param being re-edited. `type` is the
@@ -724,10 +834,23 @@ interface CoreOptions {
      */
     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.
+     * When true (default), the dropdown renders a horizontal row of product
+     * cards below the options grid whenever it has products to show: by default
+     * the items the `/suggest` response reports as matching the query, or the
+     * results of a custom `products` search. Set to false to render no strip and
+     * run no custom search; `customFields` stays readable either way.
+     *
+     * Turning it back on restores the server's items at once — they are already
+     * in the store — while a custom `products` config repopulates on the next
+     * request, since its search rides the suggest cadence.
+     */
+    showProducts?: boolean;
+    /**
+     * Custom source for the product strip. Omit it and the strip shows the items
+     * the `/suggest` response itself reports (`custom_fields.items`), with no
+     * extra request. Set it and the dropdown is fed by your own search endpoint
+     * on the SDK's existing fetch cadence instead; the server's items are then
+     * not rendered.
      */
     products?: ProductsConfig;
     /** Called when the user submits (Enter, or the submit button in Tier 1). */
@@ -1669,6 +1792,31 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
  */
 declare function toWireIdentifiedParams(params: IdentifiedParamState[]): IdentifiedParam[];
 
+/**
+ * Where the product strip links a server-matched item to. The server ships a
+ * bare `handle` on purpose: the only shop domain it holds is the internal one,
+ * and an absolute link built from it would send a shopper off the storefront
+ * the widget is running on. A relative path resolves against the page the
+ * widget is on, which for a storefront embed is the shop itself.
+ */
+declare const PRODUCT_PATH_PREFIX = "/products/";
+/**
+ * Maps one item the `/suggest` response reported onto the strip's `Product`
+ * shape. Pure, so a Tier 3 consumer rendering its own strip from
+ * `customFields` gets the same cards the built-in one draws.
+ *
+ * An item without a `handle` yields a card without a `url`: still activatable,
+ * still emitting `onProductSelect`, just nothing for cmd-click to open.
+ */
+declare function productFromMatchedItem(item: MatchedItem): Product;
+/**
+ * The strip's contents for a response's catalog report. `null` — no block on
+ * the response — is an empty strip rather than "keep the previous one": the
+ * previous items answered a previous query, and a strip must never show
+ * results belonging to an older one.
+ */
+declare function productsFromCustomFields(report: CustomFieldsReport | null | undefined): Product[];
+
 declare class ModeController {
     private container;
     private mode;
@@ -1730,6 +1878,13 @@ interface SubmitResultExtras {
     identifiedParams?: IdentifiedParamState[];
     /** Server's "query is complete" verdict (`state.isReady`). Default: false. */
     isReady?: boolean;
+    /**
+     * The catalog grounding report the latest response carried
+     * (`state.customFields`). Default: none, and the result then has no
+     * `custom_fields` key at all — mirroring the wire, where the block is absent
+     * rather than null when no catalog was read.
+     */
+    customFields?: CustomFieldsReport | null;
 }
 /**
  * Builds the `AutocompleteResult` handed to `onSubmit` and `onResult`: the
@@ -1743,4 +1898,4 @@ interface SubmitResultExtras {
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[], extras?: SubmitResultExtras): 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, DATE_RANGE_META_END, DATE_RANGE_META_START, type DateMonthView, type DateRange, type DateSelection, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, type Product, type ProductsConfig, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionEnterDelayMs, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, 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 CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, PRODUCT_PATH_PREFIX, type Product, type ProductsConfig, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, computeOptionsGridLayout, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionEnterDelayMs, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };