@magicx-eng/ai-autocomplete-vanilla 0.22.0 → 0.23.1

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`)
 
@@ -734,6 +734,10 @@ Constructor callbacks (`onSubmit`, `onChange`, etc.) are registered once at cons
 
 Styles are auto-injected at runtime (Tier 1 and Tier 2). No CSS import needed. The component ships built-in light and dark defaults.
 
+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).
+
 ### Shadow DOM
 
 Mount the container inside a shadow root and the widget works there — the stylesheet is injected into that root rather than `document.head`, and the caret is read from the root that owns the editor:
@@ -755,7 +759,7 @@ This is the way to embed the widget in a page whose CSS you don't control. In th
 
 ### CSS Variables
 
-Override these on the container element. All built-in defaults use `:where()` (zero specificity) — your overrides always win without `!important`.
+Override these on the container element. The variables are declared with `:where()` (zero specificity), so a value you set on the container always wins without `!important`.
 
 | Variable | Default (light) | Default (dark) | Description |
 |---|---|---|---|
@@ -837,6 +841,7 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 
 | Attribute | Element |
 |---|---|
+| `[data-aia-input-wrapper]` | Wrapper around the editor area and the submit button — one of the two roots the SDK isolates from page CSS (the dropdown is the other) |
 | `[data-aia-editor]` | Editor area wrapping the contentEditable + inline pill list |
 | `[data-aia-input]` | The contentEditable `<div>` that owns typed text and bold completed params. Replaces the previous `[data-aia-textarea]` selector. |
 | `[data-aia-pill-list-container]` | Inline sibling of the editor that holds unfilled-suggestion pills |
@@ -858,7 +863,7 @@ For styling beyond the CSS variables, target these stable `data-aia-*` attribute
 | `[data-aia-product]` | Each product card |
 | `[data-aia-product-placeholder]` | Media tile of a card whose product has no image |
 
-Completed params render as inline `<strong>` elements inside the editor. Override their weight with `[data-aia-input] strong { font-weight: 700; }` (the built-in style uses `:where()` so any consumer selector wins without `!important`).
+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.
 
 The vanilla core also exposes stable BEM class names (`magicx-aia-*`); both can be used.
 

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;

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;