@reliability-design/web 1.4.6 → 1.4.8

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

@@ -1,110 +1,88 @@
-# rel-progress
-
-## Overview
-A progress indicator component supporting four modes: linear-determinate, linear-indeterminate, circular-determinate, and circular-indeterminate. Features smooth animations, proper ARIA attributes, and respects user motion preferences by disabling animations when requested.
-
-## Usage
-```html
-<!-- Linear progress (determinate) -->
-<rel-progress mode="linear-determinate" value="45"></rel-progress>
-<rel-progress mode="linear-determinate" value="100"></rel-progress>
-
-<!-- Linear progress (indeterminate/loading) -->
-<rel-progress mode="linear-indeterminate"></rel-progress>
-
-<!-- Circular progress (determinate) -->
-<rel-progress mode="circular-determinate" value="75"></rel-progress>
-
-<!-- Circular progress (indeterminate/spinner) -->
-<rel-progress mode="circular-indeterminate"></rel-progress>
-
-<!-- Dynamic progress update -->
-<rel-progress id="uploadProgress" mode="linear-determinate" value="0"></rel-progress>
-<script>
-  const progress = document.getElementById('uploadProgress');
-  let value = 0;
-  const interval = setInterval(() => {
-    value += 10;
-    progress.value = value;
-    if (value >= 100) clearInterval(interval);
-  }, 500);
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `mode` (reflected) | `"linear-determinate" \| "linear-indeterminate" \| "circular-determinate" \| "circular-indeterminate"` | `"linear-determinate"` | Progress indicator type |
-| `value` | `number` | `0` | Progress value (0-100) for determinate modes (ignored in indeterminate modes) |
-
-## Events
-None.
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-
-### Color Tokens
-- `--rel-border-default` - Track/background color
-- `--rel-text-default` - Active progress bar color
-
-### Border Tokens
-- `--rel-border-radius-sm` - Linear track border radius
-
-## Accessibility
-- Determinate modes use `role="progressbar"` with `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax="100"`
-- Indeterminate modes use `role="progressbar"` without value attributes
-- Respects `prefers-reduced-motion: reduce` by disabling animations
-
-### Keyboard Interactions
-- None (not focusable)
-
-### Focus Behavior
-- Not focusable
-
-## Notes / Edge Cases
-- **Linear modes**:
-  - Height: `6px`
-  - Track uses gray border color
-  - Bar uses black color
-  - Border radius: `--rel-border-radius-sm`
-  - **Determinate**: bar width transitions smoothly (0.3s ease)
-  - **Indeterminate**: 30% width bar slides left-to-right (1.5s infinite loop)
-
-- **Circular modes**:
-  - Size: `48px × 48px` (viewBox varies by mode)
-  - Stroke width: `3px` (determinate) or `4px` (indeterminate)
-  - Stroke linecap: `round`
-  - **Determinate**: 
-    - Uses `stroke-dasharray` and `stroke-dashoffset` to animate progress
-    - Circle radius: `15.9155`, circumference: `~100`
-    - Rotated -90° to start at top
-    - Progress transition: `0.35s`
-  - **Indeterminate (spinner)**: 
-    - Rotates continuously (2s linear infinite)
-    - Stroke dash animates (1.5s ease-in-out infinite)
-
-- **Value clamping**: Values are automatically clamped to 0-100 range via `safeValue` getter
-
-- **Motion preferences**:
-  - When `prefers-reduced-motion: reduce`:
-    - Linear determinate: no transition
-    - Linear indeterminate: no animation, shows full-width bar at 50% opacity
-    - Circular determinate: no transition
-    - Circular indeterminate: no rotation/dash animation, shows static partial arc
-
-- **Display modes**:
-  - Linear modes: `display: block` (full width)
-  - Circular modes: `display: inline-block` (sized to content)
-
-- The component automatically switches render methods based on `mode` property
-- Indeterminate modes ignore the `value` property
+# rel-progress
+
+`<rel-progress>` is the Figma "Progress" indicator in its two shapes and two behaviours: a full-width 2px linear bar or a 36px circular ring, each either determinate (fills to `value`, 0–100) or indeterminate (loops an animation while you wait). Use `linear-determinate` / `circular-determinate` for uploads, imports and multi-step flows where progress is known, and the `*-indeterminate` modes as a loading signal while a request is in flight. It is a passive `role="progressbar"` element — it does not block interaction (use `rel-modal` with `loading` for that) and does not announce completion on its own.
+
+## Usage
+
+```html
+<!-- Linear, determinate -->
+<rel-progress mode="linear-determinate" value="45"></rel-progress>
+<rel-progress mode="linear-determinate" value="100"></rel-progress>
+
+<!-- Linear, indeterminate (loading) -->
+<rel-progress mode="linear-indeterminate"></rel-progress>
+
+<!-- Circular, determinate -->
+<rel-progress mode="circular-determinate" value="75"></rel-progress>
+
+<!-- Circular, indeterminate (spinner) -->
+<rel-progress mode="circular-indeterminate"></rel-progress>
+
+<!-- Accessible name -->
+<rel-progress mode="linear-determinate" value="30" label="Uploading invoices"></rel-progress>
+<rel-progress mode="circular-indeterminate" label="Loading shipments"></rel-progress>
+
+<!-- Driving the value from script -->
+<rel-progress id="uploadProgress" mode="linear-determinate" value="0" label="Upload"></rel-progress>
+<script>
+  const progress = document.getElementById('uploadProgress');
+  let value = 0;
+  const interval = setInterval(() => {
+    value += 10;
+    progress.value = value;
+    if (value >= 100) clearInterval(interval);
+  }, 500);
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-progress.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `mode` | `mode` | `"linear-determinate" \| "linear-indeterminate" \| "circular-determinate" \| "circular-indeterminate"` | `"linear-determinate"` | Shape and behaviour: `linear-*` is a full-width 2px bar, `circular-*` a 36px ring; `*-determinate` fills to `value`, `*-indeterminate` loops an animation and ignores `value`. Reflected. |
+| `value` | `value` | `number` | `0` | Completion percentage 0–100 for the determinate modes; out-of-range values are clamped before rendering and before `aria-valuenow`. |
+| `label` | `label` | `string` | `""` | Accessible name of the progressbar (not rendered visually); defaults to "Progress" for determinate and "Loading" for indeterminate modes. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `track` | The linear track `<div>` that carries `role="progressbar"` (linear modes only) |
+| `indicator` | The filled / sliding bar inside the linear track (linear modes only) |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Every mode renders one element with `role="progressbar"` and an `aria-label` taken from `label`; when `label` is empty the name is "Progress" for determinate modes and "Loading" for indeterminate ones. Give it a specific `label` ("Uploading invoices") when more than one indicator can be on screen.
+- Determinate modes also set `aria-valuenow` (the clamped `value`), `aria-valuemin="0"` and `aria-valuemax="100"`. Indeterminate modes omit the value attributes, which is what tells assistive technology the progress is unknown.
+- The element is not focusable and handles no keys.
+- It does not announce anything by itself: neither the start of loading nor reaching 100% is spoken. Announce those from the surrounding UI (for example with a status message) when they matter.
+- `prefers-reduced-motion: reduce` is respected: the determinate transitions are removed, the linear indeterminate bar becomes a static full-width bar at 50% opacity, and the circular spinner stops rotating and shows a static partial arc.
+
+## Notes / Edge Cases
+
+- `value` is clamped to 0–100 before rendering and before `aria-valuenow`; the indeterminate modes ignore it entirely.
+- The `track` and `indicator` parts exist only in the two linear modes. The circular modes render an inline `<svg>` with no parts, so `::part(track)` matches nothing there.
+- Linear bars are 2px tall with a 4px radius and stretch to the host's width (host is `display: block`). Circular rings are fixed at 36px and the host switches to `display: inline-block`, so they sit inline with text.
+- The linear determinate width animates over 0.3s and the circular arc over 0.35s; a value that jumps from 0 to 100 therefore takes a moment to catch up visually.
+- Circular strokes are 3px (determinate) and 4px (indeterminate) with a flat (`butt`) line cap; the determinate ring starts at 12 o'clock via a −90° rotation.
+- The indeterminate linear bar is a 30%-wide segment that sweeps left to right on a 1.5s loop; the spinner rotates on a 2s loop with a 1.5s dash animation.

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

