@magicx-eng/ai-autocomplete-vanilla 0.23.0 → 0.23.2

package/README.md

@@ -531,7 +531,7 @@ unsub();
 
 > **Datepicker in a custom UI.** For a date parameter, `state.activeFormatType` is `"date"` and `state.filteredOptions` holds that month's day cells. Each cell's `text` is the date it commits (`"March 23"`, or `"Tuesday"` inside the next week), so rendering them as a plain list already works — `selectOption(cell)` behaves exactly as it does for an option. To draw an actual calendar, read `state.dateView` for the month on show, `cellDay(cell)` for the number to paint, and call `showPreviousMonth()` / `showNextMonth()` to page. Cells that pad the start and end of the month have `is_tappable: false`. For a **range** parameter `activeFormatType` is `"date-range"` and the same `selectOption(cell)` is called twice: the first records the start (`state.dateRangeStart` holds it, and nothing is committed yet), the second commits the span. `dateCellMarks` and `visibleDateRange` are exported to paint the two ends and the band between them the way the built-in calendars do.
 
-> **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, which keeps an `icon` that has no `icon_svg` as a legacy text prefix. 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 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.
 
 ### State shape (`CoreState`)
 
@@ -736,7 +736,7 @@ Styles are auto-injected at runtime (Tier 1 and Tier 2). No CSS import needed. T
 
 Every class name the core emits is namespaced — `magicx-aia-*` (plus the bare `magicx-aia` root) and `aia-*` for the layout primitives — so nothing it renders can match a `.container`, `.pill` or `.dropdown` rule in your own stylesheet, and none of its rules can reach your elements.
 
-**Page CSS stops at the widget's edge.** Everything inside the input wrapper (`[data-aia-input-wrapper]`) and the dropdown (`[data-aia-dropdown]`) is reset to browser defaults before the SDK's own styles apply, so element and universal rules in your stylesheet — `button { … }`, `a { … }`, `* { … }`, a CSS reset, a framework's preflight — never reach it, and inherited typography adjustments from the page (line-height, letter-spacing, text-transform, text-align, …) are pinned at those two roots. Font family, size, weight and text colour still inherit from your page; a submit button you provide is left to your own stylesheet; and nothing the SDK ships styles elements outside its own subtree. The reset sits at specificity (0,0,5), below any rule that names a class, attribute or id — your overrides on the `data-aia-*` hooks work exactly as before, and so does a page rule like `.sidebar button { … }`, which names a class: scope rules like that to your own markup. For complete isolation, including rules like that, mount the widget in a shadow root — see [Shadow DOM](#shadow-dom).
+**Page CSS stops at the widget's edge.** Everything inside the input wrapper (`[data-aia-input-wrapper]`) and the dropdown (`[data-aia-dropdown]`) is reset to browser defaults before the SDK's own styles apply, so element and universal rules in your stylesheet — `button { … }`, `a { … }`, `* { … }`, a CSS reset, a framework's preflight — never reach it, and inherited typography adjustments from the page (line-height, letter-spacing, text-transform, text-align, …) are pinned at those two roots. Font family, size, weight and text colour still inherit from your page; a submit button you provide is left to your own stylesheet; and nothing the SDK ships styles elements outside its own subtree. The SDK's inline icons are covered too: a page's `svg { display: block; max-width: 100%; margin: … }` or `svg { width: 100%; fill: currentColor }` leaves the submit arrow, the scroll chevron and the option icons as drawn. The reset sits at specificity (0,0,5), below any rule that names a class, attribute or id — your overrides on the `data-aia-*` hooks work exactly as before, and so does a page rule like `.sidebar button { … }`, which names a class: scope rules like that to your own markup. For complete isolation, including rules like that, mount the widget in a shadow root — see [Shadow DOM](#shadow-dom).
 
 ### Shadow DOM
 
@@ -791,10 +791,7 @@ Override these on the container element. The variables are declared with `:where
 | `--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-scroll-arrow-bg` | `--aia-surface` | `--aia-surface` | Fill of the "more below" arrow — the round button that fades in at the bottom of the option list while there is more to scroll to, and out while it scrolls. |
 | `--aia-scroll-arrow-color` | `--aia-option-color` | `--aia-option-color` | Chevron color of the arrow (`--aia-scroll-arrow-color-hover` on hover). |
-| `--aia-scroll-arrow-border` | `--aia-dropdown-border` | `--aia-dropdown-border` | Hairline around the arrow. |
-| `--aia-scroll-arrow-shadow` | `0 2px 8px rgba(0,0,0,0.12)` | `0 2px 8px rgba(0,0,0,0.12)` | Elevation of the arrow. |
 | `--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-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. |

package/dist/index.d.mts

@@ -8,10 +8,9 @@ interface CompletedParam {
 interface SuggestionOption {
     text: string;
     /**
-     * Icon for the option. When `icon_svg` is also set this is the icon's name
-     * (an identifier such as `"apple"`, exposed on the row as `data-aia-icon`)
-     * and the SVG is what renders. Without `icon_svg` it is legacy display text
-     * (an emoji, say) drawn as a prefix to `text`.
+     * The icon's name — an identifier such as `"apple"`, exposed on the row as
+     * `data-aia-icon` when its `icon_svg` draws. Never rendered as text: a row
+     * without a drawable `icon_svg` shows `text` alone.
      */
     icon?: string;
     /**
@@ -1587,9 +1586,11 @@ declare function scrollCaretIntoView(root: HTMLElement): void;
  */
 declare function sanitizeOptionIconSvg(markup: string): string | null;
 /**
- * The text an option row shows. With `icon_svg` the icon draws as its own
- * element and `icon` is just its name; without it, a legacy `icon` (an emoji
- * from an option override, say) is display text prefixed to the option.
+ * The text an option row shows: its `text`, alone. `icon` is the icon's name
+ * (`"apple"`), an identifier for `data-aia-icon` and consumer CSS, never
+ * display text — so it is not prefixed to the option, whether `icon_svg`
+ * came with it, failed to draw, or was switched off. A row whose icon cannot
+ * draw shows the text by itself rather than the icon's name.
  */
 declare function optionLabel(option: {
     text: string;
@@ -1655,10 +1656,11 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
 /**
  * The "more below" arrow for the options grid.
  *
- * When the option list is taller than its scroll box, a small round button
- * with a down chevron sits at the bottom-centre of the list and scrolls it a
- * page on click. It never moves — every appearance is an opacity fade in
- * place, SCROLL_ARROW_FADE_MS long (the stylesheets own the curve):
+ * When the option list is taller than its scroll box, a bare down chevron
+ * sits at the bottom-centre of the list and scrolls it a page on click. It
+ * never travels with the scroll — every appearance is an opacity fade in
+ * place, SCROLL_ARROW_FADE_MS long, and its only motion is the stylesheets'
+ * slow idle bob of a few pixels (the stylesheets own both curves):
  *
  * - At rest with more below (the list just opened, or scrolling has stopped
  *   short of the end), it fades in.
@@ -1667,9 +1669,10 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
  * - Once scrolling has been quiet for SCROLL_ARROW_SCROLL_IDLE_MS it fades
  *   back in — unless the list is now at its bottom, where it stays out.
  *
- * Earlier versions rose from behind the footer and slid or shrank away; each
- * read as the disc travelling with the scroll (2026-09-03/04), hence the
- * fade-only rule. The stylesheets key everything off one attribute,
+ * Earlier versions were a white disc that rose from behind the footer and
+ * slid or shrank away; each read as the disc travelling with the scroll
+ * (2026-09-03/04), hence the fade-only rule, and on 2026-09-05 the disc was
+ * dropped for a plain chevron. The stylesheets key everything off one attribute,
  * `data-aia-visible`: present → opacity 1, absent → opacity 0, both
  * transitioned.
  *

package/dist/index.d.ts

@@ -8,10 +8,9 @@ interface CompletedParam {
 interface SuggestionOption {
     text: string;
     /**
-     * Icon for the option. When `icon_svg` is also set this is the icon's name
-     * (an identifier such as `"apple"`, exposed on the row as `data-aia-icon`)
-     * and the SVG is what renders. Without `icon_svg` it is legacy display text
-     * (an emoji, say) drawn as a prefix to `text`.
+     * The icon's name — an identifier such as `"apple"`, exposed on the row as
+     * `data-aia-icon` when its `icon_svg` draws. Never rendered as text: a row
+     * without a drawable `icon_svg` shows `text` alone.
      */
     icon?: string;
     /**
@@ -1587,9 +1586,11 @@ declare function scrollCaretIntoView(root: HTMLElement): void;
  */
 declare function sanitizeOptionIconSvg(markup: string): string | null;
 /**
- * The text an option row shows. With `icon_svg` the icon draws as its own
- * element and `icon` is just its name; without it, a legacy `icon` (an emoji
- * from an option override, say) is display text prefixed to the option.
+ * The text an option row shows: its `text`, alone. `icon` is the icon's name
+ * (`"apple"`), an identifier for `data-aia-icon` and consumer CSS, never
+ * display text — so it is not prefixed to the option, whether `icon_svg`
+ * came with it, failed to draw, or was switched off. A row whose icon cannot
+ * draw shows the text by itself rather than the icon's name.
  */
 declare function optionLabel(option: {
     text: string;
@@ -1655,10 +1656,11 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
 /**
  * The "more below" arrow for the options grid.
  *
- * When the option list is taller than its scroll box, a small round button
- * with a down chevron sits at the bottom-centre of the list and scrolls it a
- * page on click. It never moves — every appearance is an opacity fade in
- * place, SCROLL_ARROW_FADE_MS long (the stylesheets own the curve):
+ * When the option list is taller than its scroll box, a bare down chevron
+ * sits at the bottom-centre of the list and scrolls it a page on click. It
+ * never travels with the scroll — every appearance is an opacity fade in
+ * place, SCROLL_ARROW_FADE_MS long, and its only motion is the stylesheets'
+ * slow idle bob of a few pixels (the stylesheets own both curves):
  *
  * - At rest with more below (the list just opened, or scrolling has stopped
  *   short of the end), it fades in.
@@ -1667,9 +1669,10 @@ declare function renderEditableContent(args: RenderEditableArgs): void;
  * - Once scrolling has been quiet for SCROLL_ARROW_SCROLL_IDLE_MS it fades
  *   back in — unless the list is now at its bottom, where it stays out.
  *
- * Earlier versions rose from behind the footer and slid or shrank away; each
- * read as the disc travelling with the scroll (2026-09-03/04), hence the
- * fade-only rule. The stylesheets key everything off one attribute,
+ * Earlier versions were a white disc that rose from behind the footer and
+ * slid or shrank away; each read as the disc travelling with the scroll
+ * (2026-09-03/04), hence the fade-only rule, and on 2026-09-05 the disc was
+ * dropped for a plain chevron. The stylesheets key everything off one attribute,
  * `data-aia-visible`: present → opacity 1, absent → opacity 0, both
  * transitioned.
  *