@magicx-eng/ai-autocomplete-vanilla 0.25.0 → 0.26.0

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

@@ -316,6 +316,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
@@ -851,6 +858,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
@@ -1589,11 +1606,14 @@ declare const PRODUCT_ROW_PX_PER_LINE = 32;
  *   row natively, and shift+wheel arrives as horizontal delta the same way. A
  *   diagonal that is mostly vertical is still a wheel turn;
  * - ctrl is held — that is a pinch zoom, not a scroll;
- * - the row has nothing to scroll;
- * - the turn is past either end. A row parked on its last card must not pin
- *   the page under a resting pointer, so the turn falls through and the page
- *   scrolls as it would anywhere else. `overscroll-behavior-x: contain` on the
- *   row still stops a native horizontal fling from chaining out mid-row.
+ * - the row has nothing to scroll.
+ *
+ * A turn past either end is still the row's: it returns the end the row is
+ * already at, so the binder keeps the page still rather than letting the turn
+ * chain out and scroll the page from under the dropdown. That mirrors
+ * `overscroll-behavior-x: contain` on the row, which stops a native horizontal
+ * fling from chaining out the same way. The page scrolls again the moment the
+ * pointer leaves the strip.
  *
  * Pure over the row's metrics so it can be tested without layout.
  */
@@ -1975,4 +1995,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

@@ -316,6 +316,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
@@ -851,6 +858,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
@@ -1589,11 +1606,14 @@ declare const PRODUCT_ROW_PX_PER_LINE = 32;
  *   row natively, and shift+wheel arrives as horizontal delta the same way. A
  *   diagonal that is mostly vertical is still a wheel turn;
  * - ctrl is held — that is a pinch zoom, not a scroll;
- * - the row has nothing to scroll;
- * - the turn is past either end. A row parked on its last card must not pin
- *   the page under a resting pointer, so the turn falls through and the page
- *   scrolls as it would anywhere else. `overscroll-behavior-x: contain` on the
- *   row still stops a native horizontal fling from chaining out mid-row.
+ * - the row has nothing to scroll.
+ *
+ * A turn past either end is still the row's: it returns the end the row is
+ * already at, so the binder keeps the page still rather than letting the turn
+ * chain out and scroll the page from under the dropdown. That mirrors
+ * `overscroll-behavior-x: contain` on the row, which stops a native horizontal
+ * fling from chaining out the same way. The page scrolls again the moment the
+ * pointer leaves the strip.
  *
  * Pure over the row's metrics so it can be tested without layout.
  */
@@ -1975,4 +1995,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 };