@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-autocomplete/README.md

@@ -1,97 +1,208 @@
 # rel-autocomplete
 
-## Overview
-
-A searchable single-select type-ahead field ("autocomplete") for searchable-dropdown and searchbar scenarios. Composes `rel-textfield` for all field chrome (label, sizes, variants, states, icons) and adds a suggestion panel with keyboard navigation, loading / no-results states, and clear/reset.
-
-Two data modes:
-
-- **Local** — provide `items`; typing filters them client-side (`filter` mode).
-- **Remote** — provide a `searchFn`; input is debounced (`debounce-ms`), queries are latest-wins (stale responses are discarded), and local filtering is bypassed (results arrive pre-filtered).
+`<rel-autocomplete>` is a searchable single-select type-ahead field. It composes `rel-textfield` for all field chrome (label, sizes, variants, states, prefix icon, helper / error text) and adds a suggestion panel with keyboard navigation, loading and no-results rows, and an optional clear affordance. Two data modes: **local** — set `items` and typing filters them client-side (`filter`); **remote** — set `searchFn` and input is debounced (`debounce-ms`), queries are latest-wins and local filtering is bypassed. Use it for searchable dropdowns and search bars over lists too long for `rel-select`; for a short fixed list use `rel-select`, and for plain free text use `rel-textfield`.
 
 ## Usage
 
 ```html
 <!-- Local items (strings) -->
-<rel-autocomplete id="carrier" label="Carrier" prefix-icon="search" clearable></rel-autocomplete>
+<rel-autocomplete id="carrier" label="Carrier" prefix-icon="search" placeholder="Start typing" clearable></rel-autocomplete>
 <script>
   const ac = document.getElementById("carrier");
   ac.items = ["FedEx Freight", "UPS Freight", "XPO Logistics", "Estes Express"];
   ac.addEventListener("changed", (e) => console.log(e.detail.value, e.detail.item));
+  ac.addEventListener("rel-change", (e) => console.log("typed:", e.detail));
 </script>
 
-<!-- Object items with icons -->
+<!-- Object items with icons, read through display-field / value-field -->
+<rel-autocomplete id="mode" label="Mode" display-field="name" value-field="id"></rel-autocomplete>
 <script>
-  ac.items = [
-    { value: "air", label: "Air", icon: "air" },
-    { value: "sea", label: "Sea", icon: "ship" },
+  document.getElementById("mode").items = [
+    { id: "air", name: "Air", icon: "air" },
+    { id: "sea", name: "Sea", icon: "ship" },
+    // dulled, skipped by arrow keys, ignores clicks
+    { id: "rail", name: "Rail", icon: "intermodal", disabled: true },
   ];
 </script>
 
-<!-- Custom fields for arbitrary API shapes -->
-<rel-autocomplete display-field="name" value-field="id"></rel-autocomplete>
+<!-- Filtering and limits -->
+<rel-autocomplete label="City" filter="starts-with" max-suggestions="8" min-search-length="2"></rel-autocomplete>
 
-<!-- Remote data -->
+<!-- Remote data: debounced, latest-wins -->
+<rel-autocomplete id="remote" label="Customer" debounce-ms="250" loading-text="Searching…" no-results-text="No customers match"></rel-autocomplete>
 <script>
-  ac.searchFn = async (query) => {
-    const res = await fetch(`/api/carriers?q=${encodeURIComponent(query)}`);
+  const remote = document.getElementById("remote");
+  remote.searchFn = async (query) => {
+    const res = await fetch(`/api/customers?q=${encodeURIComponent(query)}`);
     return res.json(); // (string | object)[]
   };
+  remote.addEventListener("rel-search-error", (e) => console.warn(e.detail.query, e.detail.error));
 </script>
+
+<!-- Field chrome passthroughs -->
+<rel-autocomplete label="Small underline" size="small" variant="underline"></rel-autocomplete>
+<rel-autocomplete label="Floating label" label-style="floating" helper-text="Pick a carrier"></rel-autocomplete>
+<rel-autocomplete label-style="none" placeholder="Search orders" field-aria-label="Search orders"></rel-autocomplete>
+<rel-autocomplete label="Required" required error error-message="Choose a carrier from the list"></rel-autocomplete>
+<rel-autocomplete label="Read only" value="UPS Freight" readonly></rel-autocomplete>
+<rel-autocomplete label="Disabled" disabled></rel-autocomplete>
+<rel-autocomplete label="Inline width" full-width name="carrier"></rel-autocomplete>
+```
+
+### Deprecated aliases
+
+```html
+<!-- floating-label → label-style="floating" (kept permanently as an alias; no console notice) -->
+<rel-autocomplete label="Old spelling" floating-label></rel-autocomplete>
+<rel-autocomplete label="Canonical" label-style="floating"></rel-autocomplete>
 ```
 
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-autocomplete.ts — do not edit; run readme-generate.mjs -->
+
 ## API
 
