@magicx-eng/ai-autocomplete-vanilla 0.25.1 → 0.26.1

package/README.md

@@ -103,6 +103,9 @@ const ac = new AIAutocomplete(container, {
   // Product strip. Shown by default from the items the /suggest response
   // reports; false renders no strip.
   showProducts: true,
+  // How the strip lays its cards out: a scrolling row, or "list" — the same
+  // cards stacked as full-width rows.
+  productsLayout: "row",
   // Custom source for the strip. Omit it and the server's items are shown.
   products: {
     fetch: (query, signal) => myPlatform.search(query, { signal }),
@@ -189,6 +192,15 @@ exported for a hand-rolled strip that wants the same mapping.
 Set `showProducts: false` to render no strip at all. The catalog report
 (below) stays readable either way.
 
+`productsLayout: "list"` stacks the same cards as full-width rows — thumbnail
+on the left, title, vendor and price on the right — for results that read as
+a list (courses, listings, documents) rather than products on a shelf. The
+column scrolls vertically inside `--aia-product-list-max-height` (320px by
+default); `--aia-product-list-media-size` (44px) sizes the thumbnail and
+`--aia-product-list-gap` (2px) the space between rows. `"row"`, the default,
+is the horizontal strip. `update({ productsLayout })` re-lays the strip out at
+once.
+
 #### The catalog report (`customFields`)
 
 Every response that read the catalog also says what it did with the query, and

package/dist/index.d.mts

@@ -65,6 +65,7 @@ interface AutocompleteRequest {
         language: string;
         client_version: string;
         session_id: string;
+        source?: "full-sdk" | "headless-sdk";
     };
 }
 interface AutocompleteResponse {
@@ -316,6 +317,13 @@ interface Product {
     price?: string;
     vendor?: string;
 }
+/**
+ * How the product strip lays its cards out. `"row"` is the horizontally
+ * scrolling shelf; `"list"` stacks the same cards as full-width rows —
+ * thumbnail on the left, text on the right — for results that read as a list
+ * (courses, listings, documents) rather than products on a shelf.
+ */
+type ProductsLayout = "row" | "list";
 /**
  * Custom product-search wiring for the strip. Absent (the default), the strip
  * shows the items the `/suggest` response itself reports as matching the query
@@ -825,9 +833,10 @@ interface CoreOptions {
      */
     styleRoot?: Document | ShadowRoot;
     /**
-     * Identifies which SDK surface is in use, for telemetry only. The hook can't
-     * distinguish on its own — the Tier 1 component sets "full-sdk" when wiring
-     * it up. Default: "headless-sdk".
+     * Identifies which SDK surface is in use — sent as meta.source on both
+     * /api/suggest and telemetry events. The hook can't distinguish on its own
+     * — the Tier 1 component sets "full-sdk" when wiring it up. Default:
+     * "headless-sdk".
      * @internal
      */
     source?: "full-sdk" | "headless-sdk";
@@ -851,6 +860,16 @@ interface CoreOptions {
      * request, since its search rides the suggest cadence.
      */
     showProducts?: boolean;
+    /**
+     * How the product strip lays its cards out. `"row"` (the default) is a
+     * horizontally scrolling shelf of cards. `"list"` stacks the same cards as
+     * full-width rows — thumbnail on the left, title, vendor and price on the
+     * right — for results that read as a list (courses, listings, documents)
+     * rather than products on a shelf; the column scrolls vertically inside
+     * `--aia-product-list-max-height`. Changing it through `update()` re-lays
+     * the strip out at once.
+     */
+    productsLayout?: ProductsLayout;
     /**
      * Custom source for the product strip. Omit it and the strip shows the items
      * the `/suggest` response itself reports (`custom_fields.items`), with no
@@ -1117,6 +1136,7 @@ declare class AIAutocomplete {
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
+    private resolveSource;
     private fireTelemetry;
     private setupContainer;
     private buildAndRenderFull;
@@ -1978,4 +1998,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, 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, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductRowMetrics, type ProductRowWheel, 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, attachProductRowWheel, 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, productRowWheelTarget, productsFromCustomFields, 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, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, 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, attachProductRowWheel, 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, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };

package/dist/index.d.ts

@@ -65,6 +65,7 @@ interface AutocompleteRequest {
         language: string;
         client_version: string;
         session_id: string;
+        source?: "full-sdk" | "headless-sdk";
     };
 }
 interface AutocompleteResponse {
@@ -316,6 +317,13 @@ interface Product {
     price?: string;
     vendor?: string;
 }
+/**
+ * How the product strip lays its cards out. `"row"` is the horizontally
+ * scrolling shelf; `"list"` stacks the same cards as full-width rows —
+ * thumbnail on the left, text on the right — for results that read as a list
+ * (courses, listings, documents) rather than products on a shelf.
+ */
+type ProductsLayout = "row" | "list";
 /**
  * Custom product-search wiring for the strip. Absent (the default), the strip
  * shows the items the `/suggest` response itself reports as matching the query
@@ -825,9 +833,10 @@ interface CoreOptions {
      */
     styleRoot?: Document | ShadowRoot;
     /**
-     * Identifies which SDK surface is in use, for telemetry only. The hook can't
-     * distinguish on its own — the Tier 1 component sets "full-sdk" when wiring
-     * it up. Default: "headless-sdk".
+     * Identifies which SDK surface is in use — sent as meta.source on both
+     * /api/suggest and telemetry events. The hook can't distinguish on its own
+     * — the Tier 1 component sets "full-sdk" when wiring it up. Default:
+     * "headless-sdk".
      * @internal
      */
     source?: "full-sdk" | "headless-sdk";
@@ -851,6 +860,16 @@ interface CoreOptions {
      * request, since its search rides the suggest cadence.
      */
     showProducts?: boolean;
+    /**
+     * How the product strip lays its cards out. `"row"` (the default) is a
+     * horizontally scrolling shelf of cards. `"list"` stacks the same cards as
+     * full-width rows — thumbnail on the left, title, vendor and price on the
+     * right — for results that read as a list (courses, listings, documents)
+     * rather than products on a shelf; the column scrolls vertically inside
+     * `--aia-product-list-max-height`. Changing it through `update()` re-lays
+     * the strip out at once.
+     */
+    productsLayout?: ProductsLayout;
     /**
      * Custom source for the product strip. Omit it and the strip shows the items
      * the `/suggest` response itself reports (`custom_fields.items`), with no
@@ -1117,6 +1136,7 @@ declare class AIAutocomplete {
     update(opts: CoreUpdateOptions): void;
     selectOption(option: SuggestionOption): void;
     private startSelectionAnimationTimer;
+    private resolveSource;
     private fireTelemetry;
     private setupContainer;
     private buildAndRenderFull;
@@ -1978,4 +1998,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, 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, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductRowMetrics, type ProductRowWheel, 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, attachProductRowWheel, 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, productRowWheelTarget, productsFromCustomFields, 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, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, 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, attachProductRowWheel, 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, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };