@reliability-design/web 1.4.6 → 1.4.7

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

@@ -1,141 +1,145 @@
-# rel-alert
-
-## Overview
-A versatile alert component for displaying informational, success, warning, error, or neutral messages. Features built-in icons, optional dismissibility, secondary message text, and inline links. Automatically hides when dismissed via the `dismissed` reflected attribute.
-
-## Usage
-```html
-<!-- Basic neutral alert -->
-<rel-alert
-  message1="This is a neutral alert"
-  type="neutral">
-</rel-alert>
-
-<!-- Info alert with secondary message -->
-<rel-alert
-  type="info"
-  message1="System Notification"
-  message2="Your settings have been updated successfully.">
-</rel-alert>
-
-<!-- Success alert -->
-<rel-alert
-  type="success"
-  message1="Operation Completed"
-  message2="Your data has been saved.">
-</rel-alert>
-
-<!-- Warning alert -->
-<rel-alert
-  type="warning"
-  message1="Warning"
-  message2="Please verify your input before continuing.">
-</rel-alert>
-
-<!-- Error alert -->
-<rel-alert
-  type="error"
-  message1="Error Occurred"
-  message2="Unable to process your request.">
-</rel-alert>
-
-<!-- With action link -->
-<rel-alert
-  type="info"
-  message1="Update Available"
-  message2="A new version is ready."
-  urlText="Learn More"
-  urlHref="https://example.com/release-notes">
-</rel-alert>
-
-<!-- Non-dismissible -->
-<rel-alert
-  type="warning"
-  message1="Required Action"
-  dismissible="false">
-</rel-alert>
-
-<!-- Listen for dismiss -->
-<rel-alert id="myAlert" type="success" message1="Success!"></rel-alert>
-<script>
-  const alert = document.getElementById('myAlert');
-  alert.addEventListener('dismiss', () => {
-    console.log('Alert was dismissed');
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `type` | `"info" \| "success" \| "warning" \| "error" \| "neutral"` | `"neutral"` | Alert type determining icon and color scheme |
-| `message1` | `string` | `""` | Primary message text (bold) |
-| `message2` | `string` | - | Optional secondary message text (smaller, slightly transparent) |
-| `urlText` | `string` | - | Link text (shown below messages) |
-| `urlHref` | `string` | - | Link URL (both `urlText` and `urlHref` required for link to show) |
-| `dismissible` | `boolean` | `true` | Whether to show the close (✕) button |
-| `dismissed` | `boolean` (reflected) | `false` | When true, hides the component via `:host([dismissed])` |
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `dismiss` | None | Fired when the close button is clicked (sets `dismissed` to true) |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-md-regular-font-size` - Primary message font size
-- `--rel-body-sm-regular-font-size` - Secondary message and link font size
-- `--rel-fonts-weight-body-medium` - Primary message and link font weight
-- `--rel-fonts-weight-body-semibold` - Used implicitly in link styling
-
-### Spacing Tokens
-- `--rel-spacing-xs` - Gap between icon and content
-- `--rel-spacing-sm` - Vertical padding
-- `--rel-spacing-md` - Horizontal padding
-- `--rel-spacing-2xs` - Close button padding
-
-### Color Tokens (by type)
-- **info**: `--rel-bg-info-light` (background), `--rel-text-info` (text), `--rel-text-info` (icon)
-- **success**: `--rel-bg-success-light`, `--rel-text-success`, `--rel-text-success`
-- **warning**: `--rel-bg-warning-light`, `--rel-text-warning`, `--rel-text-warning`
-- **error**: `--rel-bg-danger-light`, `--rel-text-error`, `--rel-text-danger`
-- **neutral**: `--rel-bg-surface` (background), `--rel-text-default` (text), `--rel-text-default` (icon), `--rel-border-default` (border)
-
-### Border Tokens
-- `--rel-border-radius-sm` - Border radius
-
-## Accessibility
-- Uses `role="alert"` for screen reader announcements
-- Close button has `aria-label="Dismiss"`
-- Focus visible states on close button with 2px outline
-- Secondary message has reduced opacity for visual hierarchy
-
-### Keyboard Interactions
-- `Tab` - Focus the close button (if dismissible)
-- `Space/Enter` - Dismiss the alert (when close button focused)
-
-### Focus Behavior
-- Close button shows 2px outline matching the alert's text color with 2px offset
-- Border radius applied to maintain visual consistency
-
-## Notes / Edge Cases
-- Icons are built-in SVG graphics that change based on `type` (info: ℹ️, success: ✓, warning: ⚠️, error: ❗, neutral: ℹ️)
-- Icon colors are controlled by type-specific `--rel-icon-*` tokens
-- The alert has a minimum width of `360px`
-- Both `urlText` and `urlHref` must be set for the link to appear
-- Links inherit the alert's text color and are underlined
-- `message2` has `opacity: 0.9` for subtle contrast with `message1`
-- When `dismissed` is set to `true`, the component applies `display: none` via `:host([dismissed])`
-- `dismissed` is a reflected attribute, meaning it appears in the HTML when true
-- The close button is always positioned at the right edge via `margin-left: auto`
-- Neutral type includes a 1px border while colored types do not
+# rel-alert
+
+`<rel-alert>` is the inline status banner of the Reliability Design System (Figma "Alert"). It renders a tone-coloured box with a leading status icon, a bold title (`message1`), optional supporting text (`message2`), an optional inline link and an optional dismiss button, in the Figma Tone (neutral / info / success / warning / destructive) and Style (subtle / solid / outline) variants. Use it for persistent, in-flow messages about a page or section — form-level validation, degraded-service notices, onboarding hints. For transient feedback that disappears on its own use `<rel-toast>` or `<rel-snackbar>`; for blocking decisions use `<rel-modal>`.
+
+## Usage
+
+```html
+<!-- Neutral (default tone, subtle appearance) -->
+<rel-alert message1="Scheduled maintenance on Sunday 02:00–04:00 UTC"></rel-alert>
+
+<!-- Tones -->
+<rel-alert tone="info" message1="Update available" message2="Version 2.3 adds offline mode."></rel-alert>
+<rel-alert tone="success" message1="Changes saved" message2="Your profile is up to date."></rel-alert>
+<rel-alert tone="warning" message1="Storage almost full" message2="You have used 95% of your quota."></rel-alert>
+<rel-alert tone="destructive" message1="Upload failed" message2="The file exceeds the 25 MB limit."></rel-alert>
+
+<!-- Appearance: subtle (default) | solid | outline -->
+<rel-alert tone="info" appearance="solid" message1="Solid alert"></rel-alert>
+<rel-alert tone="info" appearance="outline" message1="Outline alert"></rel-alert>
+
+<!-- Inline link: both url-text and url-href are required for it to render -->
+<rel-alert
+  tone="info"
+  message1="Release notes"
+  message2="See what changed in this version."
+  url-text="Read more"
+  url-href="https://example.com/release-notes"
+></rel-alert>
+
+<!-- Non-dismissible: the boolean must be cleared from script (see the js block) -->
+<rel-alert id="locked" tone="warning" message1="Action required"></rel-alert>
+
+<!-- Listen for dismissal -->
+<rel-alert id="saved" tone="success" message1="Saved"></rel-alert>
+```
+
+```js
+// A Lit boolean attribute is true whenever present, so dismissible="false" does NOT work.
+document.getElementById("locked").dismissible = false;
+
+const saved = document.getElementById("saved");
+saved.addEventListener("dismiss", () => {
+  saved.dismissed; // true — the host is now display: none
+});
+// Show it again later:
+saved.dismissed = false;
+```
+
+### Deprecated aliases
+
+```html
+<!-- type= is the deprecated alias of tone= (tone wins when both are set). Logs once per page:
+     [rel-alert] "type" is deprecated and will be removed in 3.0 — use "tone" instead. Note: tone="destructive" replaces type="error". -->
+<rel-alert type="error" message1="Upload failed"></rel-alert>
+
+<!-- tone="error" | "danger" | "critical" are deprecated spellings of tone="destructive". Logs once per spelling:
+     [rel-alert] "tone="error"" is deprecated and will be removed in 3.0 — use "tone="destructive"" instead. -->
+<rel-alert tone="error" message1="Upload failed"></rel-alert>
+<rel-alert tone="critical" message1="Upload failed"></rel-alert>
+
+<!-- appearance="filled" is the deprecated alias of appearance="solid" (no console notice). -->
+<rel-alert tone="info" appearance="filled" message1="Solid alert"></rel-alert>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-alert.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `tone` | `"neutral" \| "info" \| "success" \| "warning" \| "destructive" \| "error" \| "danger" \| "critical"` | `undefined` | Semantic tone (Figma "Tone"): `"neutral"` (default) \| `"info"` \| `"success"` \| `"warning"` \| `"destructive"`. Drives the fill/border colour, the title colour and the leading icon (info, check-circle, alert-circle, error). `"error"`, `"danger"` and `"critical"` are deprecated aliases of `"destructive"` and log a one-time console notice. Takes precedence over the deprecated `type` prop. |
+| `appearance` | `appearance` | `"solid" \| "subtle" \| "outline" \| "filled"` | `"subtle"` | Visual treatment (Figma "Style"): `"subtle"` (default: tone-light fill, no border) \| `"solid"` (tone fill, inverse text, `--rel-shadows-md` elevation) \| `"outline"` (transparent fill, tone border). `"filled"` is a deprecated alias of `"solid"` (no console notice). Reflected. |
+| `message1` | `message1` | `string` | `""` | Primary message (title), rendered in body-lg medium weight in the tone colour. |
+| `message2` | `message2` | `string` | `undefined` | Optional secondary message rendered under the title in body-md at 90% opacity; omitted when unset. |
+| `urlText` | `url-text` | `string` | `undefined` | Text of the inline link rendered under the messages. The link appears only when both `urlText` and `urlHref` are set. |
+| `urlHref` | `url-href` | `string` | `undefined` | `href` of the inline link. The link appears only when both `urlText` and `urlHref` are set. |
+| `dismissible` | `dismissible` | `boolean` | `true` | Shows the dismiss (✕) button. Defaults to true; because it is a Lit boolean, `dismissible="false"` is still true — set the property to `false` from script to hide the button. |
+| `dismissed` | `dismissed` | `boolean` | `false` | True once the alert has been dismissed; hides the host via `:host([dismissed]) { display: none }`. Set it back to `false` to show the alert again. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `type` | `type` | `"neutral" \| "info" \| "success" \| "warning" \| "destructive" \| "error" \| "danger" \| "critical"` | Deprecated since 1.4.7 — alias of `tone`; use `tone`. Same values as `tone`; `type="error"` maps to `tone="destructive"`. Ignored when `tone` is set. Logs a one-time console notice. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `resolvedTone` | `AlertTone` | Read-only canonical tone actually rendered: explicit `tone` wins, else `type`, else `"neutral"`; deprecated aliases are resolved to `"destructive"`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `dismiss` | — | bubbles / composed | Fired when the user clicks the dismiss button, after `dismissed` has been set to true. No detail. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The `role="alert"` container that carries the tone and appearance styling |
+| `icon` | Wrapper around the leading status `<rel-icon>` |
+| `content` | Column that stacks the title, helper text and link |
+| `label` | The primary message (`message1`) paragraph |
+| `helper` | The secondary message (`message2`) paragraph; rendered only when `message2` is set |
+| `action` | The inline link; rendered only when both `url-text` and `url-href` are set |
+| `close-button` | The dismiss (✕) button; rendered only while `dismissible` is true |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The container (part `base`) has `role="alert"` and `aria-atomic="true"`, so screen readers announce the whole message assertively when the element enters the DOM or its text changes. Because of that, reserve it for messages that warrant an interruption; render a `<rel-alert>` only when there is something to say rather than keeping an empty one mounted.
+- The leading status `<rel-icon>` renders `aria-hidden="true"`; the tone is not conveyed to assistive technology except through the text, so put the meaning in `message1` / `message2`.
+- The dismiss control is a native `<button>` with `aria-label="Dismiss"`. The inline link is a plain `<a href>`. Both are in the Tab order; the component adds no key handlers of its own:
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift + Tab | Move between the inline link (if any) and the dismiss button (if any) |
+| Enter / Space | Activate the focused dismiss button (fires `dismiss`, sets `dismissed`) |
+| Enter | Follow the focused link |
+
+- Keyboard focus on the dismiss button is a 2px `currentColor` outline with 2px offset (`:focus-visible` only).
+- Dismissing hides the host with `display: none`; focus is not moved, so if the dismiss button had focus the browser drops focus to `<body>`. Move focus yourself in the `dismiss` handler when the alert sits in the middle of a form.
+
+## Notes / Edge Cases
+
+- `tone` and `appearance` are independent axes; every tone renders in every appearance. Solid uses inverse text and carries the `--rel-shadows-md` elevation; subtle and outline have no shadow.
+- The status icon is fixed per tone (`info` for neutral and info, `check-circle`, `alert-circle`, `error`) and cannot be replaced or removed — there are no slots.
+- The alert has `min-width: 360px`; it stretches to its container (`display: block`) but never shrinks below that.
+- The link renders only when both `url-text` and `url-href` are set; it opens in the same tab (no `target`).
+- `dismissible` and `dismissed` are Lit booleans: any attribute value (including `"false"`) counts as true. Toggle them as properties from script.
+- `dismissed` only hides the host; the element stays in the DOM and keeps its state. Resetting `dismissed = false` shows it again without re-firing `dismiss`.
+- `resolvedTone` is the tone actually rendered after alias resolution; use it (not `tone` / `type`) if you branch on tone in script.

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

@@ -1,97 +1,192 @@
 # 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 read two keys directly whatever `display-field` / `value-field` are set to: `icon` (a `rel-icon` name shown before the label) and `disabled` (`true` dulls the row and makes it unselectable by click or keyboard). |
+| `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. |
+| `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). |
+| `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`. |
+| `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.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 |
+| --- | --- |
+| `panel` | The suggestion listbox container (same node as `list`) |
+| `list` | Alias of `panel` |
+| `option` | A suggestion row |
+| `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` | `var(--rel-border-subtle)` | 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-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-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
+- `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.