@reliability-design/web 1.4.9 → 1.4.10

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

@@ -1,117 +1,122 @@
-# rel-switch
-
-`<rel-switch>` implements the Figma **Switch** component (5917:1174, Type=Line): a 44×20 toggle with a thin 10px track and a 20px handle that slides 20px, with hover, focused, pressed and disabled states from the Figma State axis. It wraps a native checkbox with `role="switch"`, so keyboard and screen-reader behaviour are native. Use it for settings that take effect immediately (notifications on/off, dark mode); for choices that are collected and submitted with a form use `<rel-checkbox>`.
-
-## Usage
-
-```html
-<!-- Basic -->
-<rel-switch field-aria-label="Email notifications"></rel-switch>
-
-<!-- On by default -->
-<rel-switch checked field-aria-label="Dark mode"></rel-switch>
-
-<!-- Disabled, off and on -->
-<rel-switch disabled field-aria-label="Locked setting"></rel-switch>
-<rel-switch checked disabled field-aria-label="Locked setting"></rel-switch>
-
-<!-- One handler for several switches: `value` is echoed in the event detail -->
-<rel-switch value="marketing" field-aria-label="Marketing emails"></rel-switch>
-<rel-switch value="product" field-aria-label="Product updates"></rel-switch>
-<script>
-  document.addEventListener('rel-change', (e) => {
-    if (e.target.tagName !== 'REL-SWITCH') return;
-    console.log(e.detail.value, e.detail.checked); // "marketing", true
-  });
-</script>
-
-<!-- Programmatic control (no event is fired) -->
-<rel-switch id="wifi" field-aria-label="Wi-Fi"></rel-switch>
-<script>
-  const wifi = document.getElementById('wifi');
-  wifi.checked = true;
-</script>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-switch.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `checked` | `checked` | `boolean` | `false` | Whether the switch is on. Set it to control the state programmatically; user toggles update it and fire `rel-change`. |
-| `type` | `type` | `"line" \| "pill"` | `"line"` | Shape (Figma "Type"): `"line"` (default) is the 44x20 control with a thin 40x10 rail and the handle riding on it; `"pill"` is the 44x24 filled track with the handle inside it. NOTE: Figma's own default is Pill. We default to `line` deliberately — flipping it would restyle every existing switch — so this is a recorded divergence from the design default, not an oversight. Reflected. |
-| `disabled` | `disabled` | `boolean` | `false` | Disables interaction and swaps in the dulled rail / handle fills; the handle shadow is removed. |
-| `value` | `value` | `string` | `""` | Arbitrary string echoed in the `rel-change` event detail — useful when one handler serves several switches. |
-| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the native input. Without it the switch has no label of its own, so pair it with a visible `<label>` or set this. |
-| `label` | `label` | `string` | `undefined` | Visible text beside the control. Clicking it toggles the switch, and it becomes the accessible name — use `fieldAriaLabel` instead when the switch has no visible text. For rich content (a bold word, an icon) slot it in the default slot rather than setting this. |
-| `labelPlacement` | `label-placement` | `"end" \| "start"` | `"end"` | Which side the label sits on: `end` (default) puts it after the control, `start` before it. Note this is a PHYSICAL side, not a writing-direction one, matching every other placement prop in the library. Reflected. |
-| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Control scale: `small`, `medium` (default) or `large`. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Figma's Switch has axes Type / State / Enabled only, with no Size, so this ramp is ours. `medium` is exactly the control that shipped before it existed, so an existing switch is unchanged. It does NOT respond to viewport width. Picking a size per breakpoint is the consuming application's decision — a control that silently resized itself at some width would be undocumentable behaviour, and the breakpoint that matters belongs to the layout around it, not to the switch. Reflected. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-change` | `{ checked: this.checked, value: this.value, }` | bubbles / composed | Fired when the user toggles the switch (not on programmatic `checked` changes). Detail: `{ checked: boolean, value: string }`. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | Rich label content beside the control, as an alternative to the `label` property. Clicking it toggles the switch. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `root` | The `<label>` holding the control and its optional text; carries the `label-placement` order |
-| `base` | The control box around the hidden input and the track |
-| `track` | The thin rail; the handle is its `::before` pseudo-element |
-| `label` | The text beside the control; not rendered when there is neither a `label` nor slotted content |
-
-## Tokens / CSS Variables
-
-### Component hooks
-
-Set these on the host (or an ancestor) to customise the element without touching design tokens.
-
-| Custom property | Default | Description |
-| --- | --- | --- |
-| `--rel-switch-disabled` | `var(--switch-disabled)` | Handle colour while disabled; default `var(--rel-bg-neutral-elevated-1)` |
-| `--rel-switch-knob-off` | `var(--switch-knob-off)` | Handle colour when unchecked; default `var(--rel-text-static-light)` |
-| `--rel-switch-knob-on` | `var(--switch-knob-on)` | Handle colour when checked; default `var(--rel-bg-neutral-inverse-2)` |
-| `--rel-switch-thumb-size` | `var(--_rel-sw-thumb)` | Handle diameter; defaults to the `size` ramp (16 / 20 / 24px), and the handle always travels its own width minus the 2px inset on each side |
-| `--rel-switch-track` | `var(--switch-track)` | Rail colour; default `var(--rel-bg-neutral-elevated-2)` |
-| `--rel-switch-track-height` | `var(--_rel-sw-h)` | Overall control height; defaults to the `size` ramp — 16 / 20 / 24px for `type="line"`, 20 / 24 / 28px for `type="pill"` |
-| `--rel-switch-track-width` | `var(--_rel-sw-w)` | Overall control width; defaults to the `size` ramp (36 / 44 / 52px) |
-| `--switch-halo` | `var(--rel-action-overlay-hover-strong)` | — |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- Renders a native `<input type="checkbox" role="switch">` with `aria-checked` mirroring `checked`; the input is visually hidden (opacity 0, zero size) inside a `<label part="base">`, so clicking anywhere on the control toggles it.
-- `field-aria-label` becomes the input's `aria-label`. The input lives in the shadow root, so an external `<label for>` cannot reference it — set `field-aria-label` for the accessible name and place any visible text beside the switch.
-- Focus: the wrapper shows a 1.5px focus outline whenever the input is focused (mouse or keyboard).
-- `disabled` disables the native input (removed from the tab order), dims the control to 50% and drops the handle shadow.
-- `prefers-reduced-motion: reduce` removes the track and handle transitions.
-
-| Key | Action |
-| --- | --- |
-| `Space` | Toggles the switch (native checkbox behaviour). |
-| `Tab` / `Shift+Tab` | Moves focus to / from the switch. |
-
-## Notes / Edge Cases
-
-- `rel-change` fires for user toggles only; setting `checked` from JavaScript updates the visuals but emits nothing.
-- Geometry follows the `size` ramp, derived from the Figma Line switch at `medium`: 44×20 control, 40×10 track inset 2px, 20px handle travelling 20px. `small` is 36×16 and `large` 52×24, holding the same invariants (handle = control height, width = 2× height + 4, rail = height ÷ 2, travel = width − 4 − handle). `type="pill"` shares the width, handle and travel but is 4px taller at every size — 20 / 24 / 28 — because its height is the handle plus its 2px inset, where Line's height *is* the handle. Changing `--rel-switch-track-width` widens the control without moving the "on" position.
-- **`size` does not respond to viewport width.** Figma has no Size axis on Switch, so the ramp is ours, and choosing a size per breakpoint is the application's decision — set it from your own media queries or container queries. A control that resized itself at some width would be behaviour a design system cannot document, and the breakpoint that matters belongs to the layout around the switch, not to the switch.
-- A `label` (or slotted content) becomes the switch's accessible name and is clickable, because the root element is the `<label>` that owns the input. Use `field-aria-label` instead when there is no visible text; when both are set, `label` wins.
-- Figma's default Type=Pill switch (44×24 filled track with the handle inside) is not implemented.
-- Hover tints the track with the action overlay and raises the handle shadow; pressed shows a 28px overlay disc behind the handle and squashes it to 20×16.
-- Legacy hook aliases still honoured: `--switch-track`, `--switch-knob-on`, `--switch-knob-off` and `--switch-disabled` are read as fallbacks of the `--rel-switch-*` hooks. The old `--switch-halo` name was never read by any rule and is not a hook.
-- `registerOnChange`, `registerOnTouched` and `writeValue` exist for the Angular `ControlValueAccessor` wrapper and are not public API.
+# rel-switch
+
+`<rel-switch>` implements the Figma **Switch** component set (9059:11244): Type Line (default; at medium a 44×20 toggle with a thin 10px track and a 20px handle that slides 20px) or Pill (a 44×24 filled track), three sizes, an optional label at either end, and the hover, pressed, focused and disabled states from the Figma State axis. It wraps a native checkbox with `role="switch"`, so keyboard and screen-reader behaviour are native. Use it for settings that take effect immediately (notifications on/off, dark mode); for choices that are collected and submitted with a form use `<rel-checkbox>`.
+
+## Usage
+
+```html
+<!-- Basic -->
+<rel-switch field-aria-label="Email notifications"></rel-switch>
+
+<!-- On by default -->
+<rel-switch checked field-aria-label="Dark mode"></rel-switch>
+
+<!-- Disabled, off and on -->
+<rel-switch disabled field-aria-label="Locked setting"></rel-switch>
+<rel-switch checked disabled field-aria-label="Locked setting"></rel-switch>
+
+<!-- One handler for several switches: `value` is echoed in the event detail -->
+<rel-switch value="marketing" field-aria-label="Marketing emails"></rel-switch>
+<rel-switch value="product" field-aria-label="Product updates"></rel-switch>
+<script>
+  document.addEventListener('rel-change', (e) => {
+    if (e.target.tagName !== 'REL-SWITCH') return;
+    console.log(e.detail.value, e.detail.checked); // "marketing", true
+  });
+</script>
+
+<!-- Programmatic control (no event is fired) -->
+<rel-switch id="wifi" field-aria-label="Wi-Fi"></rel-switch>
+<script>
+  const wifi = document.getElementById('wifi');
+  wifi.checked = true;
+</script>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-switch.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `checked` | `boolean` | `false` | Whether the switch is on. Set it to control the state programmatically; user toggles update it and fire `rel-change`. |
+| `type` | `type` | `"line" \| "pill"` | `"line"` | Shape (Figma "Type"): `"line"` (default) is the 44x20 control with a thin 40x10 rail and the handle riding on it; `"pill"` is the 44x24 filled track with the handle inside it. Pressing squashes the handle; only `line` also shows a pressed disc behind it. Reflected. |
+| `disabled` | `disabled` | `boolean` | `false` | Disables interaction and swaps in the dulled rail / handle fills (for both types, checked or not) and the disabled label colour; the handle shadow is removed. An ancestor `<fieldset disabled>` disables it the same way, without changing this property. |
+| `value` | `value` | `string` | `""` | Arbitrary string echoed in the `rel-change` event detail — useful when one handler serves several switches. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the native input when the switch has no visible text. Prefer `label`, slotted text or an outer `<label>` (wrapping the switch, or `for=`), which are visible and clickable. |
+| `label` | `label` | `string` | `undefined` | Visible text beside the control. Clicking it toggles the switch, and it becomes the accessible name — use `fieldAriaLabel` instead when the switch has no visible text. For rich content (a bold word, an icon) slot it in the default slot rather than setting this. |
+| `labelPlacement` | `label-placement` | `"end" \| "start"` | `"end"` | Which side the label sits on: `end` (default) puts it after the control, `start` before it. Note this is a PHYSICAL side, not a writing-direction one, matching every other placement prop in the library. Reflected. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Control scale: `small`, `medium` (default) or `large`. `sm` / `md` / `lg` are alternative spellings and stay supported — normalised to the full words, not deprecated. Matches Figma's Size axis: controls 36 / 44 / 52px wide, labels body-sm / body-md / body-lg (12 / 14 / 16px). The default stays `medium` (Figma's own default is Large). It does NOT respond to viewport width. Picking a size per breakpoint is the consuming application's decision — a control that silently resized itself at some width would be undocumentable behaviour, and the breakpoint that matters belongs to the layout around it, not to the switch. Reflected. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ checked: this.checked, value: this.value, }` | bubbles / composed | Fired when the user toggles the switch (not on programmatic `checked` changes). Detail: `{ checked: boolean, value: string }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Rich label content beside the control, as an alternative to the `label` property. Clicking it toggles the switch. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `root` | The `<label>` holding the control and its optional text; carries the `label-placement` order and the keyboard focus ring |
+| `base` | The control box around the hidden input and the track |
+| `track` | The thin rail; the handle is its `::before` pseudo-element |
+| `label` | The text beside the control (body-sm / body-md / body-lg by `size`; `--rel-text-disabled` while disabled); not rendered when there is neither a `label` nor slotted content |
+
+## Tokens / CSS Variables
+
+### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-switch-disabled` | `var(--switch-disabled)` | Handle colour while disabled; default `var(--rel-bg-neutral-elevated-1)` |
+| `--rel-switch-knob-off` | `var(--switch-knob-off)` | Handle colour when unchecked; default `var(--rel-text-static-light)` |
+| `--rel-switch-knob-on` | `var(--switch-knob-on)` | Handle colour when checked; default `var(--rel-bg-neutral-inverse-2)` |
+| `--rel-switch-thumb-size` | `var(--_rel-sw-thumb)` | Handle diameter; defaults to the `size` ramp (16 / 20 / 24px), and the handle always travels its own width minus the 2px inset on each side |
+| `--rel-switch-track` | `var(--switch-track)` | Rail colour; default `var(--rel-bg-neutral-elevated-2)` |
+| `--rel-switch-track-height` | `var(--_rel-sw-h)` | Overall control height; defaults to the `size` ramp — 16 / 20 / 24px for `type="line"`, 20 / 24 / 28px for `type="pill"` |
+| `--rel-switch-track-width` | `var(--_rel-sw-w)` | Overall control width; defaults to the `size` ramp (36 / 44 / 52px) |
+| `--switch-halo` | `var(--rel-action-overlay-hover-strong)` | — |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Renders a native `<input type="checkbox" role="switch">` with `aria-checked` mirroring `checked`; the input is visually hidden (opacity 0, zero size) inside the `<label part="root">` that also holds the label text, so clicking anywhere on the control or its text toggles it.
+- `field-aria-label` becomes the input's `aria-label`. Use it only when there is no visible text; visible text in `label` or the default slot is clickable and becomes the accessible name.
+- An outer `<label>` works too, wrapped around the switch (`<label><rel-switch></rel-switch> Wi-Fi</label>`) or pointing at it (`<label for="wifi">Wi-Fi</label><rel-switch id="wifi">`). The element is form-associated, so clicking the label's text toggles the switch (once, with one `rel-change`); a disabled switch ignores it. The input lives in the shadow root, where `aria-labelledby` cannot reach the label, so the label's text is copied into the input's `aria-label`. That happens only when the switch has no name of its own: `label`, `field-aria-label` and slotted text each win over an outer label. The copy follows edits to the label's text.
+- Focus: keyboard focus (`:focus-visible`) draws one square 1.5px `--rel-border-focus` outline around the whole component, control and label together (the same treatment as `rel-checkbox` and `rel-radio`). A pointer click shows no ring.
+- `disabled` disables the native input (removed from the tab order), swaps in the dulled rail and handle fills, drops the handle shadow and colours the label `--rel-text-disabled`.
+- Forced colors (Windows High Contrast): the rail and handle are redrawn from system colours (a CanvasText outline, the handle filled Highlight when on, GrayText while disabled), and the focus ring stays an outline.
+- `prefers-reduced-motion: reduce` removes the track and handle transitions.
+
+| Key | Action |
+| --- | --- |
+| `Space` | Toggles the switch (native checkbox behaviour). |
+| `Tab` / `Shift+Tab` | Moves focus to / from the switch. |
+
+## Notes / Edge Cases
+
+- `rel-change` fires for user toggles only; setting `checked` from JavaScript updates the visuals but emits nothing.
+- Geometry follows the `size` ramp, derived from the Figma Line switch at `medium`: 44×20 control, 40×10 track inset 2px, 20px handle travelling 20px. `small` is 36×16 and `large` 52×24, holding the same invariants (handle = control height, width = 2× height + 4, rail = height ÷ 2, travel = width − 4 − handle). `type="pill"` shares the width, handle and travel but is 4px taller at every size — 20 / 24 / 28 — because its height is the handle plus its 2px inset, where Line's height *is* the handle. Changing `--rel-switch-track-width` widens the control without moving the "on" position.
+- The label type follows the size: body-sm / body-md / body-lg (12 / 14 / 16px) for small / medium / large.
+- **`size` does not respond to viewport width.** It follows Figma's Size axis, and choosing a size per breakpoint is the application's decision — set it from your own media queries or container queries. A control that resized itself at some width would be behaviour a design system cannot document, and the breakpoint that matters belongs to the layout around the switch, not to the switch.
+- A `label` (or slotted content) becomes the switch's accessible name and is clickable, because the root element is the `<label>` that owns the input. Use `field-aria-label` instead when there is no visible text; when both are set, `label` wins.
+- Hover and pressed cover the whole component, label included. Hover tints the track with the action overlay and raises the handle shadow. Pressed (pointer down, or Space held) squashes the handle by 4px on Line (16×12 / 20×16 / 24×20) over an overlay disc 8px wider than the handle, and to (handle + 1) × (handle − 2) on Pill, with no disc; an unchecked rail turns `--rel-bg-neutral-elevated-1` while pressed.
+- Legacy hook aliases still honoured: `--switch-track`, `--switch-knob-on`, `--switch-knob-off` and `--switch-disabled` are read as fallbacks of the `--rel-switch-*` hooks. The old `--switch-halo` name was never read by any rule and is not a hook.
+- `registerOnChange`, `registerOnTouched` and `writeValue` exist for the Angular `ControlValueAccessor` wrapper and are not public API.
+- The element is form-associated (so an outer `<label>` can find it) but sets no form value: it is still NOT submitted with a surrounding `<form>`, and form reset does not touch it. It does now appear in `form.elements`. Read `checked` or listen to `rel-change`.
+- Inside a `<fieldset disabled>` the switch behaves disabled (input disabled, dulled fills, no toggling) without its `disabled` property changing.
+- `el.click()` from script now toggles the switch, like a native checkbox; it used to do nothing.