@magicx-eng/ai-autocomplete-vanilla 0.26.2 → 0.28.0

package/README.md

@@ -91,6 +91,9 @@ const ac = new AIAutocomplete(container, {
   showSkipButton: true,      // false = hide the pill bar's trailing "skip" button
   showOptionIcons: true,     // false = render option rows as text only (no icons)
   showChipIcons: true,       // false = render completed chips as text only (no icons)
+  showChipImages: true,      // false = never draw an option's picture on its completed chip
+  showOptionImages: true,    // false = never draw an option's image_url thumbnail
+  showOptionCounts: true,    // false = never show an option's item_count
 
   // Focus
   autoFocus: true,           // focus the input on mount (Tier 1 only)
@@ -546,6 +549,8 @@ 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` while its picture loads; 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`.
+
 ### State shape (`CoreState`)
 
 | Field | Type | Description |
@@ -792,10 +797,10 @@ Override these on the container element. The variables are declared with `:where
 | `--aia-submit-bg-disabled` | `--aia-submit-bg` | `--aia-submit-bg` | Submit background when disabled (empty input). Defaults to the enabled background so themed colors aren't washed out. Set this for a faded rest state. |
 | `--aia-submit-color-disabled` | `--aia-submit-color` | `--aia-submit-color` | Submit arrow color when disabled. Defaults to the enabled color. |
 | `--aia-border` | `rgba(17, 24, 39, 0.14)` | `#505050` | Input container border color |
-| `--aia-shadow` | `inset 0 1px 0 rgba(255,255,255,0.9), 0 1px 2px rgba(16,24,40,0.1), 0 8px 24px rgba(16,24,40,0.16)` | `inset 0 1px 0 rgba(255,255,255,0.06), 0 1px 2px rgba(0,0,0,0.4), 0 8px 24px rgba(0,0,0,0.5)` | Input container elevation (box-shadow) |
+| `--aia-shadow` | `none` | `none` | Input container elevation (box-shadow). Flat by default; set it to add one |
 | `--aia-dropdown-offset` | `13px` | `13px` | Gap between the input box and the dropdown (the dropdown's margin toward the input). |
 | `--aia-content-inset-left` | `16px` | `16px` | Left inset of the SDK's content: the input wrapper's left padding, and the line the dropdown's content (parameter label, option text, product strip) starts on. Set it when you pad the field to clear a leading icon of your own, so the dropdown's content stays aligned under the typed text. Practical minimum is `10px` (the option text's own inset); both surfaces floor it there. |
-| `--aia-footer-gap` | `8px` | `8px` | Breathing room above the dropdown footer (badge / keyboard hints), additive to the dropdown's 8px section gap. |
+| `--aia-footer-gap` | `12px` | `12px` | Breathing room above the dropdown footer (badge / keyboard hints), additive to the dropdown's 8px section gap. |
 | `--aia-footer-chip-bg` | `--aia-surface` at 65% | `--aia-surface` at 65% | Fill behind the footer's keyboard hint and AI-Autocomplete badge. The option list scrolls under the footer, so this keeps both legible over the row passing behind them. `transparent` on the glass surface. |
 | `--aia-dropdown-bg` | — | — | Optional bg color the dropdown's "glass" rim shadow tints toward. Set this to the page background behind the dropdown so the bottom-corner glow blends seamlessly. |
 | `--aia-scrollbar-thumb` | `rgba(0, 0, 0, 0.3)` | `rgba(0, 0, 0, 0.3)` | Color of the option list's scrollbar thumb (Firefox + WebKit). |

package/dist/index.d.mts

@@ -29,6 +29,22 @@ interface SuggestionOption {
      * touches the DOM; markup that fails it renders no icon.
      */
     icon_svg?: string;
+    /**
+     * URL of a picture for the option — the image of the best-matching catalog
+     * item offering it. Present only when the server includes pictures for the
+     * catalog being searched; absent otherwise. The built-in dropdown draws it
+     * as a square thumbnail before the text (see `optionImageSrc` for which
+     * URLs load).
+     */
+    image_url?: string;
+    /**
+     * How many catalog items offer this option. Present only when the server
+     * includes counts, in which case the options also arrive ordered by it,
+     * most items first; absent otherwise (a starting state carries pictures but
+     * no counts). The built-in dropdown shows it at the row's trailing edge
+     * (see `optionCountLabel`).
+     */
+    item_count?: number;
     tag?: string;
     is_tappable: boolean;
     kind: TaskKind | null;
@@ -197,6 +213,12 @@ interface CompletedParamState extends CompletedParam {
      */
     icon?: string;
     icon_svg?: string;
+    /**
+     * The picked option's `image_url`, carried over so the completed chip draws
+     * the same picture its option row did, in place of the icon. Absent when
+     * the option carried none.
+     */
+    image_url?: string;
 }
 /**
  * A suggestion the user dismissed with the skip key (→) instead of filling.
@@ -821,6 +843,12 @@ interface CoreOptions {
     showOptionIcons?: boolean;
     /** When true (default), a completed chip in the input draws the icon of the option that answered it. Set to false to render chips as text only. */
     showChipIcons?: boolean;
+    /** When true (default), a completed chip in the input draws the picture (`image_url`) of the option that answered it, in place of its icon. Set to false to render chips without pictures. */
+    showChipImages?: boolean;
+    /** When true (default), an option that carries an `image_url` draws it as a square thumbnail before its text in the dropdown (in place of its `icon_svg`). Set to false to render option rows without pictures. */
+    showOptionImages?: boolean;
+    /** When true (default), an option that carries an `item_count` shows it as a muted label at the row's trailing edge ("12 items"). Set to false to hide the counts. */
+    showOptionCounts?: boolean;
     /**
      * When true (default), the dropdown's pill bar ends in a small "skip" button
      * that dismisses the active pill — same action as pressing → at the end of
@@ -1414,11 +1442,15 @@ declare function dateCellMarks(iso: string | null, args: {
  * suggestion bubbles, 2026-08-19): opacity 0→1 over ~150 ms, a ~16 px rise
  * easing out over ~280 ms, consecutive rows ~80–110 ms apart.
  *
- * The per-row motion is CSS: the option rule in each package's stylesheet
- * fades the cell, and the option's content rule rises it — the rise is on the
- * inner content, not the cell, because a transformed cell extends the grid's
- * scrollable area and flashed a scrollbar through the entrance (keep the three
- * copies identical; the parity test compares them). This module
+ * The per-row motion is CSS: the option's *content* rule in each package's
+ * stylesheet both fades and rises it. Neither half runs on the cell — the
+ * tappable element — itself: the rise because a transformed cell extends the
+ * grid's scrollable area and flashed a scrollbar through the entrance, the
+ * fade because iOS Safari drops a tap on a scripted-clickable element (the
+ * row is a div with a click handler) whose own opacity is mid-animation — it
+ * fires the hover events, so the row highlights, and never the click. Keep
+ * the three copies identical; the parity test compares them and
+ * tests/render/optionEntranceOverflow.test.ts pins the split. This module
  * owns the *timing numbers* and the per-row delay, so vanilla, React and
  * Angular can't drift onto three different cascades. `OPTION_ENTER_RISE_MS` and
  * `OPTION_ENTER_FADE_MS` must match the durations declared in those rules.
@@ -1674,6 +1706,55 @@ declare function attachProductRowWheel(row: HTMLElement): () => void;
  */
 declare function scrollCaretIntoView(root: HTMLElement): void;
 
+/**
+ * The picture an option may carry (`image_url`) and the number of catalog
+ * items behind it (`item_count`). Both are optional on the wire — present
+ * only when the server includes them for the catalog being searched — and
+ * both are drawn by the built-in dropdown: the picture as a square thumbnail
+ * before the text, the count as a muted label at the row's trailing edge.
+ * These helpers are what the three packages' rows share, and are exported
+ * for a custom dropdown that renders options itself.
+ */
+/**
+ * The `src` to draw an option's `image_url` with, or `null` when the URL must
+ * not be loaded. Only an `http(s)` URL is accepted — resolved against the
+ * page, so a root-relative path from a same-origin catalog still works —
+ * which keeps `javascript:`, `data:` and `blob:` sources out of an `<img>`
+ * the server populates.
+ */
+declare function optionImageSrc(url: string | undefined): string | null;
+/**
+ * An option's `item_count` as the built-in rows print it: the number alone,
+ * grouped the way the page's locale groups numbers (`"1,200"`). The unit word
+ * after it is the stylesheet's — `--aia-option-count-unit` (default
+ * `"items"`, `--aia-option-count-unit-one` for a count of 1) — so a consumer
+ * names what is being counted, or blanks it, without a render option. `null`
+ * for an absent, negative or non-integer count: a count the server did not
+ * send is not a count of zero.
+ */
+declare function formatOptionCount(count: number | undefined): string | null;
+/** The unit `optionCountLabel` appends when given none: `"1 item"`, `"12 items"`. */
+declare const DEFAULT_OPTION_COUNT_UNIT: {
+    readonly one: "item";
+    readonly other: "items";
+};
+/**
+ * A full label for an option's `item_count`, for a custom dropdown that
+ * prints the unit itself: `formatOptionCount` followed by the unit — one
+ * word for every count, or a singular/plural pair — or the number alone for
+ * an empty unit. `null` when there is no count.
+ */
+declare function optionCountLabel(count: number | undefined, unit?: string | {
+    one: string;
+    other: string;
+}): string | null;
+/**
+ * Whether `option` carries a picture the built-in dropdown would draw: an
+ * `image_url` that `optionImageSrc` accepts. (The dropdown still skips it
+ * when its images are switched off.)
+ */
+declare function optionHasImage(option: SuggestionOption): boolean;
+
 /**
  * Reduces an option's `icon_svg` markup to plain vector drawing before it is
  * inserted into the dropdown. The icons come from the server's own curated
@@ -1740,6 +1821,8 @@ interface RenderEditableArgs {
     isFocused: boolean;
     /** Whether completed chips draw the icon of the option that answered them. Default: true. */
     showChipIcons?: boolean;
+    /** Whether completed chips draw the picture of the option that answered them, in place of the icon. Default: true. */
+    showChipImages?: boolean;
 }
 /**
  * Renders text segments into the contentEditable input. Completed params are
@@ -2010,4 +2093,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, 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 };
+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, 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, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, 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

@@ -29,6 +29,22 @@ interface SuggestionOption {
      * touches the DOM; markup that fails it renders no icon.
      */
     icon_svg?: string;
+    /**
+     * URL of a picture for the option — the image of the best-matching catalog
+     * item offering it. Present only when the server includes pictures for the
+     * catalog being searched; absent otherwise. The built-in dropdown draws it
+     * as a square thumbnail before the text (see `optionImageSrc` for which
+     * URLs load).
+     */
+    image_url?: string;
+    /**
+     * How many catalog items offer this option. Present only when the server
+     * includes counts, in which case the options also arrive ordered by it,
+     * most items first; absent otherwise (a starting state carries pictures but
+     * no counts). The built-in dropdown shows it at the row's trailing edge
+     * (see `optionCountLabel`).
+     */
+    item_count?: number;
     tag?: string;
     is_tappable: boolean;
     kind: TaskKind | null;
@@ -197,6 +213,12 @@ interface CompletedParamState extends CompletedParam {
      */
     icon?: string;
     icon_svg?: string;
+    /**
+     * The picked option's `image_url`, carried over so the completed chip draws
+     * the same picture its option row did, in place of the icon. Absent when
+     * the option carried none.
+     */
+    image_url?: string;
 }
 /**
  * A suggestion the user dismissed with the skip key (→) instead of filling.
@@ -821,6 +843,12 @@ interface CoreOptions {
     showOptionIcons?: boolean;
     /** When true (default), a completed chip in the input draws the icon of the option that answered it. Set to false to render chips as text only. */
     showChipIcons?: boolean;
+    /** When true (default), a completed chip in the input draws the picture (`image_url`) of the option that answered it, in place of its icon. Set to false to render chips without pictures. */
+    showChipImages?: boolean;
+    /** When true (default), an option that carries an `image_url` draws it as a square thumbnail before its text in the dropdown (in place of its `icon_svg`). Set to false to render option rows without pictures. */
+    showOptionImages?: boolean;
+    /** When true (default), an option that carries an `item_count` shows it as a muted label at the row's trailing edge ("12 items"). Set to false to hide the counts. */
+    showOptionCounts?: boolean;
     /**
      * When true (default), the dropdown's pill bar ends in a small "skip" button
      * that dismisses the active pill — same action as pressing → at the end of
@@ -1414,11 +1442,15 @@ declare function dateCellMarks(iso: string | null, args: {
  * suggestion bubbles, 2026-08-19): opacity 0→1 over ~150 ms, a ~16 px rise
  * easing out over ~280 ms, consecutive rows ~80–110 ms apart.
  *
- * The per-row motion is CSS: the option rule in each package's stylesheet
- * fades the cell, and the option's content rule rises it — the rise is on the
- * inner content, not the cell, because a transformed cell extends the grid's
- * scrollable area and flashed a scrollbar through the entrance (keep the three
- * copies identical; the parity test compares them). This module
+ * The per-row motion is CSS: the option's *content* rule in each package's
+ * stylesheet both fades and rises it. Neither half runs on the cell — the
+ * tappable element — itself: the rise because a transformed cell extends the
+ * grid's scrollable area and flashed a scrollbar through the entrance, the
+ * fade because iOS Safari drops a tap on a scripted-clickable element (the
+ * row is a div with a click handler) whose own opacity is mid-animation — it
+ * fires the hover events, so the row highlights, and never the click. Keep
+ * the three copies identical; the parity test compares them and
+ * tests/render/optionEntranceOverflow.test.ts pins the split. This module
  * owns the *timing numbers* and the per-row delay, so vanilla, React and
  * Angular can't drift onto three different cascades. `OPTION_ENTER_RISE_MS` and
  * `OPTION_ENTER_FADE_MS` must match the durations declared in those rules.
@@ -1674,6 +1706,55 @@ declare function attachProductRowWheel(row: HTMLElement): () => void;
  */
 declare function scrollCaretIntoView(root: HTMLElement): void;
 
+/**
+ * The picture an option may carry (`image_url`) and the number of catalog
+ * items behind it (`item_count`). Both are optional on the wire — present
+ * only when the server includes them for the catalog being searched — and
+ * both are drawn by the built-in dropdown: the picture as a square thumbnail
+ * before the text, the count as a muted label at the row's trailing edge.
+ * These helpers are what the three packages' rows share, and are exported
+ * for a custom dropdown that renders options itself.
+ */
+/**
+ * The `src` to draw an option's `image_url` with, or `null` when the URL must
+ * not be loaded. Only an `http(s)` URL is accepted — resolved against the
+ * page, so a root-relative path from a same-origin catalog still works —
+ * which keeps `javascript:`, `data:` and `blob:` sources out of an `<img>`
+ * the server populates.
+ */
+declare function optionImageSrc(url: string | undefined): string | null;
+/**
+ * An option's `item_count` as the built-in rows print it: the number alone,
+ * grouped the way the page's locale groups numbers (`"1,200"`). The unit word
+ * after it is the stylesheet's — `--aia-option-count-unit` (default
+ * `"items"`, `--aia-option-count-unit-one` for a count of 1) — so a consumer
+ * names what is being counted, or blanks it, without a render option. `null`
+ * for an absent, negative or non-integer count: a count the server did not
+ * send is not a count of zero.
+ */
+declare function formatOptionCount(count: number | undefined): string | null;
+/** The unit `optionCountLabel` appends when given none: `"1 item"`, `"12 items"`. */
+declare const DEFAULT_OPTION_COUNT_UNIT: {
+    readonly one: "item";
+    readonly other: "items";
+};
+/**
+ * A full label for an option's `item_count`, for a custom dropdown that
+ * prints the unit itself: `formatOptionCount` followed by the unit — one
+ * word for every count, or a singular/plural pair — or the number alone for
+ * an empty unit. `null` when there is no count.
+ */
+declare function optionCountLabel(count: number | undefined, unit?: string | {
+    one: string;
+    other: string;
+}): string | null;
+/**
+ * Whether `option` carries a picture the built-in dropdown would draw: an
+ * `image_url` that `optionImageSrc` accepts. (The dropdown still skips it
+ * when its images are switched off.)
+ */
+declare function optionHasImage(option: SuggestionOption): boolean;
+
 /**
  * Reduces an option's `icon_svg` markup to plain vector drawing before it is
  * inserted into the dropdown. The icons come from the server's own curated
@@ -1740,6 +1821,8 @@ interface RenderEditableArgs {
     isFocused: boolean;
     /** Whether completed chips draw the icon of the option that answered them. Default: true. */
     showChipIcons?: boolean;
+    /** Whether completed chips draw the picture of the option that answered them, in place of the icon. Default: true. */
+    showChipImages?: boolean;
 }
 /**
  * Renders text segments into the contentEditable input. Completed params are
@@ -2010,4 +2093,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, 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 };
+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, 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, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };