@reliability-design/web 1.4.8 → 1.4.10

package/dist/components/rel-segmented-button/README.md

@@ -1,156 +1,158 @@
-# rel-segmented-button
-
-A single-select segmented button group: a row of buttons on a 2px-inset track where exactly one segment is active at a time. Each entry in `options` renders as a native `<button role="radio">` inside a `role="radiogroup"`, so the group behaves like a compact radio group (one Tab stop, arrow keys move the selection). Use it for mutually exclusive view or mode switches with two to five short options (list / grid, day / week / month, sort order); do not use it for navigation between pages (use `rel-tab`) or for actions (use `rel-button`).
-
-The control comes in three sizes that match the text field ramp — `small` 32px, `medium` 40px, `large` 48px — and each option can carry a leading `icon`.
-
-## Usage
-
-```html
-<!-- Basic: options are set as a property, `active` holds the selected value -->
-<rel-segmented-button id="view-mode" active="grid" field-aria-label="View mode"></rel-segmented-button>
-<script>
-  document.getElementById('view-mode').options = [
-    { label: 'List', value: 'list' },
-    { label: 'Grid', value: 'grid' },
-    { label: 'Table', value: 'table' }
-  ];
-</script>
-
-<!-- Options as a JSON attribute, small size -->
-<rel-segmented-button
-  size="small"
-  active="week"
-  field-aria-label="Calendar range"
-  options='[{"label":"Day","value":"day"},{"label":"Week","value":"week"},{"label":"Month","value":"month"}]'>
-</rel-segmented-button>
-
-<!-- Large size (48px), matching a large text field -->
-<rel-segmented-button
-  size="large"
-  active="grid"
-  field-aria-label="View mode"
-  options='[{"label":"List","value":"list"},{"label":"Grid","value":"grid"}]'>
-</rel-segmented-button>
-
-<!-- Leading icons: `icon` names a rel-icon, sized 16 / 18 / 20 with the control -->
-<rel-segmented-button
-  active="list"
-  field-aria-label="View mode"
-  options='[{"label":"List","value":"list","icon":"bullet-list"},{"label":"Grid","value":"grid","icon":"dashboard"}]'>
-</rel-segmented-button>
-
-<!-- Disabled option: rendered but not selectable or focusable -->
-<rel-segmented-button id="plan" active="free" field-aria-label="Plan"></rel-segmented-button>
-<script>
-  document.getElementById('plan').options = [
-    { label: 'Free', value: 'free' },
-    { label: 'Pro', value: 'pro' },
-    { label: 'Enterprise', value: 'enterprise', disabled: true }
-  ];
-</script>
-
-<!-- Alignment inside a wider host (align only matters when the host is stretched) -->
-<rel-segmented-button
-  style="display: block; width: 100%"
-  align="middle"
-  active="asc"
-  field-aria-label="Sort direction"
-  options='[{"label":"Ascending","value":"asc"},{"label":"Descending","value":"desc"}]'>
-</rel-segmented-button>
-
-<!-- Listen for changes -->
-<rel-segmented-button id="sort-order" active="newest" field-aria-label="Sort order"></rel-segmented-button>
-<script>
-  const sortOrder = document.getElementById('sort-order');
-  sortOrder.options = [
-    { label: 'Newest', value: 'newest' },
-    { label: 'Oldest', value: 'oldest' },
-    { label: 'Popular', value: 'popular' }
-  ];
-  sortOrder.addEventListener('changed', (e) => {
-    console.log('Selected:', e.detail.value);
-  });
-</script>
-```
-
-The `SegmentOption` interface and the `SegmentSize` / `SegmentAlign` unions are exported from the package:
-
-```typescript
-import type { SegmentOption } from '@reliability-design/web';
-
-const options: SegmentOption[] = [
-  { label: 'List', value: 'list' },                      // label = visible text, value = what `active` / the event carry
-  { label: 'Grid', value: 'grid', icon: 'dashboard' },   // icon = a rel-icon name, drawn before the label
-  { label: 'Archive', value: 'archive', disabled: true } // rendered at 50% opacity, skipped by the arrow keys
-];
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-segmented-button.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `options` | `options` | `SegmentOption[]` | `[]` | The segments in order, each `{ label: string; value: string; disabled?: boolean; icon?: string; badge?: number \| string \| boolean }`. Set as a property (or a JSON array attribute); a disabled entry is rendered but cannot be selected, and `icon` names a `rel-icon` drawn before the label. |
-| `active` | `active` | `string` | `""` | `value` of the currently selected segment. Updated by the component on click / arrow keys; set it to pre-select a segment (an unknown value selects nothing). |
-| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height, matching the TextField ramp: `small` (32px — 28px segments, `action-md` 12px text, 16px icons), `medium` (default, 40px — 36px segments, `action-lg` 14px text, 18px icons) or `large` (48px — 44px segments, `action-xl` 16px text, 20px icons). |
-| `align` | `align` | `"left" \| "middle" \| "right"` | `"left"` | `justify-content` of the group's inline-flex container: `left` (default), `middle` or `right`. Only visible when the host is made wider than its content. |
-| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `changed` | `{ value: option.value }` | bubbles / composed | Fired after a non-disabled segment is selected by click or arrow / Home / End key (also when it was already the active one). Detail: `{ value: string }`. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `option` | Each segment's native `<button role="radio">`; the active one carries the `active` class and `aria-checked="true"`. |
-| `icon` | A segment's optional leading `rel-icon` element. |
-| `label` | The wrapper around a segment's label text. |
-| `badge` | A segment's optional trailing `rel-badge`; rendered only when the option sets `badge`. |
-| `base` | The `role="radiogroup"` track that lays out the segments. |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- The container is a `role="radiogroup"`; give it a name with `field-aria-label` — the component renders no visible group label, so without it screen readers announce an unnamed group.
-- Every segment is a native `<button role="radio">` with `aria-checked="true"` on the active one and `aria-checked="false"` on the rest. Disabled options get the native `disabled` attribute, so they are not focusable and do not fire `click`.
-- Roving tabindex (APG radio-group pattern): the whole group is a single Tab stop. The active segment carries `tabindex="0"`; if `active` matches no enabled option, the first enabled segment takes the Tab stop instead (without becoming selected). All other segments are `tabindex="-1"`.
-- Arrow keys both move focus and select, so they emit `changed` immediately. Focus is moved to the newly active segment after the re-render.
-- Focus ring: a 2px `border-focus` outline drawn inside the segment (`outline-offset: -2px`) and raised with `z-index: 1` so it stays above the neighbouring segment.
-- Nothing is announced beyond the native `aria-checked` change.
-
-| Key | Action |
-| --- | --- |
-| `Tab` / `Shift+Tab` | Move focus into / out of the group (one stop, on the active segment) |
-| `ArrowRight` / `ArrowDown` | Select and focus the next enabled segment (wraps to the first) |
-| `ArrowLeft` / `ArrowUp` | Select and focus the previous enabled segment (wraps to the last) |
-| `Home` / `End` | Select and focus the first / last enabled segment |
-| `Enter` / `Space` | Native button activation: selects the focused segment |
-
-## Notes / Edge Cases
-
-- The change event is named `changed` (no `rel-` prefix, unlike most components); it bubbles and is composed, so it can be listened for on any ancestor. It also fires when the already-active segment is clicked again.
-- `active` is a plain string compared against `option.value`; setting it to a value that is not in `options` (or to a disabled option's value) renders no active segment.
-- `options` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
-- The host is `display: inline-block` and the group `inline-flex`, so it sizes to its content; `align` has no visible effect until the host is stretched (e.g. `style="display: block; width: 100%"`). Every segment has `min-width: 80px`, so a group is never narrower than 80px per segment.
-- Sizing: the track is a `bg-neutral` surface with `spacing-3xs` (2px) padding and a `border-radius-xs` corner — there is no outer border and no dividers between segments. Each segment carries the full `border-radius-xs` on all four corners in every state. Segment heights are 28 / 36 / 44 for `small` / `medium` / `large`, which with the 2px inset give control heights of 32 / 40 / 48.
-- Per size: padding `spacing-3xs spacing-sm` / `spacing-2xs spacing-md` / `spacing-xs spacing-lg`, text `action-md` (12px) / `action-lg` (14px) / `action-xl` (16px), and leading icons at 16 / 18 / 20px with an `spacing-xs` (8px) gap.
-- Colours: the active segment uses `action-neutral-fill` with inverse text (and `action-neutral-fill-hover` on hover); a non-active segment is transparent so the `action-overlay-hover` alpha composites over the track; disabled segments are drawn at 50% opacity with `bg-neutral-elevated-1` and a `not-allowed` cursor. Background and colour transitions are 0.2s.
-- A per-option `icon` renders a `rel-icon` before the label. Its size rides `--rel-icon-size` set directly on the `rel-icon` element — not on a wrapper, since `rel-icon` reflects `size="md"` and its own `:host([size])` rule would otherwise win.
-- No design-token overrides or `--rel-segmented-button-*` hooks are exposed; style through the `base` / `option` / `icon` / `label` parts.
+# rel-segmented-button
+
+A single-select segmented button group: a row of buttons on a 2px-inset track where exactly one segment is active at a time. Each entry in `options` renders as a native `<button role="radio">` inside a `role="radiogroup"`, so the group behaves like a compact radio group (one Tab stop, arrow keys move the selection). Use it for mutually exclusive view or mode switches with two to five short options (list / grid, day / week / month, sort order); do not use it for navigation between pages (use `rel-tab`) or for actions (use `rel-button`).
+
+The control comes in three sizes that match the text field ramp — `small` 32px, `medium` 40px, `large` 48px — and each option can carry a leading `icon`.
+
+## Usage
+
+```html
+<!-- Basic: options are set as a property, `active` holds the selected value -->
+<rel-segmented-button id="view-mode" active="grid" field-aria-label="View mode"></rel-segmented-button>
+<script>
+  document.getElementById('view-mode').options = [
+    { label: 'List', value: 'list' },
+    { label: 'Grid', value: 'grid' },
+    { label: 'Table', value: 'table' }
+  ];
+</script>
+
+<!-- Options as a JSON attribute, small size -->
+<rel-segmented-button
+  size="small"
+  active="week"
+  field-aria-label="Calendar range"
+  options='[{"label":"Day","value":"day"},{"label":"Week","value":"week"},{"label":"Month","value":"month"}]'>
+</rel-segmented-button>
+
+<!-- Large size (48px), matching a large text field -->
+<rel-segmented-button
+  size="large"
+  active="grid"
+  field-aria-label="View mode"
+  options='[{"label":"List","value":"list"},{"label":"Grid","value":"grid"}]'>
+</rel-segmented-button>
+
+<!-- Leading icons: `icon` names a rel-icon, sized 16 / 18 / 20 with the control -->
+<rel-segmented-button
+  active="list"
+  field-aria-label="View mode"
+  options='[{"label":"List","value":"list","icon":"bullet-list"},{"label":"Grid","value":"grid","icon":"dashboard"}]'>
+</rel-segmented-button>
+
+<!-- Disabled option: rendered but not selectable or focusable -->
+<rel-segmented-button id="plan" active="free" field-aria-label="Plan"></rel-segmented-button>
+<script>
+  document.getElementById('plan').options = [
+    { label: 'Free', value: 'free' },
+    { label: 'Pro', value: 'pro' },
+    { label: 'Enterprise', value: 'enterprise', disabled: true }
+  ];
+</script>
+
+<!-- Alignment inside a wider host (align only matters when the host is stretched) -->
+<rel-segmented-button
+  style="display: block; width: 100%"
+  align="middle"
+  active="asc"
+  field-aria-label="Sort direction"
+  options='[{"label":"Ascending","value":"asc"},{"label":"Descending","value":"desc"}]'>
+</rel-segmented-button>
+
+<!-- Listen for changes -->
+<rel-segmented-button id="sort-order" active="newest" field-aria-label="Sort order"></rel-segmented-button>
+<script>
+  const sortOrder = document.getElementById('sort-order');
+  sortOrder.options = [
+    { label: 'Newest', value: 'newest' },
+    { label: 'Oldest', value: 'oldest' },
+    { label: 'Popular', value: 'popular' }
+  ];
+  sortOrder.addEventListener('rel-change', (e) => {
+    console.log('Selected:', e.detail.value);
+  });
+</script>
+```
+
+The `SegmentOption` interface and the `SegmentSize` / `SegmentAlign` unions are exported from the package:
+
+```typescript
+import type { SegmentOption } from '@reliability-design/web';
+
+const options: SegmentOption[] = [
+  { label: 'List', value: 'list' },                      // label = visible text, value = what `active` / the event carry
+  { label: 'Grid', value: 'grid', icon: 'dashboard' },   // icon = a rel-icon name, drawn before the label
+  { label: 'Archive', value: 'archive', disabled: true } // rendered at 50% opacity, skipped by the arrow keys
+];
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-segmented-button.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | `options` | `SegmentOption[]` | `[]` | The segments in order, each `{ label: string; value: string; disabled?: boolean; icon?: string; badge?: number \| string \| boolean }`. Set as a property (or a JSON array attribute); a disabled entry is rendered but cannot be selected, and `icon` names a `rel-icon` drawn before the label. |
+| `active` | `active` | `string` | `""` | `value` of the currently selected segment. Updated by the component on click / arrow keys; set it to pre-select a segment (an unknown value selects nothing). |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the whole group (click and keyboard) without changing individual `options[].disabled` settings. Angular `control.disable()` uses it. New in 1.5.0. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height, matching the TextField ramp: `small` (32px — 28px segments, `action-md` 12px text, 16px icons), `medium` (default, 40px — 36px segments, `action-lg` 14px text, 18px icons) or `large` (48px — 44px segments, `action-xl` 16px text, 20px icons). |
+| `align` | `align` | `"left" \| "middle" \| "right"` | `"left"` | `justify-content` of the group's inline-flex container: `left` (default), `middle` or `right`. Only visible when the host is made wider than its content. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `changed` | `{ value: option.value }` | bubbles / composed | Legacy alias of `rel-change`, fired with the same detail at the same time. Kept indefinitely so existing listeners keep working; new code should use `rel-change`. |
+| `rel-change` | `{ value: option.value }` | bubbles / composed | Fired after a non-disabled segment is selected by click or arrow / Home / End key (also when it was already the active one). Detail: `{ value: string }`. The canonical name — prefer it over the legacy `changed`, which fires alongside it with the same detail. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `option` | Each segment's native `<button role="radio">`; the active one carries the `active` class and `aria-checked="true"`. |
+| `icon` | A segment's optional leading `rel-icon` element. |
+| `label` | The wrapper around a segment's label text. |
+| `badge` | A segment's optional trailing `rel-badge`; rendered only when the option sets `badge`. |
+| `base` | The `role="radiogroup"` track that lays out the segments. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The container is a `role="radiogroup"`; give it a name with `field-aria-label` — the component renders no visible group label, so without it screen readers announce an unnamed group.
+- Every segment is a native `<button role="radio">` with `aria-checked="true"` on the active one and `aria-checked="false"` on the rest. Disabled options get the native `disabled` attribute, so they are not focusable and do not fire `click`.
+- Roving tabindex (APG radio-group pattern): the whole group is a single Tab stop. The active segment carries `tabindex="0"`; if `active` matches no enabled option, the first enabled segment takes the Tab stop instead (without becoming selected). All other segments are `tabindex="-1"`.
+- Arrow keys both move focus and select, so they emit the change event immediately. Focus is moved to the newly active segment after the re-render.
+- Focus ring: a 2px `border-focus` outline drawn inside the segment (`outline-offset: -2px`) and raised with `z-index: 1` so it stays above the neighbouring segment.
+- Nothing is announced beyond the native `aria-checked` change.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus into / out of the group (one stop, on the active segment) |
+| `ArrowRight` / `ArrowDown` | Select and focus the next enabled segment (wraps to the first) |
+| `ArrowLeft` / `ArrowUp` | Select and focus the previous enabled segment (wraps to the last) |
+| `Home` / `End` | Select and focus the first / last enabled segment |
+| `Enter` / `Space` | Native button activation: selects the focused segment |
+
+## Notes / Edge Cases
+
+- **Two events fire for one selection — listen to ONE of them or your handler runs twice.** The change event is `rel-change`, matching the rest of the library. The legacy un-prefixed `changed` fires alongside it with the same detail and is kept so existing listeners keep working — listen to one, not both. Both bubble and are composed, so either can be caught on any ancestor, and both fire when the already-active segment is clicked again.
+- `active` is a plain string compared against `option.value`; setting it to a value that is not in `options` (or to a disabled option's value) renders no active segment.
+- `options` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
+- The host is `display: inline-block` and the group `inline-flex`, so it sizes to its content; `align` has no visible effect until the host is stretched (e.g. `style="display: block; width: 100%"`). Every segment has `min-width: 80px`, so a group is never narrower than 80px per segment.
+- Sizing: the track is a `bg-neutral` surface with `spacing-3xs` (2px) padding and a `border-radius-xs` corner — there is no outer border and no dividers between segments. Each segment carries the full `border-radius-xs` on all four corners in every state. Segment heights are 28 / 36 / 44 for `small` / `medium` / `large`, which with the 2px inset give control heights of 32 / 40 / 48.
+- Per size: padding `spacing-3xs spacing-sm` / `spacing-2xs spacing-md` / `spacing-xs spacing-lg`, text `action-md` (12px) / `action-lg` (14px) / `action-xl` (16px), and leading icons at 16 / 18 / 20px with an `spacing-xs` (8px) gap.
+- Colours: the active segment uses `action-neutral-fill` with inverse text (and `action-neutral-fill-hover` on hover); a non-active segment is transparent so the `action-overlay-hover` alpha composites over the track; disabled segments are drawn at 50% opacity with `bg-neutral-elevated-1` and a `not-allowed` cursor. Background and colour transitions are 0.2s.
+- A per-option `icon` renders a `rel-icon` before the label. Its size rides `--rel-icon-size` set directly on the `rel-icon` element — not on a wrapper, since `rel-icon` reflects `size="md"` and its own `:host([size])` rule would otherwise win.
+- No design-token overrides or `--rel-segmented-button-*` hooks are exposed; style through the `base` / `option` / `icon` / `label` parts.

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

@@ -10,10 +10,10 @@
 <script>
   const country = document.getElementById("country");
   country.options = ["USA", "Canada", "Mexico"];
-  country.addEventListener("changed", (e) => console.log(e.detail.value)); // "Canada"
+  country.addEventListener("rel-change", (e) => console.log(e.detail.value)); // "Canada"
 </script>
 
-<!-- Object options: value / label / icon / supportingText (supportingText shows in multi-select rows only) -->
+<!-- Object options: value / label / icon / supportingText (a second line under the label, in single and multi rows) -->
 <script>
   country.options = [
     { value: "air", label: "Air freight", icon: "air" },
@@ -22,8 +22,8 @@
 </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>
+<rel-select label="Email preference" selected="weekly" supporting-text="How often we email you" left-icon="email"></rel-select>
+<rel-select label="Custom chevron" right-icon="chevron-down"></rel-select>
 
 <!-- Sizes, corners, label styles -->
 <rel-select label="Small" size="small"></rel-select>
@@ -52,7 +52,7 @@
 <script>
   const tags = document.getElementById("tags");
   tags.options = ["urgent", "fragile", "hazmat", "oversize", "refrigerated"];
-  tags.addEventListener("changed", (e) => console.log(e.detail.value)); // ["urgent", "fragile", ...]
+  tags.addEventListener("rel-change", (e) => console.log(e.detail.value)); // ["urgent", "fragile", ...]
 </script>
 ```
 
@@ -85,13 +85,14 @@
 | `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. |
+| `noSearch` | `no-search` | `boolean` | `false` | Hides the in-panel search field. The search row shows in single- and multi-select panels alike unless this is set; use it for short lists that don't need searching (Figma's "Single Option" dropdown has no search bar). |
 
 ## Events
 
 | 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`. |
+| `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`. Legacy name, kept indefinitely: it fires together with `rel-change`, same detail, same moment. |
+| `rel-change` | `{ value: this.multiple ? this.selectedValues : this.selected }` | bubbles / composed | Prefixed alias of `changed`, fired on the same action with the same detail (added in 1.4.9). The name the rest of the library uses — prefer it in new code. |
 
 ## Slots
 
@@ -105,9 +106,9 @@
 | --- | --- |
 | `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) |
