@reliability-design/web 1.4.6 → 1.4.8

package/dist/components/rel-segmented-button/README.md

@@ -1,141 +1,156 @@
-# rel-segmented-button
-
-## Overview
-A segmented button group for mutually exclusive selections. Displays multiple options as connected buttons with a single active selection. Supports size variants, alignment options, and individual option states (disabled).
-
-## Usage
-```html
-<!-- Basic segmented button -->
-<rel-segmented-button id="viewMode" active="grid"></rel-segmented-button>
-<script>
-  const viewMode = document.getElementById('viewMode');
-  viewMode.options = [
-    { label: 'List', value: 'list' },
-    { label: 'Grid', value: 'grid' },
-    { label: 'Table', value: 'table' }
-  ];
-</script>
-
-<!-- Small size with alignment -->
-<rel-segmented-button
-  id="textAlign"
-  size="small"
-  align="middle"
-  active="center">
-</rel-segmented-button>
-<script>
-  const textAlign = document.getElementById('textAlign');
-  textAlign.options = [
-    { label: 'Left', value: 'left' },
-    { label: 'Center', value: 'center' },
-    { label: 'Right', value: 'right' }
-  ];
-</script>
-
-<!-- With disabled option -->
-<rel-segmented-button id="planSelector"></rel-segmented-button>
-<script>
-  const planSelector = document.getElementById('planSelector');
-  planSelector.options = [
-    { label: 'Free', value: 'free' },
-    { label: 'Pro', value: 'pro' },
-    { label: 'Enterprise', value: 'enterprise', disabled: true }
-  ];
-  planSelector.active = 'free';
-</script>
-
-<!-- Listen for changes -->
-<rel-segmented-button id="sortOrder"></rel-segmented-button>
-<script>
-  const sortOrder = document.getElementById('sortOrder');
-  sortOrder.options = [
-    { label: 'Newest', value: 'newest' },
-    { label: 'Oldest', value: 'oldest' },
-    { label: 'Popular', value: 'popular' }
-  ];
-  sortOrder.addEventListener('changed', (e) => {
-    console.log('Selected:', e.detail.value);
-  });
-</script>
-```
-
-## API
-
-### Attributes/Properties
-| Name | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `SegmentOption[]` | `[]` | Array of segment options (see SegmentOption interface below) |
-| `active` | `string` | `""` | Value of the currently active segment |
-| `size` | `"small" \| "medium"` | `"medium"` | Size variant |
-| `align` | `"left" \| "middle" \| "right"` | `"left"` | Horizontal alignment of the button group |
-
-### SegmentOption Interface
-```typescript
-interface SegmentOption {
-  label: string;      // Display text for the button
-  value: string;      // Unique value identifier
-  disabled?: boolean; // Optional: disable this specific segment
-}
-```
-
-## Events
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `changed` | `{ value: string }` | Fired when a different segment is selected |
-
-## Slots
-Default slot not used.
-
-## CSS Parts
-None exposed.
-
-## Tokens / CSS Variables
-
-### Semantic Tokens
-- `--rel-fonts-font-family` - Font family
-- `--rel-body-xs-regular-font-size`, `--rel-body-sm-regular-font-size` - Font sizes for small and medium variants
-- `--rel-fonts-weight-body-medium` - Font weight for segment labels
-
-### Spacing Tokens
-- `--rel-spacing-3xs`, `--rel-spacing-2xs` - Vertical padding for sizes
-- `--rel-spacing-xs`, `--rel-spacing-sm` - Horizontal padding for sizes
-
-### Color Tokens
-- `--rel-bg-surface` - Default segment background
-- `--rel-border-default` - Outer border and segment dividers
-- `--rel-text-label` - Active segment background and default text color
-- `--rel-bg-neutral-elevated-1` - Hover and disabled background
-- `--rel-text-disabled` - Disabled text color
-- `--rel-border-info` - Focus outline color
-
-### Border Tokens
-- `--rel-border-radius-md` - Border radius for the group
-
-## Accessibility
-- Uses native `<button>` elements for proper keyboard navigation
-- Focus visible state with inner outline for keyboard users
-- Disabled segments use `pointer-events: none` and reduced opacity
-- Each segment can receive focus independently
-
-### Keyboard Interactions
-- `Tab` - Move focus between segments
-- `Space/Enter` - Activate focused segment
-- `Arrow Left/Right` - Navigate between segments (browser default)
-
-### Focus Behavior
-- Focus outline appears inside the button boundary with `-2px` offset
-- Uses info border color for high contrast
-- Active button has `z-index: 1` to ensure focus ring is visible over adjacent segments
-
-## Notes / Edge Cases
-- The component is `display: inline-block` and sizes to fit content
-- All segments are connected with shared borders (2px solid gray)
-- The last segment has no right border to avoid doubling with the outer container border
-- Active segment has inverted colors (dark background, white text)
-- Hovering a non-active, non-disabled segment shows a light gray background
-- Hovering the active segment does not change its appearance
-- Disabled segments show reduced opacity (0.5), gray background, and are non-interactive
-- The `align` property uses flexbox justify-content (left → flex-start, middle → center, right → flex-end)
-- Size variants affect both font size and padding
-- Smooth transitions (0.2s ease-in-out) apply to all visual changes
-- Clicking a disabled option will not change the `active` value or dispatch events
+# rel-segmented-button
+
+A single-select segmented button group: a row of buttons on a 2px-inset track where exactly one segment is active at a time. Each entry in `options` renders as a native `<button role="radio">` inside a `role="radiogroup"`, so the group behaves like a compact radio group (one Tab stop, arrow keys move the selection). Use it for mutually exclusive view or mode switches with two to five short options (list / grid, day / week / month, sort order); do not use it for navigation between pages (use `rel-tab`) or for actions (use `rel-button`).
+
+The control comes in three sizes that match the text field ramp — `small` 32px, `medium` 40px, `large` 48px — and each option can carry a leading `icon`.
+
+## Usage
+
+```html
+<!-- Basic: options are set as a property, `active` holds the selected value -->
+<rel-segmented-button id="view-mode" active="grid" field-aria-label="View mode"></rel-segmented-button>
+<script>
+  document.getElementById('view-mode').options = [
+    { label: 'List', value: 'list' },
+    { label: 'Grid', value: 'grid' },
+    { label: 'Table', value: 'table' }
+  ];
+</script>
+
+<!-- Options as a JSON attribute, small size -->
+<rel-segmented-button
+  size="small"
+  active="week"
+  field-aria-label="Calendar range"
+  options='[{"label":"Day","value":"day"},{"label":"Week","value":"week"},{"label":"Month","value":"month"}]'>
+</rel-segmented-button>
+
+<!-- Large size (48px), matching a large text field -->
+<rel-segmented-button
+  size="large"
+  active="grid"
+  field-aria-label="View mode"
+  options='[{"label":"List","value":"list"},{"label":"Grid","value":"grid"}]'>
+</rel-segmented-button>
+
+<!-- Leading icons: `icon` names a rel-icon, sized 16 / 18 / 20 with the control -->
+<rel-segmented-button
+  active="list"
+  field-aria-label="View mode"
+  options='[{"label":"List","value":"list","icon":"bullet-list"},{"label":"Grid","value":"grid","icon":"dashboard"}]'>
+</rel-segmented-button>
+
+<!-- Disabled option: rendered but not selectable or focusable -->
+<rel-segmented-button id="plan" active="free" field-aria-label="Plan"></rel-segmented-button>
+<script>
+  document.getElementById('plan').options = [
+    { label: 'Free', value: 'free' },
+    { label: 'Pro', value: 'pro' },
+    { label: 'Enterprise', value: 'enterprise', disabled: true }
+  ];
+</script>
+
+<!-- Alignment inside a wider host (align only matters when the host is stretched) -->
+<rel-segmented-button
+  style="display: block; width: 100%"
+  align="middle"
+  active="asc"
+  field-aria-label="Sort direction"
+  options='[{"label":"Ascending","value":"asc"},{"label":"Descending","value":"desc"}]'>
+</rel-segmented-button>
+
+<!-- Listen for changes -->
+<rel-segmented-button id="sort-order" active="newest" field-aria-label="Sort order"></rel-segmented-button>
+<script>
+  const sortOrder = document.getElementById('sort-order');
+  sortOrder.options = [
+    { label: 'Newest', value: 'newest' },
+    { label: 'Oldest', value: 'oldest' },
+    { label: 'Popular', value: 'popular' }
+  ];
+  sortOrder.addEventListener('changed', (e) => {
+    console.log('Selected:', e.detail.value);
+  });
+</script>
+```
+
+The `SegmentOption` interface and the `SegmentSize` / `SegmentAlign` unions are exported from the package:
+
+```typescript
+import type { SegmentOption } from '@reliability-design/web';
+
+const options: SegmentOption[] = [
+  { label: 'List', value: 'list' },                      // label = visible text, value = what `active` / the event carry
+  { label: 'Grid', value: 'grid', icon: 'dashboard' },   // icon = a rel-icon name, drawn before the label
+  { label: 'Archive', value: 'archive', disabled: true } // rendered at 50% opacity, skipped by the arrow keys
+];
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-segmented-button.ts — do not edit; run readme-generate.mjs -->
+
+## API
+
+### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | `options` | `SegmentOption[]` | `[]` | The segments in order, each `{ label: string; value: string; disabled?: boolean; icon?: string; badge?: number \| string \| boolean }`. Set as a property (or a JSON array attribute); a disabled entry is rendered but cannot be selected, and `icon` names a `rel-icon` drawn before the label. |
+| `active` | `active` | `string` | `""` | `value` of the currently selected segment. Updated by the component on click / arrow keys; set it to pre-select a segment (an unknown value selects nothing). |
+| `size` | `size` | `"small" \| "medium" \| "large"` | `"medium"` | Control height, matching the TextField ramp: `small` (32px — 28px segments, `action-md` 12px text, 16px icons), `medium` (default, 40px — 36px segments, `action-lg` 14px text, 18px icons) or `large` (48px — 44px segments, `action-xl` 16px text, 20px icons). |
+| `align` | `align` | `"left" \| "middle" \| "right"` | `"left"` | `justify-content` of the group's inline-flex container: `left` (default), `middle` or `right`. Only visible when the host is made wider than its content. |
+| `fieldAriaLabel` | `field-aria-label` | `string` | `undefined` | Accessible name for the radiogroup (it renders no visible group label). |
+
+## Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `changed` | `{ value: option.value }` | bubbles / composed | Fired after a non-disabled segment is selected by click or arrow / Home / End key (also when it was already the active one). Detail: `{ value: string }`. |
+
+## Slots
+
+| Slot | Description |
+| --- | --- |
+| — | This element has no slots. |
+
+## CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `option` | Each segment's native `<button role="radio">`; the active one carries the `active` class and `aria-checked="true"`. |
+| `icon` | A segment's optional leading `rel-icon` element. |
+| `label` | The wrapper around a segment's label text. |
+| `badge` | A segment's optional trailing `rel-badge`; rendered only when the option sets `badge`. |
+| `base` | The `role="radiogroup"` track that lays out the segments. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The container is a `role="radiogroup"`; give it a name with `field-aria-label` — the component renders no visible group label, so without it screen readers announce an unnamed group.
+- Every segment is a native `<button role="radio">` with `aria-checked="true"` on the active one and `aria-checked="false"` on the rest. Disabled options get the native `disabled` attribute, so they are not focusable and do not fire `click`.
+- Roving tabindex (APG radio-group pattern): the whole group is a single Tab stop. The active segment carries `tabindex="0"`; if `active` matches no enabled option, the first enabled segment takes the Tab stop instead (without becoming selected). All other segments are `tabindex="-1"`.
+- Arrow keys both move focus and select, so they emit `changed` immediately. Focus is moved to the newly active segment after the re-render.
+- Focus ring: a 2px `border-focus` outline drawn inside the segment (`outline-offset: -2px`) and raised with `z-index: 1` so it stays above the neighbouring segment.
+- Nothing is announced beyond the native `aria-checked` change.
+
+| Key | Action |
+| --- | --- |
+| `Tab` / `Shift+Tab` | Move focus into / out of the group (one stop, on the active segment) |
+| `ArrowRight` / `ArrowDown` | Select and focus the next enabled segment (wraps to the first) |
+| `ArrowLeft` / `ArrowUp` | Select and focus the previous enabled segment (wraps to the last) |
+| `Home` / `End` | Select and focus the first / last enabled segment |
+| `Enter` / `Space` | Native button activation: selects the focused segment |
+
+## Notes / Edge Cases
+
+- The change event is named `changed` (no `rel-` prefix, unlike most components); it bubbles and is composed, so it can be listened for on any ancestor. It also fires when the already-active segment is clicked again.
+- `active` is a plain string compared against `option.value`; setting it to a value that is not in `options` (or to a disabled option's value) renders no active segment.
+- `options` is compared by reference: mutate-in-place changes are not picked up — assign a new array.
+- The host is `display: inline-block` and the group `inline-flex`, so it sizes to its content; `align` has no visible effect until the host is stretched (e.g. `style="display: block; width: 100%"`). Every segment has `min-width: 80px`, so a group is never narrower than 80px per segment.
+- Sizing: the track is a `bg-neutral` surface with `spacing-3xs` (2px) padding and a `border-radius-xs` corner — there is no outer border and no dividers between segments. Each segment carries the full `border-radius-xs` on all four corners in every state. Segment heights are 28 / 36 / 44 for `small` / `medium` / `large`, which with the 2px inset give control heights of 32 / 40 / 48.
+- Per size: padding `spacing-3xs spacing-sm` / `spacing-2xs spacing-md` / `spacing-xs spacing-lg`, text `action-md` (12px) / `action-lg` (14px) / `action-xl` (16px), and leading icons at 16 / 18 / 20px with an `spacing-xs` (8px) gap.
+- Colours: the active segment uses `action-neutral-fill` with inverse text (and `action-neutral-fill-hover` on hover); a non-active segment is transparent so the `action-overlay-hover` alpha composites over the track; disabled segments are drawn at 50% opacity with `bg-neutral-elevated-1` and a `not-allowed` cursor. Background and colour transitions are 0.2s.
+- A per-option `icon` renders a `rel-icon` before the label. Its size rides `--rel-icon-size` set directly on the `rel-icon` element — not on a wrapper, since `rel-icon` reflects `size="md"` and its own `:host([size])` rule would otherwise win.
+- No design-token overrides or `--rel-segmented-button-*` hooks are exposed; style through the `base` / `option` / `icon` / `label` parts.