-### Attributes/Properties
-
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `(string \| object)[]` | `[]` | Local suggestion list. Objects are read through `display-field` / `value-field`; an `icon` field renders a leading `rel-icon` on the row |
-| `value` | `string` | `""` | Committed value — the selected item's `value-field` string. Typing alone does not change it; selection (or an exact label/value match on Enter/blur) does. Settable externally: the field shows the matching item's label, or the raw string when unknown |
-| `display-field` | `string` | `"label"` | Object key used as the row label |
-| `value-field` | `string` | `"value"` | Object key used as the committed value |
-| `filter` | `"contains" \| "starts-with" \| "none"` | `"contains"` | Local filtering mode. `"none"` shows `items` as-is (use when the app pre-filters). Ignored when `searchFn` is set |
-| `searchFn` | `(query: string) => Promise<items>` | — | Property-only. Async data source; enables debounce + loading + latest-wins handling |
-| `debounce-ms` | `number` | `300` | Debounce before `searchFn` fires |
-| `min-search-length` | `number` | `1` | Minimum typed characters before the panel opens / `searchFn` fires. `0` opens on focus showing all items |
-| `max-suggestions` | `number` | `Infinity` | Optional cap on rendered rows (the panel scrolls regardless) |
-| `clearable` | `boolean` | `false` | Trailing ✕ clears text + value, emits `rel-clear` and `changed` |
-| `loading` | `boolean` | `false` | Externally-controlled loading row (internal `searchFn` loading is automatic) |
-| `no-results-text` | `string` | `"No results found"` | Row shown when a query yields nothing |
-| `loading-text` | `string` | `"Loading…"` | Text next to the loading spinner |
-| `label`, `placeholder`, `size`, `variant`, `label-style`, `floating-label`, `field-aria-label`, `field-aria-labelledby`, `prefix-icon`, `disabled`, `readonly`, `required`, `error`, `error-message`, `helper-text`, `name`, `full-width` | — | — | Passed through to the inner `rel-textfield` unchanged |
-| `label-style` | `"default" \| "floating" \| "none"` | — | Label presentation. `"none"` renders no label — pair it with `field-aria-label`. Unset, the deprecated `floating-label` boolean decides |
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `items` | `(string \| Record<string, unknown>)[]` | `[]` | Local (or fallback initial) suggestion list. Ignored while searchFn drives results. Object items are read through `displayField` / `valueField` plus the fixed keys `icon`, `disabled` and `supportingText` (the last renamable via `supporting-field`); `supportingText` renders as a second line in the row and is matched by the filter alongside the label. |
+| `value` | `value` | `string` | `""` | Committed value — the selected item's valueField string ("" = none). |
+| `displayField` | `display-field` | `string` | `"label"` | Object key read for the row label when items are objects. |
+| `valueField` | `value-field` | `string` | `"value"` | Object key read for the committed value when items are objects. |
+| `supportingField` | `supporting-field` | `string` | `"supportingText"` | Object key read for the row's optional second line. Defaults to `supportingText`, the fixed key `rel-select` and `rel-radio` already use; point it elsewhere when your records cannot be reshaped. |
+| `filter` | `filter` | `"contains" \| "starts-with" \| "none"` | `"contains"` | Local filtering mode. Ignored when searchFn is set (results arrive pre-filtered). |
+| `searchFn` | — | `(query: string) => Promise<AutocompleteItem[]>` | `undefined` | Async data source. When set, local filtering is bypassed entirely. Property only. |
+| `debounceMs` | `debounce-ms` | `number` | `300` | Debounce for searchFn calls, in ms. |
+| `minSearchLength` | `min-search-length` | `number` | `1` | Minimum typed characters before the panel opens / searchFn fires. 0 = open on focus. |
+| `maxSuggestions` | `max-suggestions` | `number` | `Infinity` | Optional cap on rendered suggestions (panel scrolls regardless). |
+| `multiple` | `multiple` | `boolean` | `false` | Multi-select mode: rows become checkboxes with a Select-all row, and the committed values live in `selectedValues` rather than `value`. Mirrors `rel-select`'s `multiple` rather than introducing a second pattern. THE TEXT INPUT STAYS A SEARCH BOX. In single mode the input shows the selected label, which is the point of a type-ahead; in multi mode there is no single label to show, and writing a value list into the field would destroy the query the user is typing. `rel-select` can put chips inside its trigger because a trigger is not an editable surface — an input is. So the chips render beneath the field, the query clears after each toggle so the next search starts fresh, and the panel stays open. Reflected. |
+| `selectedValues` | `selected-values` | `string[]` | `[]` | Committed values in `multiple` mode (ignored otherwise). Mirrors `rel-select.selectedValues`. |
+| `selectAllLabel` | `select-all-label` | `string` | `"Select all"` | Label of the Select-all row shown at the top of the panel in `multiple` mode. |
+| `clearable` | `clearable` | `boolean` | `false` | Shows a trailing ✕ that clears the text and the committed value. |
+| `loading` | `loading` | `boolean` | `false` | Externally-controlled loading state (internal searchFn loading is automatic). |
+| `noResultsText` | `no-results-text` | `string` | `"No results found"` | Row shown when a query yields nothing. |
+| `loadingText` | `loading-text` | `string` | `"Loading…"` | Text shown next to the spinner while suggestions load. |
+| `label` | `label` | `string` | `undefined` | Visible label, forwarded to the inner `rel-textfield`. Also names the suggestion panel. |
+| `placeholder` | `placeholder` | `string` | `""` | Placeholder of the input, forwarded to the inner `rel-textfield`. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height — `small` 32px, `medium` 40px, `large` 48px — forwarded to the inner `rel-textfield`. Also drives the suggestion panel's row ramp. Reflected. |
+| `variant` | `variant` | `"default" \| "underline" \| "legend"` | `"default"` | Field chrome (`default` outlined, `underline`, `legend` notched outline), forwarded to the inner `rel-textfield`. |
+| `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `undefined` | Label presentation (`default` / `floating` / `none`), forwarded to the inner field. Left `undefined`, the deprecated `floatingLabel` decides. Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the input. Required when `labelStyle="none"`. |
+| `fieldAriaLabelledby` | `field-aria-labelledby` | `string` | `undefined` | IDREF list of external element(s) naming the input. Wins over `fieldAriaLabel`. |
+| `prefixIcon` | `prefix-icon` | `string` | `undefined` | Leading `rel-icon` name in the field's prefix block, e.g. `search`. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the field; the panel never opens and the clear affordance is hidden. |
+| `readonly` | `readonly` | `boolean` | `false` | Read-only field: focusable but not editable; the panel never opens and the clear affordance is hidden. |
+| `required` | `required` | `boolean` | `false` | Marks the input required (native `required` / `aria-required`, asterisk on the label). |
+| `error` | `error` | `boolean` | `false` | Puts the field in the error state (danger border, `aria-invalid`); pair with `errorMessage`. |
+| `errorMessage` | `error-message` | `string` | `undefined` | Text shown below the field instead of `helperText` while `error` is set. |
+| `helperText` | `helper-text` | `string` | `undefined` | Helper line below the field, linked to the input via `aria-describedby`. |
+| `name` | `name` | `string` | `undefined` | Form field name forwarded to the native input. |
+| `fullWidth` | `full-width` | `boolean` | `true` | Fills the parent width as a block element (default). Unset it to render inline at the content's natural width. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `floatingLabel` | `floating-label` | `boolean` | Use `labelStyle="floating"`. Kept permanently as an alias. |
+
+### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `focus` | `focus()` | Delegates focus to the inner textfield. |
 
 ## Events
 
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `changed` | `{ value: string, item: object \| string \| null }` | An item was selected (or cleared — `value: ""`, `item: null`). This is the form-value event (Angular CVA binds it) |
-| `rel-change` | `string` | Fired on every keystroke with the raw text — use for the controlled/remote pattern (fetch, then set `.items`) |
-| `rel-clear` | — | The clear (✕) affordance was used |
-| `rel-search-error` | `{ query, error }` | `searchFn` rejected — the panel shows the no-results state |
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `changed` | `{ value: this.selectedValues, item: null } / { value: this.value, item: item ? item.item : null }` | bubbles / composed | Fired when the committed value changes — an item was selected (click, Enter, or an exact text match on Enter / Tab / blur) or the field was cleared. Detail: `{ value, item }`, where `item` is the original string or object, or `null` after a clear. |
+| `rel-change` | `inputText / ""` | bubbles / composed | Fired on every keystroke with the raw input text as the detail (and with `""` after a clear). The committed `value` does not change until an item is selected. |
+| `rel-clear` | — | bubbles / composed | Fired when the clear icon empties a non-empty field (followed by `changed` and `rel-change`). No detail. |
+| `rel-search-error` | `{ query, error: err }` | bubbles / composed | Fired when `searchFn` rejects; the panel then shows the no-results row. Detail: `{ query, error }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `chips` | — |
+| `chip` | — |
+| `panel` | The suggestion listbox container (same node as `list`) |
+| `list` | Alias of `panel` |
+| `select-all` | — |
+| `option` | A suggestion row. Emitted in BOTH single and `multiple` mode, unlike the two parts below |
+| `option-label` | The row's first line (the matched label). SINGLE-SELECT ROWS ONLY |
+| `option-supporting-text` | The row's optional second line, rendered only when the item supplies one. SINGLE-SELECT ROWS ONLY — under `multiple` the row is a nested `rel-checkbox` and the second line is that component's own `helper` part, inside its shadow root with nothing forwarding it out, so it cannot be reached with `::part()` at all. Style both modes with the `--rel-*` tokens instead |
+| `label` | The inner field's label (re-exported from `rel-textfield`) |
+| `control` | The inner field's bordered control box (re-exported from `rel-textfield`) |
+| `input` | The inner native input (re-exported from `rel-textfield`) |
+| `helper` | The inner field's helper / error line (re-exported from `rel-textfield`) |
+| `right-icon` | The clear icon shown when `clearable` (re-exported from `rel-textfield`) |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-autocomplete-bg` | `var(--rel-bg-neutral)` | Panel and row background |
+| `--rel-autocomplete-divider` | `transparent` | Hairline between rows |
+| `--rel-autocomplete-icon-color` | `var(--rel-text-default)` | Colour of a row's leading `icon` |
+| `--rel-autocomplete-menu-border` | `var(--rel-border-default)` | Panel border colour. The panel is borderless by design and only draws this on dark surfaces, where its shadow alone can't separate it from the page. |
+| `--rel-autocomplete-menu-max-height` | `360px` | Scroll ceiling of the suggestion panel; default `360px`. Code-owned rather than Figma-derived — every Figma Menu variant hugs its content with no ceiling, which is not shippable for an unbounded result list. |
+| `--rel-autocomplete-menu-radius` | `var(--rel-border-radius-xs)` | Panel corner radius |
+| `--rel-autocomplete-menu-shadow` | `var(--rel-shadows-md)` | Panel box-shadow |
+| `--rel-autocomplete-option-hover` | `var(--rel-action-overlay-hover)` | Background of the hovered / keyboard-highlighted / selected row |
+| `--rel-autocomplete-option-pressed` | `var(--rel-action-overlay-pressed)` | Background of a row while it is being pressed |
+| `--rel-autocomplete-status-color` | `var(--rel-text-body)` | Colour of the loading / no-results status rows |
+| `--rel-autocomplete-supporting-color` | `var(--rel-text-caption)` | — |
+| `--rel-autocomplete-value-color` | `var(--rel-text-default)` | Suggestion label colour |
+
+<!-- readme-gen:end -->
 
-## Keyboard Interactions
+## Accessibility
 
-- Typing — filters (local) or queries (remote) and opens the panel
-- `Arrow Down` / `Arrow Up` — open the panel / move the highlight
-- `Enter` — selects the highlighted row; with no highlight, commits an exact label/value match, otherwise keeps the free text and closes
-- `Escape` — closes the panel without touching the text
-- `Tab` — commits an exact match, closes, and moves on
+- Combobox pattern: a wrapper around the inner field carries `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` and `aria-activedescendant` (the highlighted row). The role sits on the wrapper rather than the `<input>` because the input lives in `rel-textfield`'s nested shadow root, which `aria-activedescendant` cannot reference across — the pragmatic pattern for composed shadow components.
+- The panel is `role="listbox"` named by the visible `label` (or `field-aria-label` under `label-style="none"`, falling back to "Suggestions"); rows are `role="option"` with `aria-selected` on the committed value. The loading row is `role="status"`.
+- Field-level semantics come from `rel-textfield`: `<label for>`, `aria-required`, `aria-invalid`, `aria-describedby` on the helper / error line. With `label-style="none"` the inner field logs a console warning once if neither `field-aria-label` nor `field-aria-labelledby` is set.
+- The clear affordance (`clearable`) is the inner field's clickable trailing icon: `role="button"`, focusable, labelled "Clear".
+- Screen-reader announcements via the shared `announce()` helper: `"Loading suggestions"` when the loading row appears, `"{label}, i of n"` while arrowing through rows, `"N results available"` when results change, and the `no-results-text` when a query yields nothing.
+- Disabled and read-only fields never open the panel and hide the clear icon.
 
-## Accessibility
+| Key | Action |
+|-----|--------|
+| Typing | Filters local items or queries `searchFn`, and opens the panel once the query reaches `min-search-length` |
+| `ArrowDown` | Open the panel (if the query is long enough) or move the highlight down |
+| `ArrowUp` | Move the highlight up |
+| `Enter` | Select the highlighted row; with no highlight, commit an exact label / value match, otherwise keep the free text and close |
+| `Escape` | Close the panel without touching the text |
+| `Tab` | Commit an exact match (if any), close, and move focus on |
 
-- Combobox pattern: `role="combobox"` with `aria-expanded`, `aria-controls`, and `aria-activedescendant`; panel is `role="listbox"` with `role="option"` rows
-- Known limitation: the combobox role sits on a wrapper around the field rather than on the `<input>` itself — the input lives in `rel-textfield`'s nested shadow root, which `aria-activedescendant` cannot reference across. This is the standard pragmatic pattern for composed shadow components
-- Loading row uses `role="status"`; disabled/readonly never open the panel
-- With `label-style="none"` no `<label>` renders, so `field-aria-label` (or `field-aria-labelledby`) must supply the accessible name — it also names the suggestion panel. A placeholder is not a valid naming mechanism; the inner field logs a console warning when both are missing
+Focus: `focus()` on the host delegates to the inner field. Focusing the field with `min-search-length="0"` (or with a query already long enough and matching items) opens the panel. Focus leaving the component commits an exact match and closes the panel; the same happens on an outside pointerdown. After a clear, focus returns to the field.
 
 ## Notes / Edge Cases
 
-- The matched substring in each row renders bold
-- `value` set externally to a string not present in `items` displays the raw string (common with remote data on init); provide the item in `items` to show its label instead
-- `searchFn` rejection is treated as an empty result plus a `rel-search-error` event — the component never throws into the app
-- Form validation is *displayed* (`error`, `error-message`, `required`), not performed — validity logic belongs to the form layer (e.g. Angular validators)
-- CSS parts: `panel`, `list`, `option`, plus re-exported textfield parts (`label`, `control`, `input`, `helper`, `right-icon`)
-- Panel styling matches `rel-select`'s listbox; override via `--rel-autocomplete-bg`, `--rel-autocomplete-menu-border`, `--rel-autocomplete-menu-radius`, `--rel-autocomplete-menu-shadow`, `--rel-autocomplete-option-hover`
-- The open panel is promoted to the browser **top layer** (native Popover API, `popover="manual"`), so it renders correctly inside transformed / `overflow: hidden` containers — a centered `rel-modal`, a bottom `rel-drawer`. Engines without the Popover API fall back to `position: fixed` with a measure-and-cancel correction for transformed ancestors
+- **The second line is searchable, and that changes which rows appear.** `supportingText` is matched by the filter alongside the label, because the identifiers it usually carries (a DOT or MC number, a code) are the reason to show it at all. An item whose label does not match but whose supporting text does will now appear in the list, and the matched characters are emboldened on whichever line they were found. Set `filter="none"` or drop `supportingText` if you need the previous label-only behaviour.
+- The second line truncates with an ellipsis rather than wrapping — the panel is pinned to the field's width, and a suggestion row is a fixed-height scanning target. Rows grow from 32 / 40 / 48 to roughly 46 / 58 / 70 when an item supplies one; a row without `supportingText` is unchanged.
+- **In `multiple` mode the text input stays a search box.** It never displays the committed values: in single mode the input shows the selected label, but in multi there is no single label to show, and writing a value list into the field would overwrite the query being typed. The chips therefore render *beneath* the field (`rel-select` can carry them inside its trigger because a trigger is not editable), the query clears after each toggle so the next search starts fresh, and the panel stays open. Read the selection from `selectedValues`, not `value`; `changed` carries the array.
+- `value` and the visible text are separate: typing only emits `rel-change`; `value` (and `changed`) update when a row is picked, or when the text exactly matches an item's label or value (case-insensitive) on Enter, Tab, blur or outside click. Free text that matches nothing stays in the field but never becomes `value`.
+- Setting `value` externally (attribute, property, Angular `writeValue`) shows the matching item's label, or the raw string when no item matches (common with remote data on init) — provide the item in `items` to show its label.
+- Clearing emits, in order, `rel-clear`, `changed` (`value: ""`, `item: null`) and `rel-change` (`""`), and only when the field actually had text or a value.
+- Remote mode: `items` is ignored while `searchFn` has produced results; a shorter-than-minimum query cancels any in-flight request and closes the panel; stale responses are discarded (latest-wins); a rejected `searchFn` is treated as an empty result plus `rel-search-error` — the component never throws into the app.
+- `loading` is an external flag layered on top of the automatic `searchFn` loading state; the loading row is shown while either is true.
+- `max-suggestions` caps rendered rows only; the panel scrolls (360px max height) regardless. The matched substring in each row renders bold.
+- Validation is displayed (`error`, `error-message`, `required`) but not performed; validity logic belongs to the form layer.
+- `full-width` layout is keyed off the **attribute** (`:host(:not([full-width]))` renders inline-block) even though the property defaults to `true` and is not reflected — add the `full-width` attribute in markup when you need the block layout. This differs from `rel-textfield`, whose `fullwidth` attribute is reflected.
+- The suggestion panel mirrors `rel-select`'s listbox (same tokens, radius, shadow, row styling) and is promoted to the browser top layer (native Popover API, `popover="manual"`), so it renders correctly inside transformed or `overflow: hidden` containers such as a centered `rel-modal` or a `rel-drawer`; engines without the Popover API fall back to `position: fixed` with a measure-and-cancel correction. It matches the field width, flips above when short on space, and closes on outside pointerdown or outside scroll.
+- Only `label`, `control`, `input`, `helper` and `right-icon` are re-exported from the inner `rel-textfield`; its `prefix` / `suffix` parts and slots are not exposed.
+- The field passthroughs are a fixed subset, forwarded as **property** bindings (`.prefixIcon=${…}`), so they are unaffected by attribute-spelling differences between the two components. `rel-textfield` props outside that subset — `prefixText`, `prefixStyle`, `suffixText`, `suffixDivider`, `helperIcon`, `maxLength`, `multiline`, `rows`, `type` — are not forwarded and cannot be set through `rel-autocomplete`.
+- Several of the passthroughs take a **kebab attribute here and an all-lowercase one on `rel-textfield`**: `prefix-icon` / `prefixicon`, `helper-text` / `helpertext`, `error-message` / `errormessage`, `floating-label` / `floatinglabel`, `full-width` / `fullwidth`. Moving markup between the two elements therefore needs the attribute renamed, and a wrong spelling fails silently rather than erroring. `rel-textfield`'s README carries the full table; 3.0 unifies on the kebab spellings used here.

package/dist/components/rel-avatar/README.md

@@ -1,130 +1,118 @@
-# rel-avatar
-
-## Overview
-A circular avatar component supporting three display types: image, text initials, or custom icon content. Provides four size variants and three style variants (fill, subtle, outline), with automatic text transformation and SVG sizing for icons.
-
-## Usage
-```html
-<!-- Image avatar -->
-<rel-avatar
-  type="image"
-  src="./user-photo.jpg"
-  alt="John Doe">
-</rel-avatar>
-
-<!-- Text initials avatar -->
-<rel-avatar
-  type="text"
-  text="JD">
-</rel-avatar>
-
-<!-- Icon avatar with slotted SVG -->
-<rel-avatar type="icon">
-  <svg viewBox="0 0 24 24" fill="currentColor">
-    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
-  </svg>
-</rel-avatar>
-
-<!-- Different sizes -->
-<rel-avatar type="text" text="XS" size="xs"></rel-avatar>
-<rel-avatar type="text" text="SM" size="sm"></rel-avatar>
-<rel-avatar type="text" text="MD" size="md"></rel-avatar>
-<rel-avatar type="text" text="LG" size="lg"></rel-avatar>
-
-<!-- Style variants -->
-<rel-avatar type="text" text="AA" variant="fill"></rel-avatar>
-<rel-avatar type="text" text="AA" variant="subtle"></rel-avatar>
-<rel-avatar type="text" text="AA" variant="outline"></rel-avatar>
-
-<!-- User list with avatars -->
-<div style="display: flex; gap: 8px; align-items: center;">
-  <rel-avatar type="image" src="user1.jpg" size="sm"></rel-avatar>
-  <span>John Doe</span>
-</div>
-
-<!-- Avatar group -->
-<div style="display: flex; margin-left: -8px;">
-  <rel-avatar type="text" text="A" size="md" style="margin-left: -8px;"></rel-avatar>
-  <rel-avatar type="text" text="B" size="md" style="margin-left: -8px;"></rel-avatar>
-  <rel-avatar type="text" text="C" size="md" style="margin-left: -8px;"></rel-avatar>
-</div>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `size` (reflected) | `"lg" \| "md" \| "sm" \| "xs"` | `"md"` | Avatar size variant |
-| `type` (reflected) | `"image" \| "text" \| "icon"` | `"image"` | Display type |
-| `variant` (reflected) | `"fill" \| "subtle" \| "outline"` | `"fill"` | Style variant |
-| `src` | `string` | `""` | Image URL (for `type="image"`) |
-| `text` | `string` | `""` | Text content (for `type="text"`, usually initials) |
-| `alt` | `string` | `"Avatar"` | Alt text for the image |
-| `bg` | `string` | `""` | Direct CSS background-color override (any valid CSS color), takes precedence over `variant` |
-
-## Events
-None.
-
-## Slots
-| Slot | Description |
-|------|-------------|
-| (default) | Custom icon content (for `type="icon"`, typically an SVG) |
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-
-### Font Tokens
-- `--rel-headings-lg-font-size` - Large avatar text size
-- `--rel-body-xl-regular-font-size` - Medium avatar text size
-- `--rel-body-md-regular-font-size` - Small avatar text size
-- `--rel-body-xs-regular-font-size` - Extra small avatar text size
-- `--rel-fonts-weight-body-semibold` - Text font weight
-
-### Color Tokens (by variant)
-- **fill** (default): `--rel-avatar-bg-fill` (default `--rel-text-disabled`), `--rel-avatar-color-fill` (default `#ffffff`)
-- **subtle**: `--rel-avatar-bg-subtle` (default `--rel-bg-neutral-elevated-1`), `--rel-avatar-color-subtle` (default `--rel-text-label`)
-- **outline**: `--rel-avatar-bg-outline` (default `--rel-bg-surface`), `--rel-avatar-border-outline` (default `--rel-border-default`), `--rel-avatar-color-outline` (default `--rel-text-label`)
-- `--rel-stroke-sm` - Border width (all variants; `fill`/`subtle` use a transparent border to keep sizing consistent)
-
-All of the above semantic tokens (`--rel-bg-*`, `--rel-text-label`, `--rel-border-*`, `--rel-text-disabled`) have dark-mode overrides defined in `vars.css` under `:root[data-theme="dark"]`, so all three variants automatically adapt to dark mode with no extra configuration.
-
-## Accessibility
-- Image avatars include `alt` attribute for screen readers
-- Text is automatically uppercased for consistency
-- Ensure meaningful `alt` text is provided for image avatars
-
-### Keyboard Interactions
-- None (purely presentational)
-
-### Focus Behavior
-- Does not receive focus
-
-## Notes / Edge Cases
-- **Size variants**:
-  - **lg**: 40px × 40px, font-size: `--rel-headings-lg-font-size`
-  - **md**: 32px × 32px, font-size: `--rel-body-xl-regular-font-size`
-  - **sm**: 24px × 24px, font-size: `--rel-body-md-regular-font-size`
-  - **xs**: 18px × 18px, font-size: `--rel-body-xs-regular-font-size`
-
-- **Display types**:
-  - **image**: Displays an `<img>` with `src` and `alt`
-    - Uses `object-fit: cover` for proper image scaling
-    - Image is `width: 100%`, `height: 100%`
-  - **text**: Displays the `text` property in a `<span>`
-    - Text is automatically uppercased via `text-transform: uppercase`
-  - **icon**: Displays slotted content (typically SVG)
-    - Slotted SVGs are automatically sized to 50% of the avatar size
-
-- The avatar is always circular via `border-radius: 50%`
-- The avatar uses `overflow: hidden` to clip images to circle shape
-- Text and icons are centered using flexbox
-- The avatar is `inline-flex` for easy inline usage with text
-- The `size` and `type` attributes are reflected in HTML
-- The component uses `user-select: none` to prevent text selection
-- If `type` is `image` but `src` is empty, nothing is displayed (no fallback)
+# rel-avatar
+
+`<rel-avatar>` is the circular identity mark of the Figma "Avatar" component: a 20–40px disc that shows a photo (`type="image"`), uppercase initials (`type="text"`) or a slotted icon (`type="icon"`), in a solid `fill`, a neutral `subtle` or a bordered `outline` variant. Use it wherever a person, team or account needs a compact visual identity — user menus, comment threads, assignee columns, stacked avatar groups. It is purely presentational: it takes no focus and emits no events, so wrap it in a button or link when it should be clickable, and overlay a `rel-badge` when it needs a status or count.
+
+## Usage
+
+```html
+<!-- Image avatar (always pass a meaningful alt) -->
+<rel-avatar type="image" src="./user-photo.jpg" alt="Priya Natarajan"></rel-avatar>
+
+<!-- Initials -->
+<rel-avatar type="text" text="PN"></rel-avatar>
+
+<!-- Slotted icon -->
+<rel-avatar type="icon">
+  <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+    <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"/>
+  </svg>
+</rel-avatar>
+
+<!-- Sizes: xs 20px, sm 24px, md 32px (default), lg 40px -->
+<rel-avatar type="text" text="XS" size="extra-small"></rel-avatar>
+<rel-avatar type="text" text="SM" size="small"></rel-avatar>
+<rel-avatar type="text" text="MD" size="medium"></rel-avatar>
+<rel-avatar type="text" text="LG" size="large"></rel-avatar>
+
+<!-- Variants -->
+<rel-avatar type="text" text="AA" variant="fill"></rel-avatar>
+<rel-avatar type="text" text="AA" variant="subtle"></rel-avatar>
+<rel-avatar type="text" text="AA" variant="outline"></rel-avatar>
+
+<!-- Inline colour overrides (any CSS colour) -->
+<rel-avatar type="text" text="JD" bg="#1d4ed8" color="#ffffff"></rel-avatar>
+
+<!-- Stacked group -->
+<div style="display: flex; padding-left: 8px;">
+  <rel-avatar type="text" text="A" style="margin-left: -8px;"></rel-avatar>
+  <rel-avatar type="text" text="B" style="margin-left: -8px;"></rel-avatar>
+  <rel-avatar type="text" text="C" style="margin-left: -8px;"></rel-avatar>
+</div>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-avatar.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "extra-small" \| "lg" \| "md" \| "sm" \| "xs"` | `"medium"` | Diameter step: `large` 40px, `medium` 32px, `small` 24px, `extra-small` 20px; each binds the matching body-*-semibold text role for initials. `lg` / `md` / `sm` / `xs` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. Reflected. |
+| `type` | `type` | `"image" \| "text" \| "icon"` | `"image"` | What is rendered inside the circle: `image` shows `src`, `text` shows the `text` initials, `icon` shows the default slot. Reflected. |
+| `variant` | `variant` | `"fill" \| "subtle" \| "outline"` | `"fill"` | Fill style: `fill` = solid inverse background with light text, `subtle` = elevated neutral background, `outline` = transparent with a 1px border. Reflected. |
+| `src` | `src` | `string` | `""` | Image URL for `type="image"`; when empty nothing is rendered inside the circle (there is no fallback to initials). |
+| `text` | `text` | `string` | `""` | Initials shown for `type="text"`; rendered uppercase via `text-transform`. |
+| `alt` | `alt` | `string` | `"Avatar"` | Alt text of the `<img>` for `type="image"`; the default is the generic word "Avatar", so pass the person's name. |
+| `bg` | `bg` | `string` | `""` | Any CSS colour applied inline as `background-color` on the circle, overriding the variant background. |
+| `color` | `color` | `string` | `""` | Any CSS colour applied inline as `color` on the circle (initials / icon), overriding the variant text colour. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Icon content rendered when `type="icon"` (typically an inline SVG, sized 20 / 18 / 16 / 12px by `size`) |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The circular wrapper that carries the size, variant and inline `bg` / `color` overrides |
+| `icon` | The `<img>` (`type="image"`) or the icon wrapper span around the slot (`type="icon"`) |
+| `label` | The `<span>` holding the initials when `type="text"` |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-avatar-bg-fill` | `var(--rel-bg-neutral-inverse-2)` | Background colour of the `fill` variant |
+| `--rel-avatar-bg-outline` | `var(--rel-bg-neutral)` | Background colour of the `outline` variant; defaults to --rel-bg-neutral |
+| `--rel-avatar-bg-subtle` | `var(--rel-bg-neutral-elevated-1)` | Background colour of the `subtle` variant |
+| `--rel-avatar-border-outline` | `var(--rel-border-default)` | 1px border colour of the `outline` variant |
+| `--rel-avatar-color-fill` | `var(--rel-text-inverse)` | Text / icon colour of the `fill` variant |
+| `--rel-avatar-color-outline` | `var(--rel-text-default)` | Text / icon colour of the `outline` variant |
+| `--rel-avatar-color-subtle` | `var(--rel-text-default)` | Text / icon colour of the `subtle` variant |
+| `--rel-avatar-font-size` | `var(--_rel-avatar-font-size)` | Overrides the initials' font-size, for use alongside `--rel-avatar-size`; defaults to the preset's text role |
+| `--rel-avatar-icon-size` | `var(--_rel-avatar-icon-size)` | Overrides the slotted icon's size; defaults to the preset ramp (20 / 18 / 16 / 12px) |
+| `--rel-avatar-size` | `var(--_rel-avatar-size)` | Overrides the circle's width/height for sizes between (or below) the `size` presets; defaults to the preset's diameter |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The host has no ARIA role and no keyboard handling, and it is never focusable. Put it inside a `<button>` or `<a>` when it should be interactive and give that element the accessible name.
+- `type="image"` renders a real `<img>` whose alt text comes from the `alt` prop. The default is the generic word "Avatar" — pass the person's name, or an empty string when the avatar sits next to visible text with the same name.
+- `type="text"` renders the initials as plain text in the `label` part, so screen readers read the letters ("P N"). If the initials alone are meaningless, add `aria-hidden="true"` and keep the full name in nearby text.
+- `type="icon"` slots your SVG unchanged; add `aria-hidden="true"` to decorative icons or a `<title>` to meaningful ones.
+- The three variants differ only by colour; every colour used has a dark-mode value in `vars.css`, so no extra theming is needed.
+
+## Notes / Edge Cases
+
+- The disc is `border-radius: 50%` with `overflow: hidden`; images use `object-fit: cover`, so non-square sources are centre-cropped rather than stretched.
+- `type="image"` with an empty `src` renders an empty circle — there is no automatic fallback to initials. Switch `type` yourself when the photo is missing.
+- Every variant keeps a 1px border (`--rel-stroke-sm`); `fill` and `subtle` make it transparent so the outer size is identical across variants.
+- `bg` and `color` are written as inline styles on the `base` part, so they win over both the `--rel-avatar-*` hooks and the variant tokens.
+- Initials are forced uppercase and `user-select: none`. `size`, `type` and `variant` are reflected, so `rel-avatar[size="large"]` works as a selector. Because `lg` / `md` / `sm` / `xs` are normalised to the full words before reflection, the selector matches whichever spelling was written.
+- The `icon` part name is shared by the `<img>` (`type="image"`) and the slot wrapper (`type="icon"`); `::part(icon)` matches whichever one is rendered.