@magicx-eng/ai-autocomplete-vanilla 0.28.1 → 0.29.0

package/README.md

@@ -109,6 +109,8 @@ const ac = new AIAutocomplete(container, {
   // How the strip lays its cards out: a scrolling row, or "list" — the same
   // cards stacked as full-width rows.
   productsLayout: "row",
+  // Missing/blank URL or load error: "image" (default) or the title initial.
+  productImageFallback: "image",
   // Custom source for the strip. Omit it and the server's items are shown.
   products: {
     fetch: (query, signal) => myPlatform.search(query, { signal }),
@@ -138,6 +140,15 @@ const ac = new AIAutocomplete(container, {
 });
 ```
 
+Product display options apply to both `renderMode: "full"` and
+`renderMode: "dropdown"`, at construction and through `update()`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `showProducts?` | `boolean` | `true` | Show product cards whenever there are products to display. |
+| `productsLayout?` | `"row" \| "list"` | `"row"` | Lay out cards as a scrolling row or a vertical list. |
+| `productImageFallback?` | `"image" \| "initial"` | `"image"` | Fallback for a missing or blank product image URL, or an image load error. `"image"` shows the placeholder pictogram; `"initial"` shows the title initial. A working image still takes priority. See [Product strip](#product-strip). |
+
 ### Methods
 
 ```ts
@@ -204,6 +215,44 @@ default); `--aia-product-list-media-size` (44px) sizes the thumbnail and
 is the horizontal strip. `update({ productsLayout })` re-lays the strip out at
 once.
 
+**Product image fallback.** A product's image takes priority when its
+`imageUrl` loads successfully. A missing or blank URL, or an image load error,
+uses `productImageFallback`: `"image"` (the default) shows the existing
+placeholder pictogram; `"initial"` shows the first character of the trimmed,
+uppercased title. This is a Unicode grapheme (so a combined character or emoji
+stays together), with a Unicode code point fallback in older browsers. An
+empty or whitespace-only title shows `?`. The fallback works in both row and
+list layouts. Initial tiles are decorative (`aria-hidden="true"`); the card's
+visible title supplies its text.
+
+Set the option at construction or change it through `update()`. Both
+rendered tiers (`"full"` and `"dropdown"`) apply it to the visible cards:
+
+```ts
+const ac = new AIAutocomplete(container, {
+  apiConfig: { apiKey: "..." },
+  productImageFallback: "initial",
+});
+
+// Switch existing fallback tiles back to the placeholder pictogram.
+ac.update({ productImageFallback: "image" });
+```
+
+Style the initial tile itself with `[data-aia-product-initial]`. For
+example, wrap the widget in an element with `id="catalog-search"` and add this
+rule to your stylesheet. The existing `--aia-product-media-bg` variable sets
+the background; `color`, `font-size` and `border-radius` style the initial
+without additional SDK options.
+
+```css
+#catalog-search [data-aia-product-initial] {
+  --aia-product-media-bg: #eef2ff;
+  color: #4338ca;
+  font-size: 22px;
+  border-radius: 12px;
+}
+```
+
 #### The catalog report (`customFields`)
 
 Every response that read the catalog also says what it did with the query, and
@@ -294,7 +343,7 @@ type Product = {
   id: string;
   title: string;
   url?: string;               // absent = a card with no link (still activatable)
-  imageUrl?: string | null;   // null renders the placeholder tile
+  imageUrl?: string | null;   // null uses the configured productImageFallback
   price?: string;             // pre-formatted by you
   vendor?: string;
 };
@@ -489,7 +538,7 @@ input.addEventListener("blur", () => ac.setFocused(false));
 
 Pills always render inside the dropdown in this mode. The library creates the dropdown DOM inside your container — you just provide the element and wire up your input's events.
 
-The [product strip](#product-strip) works here too: it renders inside the dropdown the library owns, from the server's items by default, and `products` / `showProducts` / `onProductSelect` behave exactly as in Tier 1.
+The [product strip](#product-strip) works here too: it renders inside the dropdown the library owns, from the server's items by default, and `products` / `showProducts` / `productImageFallback` / `onProductSelect` behave exactly as in Tier 1.
 
 > Focus/blur wiring is required when `dropdownTrigger` is `"auto"` (the default) — the dropdown only opens while the input is focused. Without `setFocused()`, the dropdown will never open.
 
@@ -549,7 +598,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` 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`.
+> **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; 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`).
 
 ### State shape (`CoreState`)
 
@@ -809,10 +858,10 @@ Override these on the container element. The variables are declared with `:where
 | `--aia-product-gap` | `8px` | `8px` | Gap between product cards. |
 | `--aia-product-bg` | `transparent` | `transparent` | Product card background. |
 | `--aia-product-bg-active` | `--aia-option-bg` | `--aia-option-bg` | Product card background on hover. |
-| `--aia-product-media-bg` | `--aia-skeleton-bg` | `--aia-skeleton-bg` | Fill behind the product image, and of the placeholder tile when a product has no image. |
+| `--aia-product-media-bg` | `--aia-skeleton-bg` | `--aia-skeleton-bg` | Fill behind product images and both fallback tiles (placeholder pictogram or title initial), used when an image URL is missing, blank or fails to load. |
 | `--aia-scroll-arrow-color` | `--aia-option-color` | `--aia-option-color` | Chevron color of the arrow (`--aia-scroll-arrow-color-hover` on hover). |
 | `--aia-placeholder-fade` | `120ms` | `120ms` | Fade-out of the outgoing placeholder phrase when the starting-state placeholder changes (the incoming one types itself in). |
-| `--aia-product-placeholder-image` | storefront pictogram | storefront pictogram | The image drawn on the placeholder tile when a product has no `imageUrl`: a two-tone storefront pictogram, inlined as a data URI. Set it to any `url(...)` to swap the pictogram; it is drawn centered and contained inside the tile, over `--aia-product-media-bg`. |
+| `--aia-product-placeholder-image` | storefront pictogram | storefront pictogram | The pictogram used by `productImageFallback: "image"` (the default) when an image URL is missing, blank or fails to load. Defaults to a two-tone storefront inlined as a data URI. Set any `url(...)` to swap it; it is centered and contained over `--aia-product-media-bg`. Does not affect `"initial"` tiles. |
 | `--aia-product-title-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product title text. Follows the option colors by default, so theming the panel moves suggestions and products together. |
 | `--aia-product-price-color` | `--aia-option-color-selected` | `--aia-option-color-selected` | Product price text. |
 | `--aia-product-vendor-color` | `--aia-option-color` | `--aia-option-color` | Product vendor line. |
@@ -831,7 +880,7 @@ Override these on the container element. The variables are declared with `:where
 | `--aia-date-today-ring` | `--aia-option-color` | `--aia-option-color` | Outline drawn around today's date. |
 | `--aia-date-selected-bg` | white at 12% | white at 12% | Fill behind the date a re-edited parameter already holds. |
 | `--aia-date-range-bg` | white at 6% | white at 6% | Band across the days between the two ends of a picked date range. The ends themselves use `--aia-date-selected-bg`. |
-| `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.25)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options. |
+| `--aia-skeleton-bg` | `rgba(189, 189, 189, 0.083)` | `#1a1b1d` | Fill color for the loading skeleton bars and the masked text in cached pills/options, and of the option and chip image tiles while their picture loads (unless `--aia-option-image-bg` / `--aia-chip-image-bg` are set). |
 
 ### Per-mode Overrides
 
@@ -877,7 +926,8 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-products]` | Product strip section (label + row) |
 | `[data-aia-products-row]` | The horizontally scrolling row of cards |
 | `[data-aia-product]` | Each product card |
-| `[data-aia-product-placeholder]` | Media tile of a card whose product has no image |
+| `[data-aia-product-placeholder]` | Media tile showing the placeholder pictogram (`productImageFallback: "image"`) after a missing/blank URL or load error. The existing hook is unchanged. |
+| `[data-aia-product-initial]` | The media tile itself when it shows the title initial (`productImageFallback: "initial"`). Decorative (`aria-hidden="true"`); target it to style the background, color, font size and border radius. |
 
 Completed params render as inline `<strong>` elements inside the editor. Override their weight with `[data-aia-input] strong { font-weight: 700; }` — a selector that names the editor wins without `!important`, while a bare `strong { … }` page rule is kept out by the isolation reset.
 

package/dist/index.d.mts

@@ -358,6 +358,8 @@ interface Product {
  * (courses, listings, documents) rather than products on a shelf.
  */
 type ProductsLayout = "row" | "list";
+/** What a product tile shows when its image is missing or fails to load. */
+type ProductImageFallback = "image" | "initial";
 /**
  * Custom product-search wiring for the strip. Absent (the default), the strip
  * shows the items the `/suggest` response itself reports as matching the query
@@ -666,6 +668,27 @@ interface CoreInputState {
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
+    /**
+     * The options that were on screen when the user answered, held while the
+     * answer's request is in flight so the loading skeleton draws *those* rows —
+     * same count, same widths, same columns — instead of the next cached pill's.
+     * Display-only: the active suggestion is unaffected, so nothing can select
+     * from it. Null outside that window, and for a calendar answer (day cells
+     * have no skeleton form).
+     */
+    skeletonOptions: SuggestionOption[] | null;
+    /**
+     * The question `skeletonOptions` were answering — the dropdown's active
+     * pill at pick time (or the pill being re-edited). See `dropdownSuggestion`.
+     */
+    skeletonSuggestion: Suggestion | null;
+    /**
+     * Whether the answer's request has started since `skeletonOptions` was set.
+     * Lets the derive layer tell "the request settled" (fade the skeleton out)
+     * from "the request hasn't started yet" without a follow-up write — see
+     * `skeletonExiting`.
+     */
+    skeletonRequested: boolean;
     /**
      * Which month the datepicker is showing, when one is showing at all.
      *
@@ -790,6 +813,36 @@ interface CoreDerivedState {
      * should treat it the same way. Never true for a pill without a source.
      */
     isSearchingOptions: boolean;
+    /**
+     * Whether the dropdown draws its loading skeleton: a request in flight
+     * (outside re-edit and the post-answer press window), a consumer option
+     * source still answering, or the skeleton's fade-out. Every built-in
+     * dropdown reads this rather than `isLoading`.
+     */
+    dropdownLoading: boolean;
+    /**
+     * True for the short fade-out after the answer's request settles, while the
+     * skeleton is still drawn from `skeletonOptions` and the dropdown carries
+     * `data-aia-skeleton-exiting`. Derived, so it switches on in the same state
+     * update that ends the loading — a renderer never sees a frame between the
+     * two.
+     */
+    skeletonExiting: boolean;
+    /**
+     * The options the dropdown renders: `skeletonOptions` while that skeleton
+     * is drawn, otherwise `filteredOptions`. Rows are only interactive when
+     * `dropdownLoading` is false, and then this *is* `filteredOptions`.
+     */
+    dropdownOptions: SuggestionOption[];
+    /**
+     * The question the dropdown's rows belong to while it draws the mirrored
+     * skeleton (`skeletonSuggestion`), else null — use the active pill. Renderers
+     * key rows by their question, so holding it steady keeps the skeleton rows
+     * mounted from the pick through the fade-out; letting it follow the active
+     * pill remounts them as the response lands, which replays their entrance
+     * and flashes the old option text.
+     */
+    dropdownSuggestion: Suggestion | null;
     isDropdownOpen: boolean;
     /**
      * Whether the active (leading) pill should render in its `selected` state
@@ -910,6 +963,12 @@ interface CoreOptions {
      * the strip out at once.
      */
     productsLayout?: ProductsLayout;
+    /**
+     * Fallback for a missing or failed product image. "image" (default) uses
+     * the placeholder image; "initial" uses the title's first character.
+     * Style initial tiles with `[data-aia-product-initial]` in CSS.
+     */
+    productImageFallback?: ProductImageFallback;
     /**
      * Custom source for the product strip. Omit it and the strip shows the items
      * the `/suggest` response itself reports (`custom_fields.items`), with no
@@ -1192,6 +1251,15 @@ declare class AIAutocomplete {
     /** Batched render subscriber — coalesces multiple store.set calls into one DOM update. */
     private subscribeBatchedRender;
     /** Auto-clear newParamId after shimmer animation. */
+    /**
+     * Tracks the answer's request for the skeleton mirror. When the request
+     * starts, `skeletonRequested` records it (the skeleton is already showing,
+     * so the extra write changes nothing on screen). When it settles, the
+     * derived `skeletonExiting` is already true in that same state — this only
+     * schedules the release after SKELETON_FADE_MS, or releases at once when the
+     * response beat the press window and no skeleton was ever drawn.
+     */
+    private subscribeSkeletonMirror;
     private subscribeNewParamTimer;
     private handleChange;
     /**
@@ -1570,6 +1638,19 @@ declare function measureOptionsGrid(grid: HTMLElement): {
 declare function optionsGridTemplateColumns(cols: number): string;
 /** Whether the current viewport is phone-width. `false` when there's no DOM. */
 declare function isOptionsGridMobileViewport(): boolean;
+/**
+ * Whether two option lists draw the same rows (same texts, same order). A
+ * grid that measured `measured` keeps that plan while `next` shows as a
+ * loading skeleton: after an answer the skeleton mirrors the rows just on
+ * screen (`CoreInputState.skeletonOptions`), so their measured columns still
+ * describe it — re-planning would drop a two-column grid to the one-column
+ * baseline under the user's eyes.
+ */
+declare function sameOptionRows(measured: readonly {
+    text: string;
+}[] | null, next: readonly {
+    text: string;
+}[]): boolean;
 
 /**
  * Plain-text caret utilities for contentEditable elements.
@@ -2043,6 +2124,9 @@ declare class ModeController {
  */
 declare function identifiedParamLabel(type: string): string;
 
+/** Uppercase first character for a product tile; an empty title displays "?". */
+declare function productInitial(title: string): string;
+
 /**
  * Sentinel `text` marking a `completed_params` entry the user skipped (→)
  * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
@@ -2093,4 +2177,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, 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 };
+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 ProductImageFallback, 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, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };

package/dist/index.d.ts

@@ -358,6 +358,8 @@ interface Product {
  * (courses, listings, documents) rather than products on a shelf.
  */
 type ProductsLayout = "row" | "list";
+/** What a product tile shows when its image is missing or fails to load. */
+type ProductImageFallback = "image" | "initial";
 /**
  * Custom product-search wiring for the strip. Absent (the default), the strip
  * shows the items the `/suggest` response itself reports as matching the query
@@ -666,6 +668,27 @@ interface CoreInputState {
      * Set by selectOption / ReEditManager.selectOption, cleared by a timer.
      */
     inSelectionAnimation: boolean;
+    /**
+     * The options that were on screen when the user answered, held while the
+     * answer's request is in flight so the loading skeleton draws *those* rows —
+     * same count, same widths, same columns — instead of the next cached pill's.
+     * Display-only: the active suggestion is unaffected, so nothing can select
+     * from it. Null outside that window, and for a calendar answer (day cells
+     * have no skeleton form).
+     */
+    skeletonOptions: SuggestionOption[] | null;
+    /**
+     * The question `skeletonOptions` were answering — the dropdown's active
+     * pill at pick time (or the pill being re-edited). See `dropdownSuggestion`.
+     */
+    skeletonSuggestion: Suggestion | null;
+    /**
+     * Whether the answer's request has started since `skeletonOptions` was set.
+     * Lets the derive layer tell "the request settled" (fade the skeleton out)
+     * from "the request hasn't started yet" without a follow-up write — see
+     * `skeletonExiting`.
+     */
+    skeletonRequested: boolean;
     /**
      * Which month the datepicker is showing, when one is showing at all.
      *
@@ -790,6 +813,36 @@ interface CoreDerivedState {
      * should treat it the same way. Never true for a pill without a source.
      */
     isSearchingOptions: boolean;
+    /**
+     * Whether the dropdown draws its loading skeleton: a request in flight
+     * (outside re-edit and the post-answer press window), a consumer option
+     * source still answering, or the skeleton's fade-out. Every built-in
+     * dropdown reads this rather than `isLoading`.
+     */
+    dropdownLoading: boolean;
+    /**
+     * True for the short fade-out after the answer's request settles, while the
+     * skeleton is still drawn from `skeletonOptions` and the dropdown carries
+     * `data-aia-skeleton-exiting`. Derived, so it switches on in the same state
+     * update that ends the loading — a renderer never sees a frame between the
+     * two.
+     */
+    skeletonExiting: boolean;
+    /**
+     * The options the dropdown renders: `skeletonOptions` while that skeleton
+     * is drawn, otherwise `filteredOptions`. Rows are only interactive when
+     * `dropdownLoading` is false, and then this *is* `filteredOptions`.
+     */
+    dropdownOptions: SuggestionOption[];
+    /**
+     * The question the dropdown's rows belong to while it draws the mirrored
+     * skeleton (`skeletonSuggestion`), else null — use the active pill. Renderers
+     * key rows by their question, so holding it steady keeps the skeleton rows
+     * mounted from the pick through the fade-out; letting it follow the active
+     * pill remounts them as the response lands, which replays their entrance
+     * and flashes the old option text.
+     */
+    dropdownSuggestion: Suggestion | null;
     isDropdownOpen: boolean;
     /**
      * Whether the active (leading) pill should render in its `selected` state
@@ -910,6 +963,12 @@ interface CoreOptions {
      * the strip out at once.
      */
     productsLayout?: ProductsLayout;
+    /**
+     * Fallback for a missing or failed product image. "image" (default) uses
+     * the placeholder image; "initial" uses the title's first character.
+     * Style initial tiles with `[data-aia-product-initial]` in CSS.
+     */
+    productImageFallback?: ProductImageFallback;
     /**
      * Custom source for the product strip. Omit it and the strip shows the items
      * the `/suggest` response itself reports (`custom_fields.items`), with no
@@ -1192,6 +1251,15 @@ declare class AIAutocomplete {
     /** Batched render subscriber — coalesces multiple store.set calls into one DOM update. */
     private subscribeBatchedRender;
     /** Auto-clear newParamId after shimmer animation. */
+    /**
+     * Tracks the answer's request for the skeleton mirror. When the request
+     * starts, `skeletonRequested` records it (the skeleton is already showing,
+     * so the extra write changes nothing on screen). When it settles, the
+     * derived `skeletonExiting` is already true in that same state — this only
+     * schedules the release after SKELETON_FADE_MS, or releases at once when the
+     * response beat the press window and no skeleton was ever drawn.
+     */
+    private subscribeSkeletonMirror;
     private subscribeNewParamTimer;
     private handleChange;
     /**
@@ -1570,6 +1638,19 @@ declare function measureOptionsGrid(grid: HTMLElement): {
 declare function optionsGridTemplateColumns(cols: number): string;
 /** Whether the current viewport is phone-width. `false` when there's no DOM. */
 declare function isOptionsGridMobileViewport(): boolean;
+/**
+ * Whether two option lists draw the same rows (same texts, same order). A
+ * grid that measured `measured` keeps that plan while `next` shows as a
+ * loading skeleton: after an answer the skeleton mirrors the rows just on
+ * screen (`CoreInputState.skeletonOptions`), so their measured columns still
+ * describe it — re-planning would drop a two-column grid to the one-column
+ * baseline under the user's eyes.
+ */
+declare function sameOptionRows(measured: readonly {
+    text: string;
+}[] | null, next: readonly {
+    text: string;
+}[]): boolean;
 
 /**
  * Plain-text caret utilities for contentEditable elements.
@@ -2043,6 +2124,9 @@ declare class ModeController {
  */
 declare function identifiedParamLabel(type: string): string;
 
+/** Uppercase first character for a product tile; an empty title displays "?". */
+declare function productInitial(title: string): string;
+
 /**
  * Sentinel `text` marking a `completed_params` entry the user skipped (→)
  * rather than filled. Sent regardless of `maskCompletedText` — it's a fixed
@@ -2093,4 +2177,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, 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 };
+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 ProductImageFallback, 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, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };