@magicx-eng/ai-autocomplete-vanilla 0.49.4 → 0.50.0

package/README.md

@@ -642,7 +642,7 @@ unsub();
 
 > **Option icons.** An option may carry an icon: `icon_svg` is inline SVG markup and `icon` its name. The built-in dropdown draws the SVG before the option's text, in the text color, and hides it while the row shows its loading skeleton. When rendering options yourself, pass `icon_svg` through the exported `sanitizeOptionIconSvg` before inserting it — it reduces the markup to plain vector drawing and returns `null` for anything else — and use `optionLabel(option)` for the text — it is the option's `text` alone; `icon` is the icon's name and is never shown as text, even when `icon_svg` is missing or fails to draw. A picked option's `icon` / `icon_svg` are copied onto its completed parameter, and the chip in the input draws the glyph before its text. Both surfaces can be switched off: `showOptionIcons: false` renders option rows as text only and `showChipIcons: false` renders chips as text only; either way the icon element is omitted rather than hidden.
 
-> **Option pictures and counts.** An option may also carry `image_url` — a picture of the best-matching catalog item offering it — and `item_count`, how many items offer it (each is present only when the server includes it; when it includes counts, the options also arrive ordered by them, most items first; a starting state carries pictures but no counts). The built-in dropdown draws the picture as a square thumbnail before the option's text (in place of its `icon_svg`, so a row never leads with two visuals) and the count as a muted label at the row's trailing edge (`"12 items"`); a skeleton row keeps the tile's placeholder fill and hides the count. The unit word after the number is a token: set `--aia-option-count-unit: "sneakers"` to name what is being counted, `--aia-option-count-unit-one: "sneaker"` for a count of 1 (it falls back to the plural token), or `--aia-option-count-unit: ""` for the number alone. When rendering options yourself, pass `image_url` through the exported `optionImageSrc` before using it as an `<img src>` — it returns the URL only when it is `http(s)` and `null` otherwise — and `formatOptionCount(option.item_count)` gives the number the built-in rows print (`null` when there is no count); `optionCountLabel(count, unit?)` appends a unit for a dropdown that prints the word itself (`"item"` / `"items"` by default; one word, a `{ one, other }` pair, or `""` for none). Both surfaces can be switched off: `showOptionImages: false` renders rows without pictures (an option's icon then draws instead) and `showOptionCounts: false` hides the counts. A picked option's `image_url` is copied onto its completed parameter too, and the chip in the input draws it as a small rounded tile before its text, in place of the icon; `showChipImages: false` renders chips without pictures (the icon then draws instead). The tile is sized by `--aia-option-image-size` (40px), rounded by `--aia-option-image-radius` (12px), spaced by `--aia-option-image-gap` (12px) and filled by `--aia-option-image-bg` (default: `--aia-skeleton-bg`) while its picture loads; in a grid with pictures, an icon row draws its glyph at `--aia-option-tile-icon-size` (1.5em) so it holds the picture column; the count reads `--aia-option-count-font-size` (12px), `--aia-option-count-color` and `--aia-option-count-opacity` (0.6); the chip's tile reads `--aia-chip-image-size` (1.25em of the chip's font), `--aia-chip-image-radius` (4px) and `--aia-chip-image-bg` (default: `--aia-skeleton-bg`).
+> **Option pictures and counts.** An option may also carry `image_url` — a picture of the best-matching catalog item offering it — and `item_count`, how many items offer it (each is present only when the server includes it; when it includes counts, the options also arrive ordered by them, most items first; a starting state carries pictures but no counts). The built-in dropdown draws the picture as a square thumbnail before the option's text (in place of its `icon_svg`, so a row never leads with two visuals) and the count as a muted label at the row's trailing edge (`"12 items"`); a skeleton row keeps the tile's placeholder fill and hides the count. Icons and pictures are all-or-nothing per list: if any tappable option would draw neither, no row draws one, so a list never mixes rows with and without a leading visual (non-tappable rows don't count). A custom dropdown can apply the same rule with the exported `optionsShowLeadingVisuals(options, showIcons, showImages)`. The unit word after the number is a token: set `--aia-option-count-unit: "sneakers"` to name what is being counted, `--aia-option-count-unit-one: "sneaker"` for a count of 1 (it falls back to the plural token), or `--aia-option-count-unit: ""` for the number alone. When rendering options yourself, pass `image_url` through the exported `optionImageSrc` before using it as an `<img src>` — it returns the URL only when it is `http(s)` and `null` otherwise — and `formatOptionCount(option.item_count)` gives the number the built-in rows print (`null` when there is no count); `optionCountLabel(count, unit?)` appends a unit for a dropdown that prints the word itself (`"item"` / `"items"` by default; one word, a `{ one, other }` pair, or `""` for none). Both surfaces can be switched off: `showOptionImages: false` renders rows without pictures (an option's icon then draws instead) and `showOptionCounts: false` hides the counts. A picked option's `image_url` is copied onto its completed parameter too, and the chip in the input draws it as a small rounded tile before its text, in place of the icon; `showChipImages: false` renders chips without pictures (the icon then draws instead). The tile is sized by `--aia-option-image-size` (40px), rounded by `--aia-option-image-radius` (12px), spaced by `--aia-option-image-gap` (12px) and filled by `--aia-option-image-bg` (default: `--aia-skeleton-bg`) while its picture loads; in a grid with pictures, an icon row draws its glyph at `--aia-option-tile-icon-size` (1.5em) so it holds the picture column; the count reads `--aia-option-count-font-size` (12px), `--aia-option-count-color` and `--aia-option-count-opacity` (0.6); the chip's tile reads `--aia-chip-image-size` (1.25em of the chip's font), `--aia-chip-image-radius` (4px) and `--aia-chip-image-bg` (default: `--aia-skeleton-bg`).
 
 > **Parameter names under options.** An option that completes the word being typed (the server's `traditional_autocomplete` suggestion) can read the same as an option of another parameter, so the built-in dropdown draws the name of the parameter it answers under its text, muted and smaller (`Flavor`, `Subcategory`); the SDK sets it as `parameterLabel` from the option's `parameter`, and a skeleton row hides it. It reads `--aia-option-parameter-font-size` (12px), `--aia-option-parameter-color` and `--aia-option-parameter-opacity` (0.6).
 

package/dist/index.d.mts

@@ -2101,6 +2101,15 @@ declare function optionCountLabel(count: number | undefined, unit?: string | {
  * when its images are switched off.)
  */
 declare function optionHasImage(option: SuggestionOption): boolean;
+/**
+ * Whether a list's rows may lead with their icon or picture at all. Leading
+ * visuals are all-or-nothing per list: if any tappable option would draw
+ * neither, no row draws one, so a list never mixes rows with and without a
+ * visual before the text. Non-tappable rows don't count — they're
+ * informational and typically carry neither. The three packages' grids gate
+ * `showIcons` / `showImages` on this.
+ */
+declare function optionsShowLeadingVisuals(options: readonly SuggestionOption[], showIcons: boolean, showImages: boolean): boolean;
 
 /**
  * Reduces an option's `icon_svg` markup to plain vector drawing before it is
@@ -2636,4 +2645,4 @@ declare function labelTraditionalAutocomplete(suggestions: Suggestion[], header:
 /** True when some pill is a question the shopper can decline. */
 declare function hasSkippablePill(suggestions: Suggestion[]): boolean;
 
-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, DEFAULT_OPTION_COUNT_UNIT, 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, OPTION_IMAGE_WIDTH, 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_IMAGE_WIDTH, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type PhraseMatch, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, 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 SuggestionType, type TaskKind, type TextPart, type UIStrings, VIEWPORT_FIT_ATTR, VIEWPORT_FIT_HEIGHT_VAR, type ViewportFitArgs, type ViewportFitController, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, attachViewportFit, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, hasSkippablePill, highlightParts, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isTraditionalAutocompleteSuggestion, isoDate, keepCaretOnChip, labelTraditionalAutocomplete, matchTypedPhrase, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSources, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productImageSources, productImageSrc, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, shopifyImageSrc, toWireIdentifiedParams, typedFragment, uiStringsFor, visibleDateRange, withSkippedParams, withoutTraditionalAutocomplete };
+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, DEFAULT_OPTION_COUNT_UNIT, 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, OPTION_IMAGE_WIDTH, 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_IMAGE_WIDTH, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type PhraseMatch, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, 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 SuggestionType, type TaskKind, type TextPart, type UIStrings, VIEWPORT_FIT_ATTR, VIEWPORT_FIT_HEIGHT_VAR, type ViewportFitArgs, type ViewportFitController, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, attachViewportFit, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, hasSkippablePill, highlightParts, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isTraditionalAutocompleteSuggestion, isoDate, keepCaretOnChip, labelTraditionalAutocomplete, matchTypedPhrase, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSources, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, optionsShowLeadingVisuals, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productImageSources, productImageSrc, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, shopifyImageSrc, toWireIdentifiedParams, typedFragment, uiStringsFor, visibleDateRange, withSkippedParams, withoutTraditionalAutocomplete };