+| `value` | The value area: the selected label or placeholder inside the trigger. In multi-select with chips (since 1.5.0) it is the chip overlay, a sibling laid over the trigger's value area rather than a child of it |
 | `helper` | The supporting / error text below the trigger |
-| `panel` | The dropdown listbox container (same node as `list`) |
+| `panel` | The dropdown panel (a `role="group"` holding the search, Select-all and the options listbox; same node as `list`) |
 | `list` | Alias of `panel` |
 | `input` | The search input inside the panel |
 | `option` | A single-select option row |
@@ -123,7 +124,8 @@ Set these on the host (or an ancestor) to customise the element without touching
 | 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-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
+| `--rel-select-bg` | `var(--rel-bg-neutral)` | Background of the trigger, the panel and its sticky header. No longer paints behind the floating label — see `--rel-select-surface`. |
 | `--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"` |
@@ -132,7 +134,7 @@ Set these on the host (or an ancestor) to customise the element without touching
 | `--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-border` | `var(--rel-border-subtle)` | 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 |
@@ -142,6 +144,8 @@ Set these on the host (or an ancestor) to customise the element without touching
 | `--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-surface` | `var(--rel-select-bg, var(--rel-bg-neutral))` | Colour of the strip the floating label lays over the trigger's top border and focus ring, so the label appears to sit in a notch. It overshoots the band by 2px on the page side, so it must match the surface the field sits on. Defaults to `--rel-select-bg`. Set it when the field sits on a surface that is not the trigger's own fill, otherwise the strip shows as a short dash of the wrong colour. Mirrors `--rel-textfield-surface`. |
