@reliability-design/web 1.4.9 → 1.4.11

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

@@ -1,171 +1,171 @@
-# rel-stepper
-
-A multi-step progress indicator implementing the Figma "Stepper" component: its `Type` axis (default, dot, number, icon indicators), its `Typel` label-placement axis (top, centered, inverted), two sizes and both orientations. Each entry in `steps` renders as a focusable step with a circular indicator, a label and a connector to the next step, styled by its status (`done`, `progress`, `disabled`). Use it to show where the user is in a linear flow (checkout, onboarding, a wizard) and to let them jump back to completed steps; the component is presentation only — it never changes a step's status itself, so drive `steps` from your own state.
-
-## Usage
-
-```html
-<!-- Horizontal (default), labels under the indicators -->
-<rel-stepper id="checkout"></rel-stepper>
-<script>
-  document.getElementById('checkout').steps = [
-    { title: 'Cart', status: 'done' },
-    { title: 'Shipping', status: 'progress' },
-    { title: 'Payment', status: 'disabled' },
-    { title: 'Confirmation', status: 'disabled' }
-  ];
-</script>
-
-<!-- Vertical, label beside the indicator (Figma Type = Centered).
-     `size` is DEPRECATED and deliberately omitted: Figma has no Size axis on the
-     Stepper — the connector geometry is fixed — so it was a code-only scale. It is
-     still accepted so existing markup keeps working, but it now resolves to the one
-     Figma geometry and logs a one-time notice. Retune with
-     `--rel-stepper-connector-length` instead. -->
-<rel-stepper id="onboarding" orientation="vertical" label-placement="centered"></rel-stepper>
-<script>
-  document.getElementById('onboarding').steps = [
-    { title: 'Create account', status: 'done' },
-    { title: 'Verify email', status: 'done' },
-    { title: 'Set up profile', status: 'progress' },
-    { title: 'Done', status: 'disabled' }
-  ];
-</script>
-
-<!-- Figma Type axis: dot / number / icon indicators -->
-<rel-stepper type="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
-<rel-stepper type="number" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
-<rel-stepper type="icon" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
-
-<!-- Figma .Line Types axis: the CONNECTOR between steps, dashed 2px on / 2px off.
-     Distinct from type="dot" above, which is the indicator disc — combine freely. -->
-<rel-stepper connector="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
-<rel-stepper connector="dot" type="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
-
-<!-- Label placement (Figma Typel): top-aligned beside the indicator, or indicator above the label -->
-<rel-stepper orientation="vertical" label-placement="top" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
-<rel-stepper label-placement="inverted" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
-
-<!-- Let users jump back to a completed step -->
-<rel-stepper id="wizard"></rel-stepper>
-<script>
-  const wizard = document.getElementById('wizard');
-  wizard.steps = [
-    { title: 'Select', status: 'done' },
-    { title: 'Configure', status: 'progress' },
-    { title: 'Review', status: 'disabled' }
-  ];
-  wizard.addEventListener('rel-step-change', (e) => {
-    console.log('Activated step', e.detail.index, e.detail.step.title);
-    // Recompute statuses and assign a new array so the stepper re-renders
-    wizard.steps = wizard.steps.map((s, i) => ({
-      ...s,
-      status: i < e.detail.index ? 'done' : i === e.detail.index ? 'progress' : 'disabled'
-    }));
-  });
-</script>
-```
-
-### Deprecated aliases
-
-```html
-<!-- textalign="right" → label-placement="centered"; textalign="below" → label-placement="inverted".
-     Still supported and still the fallback when label-placement is unset. Since 1.4.9 a
-     non-default value logs a one-time console notice; it had been marked deprecated since the
-     rename but never said so at runtime. Setting label-placement supersedes it and stays silent. -->
-<rel-stepper textalign="right" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
-```
-
-The `Step` type and the `StepStatus`, `StepperType`, `StepperConnector` and `LabelPlacement` unions are exported from the package:
-
-```typescript
-import type { Step } from '@reliability-design/web';
-
-const steps: Step[] = [
-  { title: 'Cart', status: 'done' },        // filled indicator with a check mark
-  { title: 'Shipping', status: 'progress' }, // current step (aria-current="step")
-  { title: 'Payment', status: 'disabled' }   // not yet reachable; rendered at 40% opacity, not focusable
-];
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-stepper.ts — do not edit; run readme-generate.mjs -->
-
-## API
-
-### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `steps` | `steps` | `Step[]` | `[]` | The steps in order, each `{ title: string; subtitle?: string; status: "done" \| "progress" \| "disabled" }`. Set as a property (or a JSON array attribute); the component never mutates it — update it from the `rel-step-change` handler. |
-| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout axis: `horizontal` (default) lays the steps out in a centred row; `vertical` stacks them. |
-| `type` | `type` | `"default" \| "dot" \| "number" \| "icon"` | `"default"` | Figma "Type" axis — what the INDICATOR shows: `default` (step number, check mark once done), `dot` (8px dot, no glyph), `number` (always the number) or `icon` (always the check mark). Not the same axis as `connector="dot"`, which dashes the line between steps. Reflected. |
-| `connector` | `connector` | `"solid" \| "dot"` | `"solid"` | Figma ".Line Types" axis — how the line BETWEEN steps is drawn: `solid` (an unbroken 1px rule) or `dot` (a 1px rule dashed 2px on, 2px off). Applies to both orientations. Not the same axis as `type="dot"`, which is the indicator disc; the two are independent and can be combined. Reflected. |
-| `labelPlacement` | `label-placement` | `"top" \| "centered" \| "inverted"` | `undefined` | Figma "Typel" axis — where the label sits: `top` (top-aligned beside the indicator), `centered` (vertically centred beside it) or `inverted` (indicator above the label). When unset, the deprecated `textAlign` prop drives the layout (`below` ≈ `inverted`, `right` ≈ `centered`). Figma marks Top + Horizontal as an unsupported combination. Reflected. |
-
-#### Deprecated (still supported — removal targeted for 3.0)
-
-| Property | Attribute | Type | Use instead |
-| --- | --- | --- | --- |
-| `textAlign` | `textalign` | `"right" \| "below"` | Deprecated alias of `label-placement`; use `label-placement="inverted"` instead of `textalign="below"` and `label-placement="centered"` instead of `textalign="right"`. |
-| `size` | `size` | `"small" \| "large"` | Figma has no Size axis on the Stepper — the connector geometry is fixed — so this was a code-only scale. It stays accepted so existing markup keeps working, and now resolves to the one Figma geometry. Retune it with `--rel-stepper-connector-length` instead. Logs a one-time notice. |
-
-## Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-step-change` | `{ index, step, }` | bubbles / composed | Fired when a step whose status is not `disabled` is clicked or activated with Enter / Space. Detail: `{ index: number, step: Step }`. Statuses are not changed by the component — update `steps` in the handler. |
-
-## Slots
-
-| Slot | Description |
-| --- | --- |
-| — | This element has no slots. |
-
-## CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `indicator` | The 24px circle (8px for `type="dot"`) that holds the step number, check mark or icon. |
-| `track` | The 1px connector line from a step to the next one (not rendered on the last step). |
-| `label` | The step title text. |
-| `subtitle` | The optional second line under the title; rendered only when a step sets `subtitle`. |
-
-## 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-stepper-connector-length` | `var(--rel-stepper-connector-length-lg, 96px)` | Length of the connector line; the step gap is derived from it by adding Figma's clear space at both ends. Defaults to Figma's fixed geometry: 96px horizontally, 34px vertically with `label-placement="centered"`, 51px with `inverted`. |
-| `--rel-stepper-indicator-size` | `24px` | Indicator diameter (default 24px; `type="dot"` is fixed at 8px). |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- The list renders as a `role="group"` with the fixed name "Progress steps" (not configurable).
-- Every step is a `role="button"` element with `aria-label="<title>, step n of N"`, plus ", completed" for `done` steps. The `progress` step carries `aria-current="step"`; `disabled` steps carry `aria-disabled="true"` and `tabindex="-1"` so they are skipped in the Tab order and by the arrow keys.
-- Enabled steps are individual Tab stops (`tabindex="0"`) with a 2px focus ring; the indicators and connectors are purely visual (the check mark SVG is `aria-hidden`).
-- Activating a step only emits `rel-step-change`; nothing is announced and no status changes until you update `steps`.
-
-| Key | Action |
-| --- | --- |
-| `Enter` / `Space` | Activate the focused step (emits `rel-step-change`; ignored on `disabled` steps) |
-| `ArrowRight` / `ArrowDown` | Move focus to the next enabled step (wraps to the first) |
-| `ArrowLeft` / `ArrowUp` | Move focus to the previous enabled step (wraps to the last) |
-| `Home` / `End` | Move focus to the first / last enabled step |
-
-## Notes / Edge Cases
-
-- `label-placement` is the canonical layout switch (Figma `Typel`). When it is unset the deprecated `textalign` prop decides: `below` renders like `inverted` (indicator above the label), `right` renders like `centered` (label beside the indicator). `top` differs from `centered` only in aligning the label to the top of the indicator. Figma marks Top + Horizontal as an unsupported combination.
-- Statuses map to the Figma `.Artwork` states: `done` = inverse fill with a check mark (or the number when `type="number"`, nothing when `type="dot"`), `progress` = neutral fill with a strong 1px border, `disabled` = the same drawn at 40% opacity. Connectors are `border-strong` after a `done` / `progress` step and `border-default` otherwise.
-- `type="icon"` shows the check mark on every step regardless of status; `type="dot"` shrinks the indicator to 8px and fills it for `done` and `progress`.
-- Two axes spell one value "dot" and they are independent: `type="dot"` is the INDICATOR (an 8px disc replacing the number), `connector="dot"` is the LINE between steps. `connector="dot"` draws a 1px rule dashed 2px on / 2px off, matching Figma `.Line Types` `Type=Dot` (`strokeWeight=1`, `strokeDashes=[2,2]`). It is a repeating gradient rather than a dashed border because no engine lets you state a 2/2 dash period. The dash takes the connector's own state colour, so it goes `border-strong` after a `done` / `progress` step like the solid line does.
-- Connector length doubles as the gap between steps and depends on `size` and `orientation`: large = `--rel-stepper-connector-length-lg` (86px) in both orientations; small horizontal = `--rel-stepper-connector-length-md` (60px); small vertical = `--rel-stepper-connector-length-sm` (42px). Note the `md` / `sm` suffixes refer to those defaults, not to a size value.
-- Labels never wrap (`white-space: nowrap`); keep titles short or widen the connector hooks.
-- `steps` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
-- Steps are `<div role="button">` elements, not native buttons, so they do not submit forms and do not get native disabled styling.
+# rel-stepper
+
+A multi-step progress indicator implementing the Figma "Stepper" component: its `Type` axis (default, dot, number, icon indicators), its `Typel` label-placement axis (top, centered, inverted), two sizes and both orientations. Each entry in `steps` renders as a focusable step with a circular indicator, a label and a connector to the next step, styled by its status (`done`, `progress`, `disabled`). Use it to show where the user is in a linear flow (checkout, onboarding, a wizard) and to let them jump back to completed steps; the component is presentation only — it never changes a step's status itself, so drive `steps` from your own state.
+
+## Usage
+
+```html
+<!-- Horizontal (default), labels under the indicators -->
+<rel-stepper id="checkout"></rel-stepper>
+<script>
+  document.getElementById('checkout').steps = [
+    { title: 'Cart', status: 'done' },
+    { title: 'Shipping', status: 'progress' },
+    { title: 'Payment', status: 'disabled' },
+    { title: 'Confirmation', status: 'disabled' }
+  ];
+</script>
+
+<!-- Vertical, label beside the indicator (Figma Type = Centered).
+     `size` is DEPRECATED and deliberately omitted: Figma has no Size axis on the
+     Stepper — the connector geometry is fixed — so it was a code-only scale. It is
+     still accepted so existing markup keeps working, but it now resolves to the one
+     Figma geometry and logs a one-time notice. Retune with
+     `--rel-stepper-connector-length` instead. -->
+<rel-stepper id="onboarding" orientation="vertical" label-placement="centered"></rel-stepper>
+<script>
+  document.getElementById('onboarding').steps = [
+    { title: 'Create account', status: 'done' },
+    { title: 'Verify email', status: 'done' },
+    { title: 'Set up profile', status: 'progress' },
+    { title: 'Done', status: 'disabled' }
+  ];
+</script>
+
+<!-- Figma Type axis: dot / number / icon indicators -->
+<rel-stepper type="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+<rel-stepper type="number" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+<rel-stepper type="icon" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+
+<!-- Figma .Line Types axis: the CONNECTOR between steps, dashed 2px on / 2px off.
+     Distinct from type="dot" above, which is the indicator disc — combine freely. -->
+<rel-stepper connector="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+<rel-stepper connector="dot" type="dot" steps='[{"title":"Plan","status":"done"},{"title":"Build","status":"progress"},{"title":"Ship","status":"disabled"}]'></rel-stepper>
+
+<!-- Label placement (Figma Typel): top-aligned beside the indicator, or indicator above the label -->
+<rel-stepper orientation="vertical" label-placement="top" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
+<rel-stepper label-placement="inverted" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
+
+<!-- Let users jump back to a completed step -->
+<rel-stepper id="wizard"></rel-stepper>
+<script>
+  const wizard = document.getElementById('wizard');
+  wizard.steps = [
+    { title: 'Select', status: 'done' },
+    { title: 'Configure', status: 'progress' },
+    { title: 'Review', status: 'disabled' }
+  ];
+  wizard.addEventListener('rel-step-change', (e) => {
+    console.log('Activated step', e.detail.index, e.detail.step.title);
+    // Recompute statuses and assign a new array so the stepper re-renders
+    wizard.steps = wizard.steps.map((s, i) => ({
+      ...s,
+      status: i < e.detail.index ? 'done' : i === e.detail.index ? 'progress' : 'disabled'
+    }));
+  });
+</script>
+```
+
+### Deprecated aliases
+
+```html
+<!-- textalign="right" → label-placement="centered"; textalign="below" → label-placement="inverted".
+     Still supported and still the fallback when label-placement is unset. Since 1.4.9 a
+     non-default value logs a one-time console notice; it had been marked deprecated since the
+     rename but never said so at runtime. Setting label-placement supersedes it and stays silent. -->
+<rel-stepper textalign="right" steps='[{"title":"Review","status":"done"},{"title":"Approve","status":"progress"}]'></rel-stepper>
+```
+
+The `Step` type and the `StepStatus`, `StepperType`, `StepperConnector` and `LabelPlacement` unions are exported from the package:
+
+```typescript
+import type { Step } from '@reliability-design/web';
+
+const steps: Step[] = [
+  { title: 'Cart', status: 'done' },        // filled indicator with a check mark
+  { title: 'Shipping', status: 'progress' }, // current step (aria-current="step")
+  { title: 'Payment', status: 'disabled' }   // not yet reachable; rendered at 40% opacity, not focusable
+];
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-stepper.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `steps` | `steps` | `Step[]` | `[]` | The steps in order, each `{ title: string; subtitle?: string; status: "done" \| "progress" \| "disabled" }`. Set as a property (or a JSON array attribute); the component never mutates it — update it from the `rel-step-change` handler. |
+| `orientation` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout axis: `horizontal` (default) lays the steps out in a centred row; `vertical` stacks them. |
+| `type` | `type` | `"default" \| "dot" \| "number" \| "icon"` | `"default"` | Figma "Type" axis — what the INDICATOR shows: `default` (step number, check mark once done), `dot` (8px dot, no glyph), `number` (always the number) or `icon` (always the check mark). Not the same axis as `connector="dot"`, which dashes the line between steps. Reflected. |
+| `connector` | `connector` | `"solid" \| "dot"` | `"solid"` | Figma ".Line Types" axis — how the line BETWEEN steps is drawn: `solid` (an unbroken 1px rule) or `dot` (a 1px rule dashed 2px on, 2px off). Applies to both orientations. Not the same axis as `type="dot"`, which is the indicator disc; the two are independent and can be combined. Reflected. |
+| `labelPlacement` | `label-placement` | `"top" \| "centered" \| "inverted"` | `undefined` | Figma "Typel" axis — where the label sits: `top` (top-aligned beside the indicator), `centered` (vertically centred beside it) or `inverted` (indicator above the label). When unset, the deprecated `textAlign` prop drives the layout (`below` ≈ `inverted`, `right` ≈ `centered`). Figma marks Top + Horizontal as an unsupported combination. Reflected. |
+
+#### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `textAlign` | `textalign` | `"right" \| "below"` | Deprecated alias of `label-placement`; use `label-placement="inverted"` instead of `textalign="below"` and `label-placement="centered"` instead of `textalign="right"`. |
+| `size` | `size` | `"small" \| "large"` | Figma has no Size axis on the Stepper — the connector geometry is fixed — so this was a code-only scale. It stays accepted so existing markup keeps working, and now resolves to the one Figma geometry. Retune it with `--rel-stepper-connector-length` instead. Logs a one-time notice. |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-step-change` | `{ index, step, }` | bubbles / composed | Fired when a step whose status is not `disabled` is clicked or activated with Enter / Space. Detail: `{ index: number, step: Step }`. Statuses are not changed by the component — update `steps` in the handler. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `indicator` | The 24px circle (8px for `type="dot"`) that holds the step number, check mark or icon. |
+| `track` | The 1px connector line from a step to the next one (not rendered on the last step). |
+| `label` | The step title text. |
+| `subtitle` | The optional second line under the title; rendered only when a step sets `subtitle`. |
+
+## 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-stepper-connector-length` | `var(--rel-stepper-connector-length-lg, 96px)` | Length of the connector line; the step gap is derived from it by adding Figma's clear space at both ends. Defaults to Figma's fixed geometry: 96px horizontally, 34px vertically with `label-placement="centered"`, 51px with `inverted`. |
+| `--rel-stepper-indicator-size` | `24px` | Indicator diameter (default 24px; `type="dot"` is fixed at 8px). |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The list renders as a `role="group"` with the fixed name "Progress steps" (not configurable).
+- Every step is a `role="button"` element with `aria-label="<title>, step n of N"`, plus ", completed" for `done` steps. The `progress` step carries `aria-current="step"`; `disabled` steps carry `aria-disabled="true"` and `tabindex="-1"` so they are skipped in the Tab order and by the arrow keys.
+- Enabled steps are individual Tab stops (`tabindex="0"`) with a 2px focus ring; the indicators and connectors are purely visual (the check mark SVG is `aria-hidden`).
+- Activating a step only emits `rel-step-change`; nothing is announced and no status changes until you update `steps`.
+
+| Key | Action |
+| --- | --- |
+| `Enter` / `Space` | Activate the focused step (emits `rel-step-change`; ignored on `disabled` steps) |
+| `ArrowRight` / `ArrowDown` | Move focus to the next enabled step (wraps to the first) |
+| `ArrowLeft` / `ArrowUp` | Move focus to the previous enabled step (wraps to the last) |
+| `Home` / `End` | Move focus to the first / last enabled step |
+
+## Notes / Edge Cases
+
+- `label-placement` is the canonical layout switch (Figma `Typel`). When it is unset the deprecated `textalign` prop decides: `below` renders like `inverted` (indicator above the label), `right` renders like `centered` (label beside the indicator). `top` differs from `centered` only in aligning the label to the top of the indicator. Figma marks Top + Horizontal as an unsupported combination.
+- Statuses map to the Figma `.Artwork` states: `done` = inverse fill with a check mark (or the number when `type="number"`, nothing when `type="dot"`), `progress` = neutral fill with a strong 1px border, `disabled` = the same drawn at 40% opacity. Connectors are `border-strong` after a `done` / `progress` step and `border-default` otherwise.
+- `type="icon"` shows the check mark on every step regardless of status; `type="dot"` shrinks the indicator to 8px and fills it for `done` and `progress`.
+- Two axes spell one value "dot" and they are independent: `type="dot"` is the INDICATOR (an 8px disc replacing the number), `connector="dot"` is the LINE between steps. `connector="dot"` draws a 1px rule dashed 2px on / 2px off, matching Figma `.Line Types` `Type=Dot` (`strokeWeight=1`, `strokeDashes=[2,2]`). It is a repeating gradient rather than a dashed border because no engine lets you state a 2/2 dash period. The dash takes the connector's own state colour, so it goes `border-strong` after a `done` / `progress` step like the solid line does.
+- Connector length doubles as the gap between steps and depends on `size` and `orientation`: large = `--rel-stepper-connector-length-lg` (86px) in both orientations; small horizontal = `--rel-stepper-connector-length-md` (60px); small vertical = `--rel-stepper-connector-length-sm` (42px). Note the `md` / `sm` suffixes refer to those defaults, not to a size value.
+- Labels never wrap (`white-space: nowrap`); keep titles short or widen the connector hooks.
+- `steps` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
+- Steps are `<div role="button">` elements, not native buttons, so they do not submit forms and do not get native disabled styling.