@magicx-eng/ai-autocomplete-react 0.20.0 → 0.21.1

package/README.md

@@ -286,7 +286,7 @@ Skip `<AIAutocompleteDropdown />` and render the suggestions UI yourself. `dropd
 
 > **Datepicker in a custom UI.** For a date parameter, `dropdownProps.formatType` is `"date"` and `suggestions[0].options` 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 — `onSelect` behaves exactly as it does for an option. To draw an actual calendar, read `dateView` for the month on show, `cellDay(option)` for the number to paint, and call `onPreviousMonth` / `onNextMonth` to page. Cells that pad the start and end of the month have `is_tappable: false`. For a **range** parameter `formatType` is `"date-range"` and the same `onSelect` fires twice: the first records the start (`dropdownProps.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 calendar does.
 
-> **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.
 
 ```tsx
 import { useAIAutocomplete } from "@magicx-eng/ai-autocomplete-react";
@@ -721,9 +721,13 @@ Tier 2 consumers who build their own submit payload get the raw skips from the h
 
 Styles are auto-injected at runtime — no CSS import needed. Built-in light and dark defaults apply automatically based on `mode`.
 
+Every class name the package emits is namespaced — `aia-*` for its own (hashed CSS-module) classes and the layout primitives, `magicx-aia-*` for the classes it shares with the vanilla core — 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. Use the `--aia-*` variables and `data-aia-*` selector hooks below for overrides.
+
+**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.
+
 ### CSS Variables
 
-Override on the container (via `className`). All defaults use `:where()` (zero specificity) — your overrides always win.
+Override on the container (via `className`). The variables are declared with `:where()` (zero specificity), so a value you set on the container always wins.
 
 | Variable | Light | Dark | Description |
 |---|---|---|---|
@@ -800,6 +804,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 Tier 1 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 |
@@ -821,7 +826,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.
 
 ```css
 /* Solid (non-glass) dropdown */