@@ -1,138 +1,131 @@
-# rel-radio
-
-## Overview
-A radio button group component that allows users to select a single option from a list. Supports individual option states (disabled, error), supporting text, and comprehensive styling with design tokens.
-
-## Usage
-```html
-<!-- Basic example -->
-<rel-radio id="colorRadio" name="color-group" selectedValue="blue"></rel-radio>
-<script>
-  const radio = document.getElementById('colorRadio');
-  radio.options = [
-    { value: 'red', label: 'Red' },
-    { value: 'blue', label: 'Blue' },
-    { value: 'green', label: 'Green' }
-  ];
-</script>
-
-<!-- Example with supporting text and states -->
-<rel-radio id="planRadio" name="plan-group"></rel-radio>
-<script>
-  const planRadio = document.getElementById('planRadio');
-  planRadio.options = [
-    { value: 'basic', label: 'Basic Plan', supportingText: '$9.99/month' },
-    { value: 'pro', label: 'Pro Plan', supportingText: '$19.99/month' },
-    { value: 'enterprise', label: 'Enterprise', supportingText: 'Contact sales', disabled: true }
-  ];
-  planRadio.selectedValue = 'basic';
-</script>
-
-<!-- Horizontal row layout -->
-<rel-radio id="sizeRadio" name="size-group" orientation="horizontal"></rel-radio>
-<script>
-  const sizeRadio = document.getElementById('sizeRadio');
-  sizeRadio.options = [
-    { value: 's', label: 'Small' },
-    { value: 'm', label: 'Medium' },
-    { value: 'l', label: 'Large' }
-  ];
-</script>
-
-<!-- Listen for changes -->
-<rel-radio id="preferenceRadio"></rel-radio>
-<script>
-  const prefRadio = document.getElementById('preferenceRadio');
-  prefRadio.options = [
-    { value: 'email', label: 'Email' },
-    { value: 'sms', label: 'SMS' }
-  ];
-  prefRadio.addEventListener('changed', (e) => {
-    console.log('Selected:', prefRadio.selectedValue);
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `RadioOption[]` | `[]` | Array of radio options (see RadioOption interface below) |
-| `name` | `string` | `"radio-group"` | Name attribute for the radio group (for form grouping) |
-| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Layout axis: `"vertical"` stacks options in a column; `"horizontal"` lays them out in a wrapping row (reflected attribute) |
-| `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control scale (Figma Size L/M/S): `"medium"` = 20px control with body-lg labels; `"large"` = 24px control with body-xl labels; `"small"` = 20px control with body-md labels — S and M share the control size, only typography steps down (reflected attribute) |
-| `density` | `"compact" \| "comfortable"` | `"compact"` | Supporting-text layout (Figma Density): `"compact"` puts the supporting text on its own line under the row, indented past the control; `"comfortable"` stacks label + supporting text beside the control (reflected attribute) |
-| `alignment` | `"leading" \| "trailing"` | `"leading"` | Control position (Figma Layout): `"trailing"` pushes the control to the far edge of the row and always renders comfortable density — the spec has no compact trailing layout (reflected attribute) |
-| `selectedValue` | `string \| null` | `null` | Currently selected option value (reflected attribute) |
-| `disabled` | `boolean` | `false` | Disables the entire radio group (renders at 40% opacity) |
-
-### RadioOption Interface
-```typescript
-interface RadioOption {
-  value: string;           // Unique value for this option
-  label: string;           // Display label
-  supportingText?: string; // Optional helper text below the label
-  disabled?: boolean;      // Disable individual option
-  icon?: string;           // rel-icon name rendered before the label
-  avatar?: string;         // 1–2 initials rendered as a circular chip before the label (ignored when icon is set)
-}
-```
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `changed` | None (read `selectedValue` property) | Fired when the selected option changes |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-sm-regular-font-size`, `--rel-body-xs-regular-font-size` - Font sizes for label and supporting text
-- `--rel-fonts-weight-body-medium` - Font weight for labels
-
-### Spacing Tokens
-- `--rel-spacing-xs` - Gap between radio options (also the row gap when wrapping horizontally)
-- `--rel-spacing-xl` - Column gap between options in `orientation="horizontal"`
-- `--rel-spacing-3xs` - Gap within each option (label and supporting text)
-- `--rel-spacing-2xs` - Gap between radio circle and label
-
-### Color Tokens
-- `--rel-text-label` - Radio button border and checked dot color
-- `--rel-text-default` - Label text color
-- `--rel-text-placeholder` - Supporting text color
-- `--rel-border-info` - Focus outline color
-- `--rel-text-danger` - Error state border and dot color
-
-## Accessibility
-- The option list renders with `role="radiogroup"` and `aria-orientation` reflecting the `orientation` prop
-- Uses visually hidden native radio inputs for proper screen reader support
-- Custom visual radio circle with proper focus indicators
-- Focus visible state with outline offset for keyboard navigation
-- Label click targets the radio for larger interaction area
-- Disabled state communicated through reduced opacity and cursor change
-- Proper `name` grouping ensures only one option can be selected
-
-### Keyboard Interactions
-- `Tab` - Move focus to/from radio group
-- `Arrow Up/Down` - Navigate between radio options
-- `Space` - Select focused option
-
-### Focus Behavior
-- Focus outline appears with offset around the custom radio circle
-- Uses info border color for high contrast
-
-## Notes / Edge Cases
-- The `selectedValue` property is reflected as an attribute and can be set programmatically or via HTML
-- When `disabled` is true on the component, all options are disabled regardless of individual option settings
-- Individual options can be disabled via the `disabled` property in the `RadioOption` object
-- The `error` property on `RadioOption` changes the radio button color to red but does not prevent selection
-- Supporting text is optional and appears below the label with left margin alignment
-- Native radio inputs are visually hidden but maintain all accessibility features
-- The `name` attribute groups radios together for form submission and mutual exclusion
+# 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. `"medium"` (default, Figma M) = 20px control with body-lg labels; `"large"` (Figma L) = 24px control with body-xl labels; `"small"` = 16px control with body-md labels. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. DELIBERATE FIGMA DIVERGENCE on Small. Figma's `.Radio Control` has one size (20x20) and its row variants pin Small AND Medium to 20, so the two rendered identically and the Size axis did nothing between them. 16px is not invented: it is rel-checkbox's Small, and checkbox is radio's sibling selection control. See the size ramp in the styles below. 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`).