+| `--rel-select-surface-disabled` | `var(--rel-select-bg-disabled, var(--rel-bg-neutral-elevated-2))` | The same strip while `state="disabled"`, where the trigger fill changes. Defaults to `--rel-select-bg-disabled`. |
 | `--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 -->
@@ -150,10 +154,11 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 - 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 panel (part `panel`) is a `role="group"` named after the field (or "Options"): it holds the search combobox and the Select-all row, which a listbox may not contain. The `role="listbox"` (same name, `aria-multiselectable` in multi mode, and the id the trigger and search `aria-controls` point at) is the options container inside it; the Select-all row joins it through `aria-owns`. With no matches the listbox holds one disabled option with the "No matches found" / "No options available" text. 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.
+- Focus: opening the panel moves focus to the search input (with `preventScroll`) unless `no-search`; closing always returns focus to the trigger.
+- Multi-select chips (changed in 1.5.0): the chips are no longer inside the trigger `<button>` (interactive content in a button is invalid HTML), and their bodies and the "+N" chip are no longer Tab stops that did nothing. They sit in an overlay over the trigger's value area: a click on a chip label or on "+N" opens the panel like any click on the field. The Tab order is the trigger, then each visible chip's remove button ("Remove {label}", at least 24 × 24px). Removing a chip from the keyboard moves focus to the next chip's remove button, else the previous one, else the trigger. Backspace / Delete on the trigger (or Backspace in an empty search field) still removes the most recent selection. The "+N" chip is hidden from assistive technology, because the trigger's name already ends "plus N more". Before 1.5.0 this README said the remove buttons were not Tab stops; they were, alongside the dead stops.
 
 | Key | Action |
 |-----|--------|
@@ -171,15 +176,16 @@ Set these on the host (or an ancestor) to customise the element without touching
 
 ## Notes / Edge Cases
 
-- The change event is named `changed` (not `rel-change`); `detail.value` is a string in single mode and an array of strings when `multiple`.
+- **Two events fire for one selection — listen to ONE of them or your handler runs twice.** `rel-change` (added in 1.4.9, matching the rest of the library) and the legacy `changed` fire together with the same detail; `detail.value` is a string in single mode and an array of strings when `multiple`. Existing `changed` listeners keep working.
 - 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.
+- Since 1.5.0 the multi-select chip overlay is positioned from the field's own size (border, inline padding, icon size), not from the trigger's computed padding. Custom CSS that changes the inline padding through `::part(trigger)` therefore no longer moves the chips with it. Style `::part(value)` to adjust them as well. `::part(trigger)` is still the same button with the same box, and the chips are still `rel-chip` elements.
 - `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).
