@reliability-design/web 1.4.9 → 1.4.10

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

@@ -1,147 +1,159 @@
-# rel-checkbox
-
-A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<input type="checkbox">` behind a custom box, with a label, an optional label-prefix icon and optional supporting text. It exposes the sheet's vocabulary verbatim — `size` (small / medium / large / extra-large), `density` (compact / comfortable) and `alignment` (leading / trailing) — plus `state` for error and disabled styling. Use it for independent yes/no choices and for "select all" parents (via `status="indeterminate"`); for a single choice among several options use `rel-radio`, and for an immediate on/off setting use `rel-switch`.
-
-## Usage
-
-```html
-<!-- Basic -->
-<rel-checkbox label="Accept terms"></rel-checkbox>
-
-<!-- Supporting text, compact density (default: text on its own line, indented past the box) -->
-<rel-checkbox
-  label="Subscribe to newsletter"
-  supportingtext="We'll send you weekly updates"
-  status="unchecked"
-  state="default">
-</rel-checkbox>
-
-<!-- Comfortable density: label + supporting text stack beside the box -->
-<rel-checkbox
-  density="comfortable"
-  label="Notify the broker"
-  supportingtext="Sends an email when the POD is uploaded">
-</rel-checkbox>
-
-<!-- Trailing alignment: box at the far edge of the row (settings-row style).
-     Trailing always renders comfortable density — compact has no trailing layout. -->
-<rel-checkbox
-  alignment="trailing"
-  label="Email notifications"
-  supportingtext="Weekly summary of load activity">
-</rel-checkbox>
-
-<!-- Sizes (medium is the default) -->
-<rel-checkbox size="small" label="Include archived"></rel-checkbox>
-<rel-checkbox size="large" label="I agree to the terms"></rel-checkbox>
-
-<!-- Label prefix icon -->
-<rel-checkbox icon="truck" label="Truckload only"></rel-checkbox>
-
-<!-- Error and disabled states -->
-<rel-checkbox state="error" label="Required consent"></rel-checkbox>
-<rel-checkbox state="disabled" status="checked" label="Locked by admin"></rel-checkbox>
-
-<!-- Indeterminate (programmatic-only; a user toggle resolves to checked/unchecked) -->
-<rel-checkbox id="select-all" label="Select all" status="indeterminate"></rel-checkbox>
-<script>
-  document.getElementById('select-all').addEventListener('rel-change', (e) => {
-    console.log(e.detail.checked, e.detail.value);
-  });
-</script>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-checkbox.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `label` | `label` | `string` | `"Label"` | Label text rendered next to the box. |
-| `icon` | `icon` | `string` | `""` | rel-icon name rendered between the checkbox and the label (label prefix icon); scales with `size`. Unset renders no icon and reserves no space. |
-| `supportingtext` | `supportingtext` | `string` | `""` | Supporting text under or beside the label; where it renders depends on `density`. |
-| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state (Figma State): `"error"` swaps in the danger colours, `"disabled"` blocks input and dims the whole control to 0.4 opacity (colours unchanged, as Figma specifies). |
-| `status` | `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Check state. `"indeterminate"` is programmatic-only — a user toggle always resolves to checked or unchecked. |
-| `value` | `value` | `string` | `""` | Value reported in the `rel-change` event detail (it is not submitted with a form). |
-| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large"` | `"medium"` | Control scale (Figma Size), on Figma's four-step ramp of control frames: `"small"` 16px / body-sm, `"medium"` (default) 18px / body-md, `"large"` 20px / body-lg, `"extra-large"` 24px / body-xl. Supporting text sits one body step below the label at every size (body-xs / sm / md / lg, i.e. 10 / 12 / 14 / 16px). The drawn square is inset to 80% of the frame, so the frame is the layout footprint (what the row gap and the compact indent measure from) rather than the visible square. 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 box; `"comfortable"` stacks label + supporting text beside the box. Reflected. |
-| `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Box position (Figma Alignment). `"leading"` (default) renders the box 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. Reflected. |
-| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the native checkbox, for when the visible `label` is absent or not a usable name on its own — a checkbox in a table row, or one whose meaning comes from its column header. Normally unnecessary: the input is wrapped in the `<label>` that renders `label`, so the visible text already names it natively. Setting this puts an `aria-label` on the input, which OVERRIDES that wrapping label — so set it only when the visible text is the wrong name, not to repeat it. Left unset the attribute is not emitted at all. |
-
-### Public fields / accessors
-
-| Name | Type | Description |
-| --- | --- | --- |
-| `checked` | `boolean` | Boolean view of `status`: `true` when `status === "checked"`; setting it writes `"checked"` / `"unchecked"`. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-change` | `{ checked: this.status === "checked", value: this.value, }` | bubbles / composed | Fired after a user toggle. Detail: `{ checked: boolean, value: string }`. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `base` | The outer wrapper that carries the `state` / `status` classes |
-| `label` | The visible label text |
-| `helper` | The supporting text (rendered beside the box in comfortable density, under the row in compact) |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- A visually hidden native `<input type="checkbox">` carries the semantics; the custom box is decorative. The input is wrapped in a `<label>`, so clicking anywhere on the row (label, icon or box — the whole row in trailing alignment) toggles it.
-- `status="indeterminate"` sets the native `indeterminate` flag and `aria-checked="mixed"` on the input, so screen readers announce the mixed state.
-- `state="disabled"` sets the native `disabled` attribute (the input leaves the tab order) and blocks pointer events on the whole element.
-- Focus: `:focus-visible` on the hidden input draws a 2px `--rel-border-focus` outline with a 2px offset around the box.
-- No live-region announcements are made; the native checkbox reports its own state changes.
-
-| Key | Action |
-| --- | --- |
-| `Tab` / `Shift+Tab` | Move focus to / from the checkbox |
-| `Space` | Toggle between checked and unchecked (native behaviour; indeterminate resolves to checked) |
-
-## Notes / Edge Cases
-
-- User toggling is binary: indeterminate is never entered by interaction. Set `status="indeterminate"` programmatically (e.g. a Select-All parent driven by app state).
-- `checked` is a convenience accessor over `status` (used by the Angular ControlValueAccessor wrapper); reading it is `status === "checked"`, writing it sets `"checked"` / `"unchecked"`.
-- `alignment="trailing"` with `density="compact"` is "Not available" in the Figma sheet: the element renders comfortable density and logs `[rel-checkbox] density="compact" has no trailing layout; rendering comfortable density.` once per change.
-- Comfortable density with no supporting text is visually identical to compact.
-- The host is `display: block`, so a trailing checkbox stretches to its container width; constrain the parent to control row width.
-- `value` is only reported in the `rel-change` detail — the element does not participate in native form submission.
-- The hidden native input is absolutely positioned against the `.row` containing block; keep `position: relative` on `.row` (Tab-scroll page-jump fix, shared with rel-radio).
-- Control frames are 16 / 18 / 20 / 24px for small / medium / large / extra-large, matching Figma. The frame is the layout footprint — the row gap and the compact indent measure from it — while the drawn square is inset to 80% of the frame (12.8 / 14.4 / 16 / 19.2px), as Figma draws it.
-- The square's 2px border weight is **not** verified against Figma: the control is flattened artwork (a filled vector rather than a frame with a stroke), so the sheet gives the square's outer size but says nothing about its stroke. Carried forward from the previous implementation.
-
-### Layout matrix (mirrors the Figma sheet)
-
-| Size | Density | Leading | Trailing |
-| --- | --- | --- | --- |
-| M | Comfortable | yes | yes |
-| M | Compact | yes (default) | renders comfortable |
-| S | Comfortable | yes | yes |
-| S | Compact | yes | renders comfortable |
-| L | Comfortable | yes | yes |
-| L | Compact | yes | renders comfortable |
-| XL | Comfortable | yes | yes |
-| XL | Compact | yes | renders comfortable |
-
-### Recipes (intentionally not component props)
-
-- **Selectable list row**: `alignment="trailing"` checkbox inside a padded, hover-highlighted container.
-- **Select All / nested group**: parent checkbox with `status="indeterminate"` wired to children in app state.
-- **Selectable card**: `rel-card` wrapping a checkbox; toggle a selected border on `rel-change`.
-
-See the Storybook Checkbox stories for working recipe markup.
+# rel-checkbox
+
+A tri-state checkbox implementing the Figma "Checkbox" sheet: a hidden native `<input type="checkbox">` behind a custom box, with a label, an optional label-prefix icon and optional supporting text. It exposes the sheet's vocabulary verbatim — `size` (small / medium / large / extra-large), `density` (compact / comfortable) and `alignment` (leading / trailing) — plus `state` for error and disabled styling. Use it for independent yes/no choices and for "select all" parents (via `status="indeterminate"`); for a single choice among several options use `rel-radio`, and for an immediate on/off setting use `rel-switch`.
+
+## Usage
+
+```html
+<!-- Basic -->
+<rel-checkbox label="Accept terms"></rel-checkbox>
+
+<!-- Supporting text, compact density (default: text on its own line, indented past the box) -->
+<rel-checkbox
+  label="Subscribe to newsletter"
+  supporting-text="We'll send you weekly updates"
+  status="unchecked"
+  state="default">
+</rel-checkbox>
+
+<!-- Comfortable density: label + supporting text stack beside the box -->
+<rel-checkbox
+  density="comfortable"
+  label="Notify the broker"
+  supporting-text="Sends an email when the POD is uploaded">
+</rel-checkbox>
+
+<!-- Trailing alignment: box at the far edge of the row (settings-row style).
+     Trailing always renders comfortable density — compact has no trailing layout. -->
+<rel-checkbox
+  alignment="trailing"
+  label="Email notifications"
+  supporting-text="Weekly summary of load activity">
+</rel-checkbox>
+
+<!-- Sizes (medium is the default) -->
+<rel-checkbox size="small" label="Include archived"></rel-checkbox>
+<rel-checkbox size="large" label="I agree to the terms"></rel-checkbox>
+
+<!-- Label prefix icon -->
+<rel-checkbox icon="truck" label="Truckload only"></rel-checkbox>
+
+<!-- Error and disabled states -->
+<rel-checkbox state="error" label="Required consent"></rel-checkbox>
+<rel-checkbox state="disabled" status="checked" label="Locked by admin"></rel-checkbox>
+
+<!-- Indeterminate (programmatic-only; a user toggle resolves to checked/unchecked) -->
+<rel-checkbox id="select-all" label="Select all" status="indeterminate"></rel-checkbox>
+<script>
+  document.getElementById('select-all').addEventListener('rel-change', (e) => {
+    console.log(e.detail.checked, e.detail.value);
+  });
+</script>
+```
+
+### Deprecated aliases
+
+```html
+<!-- supportingtext → supporting-text (since 1.5.0; still works, logs a one-time console notice, removed in 3.0) -->
+<rel-checkbox label="Old spelling" supportingtext="Helper line"></rel-checkbox>
+<rel-checkbox label="Canonical" supporting-text="Helper line"></rel-checkbox>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-checkbox.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `label` | `label` | `string` | `"Label"` | Label text rendered next to the box. |
+| `icon` | `icon` | `string` | `""` | rel-icon name rendered between the checkbox and the label (label prefix icon); scales with `size`. Unset renders no icon and reserves no space. |
+| `supportingtext` | `supporting-text` | `string` | `""` | Supporting text under or beside the label; where it renders depends on `density`. The `supportingtext` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `state` | `state` | `"default" \| "error" \| "disabled"` | `"default"` | Visual and interaction state (Figma State): `"error"` swaps in the danger colours, `"disabled"` blocks input and dims the whole control to 0.4 opacity (colours unchanged, as Figma specifies). |
+| `disabled` | `disabled` | `boolean` | `false` | Disables the checkbox exactly as `state="disabled"` does (`state` stays the documented spelling). Either one disables it, and so does an ancestor `<fieldset disabled>`; none of them changes the others. New in 1.5.0. |
+| `status` | `status` | `"unchecked" \| "checked" \| "indeterminate"` | `"unchecked"` | Check state. `"indeterminate"` is programmatic-only — a user toggle always resolves to checked or unchecked. |
+| `value` | `value` | `string` | `""` | Value reported in the `rel-change` event detail (it is not submitted with a form). |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "extra-large"` | `"medium"` | Control scale (Figma Size), on Figma's four-step ramp of control frames: `"small"` 16px / body-sm, `"medium"` (default) 18px / body-md, `"large"` 20px / body-lg, `"extra-large"` 24px / body-xl. Supporting text sits one body step below the label at every size (body-xs / sm / md / lg, i.e. 10 / 12 / 14 / 16px). The drawn square is inset to 80% of the frame, so the frame is the layout footprint (what the row gap and the compact indent measure from) rather than the visible square. 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 box; `"comfortable"` stacks label + supporting text beside the box. Reflected. |
+| `alignment` | `alignment` | `"leading" \| "trailing"` | `"leading"` | Box position (Figma Alignment). `"leading"` (default) renders the box 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. Reflected. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the native checkbox, for when the visible `label` is absent or not a usable name on its own — a checkbox in a table row, or one whose meaning comes from its column header. Normally unnecessary: the input is wrapped in the `<label>` that renders `label`, so the visible text already names it natively. Setting this puts an `aria-label` on the input, which OVERRIDES that wrapping label — so set it only when the visible text is the wrong name, not to repeat it. Left unset the attribute is not emitted at all. An outer `<label>` (wrapping the checkbox, or `for=`) names it only when neither this nor a visible `label` is set. |
+
+### Public fields / accessors
+
+| Name | Type | Description |
+| --- | --- | --- |
+| `supportingText` | `string` | camelCase alias of `supportingtext`, matching rel-textfield and rel-select. The declared property is lowercase, so `el.supportingText = "…"`, lit `.supportingText=${…}` and Angular `[supportingText]` used to set an unused expando and render nothing. Reading or writing either name now hits the same reactive property; the attribute stays `supportingtext`. |
+| `checked` | `boolean` | Boolean view of `status`: `true` when `status === "checked"`; setting it writes `"checked"` / `"unchecked"`. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-change` | `{ checked: this.status === "checked", value: this.value, }` | bubbles / composed | Fired after a user toggle. Detail: `{ checked: boolean, value: string }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `base` | The outer wrapper that carries the `state` / `status` classes |
+| `label` | The visible label text |
+| `helper` | The supporting text (rendered beside the box in comfortable density, under the row in compact) |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- A visually hidden native `<input type="checkbox">` carries the semantics; the custom box is decorative. The input is wrapped in a `<label>`, so clicking anywhere on the row (label, icon or box — the whole row in trailing alignment) toggles it.
+- An outer `<label>` works too, wrapped around the checkbox (`<label><rel-checkbox label=""></rel-checkbox> Accept terms</label>`) or pointing at it (`<label for="terms">Accept terms</label><rel-checkbox id="terms" label="">`). The element is form-associated, so clicking the label's text toggles it (once, with one `rel-change`); `state="disabled"` ignores it. Set `label=""` so the default "Label" text is not rendered. 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`, but only when the checkbox has no visible `label` and no `field-aria-label`: either one wins over an outer label. The copy follows edits to the label's text.
+- `status="indeterminate"` sets the native `indeterminate` flag and `aria-checked="mixed"` on the input, so screen readers announce the mixed state.
+- `state="disabled"` sets the native `disabled` attribute (the input leaves the tab order) and blocks pointer events on the whole element.
+- Focus: `:focus-visible` on the hidden input draws a 2px `--rel-border-focus` outline with a 2px offset around the box.
+- No live-region announcements are made; the native checkbox reports its own state changes.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus to / from the checkbox |
+| `Space` | Toggle between checked and unchecked (native behaviour; indeterminate resolves to checked) |
+
+## Notes / Edge Cases
+
+- User toggling is binary: indeterminate is never entered by interaction. Set `status="indeterminate"` programmatically (e.g. a Select-All parent driven by app state).
+- `checked` is a convenience accessor over `status` (used by the Angular ControlValueAccessor wrapper); reading it is `status === "checked"`, writing it sets `"checked"` / `"unchecked"`.
+- `alignment="trailing"` with `density="compact"` is "Not available" in the Figma sheet: the element renders comfortable density and logs `[rel-checkbox] density="compact" has no trailing layout; rendering comfortable density.` once per change.
+- Comfortable density with no supporting text is visually identical to compact.
+- The host is `display: block`, so a trailing checkbox stretches to its container width; constrain the parent to control row width.
+- `value` is only reported in the `rel-change` detail — the element does not participate in native form submission. It is form-associated (so an outer `<label>` can find it) but sets no form value, so it is still not submitted and form reset does not touch it; it does now appear in `form.elements`.
+- `el.click()` from script now toggles the checkbox, like a native one; it used to do nothing.
+- The hidden native input is absolutely positioned against the `.row` containing block; keep `position: relative` on `.row` (Tab-scroll page-jump fix, shared with rel-radio).
+- Control frames are 16 / 18 / 20 / 24px for small / medium / large / extra-large, matching Figma. The frame is the layout footprint — the row gap and the compact indent measure from it — while the drawn square is inset to 80% of the frame (12.8 / 14.4 / 16 / 19.2px), as Figma draws it. The square, its wall and the check / dash marks paint at the same size wherever the checkbox sits; before, the fractional squares were rounded to 12 or 13, 14 or 15, and 19 or 20px depending on the checkbox's sub-pixel position.
+- The square's 2px border weight is **not** verified against Figma: the control is flattened artwork (a filled vector rather than a frame with a stroke), so the sheet gives the square's outer size but says nothing about its stroke. Carried forward from the previous implementation.
+
+### Layout matrix (mirrors the Figma sheet)
+
+| Size | Density | Leading | Trailing |
+| --- | --- | --- | --- |
+| M | Comfortable | yes | yes |
+| M | Compact | yes (default) | renders comfortable |
+| S | Comfortable | yes | yes |
+| S | Compact | yes | renders comfortable |
+| L | Comfortable | yes | yes |
+| L | Compact | yes | renders comfortable |
+| XL | Comfortable | yes | yes |
+| XL | Compact | yes | renders comfortable |
+
+### Recipes (intentionally not component props)
+
+- **Selectable list row**: `alignment="trailing"` checkbox inside a padded, hover-highlighted container.
+- **Select All / nested group**: parent checkbox with `status="indeterminate"` wired to children in app state.
+- **Selectable card**: `rel-card` wrapping a checkbox; toggle a selected border on `rel-change`.
+
+See the Storybook Checkbox stories for working recipe markup.