@reliability-design/web 1.4.1 → 1.4.2

package/CHANGELOG.md

@@ -1,22 +1,22 @@
-# Changelog — @reliability-design/web
-
-## 1.4.1 (2026-07-27)
-
-### Fixed
-
-- **Restored all 1.3.x design-token names removed by 1.4.0.** The RelDS 2.0 token rework in 1.4.0 renamed the token taxonomy in `vars.css` and dropped 154 of the 169 custom properties that 1.3.x shipped (`--rel-color-*`, `--rel-colors-*`, `--rel-text-*`, `--rel-background-*`, `--rel-surface-*`, `--rel-spacing-space-*`, `--rel-fontSizes-*`, `--rel-borders-*`, …). Apps referencing those tokens in their own CSS got unresolved `var()`s and lost colors/spacing/type across the board. 1.4.1 appends a **V1 compat alias block** to `vars.css`: every 1.3.x token name resolves again, pointing at its RelDS 2.0 equivalent (or its literal 1.3.x value where 2.0 has no counterpart). No import changes needed — `vars.css` remains the only stylesheet.
-
-### Upgrading
-
-- Your lockfile pins the currently resolved version, so a plain `npm i` will **not** pick this up. Run `npm update @reliability-design/web` or `npm i @reliability-design/web@latest`.
-- Works from any 1.x range: `^1.3.0` and `^1.4.0` both admit 1.4.1.
-
-### Notes
-
-- The restored V1 names are **deprecated aliases** — removal is targeted for 3.0. Migrate consumer CSS to the RelDS 2.0 semantic tokens (`--rel-text-*`, `--rel-bg-*`, `--rel-border-*`, `--rel-action-*`, `--rel-spacing-*`, …).
-- Aliased tokens follow the RelDS 2.0 **dark palette** (neutral grays). Dark-mode shades therefore differ slightly from 1.3.x's blue-tinted darks; light mode matches 1.3.x closely. Typography scale, spacing, radii, and stroke widths are value-identical to 1.3.x.
-
-## 1.4.0 (2026-07-24)
-
-- RelDS 2.0 token rework: `vars.css` regenerated from Figma (`RelDS_A1`) with a new semantic token taxonomy; all components repointed to semantic tokens; structural parity with the 2.0 Figma spec.
-- **Known issue (fixed in 1.4.1):** removed the 1.3.x token names without aliases, breaking consumer apps that referenced them.
+# Changelog — @reliability-design/web
+
+## 1.4.1 (2026-07-27)
+
+### Fixed
+
+- **Restored all 1.3.x design-token names removed by 1.4.0.** The RelDS 2.0 token rework in 1.4.0 renamed the token taxonomy in `vars.css` and dropped 154 of the 169 custom properties that 1.3.x shipped (`--rel-color-*`, `--rel-colors-*`, `--rel-text-*`, `--rel-background-*`, `--rel-surface-*`, `--rel-spacing-space-*`, `--rel-fontSizes-*`, `--rel-borders-*`, …). Apps referencing those tokens in their own CSS got unresolved `var()`s and lost colors/spacing/type across the board. 1.4.1 appends a **V1 compat alias block** to `vars.css`: every 1.3.x token name resolves again, pointing at its RelDS 2.0 equivalent (or its literal 1.3.x value where 2.0 has no counterpart). No import changes needed — `vars.css` remains the only stylesheet.
+
+### Upgrading
+
+- Your lockfile pins the currently resolved version, so a plain `npm i` will **not** pick this up. Run `npm update @reliability-design/web` or `npm i @reliability-design/web@latest`.
+- Works from any 1.x range: `^1.3.0` and `^1.4.0` both admit 1.4.1.
+
+### Notes
+
+- The restored V1 names are **deprecated aliases** — removal is targeted for 3.0. Migrate consumer CSS to the RelDS 2.0 semantic tokens (`--rel-text-*`, `--rel-bg-*`, `--rel-border-*`, `--rel-action-*`, `--rel-spacing-*`, …).
+- Aliased tokens follow the RelDS 2.0 **dark palette** (neutral grays). Dark-mode shades therefore differ slightly from 1.3.x's blue-tinted darks; light mode matches 1.3.x closely. Typography scale, spacing, radii, and stroke widths are value-identical to 1.3.x.
+
+## 1.4.0 (2026-07-24)
+
+- RelDS 2.0 token rework: `vars.css` regenerated from Figma (`RelDS_A1`) with a new semantic token taxonomy; all components repointed to semantic tokens; structural parity with the 2.0 Figma spec.
+- **Known issue (fixed in 1.4.1):** removed the 1.3.x token names without aliases, breaking consumer apps that referenced them.

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

@@ -0,0 +1,94 @@
+# 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).
+
+## Usage
+
+```html
+<!-- Local items (strings) -->
+<rel-autocomplete id="carrier" label="Carrier" prefix-icon="search" 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));
+</script>
+
+<!-- Object items with icons -->
+<script>
+  ac.items = [
+    { value: "air", label: "Air", icon: "air" },
+    { value: "sea", label: "Sea", icon: "ship" },
+  ];
+</script>
+
+<!-- Custom fields for arbitrary API shapes -->
+<rel-autocomplete display-field="name" value-field="id"></rel-autocomplete>
+
+<!-- Remote data -->
+<script>
+  ac.searchFn = async (query) => {
+    const res = await fetch(`/api/carriers?q=${encodeURIComponent(query)}`);
+    return res.json(); // (string | object)[]
+  };
+</script>
+```
+
+## 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`, `floating-label`, `prefix-icon`, `disabled`, `readonly`, `required`, `error`, `error-message`, `helper-text`, `name`, `full-width` | — | — | Passed through to the inner `rel-textfield` unchanged |
+
+## 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 |
+
+## Keyboard Interactions
+
+- 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
+
+## Accessibility
+
+- 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
+
+## 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`