@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,122 +1,185 @@
 # rel-select
 
-## Overview
-A custom combobox-style select component built on the same textfield visual language (sizes, states, border styles). Renders a typeable text trigger with a custom-styled dropdown listbox (no native `<select>`/`<option>` rendering), so the dropdown is fully themeable in both light and dark mode. Supports icons, multiple states, and sizes, with built-in keyboard navigation, type-to-filter, and an inline "ghost text" autocomplete suggestion.
+`<rel-select>` is the combobox-style dropdown from the Figma "Dropdown" component: a text-field-styled trigger button that opens a custom listbox (never a native `<select>`, so it is fully themeable in light and dark mode). It supports single- and multi-select, an optional in-panel search field, a Select-all row in multi mode, and width-adaptive selection chips that collapse into a "+N" chip instead of wrapping. Use it to pick one or several values from a known list. For free text use `rel-textfield`; for type-ahead against a large or remote list use `rel-autocomplete`; for two or three mutually exclusive options `rel-radio` is usually clearer.
 
 ## Usage
+
 ```html
-<!-- Basic example -->
-<rel-select id="countrySelect" label="Country" selected="USA"></rel-select>
+<!-- Single select -->
+<rel-select id="country" label="Country" placeholder="Select a country"></rel-select>
 <script>
-  const select = document.getElementById('countrySelect');
-  select.options = ['USA', 'Canada', 'Mexico'];
+  const country = document.getElementById("country");
+  country.options = ["USA", "Canada", "Mexico"];
+  country.addEventListener("changed", (e) => console.log(e.detail.value)); // "Canada"
 </script>
 
-<!-- Example with common options -->
+<!-- Object options: value / label / icon / supportingText (supportingText shows in multi-select rows only) -->
+<script>
+  country.options = [
+    { value: "air", label: "Air freight", icon: "air" },
+    { value: "sea", label: "Sea freight", icon: "ship", supportingText: "4-6 weeks" },
+  ];
+</script>
+
+<!-- Preselected value, helper text, icons -->
+<rel-select label="Email preference" selected="weekly" supporting-text="How often we email you" left-icon="mail"></rel-select>
+<rel-select label="Custom chevron" right-icon="expand-more"></rel-select>
+
+<!-- Sizes, corners, label styles -->
+<rel-select label="Small" size="small"></rel-select>
+<rel-select label="Large" size="large"></rel-select>
+<rel-select label="Sharp corners" border="sharp"></rel-select>
+<rel-select label="Floating label" label-style="floating"></rel-select>
+<rel-select label-style="none" placeholder="Filter by status" field-aria-label="Filter by status"></rel-select>
+
+<!-- States -->
+<rel-select label="Region" state="error" supporting-text="Pick a region to continue"></rel-select>
+<rel-select label="Locked" state="disabled" selected="USA"></rel-select>
+
+<!-- Short list without a search field (Figma "Single Option" dropdown) -->
+<rel-select label="Priority" no-search></rel-select>
+
+<!-- Multi-select with chips, Select-all and a search placeholder -->
 <rel-select
-  id="emailPreference"
-  label="Email Preference"
-  selected="Weekly"
-  size="medium"
-  state="default"
-  supportingText="Choose how often you want to receive emails"
-  leftIcon="📧">
+  id="tags"
+  label="Tags"
+  multiple
+  selected-values='["urgent","fragile"]'
+  select-all-label="Select all tags"
+  search-placeholder="Search tags"
+  max-visible-chips="3">
 </rel-select>
 <script>
-  const emailPref = document.getElementById('emailPreference');
-  emailPref.options = ['Daily', 'Weekly', 'Monthly', 'Never'];
+  const tags = document.getElementById("tags");
+  tags.options = ["urgent", "fragile", "hazmat", "oversize", "refrigerated"];
+  tags.addEventListener("changed", (e) => console.log(e.detail.value)); // ["urgent", "fragile", ...]
 </script>
 ```
 
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-select.ts — do not edit; run readme-generate.mjs -->
+
 ## API
 
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | `""` | Label text displayed above the select |
-| `label-style` | `"default" \| "floating" \| "none"` | `"default"` | Label presentation. `"default"` sits above the trigger, `"floating"` rests over the placeholder and animates onto the border line, `"none"` renders no label at all |
-| `field-aria-label` | `string` | - | Accessible name for the trigger. Required with `label-style="none"` |
-| `field-aria-labelledby` | `string` | - | IDREF list of external element(s) naming the trigger. Wins over `field-aria-label` |
-| `options` | `(string \| SelectOptionObject)[]` | `[]` | Options to display in the dropdown. Each entry is either a plain string or an object: `{ value, label?, supportingText?, icon? }`. `icon` is a `rel-icon` name rendered as a prefix (leading icon) on the menu item — before the label in single-select rows, and between the checkbox and label in multi-select rows |
-| `selected` | `string` | `""` | Currently selected option value |
-| `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state of the select |
-| `supportingText` | `string` | `""` | Helper or error text displayed below the select |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Size variant affecting padding and font size |
-| `border` | `"rounded" \| "sharp"` | `"rounded"` | Border radius style |
-| `leftIcon` | `string` | `""` | `rel-icon` name displayed on the left side |
-| `rightIcon` | `string` | `""` | `rel-icon` name to override the default right-side icon. When unset, a chevron is shown that rotates 180° on open; a custom `rightIcon` replaces the chevron entirely and does not rotate |
-| `placeholder` | `string` | `"Select option"` | Placeholder text shown when nothing is selected |
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `""` | Visible label. Rendered above the trigger (`labelStyle="default"`) or floating inside it; omitted under `labelStyle="none"`. |
+| `labelStyle` | `label-style` | `"default" \| "floating" \| "none"` | `"default"` | Label presentation: `default` static label above the trigger; `floating` label rests in the value area and floats onto the border when focused, open or filled; `none` renders no label (supply `fieldAriaLabel` / `fieldAriaLabelledby`). Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the trigger. Required when `labelStyle="none"`, since no `<label>` renders and a placeholder is not a valid naming mechanism. |
+| `fieldAriaLabelledby` | `field-aria-labelledby` | `string` | `undefined` | IDREF list of external element(s) naming the trigger. Wins over `fieldAriaLabel`. |
+| `options` | `options` | `(string \| SelectOptionObject)[]` | `[]` | Options to list. Each entry is a plain string (used as both value and label) or `{ value, label?, supportingText?, icon? }`; `icon` is a `rel-icon` name rendered before the label, `supportingText` renders as a second line in both single- and multi-select rows. NOTE — the panel's search matches the LABEL ONLY. `supportingText` is displayed but not searched, so an option is not findable by its second line here. This differs deliberately from `rel-autocomplete`, whose filter matches the supporting line as well: there the second line carries identifying data (a DOT or MC number) that a user types to find the row, whereas a select's is descriptive ("Read-only", "Can edit, not delete") and matching it would return rows whose visible label has nothing to do with the query. |
+| `multiple` | `multiple` | `boolean` | `false` | Enables multi-select: selected values render as removable chips, options as checkboxes, and a Select-all row appears in the panel. |
+| `selected` | `selected` | `string` | `""` | Selected option value in single-select mode. Ignored when `multiple` is set. |
+| `selectedValues` | `selected-values` | `string[]` | `[]` | Selected option values in multi-select mode. Reset to `[]` when `multiple` is turned off. |
+| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual / interaction state. `error` colours the border and supporting text and clears itself on the next selection; `disabled` blocks interaction and dims the whole field. |
+| `supportingText` | `supporting-text` | `string` | `""` | Helper line below the trigger; coloured as an error while `state="error"`. |
+| `supportingIcon` | `supporting-icon` | `string` | `""` | `rel-icon` name shown before the supporting text (16px, 14px at `small`). Optional: the design pairs the helper line with an icon, but existing fields without one keep their current single-line look. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Field height — `small` 32px, `medium` 40px, `large` 48px. The whole component rides this one axis: label and supporting type, trigger padding, icons (20 / 18 / 16), selection chips, and the panel's rows, search field and checkboxes all scale with it. Reflected. |
+| `border` | `border` | `"rounded" \| "sharp"` | `"rounded"` | Trigger corners: `rounded` applies the corner radius, `sharp` renders square corners. |
+| `leftIcon` | `left-icon` | `string` | `""` | `rel-icon` name rendered at the left edge of the trigger. |
+| `rightIcon` | `right-icon` | `string` | `""` | `rel-icon` name replacing the default chevron at the right edge of the trigger. A custom icon does not rotate when the panel opens. |
+| `placeholder` | `placeholder` | `string` | `"Select option"` | Text shown in the trigger while nothing is selected. |
+| `searchPlaceholder` | `search-placeholder` | `string` | `"Search option"` | Placeholder of the in-panel search field (the field is hidden when `noSearch` is set). |
+| `selectAllLabel` | `select-all-label` | `string` | `"Select all"` | Label of the Select-all row shown at the top of the panel in multi-select mode. |
+| `maxVisibleChips` | `max-visible-chips` | `number` | `Infinity` | Optional hard cap on visible chips. By default (no cap) the visible count adapts to the trigger's width: chips collapse into the "+N" badge one by one instead of wrapping to a second line. |
+| `noSearch` | `no-search` | `boolean` | `false` | DELIBERATE DIVERGENCE — do not default this to `!multiple`. Figma's `.Menu Dropdown` shows the search row only on `Type=Multioption`; its `Type=Single Option` panels contain five Select Option items and nothing else. Here the search row renders for single-select too unless this is set. Ruled by the user: our behaviour stands and the DESIGN FILE follows our docs. A long single-select list is unusable without search, and making the default depend on `multiple` would change the panel of every existing single-select. |
 
 ## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `changed` | `{ value: string }` | Fired when the selected value changes |
 
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `changed` | `{ value: this.multiple ? this.selectedValues : this.selected }` | bubbles / composed | Fired after any selection change (pick, checkbox toggle, Select-all, chip removal). Detail: `{ value }` — the selected value string in single mode, or the array of selected values when `multiple`. |
 
-## Tokens / CSS Variables
+## Slots
 
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-xs-regular-font-size`, `--rel-body-sm-regular-font-size`, `--rel-body-md-regular-font-size` - Font sizes for different size variants
-- `--rel-fonts-weight-body-medium` - Font weight for label
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
 