+- Option `icon` and `supportingText` render in both single and multi rows. Both lines truncate to one line with an ellipsis in either mode (nothing wraps or hyphenates), and a row that carries a second line gets a native `title` with its full text so hovering reveals what was cut. 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).
+- 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. On an outside scroll (since 1.5.0) it **stays open and moves with the field while the field is still visible**, and closes once the field scrolls out of the viewport or its scroll container, or under a sticky header — so the top-layer panel never paints over page furniture (the reason 1.4.9 closed it on every scroll). Only the window and the field's own scroll containers count, including ones inside shadow roots such as `rel-modal`'s body; scrolls of unrelated elements and of the panel itself are ignored, and a wheel or swipe over the panel never scrolls the page (`overscroll-behavior: contain`).
 - `--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.

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

@@ -25,7 +25,7 @@
 
 <!-- Centred dialog, small width -->
 <rel-modal side="center" size="small" title="Session expired" description="Sign in again to continue.">
-  <rel-button slot="footer" variant="primary">Sign in</rel-button>
+  <rel-button slot="footer" variant="primary" tone="brand">Sign in</rel-button>
 </rel-modal>
 
 <!-- Top-anchored sheet with extra header content -->
@@ -60,7 +60,7 @@
 <!-- Non-dismissible: no close button, backdrop and Escape ignored -->
 <rel-modal id="locked" title="Accept terms">
   <p>You must accept to continue.</p>
-  <rel-button slot="footer" variant="primary">Accept</rel-button>
+  <rel-button slot="footer" variant="primary" tone="brand">Accept</rel-button>
 </rel-modal>
 <script>
   // Boolean props that default to true can only be switched off from JS —
@@ -159,6 +159,7 @@ Set these on the host (or an ancestor) to customise the element without touching
 - `title` is also HTML's global tooltip attribute. The component reads the attribute into the property and then removes it from the host, so no native tooltip appears over the modal or its scrim.
 - `subtitle` is an alias for `description` and is only rendered when `description` is empty.
 - The footer is only rendered when the `footer` slot has content; the host gains a `has-footer` attribute while it does.
+- The header always has a bottom border. The footer's top divider shows only while the body scrolls (the host gains `body-scrolls`); short content has no footer divider. Scrolling is re-measured when the body or any slotted child resizes, so content added after opening, children growing in place (including in a `fullscreen` modal, whose body never changes size itself), images loading and window resizes all update it.
 - `dismissible` is the coarse switch and is ANDed with `close-on-backdrop-click`, `close-on-escape` and `show-close-button`; turning it off locks all three regardless of their own values.
 - `loading` blocks backdrop clicks and the close button but does **not** block `Escape`; set `disabled` (or `close-on-escape` = false) if Escape must be blocked as well.
 - Boolean props default to `true` (`dismissible`, `modal`, `close-on-*`, `show-close-button`, `auto-focus`, `restore-focus`, `scrollable`); an absent attribute keeps the default, so switch them off from JavaScript (`modal.closeOnEscape = false`).