package/dist/index.d.ts

@@ -2101,6 +2101,15 @@ declare function optionCountLabel(count: number | undefined, unit?: string | {
  * when its images are switched off.)
  */
 declare function optionHasImage(option: SuggestionOption): boolean;
+/**
+ * Whether a list's rows may lead with their icon or picture at all. Leading
+ * visuals are all-or-nothing per list: if any tappable option would draw
+ * neither, no row draws one, so a list never mixes rows with and without a
+ * visual before the text. Non-tappable rows don't count — they're
+ * informational and typically carry neither. The three packages' grids gate
+ * `showIcons` / `showImages` on this.
+ */
+declare function optionsShowLeadingVisuals(options: readonly SuggestionOption[], showIcons: boolean, showImages: boolean): boolean;
 
 /**
  * Reduces an option's `icon_svg` markup to plain vector drawing before it is
@@ -2636,4 +2645,4 @@ declare function labelTraditionalAutocomplete(suggestions: Suggestion[], header:
 /** True when some pill is a question the shopper can decline. */
 declare function hasSkippablePill(suggestions: Suggestion[]): boolean;
 
-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, DEFAULT_OPTION_COUNT_UNIT, 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, OPTION_IMAGE_WIDTH, 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_IMAGE_WIDTH, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type PhraseMatch, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, 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 SuggestionType, type TaskKind, type TextPart, type UIStrings, VIEWPORT_FIT_ATTR, VIEWPORT_FIT_HEIGHT_VAR, type ViewportFitArgs, type ViewportFitController, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, attachViewportFit, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, hasSkippablePill, highlightParts, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isTraditionalAutocompleteSuggestion, isoDate, keepCaretOnChip, labelTraditionalAutocomplete, matchTypedPhrase, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSources, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productImageSources, productImageSrc, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, shopifyImageSrc, toWireIdentifiedParams, typedFragment, uiStringsFor, visibleDateRange, withSkippedParams, withoutTraditionalAutocomplete };
+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, DEFAULT_OPTION_COUNT_UNIT, 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, OPTION_IMAGE_WIDTH, 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_IMAGE_WIDTH, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type PhraseMatch, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, 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 SuggestionType, type TaskKind, type TextPart, type UIStrings, VIEWPORT_FIT_ATTR, VIEWPORT_FIT_HEIGHT_VAR, type ViewportFitArgs, type ViewportFitController, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, attachViewportFit, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, hasSkippablePill, highlightParts, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isTraditionalAutocompleteSuggestion, isoDate, keepCaretOnChip, labelTraditionalAutocomplete, matchTypedPhrase, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSources, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, optionsShowLeadingVisuals, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productImageSources, productImageSrc, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, shopifyImageSrc, toWireIdentifiedParams, typedFragment, uiStringsFor, visibleDateRange, withSkippedParams, withoutTraditionalAutocomplete };