-### Spacing Tokens
-- `--rel-spacing-3xs`, `--rel-spacing-2xs`, `--rel-spacing-xs` - Internal padding
-- `--rel-spacing-sm`, `--rel-spacing-md`, `--rel-spacing-xl`, `--rel-spacing-2xl` - Padding and icon positioning
+## CSS Parts
 
-### Color Tokens
-- `--rel-text-label` - Label and selected-value text color
-- `--rel-text-default` - Icon color, focus border/shadow color
-- `--rel-text-placeholder` - Placeholder, supporting text, and ghost-suggestion text color
-- `--rel-text-disabled` - Disabled text/icon color
-- `--rel-border-default` - Default border color
-- `--rel-bg-surface` - Background color (trigger and dropdown panel)
-- `--rel-bg-neutral-elevated-1` - Disabled background, hovered/highlighted option background
-- `--rel-bg-danger` - Error state border, text, and icon color (light: `#D50000`, dark: `#FF5252`)
-- `--rel-shadows-shadow-200` - Dropdown panel shadow
+| Part | Description |
+| --- | --- |
+| `label` | The visible label above the trigger (default label style) |
+| `trigger` | The button that opens the panel; styled like a text field |
+| `value` | The value area inside the trigger (selected label, placeholder or chips) |
+| `helper` | The supporting / error text below the trigger |
+| `panel` | The dropdown listbox container (same node as `list`) |
+| `list` | Alias of `panel` |
+| `input` | The search input inside the panel |
+| `option` | A single-select option row |
+| `option-label` | A single-select row's first line (the option label) |
+| `option-supporting-text` | A single-select row's optional second line; rendered only when the option supplies `supportingText` |
 
