@reliability-design/web 1.4.9 → 1.4.11

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

@@ -1,131 +1,142 @@
-# rel-radio
-
-`<rel-radio>` is the single-select radio group of the Reliability Design System (Figma "Radio"). One element is one group: it renders a native radio input for every entry in `options`, with optional supporting text and an icon or avatar prefix, in the Figma Size (S/M/L), Density (compact / comfortable) and Layout (leading / trailing) variants, plus error and disabled states. Use it when the user must pick exactly one of a few visible choices (2–7). For long lists use `<rel-select>`, for independent on/off choices use `<rel-checkbox>` or `<rel-switch>`.
-
-## Usage
-
-```html
-<!-- Basic group; options as a JSON attribute, preselected via selectedvalue -->
-<rel-radio
-  name="color"
-  field-aria-label="Colour"
-  options='[{"value":"red","label":"Red"},{"value":"blue","label":"Blue"},{"value":"green","label":"Green"}]'
-  selectedvalue="blue"
-></rel-radio>
-
-<!-- Two independent groups on one page: give each its own name -->
-<rel-radio id="plan" name="plan" field-aria-label="Plan"></rel-radio>
-<rel-radio id="billing" name="billing" field-aria-label="Billing cycle" orientation="horizontal"></rel-radio>
-
-<!-- Sizes (S and M share the 20px control; L is 24px) -->
-<rel-radio id="small" name="size-small" size="small"></rel-radio>
-<rel-radio id="medium" name="size-medium" size="medium"></rel-radio>
-<rel-radio id="large" name="size-large" size="large"></rel-radio>
-
-<!-- Supporting text beside the control instead of on its own line -->
-<rel-radio id="comfortable" name="tier" density="comfortable"></rel-radio>
-
-<!-- Control on the far edge of each row (always comfortable density) -->
-<rel-radio id="trailing" name="notify" alignment="trailing"></rel-radio>
-
-<!-- Error state with a message; disabled group -->
-<rel-radio id="consent" name="consent" error errormessage="Choose one option to continue"></rel-radio>
-<rel-radio id="locked" name="locked" disabled></rel-radio>
-```
-
-```js
-const plan = document.getElementById("plan");
-plan.options = [
-  { value: "basic", label: "Basic", supportingText: "$9.99 / month" },
-  { value: "pro", label: "Pro", supportingText: "$19.99 / month", icon: "settings" },
-  { value: "team", label: "Team", avatar: "TM" },
-  { value: "enterprise", label: "Enterprise", supportingText: "Contact sales", disabled: true },
-];
-plan.selectedValue = "basic";
-
-plan.addEventListener("rel-change", (e) => {
-  e.detail.value;   // "pro" — the selected option's value
-  e.detail.checked; // always true
-  plan.selectedValue === e.detail.value; // already updated
-});
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-radio.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `options` | `options` | `RadioOption[]` | `[]` | The options to render, in order. Each entry is a `RadioOption` (`value`, `label`, optional `supportingText`, `disabled`, `icon` or `avatar`). Set as a property (`.options=`) or as a JSON attribute. |
-| `name` | `name` | `string` | `"radio-group"` | `name` given to every native radio input inside this element. It scopes native radio-group behaviour (arrow-key movement, mutual exclusion) to this group, so give each group on a page a distinct name. |
-| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Layout axis of the option list. `"vertical"` (default) stacks options in a column; `"horizontal"` lays them out in a wrapping row. Reflected. |
-| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Control scale, matching Figma's Size axis. `"small"` and `"medium"` (default) both draw a 20px control — they differ by TYPE, body-md labels against body-lg — and `"large"` steps the control to 24px with body-xl labels. Supporting text sits one body step below the label at every size (body-sm / md / lg, i.e. 12 / 14 / 16px). `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Small and Medium sharing a control is Figma's design, not an oversight: verified against the live Published DS file on 2026-09-25, `.Radio Control` measures 20x20 in all 15 Small variants and all 15 Medium ones. v1.4.8 briefly gave Small its own 16px control on the mistaken premise that the ramp was 16/20/24; 1.4.9 reverts that. Reflected. |
-| `density` | `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout (Figma Density). `"compact"` (default) puts the supporting text on its own line under the row, indented past the control; `"comfortable"` stacks label + supporting text beside the control. Reflected. |
-| `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Control position (Figma Layout). `"leading"` (default) renders the control before the label; `"trailing"` pushes it to the far edge of the row. Trailing has no compact layout in the spec, so it always renders with comfortable density. Meant for vertical orientation — trailing options stretch to the group's full width. Reflected. |
-| `selectedValue` | `selectedvalue` | `string \| null` | `null` | `value` of the currently selected option, or `null` when nothing is selected. Set it to preselect an option; it is updated on every user selection. Reflected. |
-| `disabled` | `disabled` | `boolean` | `false` | Disables every option (Figma State=Disabled: the whole group at 40% opacity). Individual options can also be disabled via `RadioOption.disabled`. |
-| `error` | `error` | `boolean` | `false` | Error state (Figma State=Error): rings, dots and supporting text turn danger. Applies to every option while nothing is selected, and only to the selected option once a choice is made. Selection is still allowed. |
-| `errorMessage` | `errormessage` | `string` | `""` | Message rendered under the group (live region) while `error` is set; hidden when `error` is false or the text is empty. |
-| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). |
-| `value` | `value` | `string` | `""` | Value reported to the Angular forms bridge (`registerOnChange` callback) on each change and compared by `writeValue`. Not used for rendering; read `selectedValue` or the `rel-change` detail for the selected option. |
-
-### Public fields / accessors
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `checked` | `boolean` | Set by the Angular forms bridge (`writeValue`) to whether the written form value equals `value`. Not used for rendering — read `selectedValue` for the selection. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-change` | `{ value, checked: true }` | bubbles / composed | Fired when the user selects an option (after `selectedValue` is updated). Detail: `{ value: string, checked: true }` — `value` is the selected option's value. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `label` | The visible label text of each option |
-| `base` | The `role="radiogroup"` container that lays out the options |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- The option container (part `base`) is a `role="radiogroup"` with `aria-orientation` = `orientation`, `aria-label` = `field-aria-label` (set it — the group renders no visible legend) and `aria-describedby` pointing at the error line.
-- Every option is a native `<input type="radio">` inside a `<label>`, so the whole row (control, label, supporting text) is the click target and the input's accessible name is the option label. The input is visually hidden (`opacity: 0`, absolutely positioned over the row) but stays in the Tab order; the drawn ring / dot mirror its `:checked` state.
-- Disabled options get the native `disabled` attribute (skipped by Tab and arrow keys) and render at 40% opacity; `disabled` on the host disables all of them.
-- The error message is a persistent `aria-live="polite"` region under the group, so a message that appears after submission is read out.
-- Avatar chips are `aria-hidden`; a prefix icon is a `<rel-icon>` and decorative.
-- Keyboard focus is shown as a 1.5px `--rel-border-focus` outline (1px offset) around the focused option; it appears only for `:focus-visible` (keyboard) focus.
-- Keyboard behaviour is the browser's native radio behaviour — the component adds no key handlers of its own:
-
-| Key | Action |
-| --- | --- |
-| Tab / Shift + Tab | Enter the group (on the checked option, else the first enabled one) or leave it |
-| ArrowDown / ArrowRight | Move to the next enabled option and select it (fires `rel-change`) |
-| ArrowUp / ArrowLeft | Move to the previous enabled option and select it (fires `rel-change`) |
-| Space | Select the focused option if it is not yet selected |
-
-## Notes / Edge Cases
-
-- `RadioOption` shape: `{ value: string; label: string; supportingText?: string; disabled?: boolean; icon?: string; avatar?: string }`. `icon` is a `rel-icon` name rendered before the label (Figma Has Icon/Avatar, Type=Icon); `avatar` is 1–2 initials rendered as a circular chip and is ignored when `icon` is also set.
-- `rel-change` fires only on user selection. Setting `selectedValue` from code (or via the `selectedvalue` attribute) updates the UI silently.
-- Grouping by `name`: the native inputs of one `<rel-radio>` share `name`, which is what gives arrow-key movement and mutual exclusion; they live in the element's shadow root, so they are not submitted with a surrounding `<form>`. Read `selectedValue` or listen to `rel-change` to collect the value. Give every group on a page its own `name` so the intent is unambiguous.
-- Error rules: while nothing is selected, every option shows the danger ring; once an option is selected only that option does. Labels keep their default colour; rings, dots and supporting text turn `--rel-border-danger` / `--rel-text-danger`. Error never blocks selection.
-- `alignment="trailing"` always renders comfortable density. Combining it with `density="compact"` logs `[rel-radio] density="compact" has no trailing layout; rendering comfortable density.` (a `console.warn`, every time either prop changes).
-- Compact supporting text is indented past the control box: 28px (S/M) and 32px (L). Comfortable density widens the control-to-label gap from 8px to 12px.
-- Hover shifts the ring, dot, label and prefix icon from `--rel-text-default` to `--rel-text-body` on enabled, non-error options.
-- `value` and `checked` exist for the Angular forms bridge (`registerOnChange` / `registerOnTouched` / `writeValue`, which are internal API). The bridge callback receives the `value` property, not the selected option — plain DOM consumers should ignore both and use `selectedValue` / `rel-change`.
-- `<rel-menu type="select-option">` renders an `inert`, `aria-hidden` `<rel-radio>` inside each row purely as a visual control; that usage does not fire `rel-change`.
-- The hidden native input is absolutely positioned inside a `position: relative` row on purpose — without that containing block, tabbing to it scrolls the wrong ancestor and jumps the page (shared fix with `rel-checkbox`).
+# rel-radio
+
+`<rel-radio>` is the single-select radio group of the Reliability Design System (Figma "Radio"). One element is one group: it renders a native radio input for every entry in `options`, with optional supporting text and an icon or avatar prefix, in the Figma Size (S/M/L), Density (compact / comfortable) and Layout (leading / trailing) variants, plus error and disabled states. Use it when the user must pick exactly one of a few visible choices (2–7). For long lists use `<rel-select>`, for independent on/off choices use `<rel-checkbox>` or `<rel-switch>`.
+
+## Usage
+
+```html
+<!-- Basic group; options as a JSON attribute, preselected via selected-value -->
+<rel-radio
+  name="color"
+  field-aria-label="Colour"
+  options='[{"value":"red","label":"Red"},{"value":"blue","label":"Blue"},{"value":"green","label":"Green"}]'
+  selected-value="blue"
+></rel-radio>
+
+<!-- Two independent groups on one page: give each its own name -->
+<rel-radio id="plan" name="plan" field-aria-label="Plan"></rel-radio>
+<rel-radio id="billing" name="billing" field-aria-label="Billing cycle" orientation="horizontal"></rel-radio>
+
+<!-- Sizes (S and M share the 20px control; L is 24px) -->
+<rel-radio id="small" name="size-small" size="small"></rel-radio>
+<rel-radio id="medium" name="size-medium" size="medium"></rel-radio>
+<rel-radio id="large" name="size-large" size="large"></rel-radio>
+
+<!-- Supporting text beside the control instead of on its own line -->
+<rel-radio id="comfortable" name="tier" density="comfortable"></rel-radio>
+
+<!-- Control on the far edge of each row (always comfortable density) -->
+<rel-radio id="trailing" name="notify" alignment="trailing"></rel-radio>
+
+<!-- Error state with a message; disabled group -->
+<rel-radio id="consent" name="consent" error error-message="Choose one option to continue"></rel-radio>
+<rel-radio id="locked" name="locked" disabled></rel-radio>
+```
+
+```js
+const plan = document.getElementById("plan");
+plan.options = [
+  { value: "basic", label: "Basic", supportingText: "$9.99 / month" },
+  { value: "pro", label: "Pro", supportingText: "$19.99 / month", icon: "settings" },
+  { value: "team", label: "Team", avatar: "TM" },
+  { value: "enterprise", label: "Enterprise", supportingText: "Contact sales", disabled: true },
+];
+plan.selectedValue = "basic";
+
+plan.addEventListener("rel-change", (e) => {
+  e.detail.value;   // "pro" — the selected option's value
+  e.detail.checked; // always true
+  plan.selectedValue === e.detail.value; // already updated
+});
+```
+
+### Deprecated aliases
+
+```html
+<!-- selectedvalue / errormessage → selected-value / error-message (since 1.5.0; still work, log a
+     one-time console notice, removed in 3.0). selectedValue still reflects as selectedvalue in 1.x. -->
+<rel-radio name="old" selectedvalue="blue" error errormessage="Pick one"></rel-radio>
+<rel-radio name="new" selected-value="blue" error error-message="Pick one"></rel-radio>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-radio.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | `options` | `RadioOption[]` | `[]` | The options to render, in order. Each entry is a `RadioOption` (`value`, `label`, optional `supportingText`, `disabled`, `icon` or `avatar`). Set as a property (`.options=`) or as a JSON attribute. |
+| `name` | `name` | `string` | `"radio-group"` | `name` given to every native radio input inside this element. It scopes native radio-group behaviour (arrow-key movement, mutual exclusion) to this group, so give each group on a page a distinct name. |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Layout axis of the option list. `"vertical"` (default) stacks options in a column; `"horizontal"` lays them out in a wrapping row. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Control scale, matching Figma's Size axis. `"small"` and `"medium"` (default) both draw a 20px control — they differ by TYPE, body-md labels against body-lg — and `"large"` steps the control to 24px with body-xl labels. Supporting text sits one body step below the label at every size (body-sm / md / lg, i.e. 12 / 14 / 16px). `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Small and Medium sharing a control is Figma's design, not an oversight: verified against the live Published DS file on 2026-09-25, `.Radio Control` measures 20x20 in all 15 Small variants and all 15 Medium ones. v1.4.8 briefly gave Small its own 16px control on the mistaken premise that the ramp was 16/20/24; 1.4.9 reverts that. Reflected. |
+| `density` | `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout (Figma Density). `"compact"` (default) puts the supporting text on its own line under the row, indented past the control; `"comfortable"` stacks label + supporting text beside the control. Reflected. |
+| `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Control position (Figma Layout). `"leading"` (default) renders the control before the label; `"trailing"` pushes it to the far edge of the row. Trailing has no compact layout in the spec, so it always renders with comfortable density. Meant for vertical orientation — trailing options stretch to the group's full width. Reflected. |
+| `selectedValue` | `selected-value` | `string \| null` | `null` | `value` of the currently selected option, or `null` when nothing is selected. Set it to preselect an option; it is updated on every user selection. Reflected (as `selectedvalue` in 1.x). The `selectedvalue` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `disabled` | `disabled` | `boolean` | `false` | Disables every option (Figma State=Disabled: the whole group at 40% opacity). Individual options can also be disabled via `RadioOption.disabled`. An ancestor `<fieldset disabled>` disables the group the same way, without changing this property. |
+| `error` | `error` | `boolean` | `false` | Error state (Figma State=Error): rings, dots and supporting text turn danger. Applies to every option while nothing is selected, and only to the selected option once a choice is made. Selection is still allowed. |
+| `errorMessage` | `error-message` | `string` | `""` | Message rendered under the group (live region) while `error` is set; hidden when `error` is false or the text is empty. The `errormessage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). Unset, an outer `<label>` (wrapping the group, or `for=`) names it instead. |
+| `value` | `value` | `string` | `""` | Value reported to the Angular forms bridge (`registerOnChange` callback) on each change and compared by `writeValue`. Not used for rendering; read `selectedValue` or the `rel-change` detail for the selected option. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `checked` | `boolean` | Set by the Angular forms bridge (`writeValue`) to whether the written form value equals `value`. Not used for rendering — read `selectedValue` for the selection. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ value, checked: true }` | bubbles / composed | Fired when the user selects an option (after `selectedValue` is updated). Detail: `{ value: string, checked: true }` — `value` is the selected option's value. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `label` | The visible label text of each option |
+| `base` | The `role="radiogroup"` container that lays out the options |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The option container (part `base`) is a `role="radiogroup"` with `aria-orientation` = `orientation`, `aria-label` = `field-aria-label` (the group renders no visible legend, so name it with this or an outer `<label>`) and `aria-describedby` pointing at the error line.
+- An outer `<label>` (`<label for="plan">Plan</label><rel-radio id="plan">`, or wrapped around the group) names the GROUP: the element is form-associated, and the label's text is copied into the radiogroup's `aria-label` when `field-aria-label` is unset. Clicking the label does not select anything. It moves focus onto the selected option, or the first enabled one when nothing is selected (where Tab would land), with no `rel-change`; then the arrow keys choose. A disabled group ignores the click. Clicking an option inside a wrapping label behaves as it always has.
+- Every option is a native `<input type="radio">` inside a `<label>`, so the whole row (control, label, supporting text) is the click target and the input's accessible name is the option label. The input is visually hidden (`opacity: 0`, absolutely positioned over the row) but stays in the Tab order; the drawn ring / dot mirror its `:checked` state.
+- Disabled options get the native `disabled` attribute (skipped by Tab and arrow keys) and render at 40% opacity; `disabled` on the host disables all of them.
+- The error message is a persistent `aria-live="polite"` region under the group, so a message that appears after submission is read out.
+- Avatar chips are `aria-hidden`; a prefix icon is a `<rel-icon>` and decorative.
+- Keyboard focus is shown as a 1.5px `--rel-border-focus` outline, flush (no offset), around the focused option; it appears only for `:focus-visible` (keyboard) focus.
+- In forced-colors mode (Windows High Contrast) the ring is drawn as a 1px `CanvasText` border and the selected dot is painted `CanvasText`, because the normal ring (an inset box-shadow) and the dot's background are not painted there.
+- Keyboard behaviour is the browser's native radio behaviour — the component adds no key handlers of its own:
+
+| Key | Action |
+| --- | --- |
+| Tab / Shift + Tab | Enter the group (on the checked option, else the first enabled one) or leave it |
+| ArrowDown / ArrowRight | Move to the next enabled option and select it (fires `rel-change`) |
+| ArrowUp / ArrowLeft | Move to the previous enabled option and select it (fires `rel-change`) |
+| Space | Select the focused option if it is not yet selected |
+
+## Notes / Edge Cases
+
+- `RadioOption` shape: `{ value: string; label: string; supportingText?: string; disabled?: boolean; icon?: string; avatar?: string }`. `icon` is a `rel-icon` name rendered before the label (Figma Has Icon/Avatar, Type=Icon); `avatar` is 1–2 initials rendered as a circular chip and is ignored when `icon` is also set.
+- `rel-change` fires only on user selection. Setting `selectedValue` from code (or via the `selected-value` attribute) updates the UI silently.
+- Grouping by `name`: the native inputs of one `<rel-radio>` share `name`, which is what gives arrow-key movement and mutual exclusion; they live in the element's shadow root, so they are not submitted with a surrounding `<form>`. The element itself is form-associated (for the outer `<label>`) but sets no form value, so that does not change; it does now appear in `form.elements`. Read `selectedValue` or listen to `rel-change` to collect the value. Give every group on a page its own `name` so the intent is unambiguous.
+- Error rules: while nothing is selected, every option shows the danger ring; once an option is selected only that option does. Labels keep their default colour; rings, dots and supporting text turn `--rel-text-danger`. Error never blocks selection.
+- `alignment="trailing"` always renders comfortable density. Combining it with `density="compact"` logs `[rel-radio] density="compact" has no trailing layout; rendering comfortable density.` (a `console.warn`, every time either prop changes).
+- Compact supporting text is indented past the control box: 28px (S/M) and 32px (L). Comfortable density widens the control-to-label gap from 8px to 12px.
+- Hover shifts the ring and dot from `--rel-text-default` to `--rel-text-body`, and the label and prefix icon to `--rel-text-label`, on enabled, non-error options.
+- `value` and `checked` exist for the Angular forms bridge (`registerOnChange` / `registerOnTouched` / `writeValue`, which are internal API). The bridge callback receives the `value` property, not the selected option — plain DOM consumers should ignore both and use `selectedValue` / `rel-change`.
+- `<rel-menu type="select-option">` renders an `inert`, `aria-hidden` `<rel-radio>` inside each row purely as a visual control; that usage does not fire `rel-change`.
+- The hidden native input is absolutely positioned inside a `position: relative` row on purpose — without that containing block, tabbing to it scrolls the wrong ancestor and jumps the page (shared fix with `rel-checkbox`).