-### Border Tokens
-- `--rel-border-radius-xs` - Rounded border radius (default `border="rounded"`)
+## Tokens / CSS Variables
 
-### Layout Tokens
-- `--rel-field-label-reserve` - Height held for the absent label row under `label-style="none"`, so the trigger bottom-aligns with labelled siblings. Defaults to the label line-height plus the wrapper gap; set to `0` to collapse the row entirely in compact contexts (toolbars, table cells)
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-field-label-reserve` | `calc(var(--rel-body-md-regular-line-height) + var(--rel-spacing-2xs))` | Height held for the label row whenever no label renders above the trigger — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the trigger — so the trigger still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells). |
+| `--rel-select-bg` | `var(--rel-bg-neutral)` | Background of the trigger, the floating label, the panel and its sticky header |
+| `--rel-select-bg-disabled` | `var(--rel-bg-neutral-elevated-2)` | Trigger background when `state="disabled"` |
+| `--rel-select-border-default` | `var(--rel-border-default)` | Trigger border colour at rest |
+| `--rel-select-border-disabled` | `var(--rel-border-accent)` | Trigger border colour when `state="disabled"` |
+| `--rel-select-border-error` | `var(--rel-border-danger)` | Trigger border colour when `state="error"` |
+| `--rel-select-border-focus` | `var(--rel-border-strong)` | Trigger border colour on hover, while focused (where it also thickens to 2px) and while the panel is open |
+| `--rel-select-divider` | `var(--rel-border-subtle)` | Hairline under the search field, the Select-all row and every option row |
+| `--rel-select-icon-color` | `var(--rel-text-default)` | Colour of the trigger icons, the search icon and option prefix icons |
+| `--rel-select-label-color` | `var(--rel-text-label)` | Colour of the static label and of the floated label |
+| `--rel-select-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-select-menu-radius` | `var(--rel-border-radius-sm)` | Panel corner radius |
+| `--rel-select-menu-shadow` | `var(--rel-shadows-md)` | Panel box-shadow |
+| `--rel-select-option-hover` | `var(--rel-action-overlay-hover)` | Background of the hovered / keyboard-highlighted / selected option and Select-all row |
+| `--rel-select-option-pressed` | `var(--rel-action-overlay-pressed)` | Background of an option row while it is being pressed |
+| `--rel-select-placeholder-color` | `var(--rel-text-placeholder)` | Placeholder colour (trigger, resting floating label, search field, empty-list message) |
+| `--rel-select-placeholder-disabled-color` | `var(--rel-text-caption)` | Placeholder colour when disabled |
+| `--rel-select-radius` | `var(--rel-border-radius-xs)` | Trigger corner radius when `border="rounded"` |
+| `--rel-select-search-border` | `var(--rel-border-default)` | Border colour of the search field inside the panel |
+| `--rel-select-supporting-color` | `var(--rel-text-body)` | Supporting text colour (non-error) |
+| `--rel-select-value-color` | `var(--rel-text-default)` | Colour of the selected value, the search text, option labels and the check mark |
+
+<!-- readme-gen:end -->
 
 ## Accessibility
-- Trigger input uses `role="combobox"` with `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls`
-- Dropdown panel uses `role="listbox"`; each option uses `role="option"` with `aria-selected`
-- `aria-activedescendant` tracks the keyboard-highlighted option
-- Label properly associated with the trigger via `for`/`id`
-- Disabled state prevents interaction and reduces opacity
-- Error state communicated through color and supporting text
-
-### Keyboard Interactions
-- Typing - Filters the dropdown to matching options and shows an inline "ghost text" suggestion for the best prefix match
-- `→ (Arrow Right)` - When the cursor is at the end of the input, accepts the current ghost-text suggestion
-- `Enter` - Opens the dropdown (if closed); if open, selects the highlighted option, or commits the typed text if it exactly matches an option
-- `Arrow Up/Down` - Open dropdown (if closed) or move the highlighted option
-- `Home/End` - Jump to first/last filtered option (when open)
-- `Escape` - Revert input text to the committed value and close the dropdown
-- `Tab` - Accept any ghost suggestion, commit or revert the typed text, close the dropdown, and move focus to the next element
-
-### Focus Behavior
-- Clear focus ring with primary color via `box-shadow` on the container (`:focus-within`)
-- Trigger input is a normal editable text field with a visible caret
+
+- The trigger is a native `<button role="combobox">` with `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` (the listbox id) and `aria-invalid` (true in the error state). Its accessible name is composed as `"{label}, {selected label}"` in single mode and `"{label}, a, b, c, plus N more"` in multi mode (first three labels), so the current selection is always announced with the name. `field-aria-labelledby` replaces that computed name entirely.
+- The static label (`label-style="default"`) is a `<label for>` linked to the trigger. The floating label is a visual `<span>`; the trigger's `aria-label` still carries the name. With `label-style="none"` the name comes from `field-aria-label` and a console warning is logged once if neither `field-aria-label` nor `field-aria-labelledby` is set.
+- The panel is `role="listbox"` with `aria-multiselectable` and an `aria-label` of the field name (or "Options"). Every row is `role="option"` with `aria-selected`; multi-select rows and the Select-all row carry an explicit `aria-label` and contain an `inert`, `aria-hidden` `rel-checkbox` used purely as the visual.
+- The in-panel search input is itself a `role="combobox"` with `aria-expanded`, `aria-controls` and `aria-activedescendant` tracking the highlighted row. With `no-search` the trigger keeps focus while open and carries `aria-activedescendant` instead.
+- Screen-reader announcements via the shared `announce()` helper: `"{label} selected"` / `"{label} deselected"` on a checkbox toggle, `"All options selected"` / `"All options deselected"`, `"{label} removed"` when a chip is removed, and `"N options available"` / `"No matches found"` / `"No options available"` while typing in the search field.
+- Focus: opening the panel moves focus to the search input (with `preventScroll`) unless `no-search`; closing always returns focus to the trigger. Chips render inside the trigger `<button>`, so their remove buttons are not Tab stops — Backspace / Delete is the keyboard path.
+
+| Key | Action |
+|-----|--------|
+| `ArrowDown` / `ArrowUp` / `Enter` / `Space` (closed) | Open the panel |
+| `Backspace` / `Delete` (closed, `multiple`) | Remove the most recently selected chip |
+| `ArrowDown` / `ArrowUp` (open) | Move the highlight; in multi mode the Select-all row is a virtual first row above the options |
+| `Home` / `End` (open) | Jump to the first / last filtered option |
+| `Enter` (open) | Select the highlighted option (single), toggle it (multi) or toggle Select-all |
+| `Space` (open, `no-search` only) | Same as Enter; with a search field Space types into it |
+| `Escape` (open) | Close the panel and return focus to the trigger |
+| `Tab` (open) | Close the panel, then focus moves on normally |
+| `Backspace` in an empty search field (`multiple`) | Remove the most recently selected chip |
+| Typing (search field) | Filters options by case-insensitive substring; the first match is highlighted |
+| Printable keys (`no-search`) | APG type-ahead: keys accumulate for 500 ms and jump to the next option whose label starts with the buffer |
 
 ## Notes / Edge Cases
-- When `state="disabled"`, the select becomes non-interactive with reduced opacity and cursor indication
-- Empty `selected` value shows the `placeholder` text ("Select option" by default)
-- Icons (left/right) adjust internal padding automatically to accommodate icon space
-- The chevron is always visible on the far right and rotates 180° when the dropdown is open; a custom `rightIcon` replaces it entirely (no chevron) and does not rotate
-- In error state, supporting text is styled with error color for visual consistency; the error state automatically clears once a valid option is selected
-- Options accept plain strings or `{ value, label?, supportingText?, icon? }` objects; string entries use the same text for value and label
-- In multi-select, selected chips stay on a single line: the number of visible chips adapts to the field's width and the rest collapse into a trailing "+N" chip (recomputed on selection changes and via `ResizeObserver` on resize). At least one chip is always shown. `max-visible-chips` is an optional additional hard cap (uncapped by default)
-- An option's `icon` renders only when set — options without one simply omit the prefix icon (no reserved empty space), and an unknown icon name logs a `rel-icon` console warning and renders nothing
-- Typed text that doesn't exactly match (case-insensitive) any option reverts to the last committed `selected` value on blur, Escape, or Tab
-- The ghost-text suggestion shows the remainder of the first option whose name starts with the typed text (case-insensitive); it has no effect on filtering, which matches substrings anywhere in an option
-- Dropdown panel is positioned via `position: fixed` and flips above the trigger if there isn't enough viewport space below
-- The open listbox 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 change event is named `changed` (not `rel-change`); `detail.value` is a string in single mode and an array of strings when `multiple`.
+- Opening the panel does not pre-highlight any row; the highlight appears on the first hover or arrow key so nothing reads as an unintended default.
+- `state="error"` clears itself to `"default"` on the next selection, toggle, Select-all or chip removal. `state="disabled"` dims the whole field to 50% opacity, makes chips non-removable and blocks pointer events on them.
+- Turning `multiple` off resets `selectedValues` to `[]`. `selected` is ignored in multi mode and `selectedValues` in single mode.
+- Chips never wrap: the number shown adapts to the trigger width (measured through a hidden copy of every chip and a `ResizeObserver`), with the remainder collapsed into a trailing "+N" chip. At least one chip always stays visible; `max-visible-chips` is an extra hard cap. A selected value with no matching option is shown as its raw value.
+- Option `icon` renders in both single and multi rows; `supportingText` only in multi rows. An unknown icon name logs a `rel-icon` warning and renders nothing (no reserved space).
+- A custom `right-icon` replaces the chevron and does not rotate when the panel opens; the default chevron rotates 180°.
+- The search field uses the small field sizing for both `small` and `medium` selects; only `large` bumps it to medium. Empty results show "No matches found" (or "No options available" when `options` is empty).
+- The `helper` part exists only while `supporting-text` is non-empty.
+- The open listbox 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. The panel matches the trigger width, flips above the trigger when there is not enough room below, is capped at 360px with internal scrolling, and closes on any outside pointerdown or outside scroll (scrolling the list itself does not close it).
+- `--rel-field-label-reserve` (see Component hooks) keeps a `label-style="none"` select bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
+- The trigger heights (32 / 40 / 48px) match `rel-textfield` and the date / time / range picker triggers so mixed form rows line up.