@bitforgehq/ui 0.3.0

package/ai/components/segmented.md

@@ -0,0 +1,517 @@
+# bf-segmented
+
+Segmented control for switching between two to four views, keyboard-navigable like radios
+
+`BfSegmentedComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfSegmentedComponent, type BfSegmentOption } from '@bitforgehq/ui';
+
+/**
+ * The bf-segmented overview.
+ *
+ * Live demo of `bf-segmented`: the default width and a full-width control sharing a number value
+ * (the range in days); then the sm, md and lg sizes in a row, and a disabled control with a
+ * selected segment (forced-colours coverage for a disabled selected item).
+ */
+@Component({
+  selector: 'app-example-segmented-overview',
+  imports: [BfSegmentedComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-segmented label="Range" [options]="ranges" [(value)]="range" />
+      <bf-segmented label="Range" [options]="ranges" [(value)]="range" [fullWidth]="true" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+      <div data-sizes class="flex flex-wrap items-center gap-3">
+        <bf-segmented size="sm" label="Small" [options]="sizeOptions" value="sm" />
+        <bf-segmented label="Medium" [options]="sizeOptions" value="md" />
+        <bf-segmented size="lg" label="Large" [options]="sizeOptions" value="lg" />
+      </div>
+      <bf-segmented
+        data-disabled
+        label="Disabled"
+        [options]="sizeOptions"
+        value="md"
+        [disabled]="true"
+      />
+    </div>
+  `,
+})
+export class SegmentedOverviewExampleComponent {
+  /** The range in days: a number value. */
+  readonly range = signal<number | null>(1);
+  /** The size row: each control selects its own step. */
+  readonly sizeOptions: BfSegmentOption[] = [
+    { value: 'sm', label: 'sm · 32' },
+    { value: 'md', label: 'md · 40' },
+    { value: 'lg', label: 'lg · 48' },
+  ];
+  readonly ranges: BfSegmentOption<number>[] = [
+    { value: 1, label: 'Day' },
+    { value: 7, label: 'Week' },
+    { value: 30, label: 'Month' },
+  ];
+
+  readonly status = computed(
+    () =>
+      `Range: ${this.ranges.find((r) => r.value === this.range())?.label ?? ''} (${this.range() ?? 0} days)`,
+  );
+}
+```
+
+## Overview
+
+Segmented control for switching between two to four views. Behaves like a radio group for
+keyboard and assistive tech; implements the Signal Forms value contract. Generic over the option
+value (a string by default), `null` while nothing is selected.
+
+A segmented control switches a view between two to four options: Day / Week / Month, All / Open / Done. It is a radio group for keyboard and screen readers and binds to Signal Forms like any other field.
+
+## When to use
+
+Use `bf-segmented` to switch a view between two to four short options: Day / Week / Month, List / Board. Use [bf-radio-group](https://bitforge-ui.web.app/components/radio-group) instead when the options need descriptions or there are more of them, [bf-select](https://bitforge-ui.web.app/components/select) for a long list, and [bf-chip](https://bitforge-ui.web.app/components/chip)s for filters that combine.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** A segmented control for a date range. */
+@Component({
+  selector: 'app-example-segmented-basic',
+  imports: [BfSegmentedComponent],
+  template: `
+    <div class="flex flex-col items-start gap-2">
+      <bf-segmented label="Range" [options]="ranges" [(value)]="range" />
+      <p class="text-caption text-text-muted">range: {{ range() }}</p>
+    </div>
+  `,
+})
+export class SegmentedBasicExampleComponent {
+  readonly ranges: BfSegmentOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+    { value: 'month', label: 'Month' },
+  ];
+  readonly range = signal<string | null>('day');
+}
+```
+
+`value` is `null` while no segment is selected; the first enabled segment then owns the tab stop.
+`(changed)` emits the chosen value after a user change.
+
+## Typed values
+
+The control is generic over the option value: numbers, ids and objects bind directly.
+`BfSegmentOption` defaults to `string`; type it for anything else, and bind a `T | null` signal or
+form field.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** A segmented control of numbers: the bound value is a day count. */
+@Component({
+  selector: 'app-example-segmented-typed',
+  imports: [BfSegmentedComponent],
+  template: `
+    <div class="flex flex-col items-start gap-2">
+      <bf-segmented label="Range" [options]="ranges" [(value)]="days" />
+      <p class="text-caption text-text-muted">days: {{ days() }}</p>
+    </div>
+  `,
+})
+export class SegmentedTypedExampleComponent {
+  readonly ranges: BfSegmentOption<number>[] = [
+    { value: 1, label: 'Day' },
+    { value: 7, label: 'Week' },
+    { value: 30, label: 'Month' },
+  ];
+  readonly days = signal<number | null>(7);
+}
+```
+
+Options are matched to `value` with `Object.is`; for object values that are equal but not the same
+instance, pass `compareWith`, e.g. `[compareWith]="byDays"` with
+`byDays = (a: Range, b: Range) => a.days === b.days` (called as `compareWith(optionValue, value)`).
+An option whose value is `null` is not supported: `null` means nothing is selected, so such an
+option never shows as selected.
+
+Migrating from 0.2: "nothing selected" is `null` (it was `''`); type bound signals and fields
+`T | null` and compare against `null`, or listen to `(changed)`.
+
+## Full width
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** A segmented control that fills its container, segments sharing the width. */
+@Component({
+  selector: 'app-example-segmented-full-width',
+  imports: [BfSegmentedComponent],
+  template: `
+    <bf-segmented label="Filter" [options]="filters" [fullWidth]="true" [(value)]="filter" />
+  `,
+})
+export class SegmentedFullWidthExampleComponent {
+  protected readonly filters: BfSegmentOption[] = [
+    { value: 'all', label: 'All' },
+    { value: 'open', label: 'Open' },
+    { value: 'done', label: 'Done' },
+  ];
+  protected readonly filter = signal<string | null>('all');
+}
+```
+
+## Sizes
+
+`size` sets the height of the whole control (the track): `sm` 32 px, `md` 40 px (default), `lg` 48 px, so it lines up with a field or button of the same step. Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer each segment is its own hit area (24 px tall at `sm`); under a coarse pointer (touch) hit areas grow to 44 px at every step.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg segmented sizes. */
+@Component({
+  selector: 'app-example-segmented-sizes',
+  imports: [BfSegmentedComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-segmented size="sm" label="Range" [options]="ranges" [(value)]="range" />
+      <bf-segmented label="Range" [options]="ranges" [(value)]="range" />
+      <bf-segmented size="lg" label="Range" [options]="ranges" [(value)]="range" />
+    </div>
+  `,
+})
+export class SegmentedSizesExampleComponent {
+  protected readonly ranges: BfSegmentOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+  ];
+  protected readonly range = signal<string | null>('week');
+}
+```
+
+## With Signal Forms
+
+Bind the field instead of the value. Required, touched, errors, disabled and readonly flow in; the
+first error shows under the track once the user leaves the control, and `errorMessage` shows at
+once (e.g. a server error). `name` is accepted for Signal Forms but not rendered, because the
+control has no native form element.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** A segmented control bound to a Signal Forms field. */
+@Component({
+  selector: 'app-example-segmented-signal-forms',
+  imports: [FormField, BfSegmentedComponent],
+  template: `
+    <div class="flex flex-col items-start gap-2">
+      <bf-segmented label="Range" [options]="ranges" [formField]="report.range" />
+      <p class="text-caption text-text-muted">range: {{ report.range().value() }}</p>
+    </div>
+  `,
+})
+export class SegmentedSignalFormsExampleComponent {
+  protected readonly ranges: BfSegmentOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+  ];
+  private readonly model = signal<{ range: string | null }>({ range: 'day' });
+  protected readonly report = form(this.model);
+}
+```
+
+## Read-only
+
+`readonly` shows the choice but blocks changes: clicks and the arrow, Home and End keys do nothing,
+focus stays on the selected segment and Tab leaves the group. The track rests on the muted surface.
+
+```ts
+import { Component } from '@angular/core';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** A read-only segmented control. */
+@Component({
+  selector: 'app-example-segmented-readonly',
+  imports: [BfSegmentedComponent],
+  template: `<bf-segmented label="Range" [options]="ranges" [readonly]="true" [value]="range" />`,
+})
+export class SegmentedReadonlyExampleComponent {
+  protected readonly ranges: BfSegmentOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+  ];
+  protected readonly range = 'week';
+}
+```
+
+## Naming the group
+
+`label` is the group's accessible name (it is not shown). Without it, use `ariaLabel`, or
+`ariaLabelledby` pointing at a visible heading. A group needs one of the three.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfSegmentOption, BfSegmentedComponent } from '@bitforgehq/ui';
+
+/** A segmented control named by the heading above it. */
+@Component({
+  selector: 'app-example-segmented-named',
+  imports: [BfSegmentedComponent],
+  template: `
+    <div class="flex flex-col items-start gap-2">
+      <h3 id="segmented-range-heading" class="text-heading">Range</h3>
+      <bf-segmented ariaLabelledby="segmented-range-heading" [options]="ranges" [(value)]="range" />
+    </div>
+  `,
+})
+export class SegmentedNamedExampleComponent {
+  protected readonly ranges: BfSegmentOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+  ];
+  protected readonly range = signal<string | null>('day');
+}
+```
+
+## Validation
+
+Once the control is touched it shows the first error as text: the error's own `message`, else the default for its kind from `provideBfLabels()`'s `validation` labels (`required` "Fill in this field", `email`, `pattern`, `parse`, `min(n)`, `max(n)`, `minLength(n)` "Use at least n characters", `maxLength(n)`, `minDate(d)`, `maxDate(d)`, and `fallback` "Check this value" for any other kind), so it never turns red without text. Reactive Forms `Validators.*` errors carry no message and get the same defaults (`minlength`/`maxlength` read their limit from the error's `context`). An explicit `errorMessage` wins over both and shows at once, e.g. for a server error.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, FormRoot, form, required } from '@angular/forms/signals';
+import { BfButtonComponent, BfSegmentedComponent, type BfSegmentOption } from '@bitforgehq/ui';
+
+/**
+ * A required segmented with the default message.
+ *
+ * `required(p.range)` has no message, so a submit with nothing chosen shows "Fill in this field".
+ */
+@Component({
+  selector: 'app-example-segmented-validation',
+  imports: [FormField, FormRoot, BfButtonComponent, BfSegmentedComponent],
+  template: `
+    <form [formRoot]="report" class="flex flex-col items-start gap-3">
+      <bf-segmented label="Range" [options]="options" [formField]="report.range" />
+      <bf-button type="submit">Run report</bf-button>
+    </form>
+  `,
+})
+export class SegmentedValidationExampleComponent {
+  protected readonly options: BfSegmentOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+  ];
+  private readonly model = signal<{ range: string | null }>({ range: null });
+  protected readonly report = form(
+    this.model,
+    (p) => {
+      required(p.range);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Desktop
+
+Hovering an inactive segment darkens its label to `text`, and the active one takes a `surface-muted` fill, with the pointer cursor; a read-only control has no hover. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The focus ring, on a 2 px `surface` offset, shows on keyboard focus only. Under a fine pointer each segment is its own hit area (24 px tall at `sm`). Desktop density is the default `md` step; `provideBfDefaults({ size: 'sm' })`, or `{ size: 'sm' }` in a component's `providers`, makes a dense toolbar, table or sidebar ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Track: `surface-sunken`.
+- Active segment: `surface` / `text` with the `shadow-segment` elevation and a 1.5 px inset `primary-strong` outline (≥ 3:1 on `surface` and the track, so the selection does not rest on the fill), hover `surface-muted` (under `forced-colors`, `Highlight` / `HighlightText` with a `CanvasText` outline). Inactive: `text-muted`, hover `text`. Pressed (editable only): `surface-pressed` with `text` (the selected segment keeps `Highlight` under `forced-colors`).
+- Read-only: track `surface-muted`, no hover, default cursor. Error: the track gets a 1.5 px `danger-border` ring and the message below is `danger`.
+- Focus ring: `ring`, drawn past a 2 px `surface` offset so it sits on `surface` (≥ 3:1) rather than on the track. Disabled segments: `text-disabled` with `cursor-not-allowed`; an unselected one takes the `surface-sunken` fill, the selected one keeps its `surface` pill without the shadow, outlined in `text-disabled` (never opacity).
+- Shape (track and segments): `rounded-control` (`--radius-control`, `9999px` by default).
+
+Segments are at least 24/32/40 px tall inside the track's 4 px padding. Under a fine pointer the segment is its hit area; under a coarse pointer (touch) an invisible extension gives each a 44 px hit area. A label longer than its segment wraps between its words and the segment grows taller; a segment never gets narrower than its longest word, so no label is cut or broken between letters. The side padding is in px, so under iOS Dynamic Type the extra width goes to the label. When the segments cannot fit even so (a long compound word in a narrow column, three segments at iOS 235 % on a phone), the control scrolls sideways; at 200 % three one-word segments still fit a phone side by side.
+
+## Accessibility
+
+`role="radiogroup"` with `aria-label` from `label` (else `ariaLabel`, or `aria-labelledby` from `ariaLabelledby`); each segment is a `<button role="radio">` with `aria-checked` mirroring selection. Only the selected (or first enabled) segment sits in the tab order — the rest carry `tabindex="-1"` — and ArrowRight/Down, ArrowLeft/Up, Home and End move the selection and focus like a native radio group, matching platform expectations. `disabled` segments are skipped by keyboard navigation and get the native attribute. The group carries `aria-required`, and once touched and invalid `aria-invalid="true"` with `aria-describedby` and `aria-errormessage` pointing at the error text. Read-only: `aria-readonly="true"` on the group; the tab stop stays focusable and selection by pointer or keyboard is ignored. `focus()` focuses the tab-stop segment; Signal Forms calls it from `focusBoundControl()`. Under forced colours (Windows High Contrast) the selected segment opts out of the adjustment (`forced-color-adjust: none`) and paints `Highlight`/`HighlightText` itself with a `CanvasText` selected outline, focus outline and focus ring (on a `Canvas` offset) and no shadow, so it paints system colours only and so no text backplate hides its label; a disabled selected segment's outline is `GrayText` instead; the others repaint in `ButtonText`.
+
+### Keyboard
+
+While `readonly` the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move nothing; <kbd>Tab</kbd> still leaves the control.
+
+| Key                                              | Action                                                                                                                           |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus into and out of the control: one tab stop, on the selected segment (else the first enabled one)                      |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowDown</kbd>     | Selects and focuses the next enabled segment in DOM order, wrapping at the end; not mirrored under `dir="rtl"` yet (a known gap) |
+| <kbd>ArrowLeft</kbd> / <kbd>ArrowUp</kbd>        | Selects and focuses the previous enabled segment in DOM order, wrapping at the start; not mirrored under `dir="rtl"` yet         |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Selects and focuses the first / last enabled segment                                                                             |
+| <kbd>Space</kbd> / <kbd>Enter</kbd>              | Selects the focused segment                                                                                                      |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                                             |
+| ---------------- | ----------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | `readonly BfSegmentOption<T>[]`                             | required    | The segments.                                                                                                                                                           |
+| `compareWith`    | `BfCompareWith<T>`                                          | `Object.is` | Equality for matching `value` to an option (default `Object.is`); pass one for object values.                                                                           |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step of the control (track): sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                                       |
+| `fullWidth`      | `boolean`                                                   | `false`     | Stretch the control and share the width between segments.                                                                                                               |
+| `disabled`       | `boolean`                                                   | `false`     | Disables every segment. Set by `[formField]`; do not bind it yourself.                                                                                                  |
+| `readonly`       | `boolean`                                                   | `false`     | Shows the choice but blocks changes; the tab stop stays focusable and the group exposes `aria-readonly`. Set by `[formField]`; do not bind it yourself.                 |
+| `required`       | `boolean`                                                   | `false`     | Marks the choice required (`aria-required` on the group). Set by `[formField]`; do not bind it yourself.                                                                |
+| `invalid`        | `boolean`                                                   | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                        |
+| `touched`        | `boolean`                                                   | `false`     | Whether the user has left the field; errors show only once touched. Set by `[formField]`; do not bind it yourself.                                                      |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`        | Validation errors from Signal Forms; the first message is shown once touched. Set by `[formField]`; do not bind it yourself.                                            |
+| `errorMessage`   | `string`                                                    | `''`        | Explicit error text; takes precedence over Signal Forms errors.                                                                                                         |
+| `label`          | `string`                                                    | `''`        | Accessible name of the group (not rendered visibly).                                                                                                                    |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name when `label` is not set.                                                                                                                                |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the group (e.g. a visible heading) when `label` is not set.                                                                           |
+| `name`           | `string`                                                    | `''`        | Name of the bound field. Not rendered, because the control has no native form element; kept so Signal Forms can bind it. Set by `[formField]`; do not bind it yourself. |
+| `id`             | `string`                                                    | `generated` | Group id; generated when not set.                                                                                                                                       |
+| `value`          | `T \| null`                                                 | `null`      | The selected option's value, `null` while nothing is selected; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.                                       |
+
+## Outputs
+
+| Name      | Payload | Description                                                                                             |
+| --------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `changed` | `T`     | Emitted with the newly selected value after a user change (never `null`).                               |
+| `touch`   | `void`  | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the segment that owns the tab stop; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+### `select(next: T): void`
+
+Selects the option whose value matches `next` under `compareWith`, as a click would.
+
+| Parameter | Type | Description                        |
+| --------- | ---- | ---------------------------------- |
+| `next`    | `T`  | The value of the option to select. |
+
+### `selectAt(index: number): void`
+
+Selects the option at `index` unless the control is disabled or read-only, the option is
+missing, or it is already selected.
+
+| Parameter | Type     | Description                              |
+| --------- | -------- | ---------------------------------------- |
+| `index`   | `number` | The position of the option in `options`. |
+
+## Notes
+
+### Do
+
+- Keep labels to one short word so all segments fit on a phone; a longer label wraps onto a second line, and a control whose segments cannot fit scrolls sideways.
+- Give the group a `label` (or `ariaLabel` / `ariaLabelledby`); it is the accessible name.
+
+### Don't
+
+- Don't use it for more than four options or for actions; use `bf-select` or buttons.
+
+## Migration notes
+
+### 0.3.0
+
+**Breaking:** typed values. `BfSegmentedComponent<T = string>` is generic over the option value
+(`BfSegmentOption<T = string>`); `value` is `T | null` and defaults to `null` (was `''`), with
+nothing checked and the first enabled segment owning the tab stop; `changed` emits `T` (was
+`string`). New `compareWith` (default `Object.is`) matches `value` to an option. `tabStop` is now
+the index of the segment that owns the tab stop (was its value, `-1` when every option is
+disabled), and `select(value)` matches through `compareWith`. See Migration 6, 7 and 10.
+
+**Breaking:** heights follow the shared `BfSize` scale: the track is `sm` 32, `md` 40 (default,
+was 44), `lg` 48 px (new); unset, `size` follows `provideBfDefaults()`'s `controlSize`. The
+segments' 44 px hit extension applies only under a coarse pointer (`pointer-coarse:`). See
+Migration 3.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+**Behaviour:** the selected segment carries a 1.5 px inset `primary-strong` outline (≥ 3:1 on
+`surface` and the track), so the selection no longer rests on a fill 1.18:1 from the track; a
+disabled selected segment is outlined in `text-disabled`. The focus ring sits on a 2 px `surface`
+offset (≥ 3:1) instead of on the track (2.79:1). The track and segments use `rounded-control`
+(`--radius-control`).
+
+**Behaviour:** under forced colours the selected segment's outline, focus ring (on a `Canvas`
+offset) and shadow use system colours only (`CanvasText`; no shadow), since it opts out of the
+adjustment; a disabled selected segment's outline is `GrayText` instead of the authored
+`text-disabled`.
+
+JSDoc of `segmented.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs; template handlers and framework hooks marked `@internal`, so the reference
+leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): an editable segment takes `surface-pressed` (an unselected one with `text`, which holds 4.5:1 there) while held down. None while disabled or read-only; under forced colours the system colours win.
+
+**Behaviour:** sets `aria-errormessage` to its error paragraph (`<id>-error`) while
+`aria-invalid="true"`, and an error that appears while a pointer button is held down (a press
+elsewhere that blurred it) shows once the press ends, so the layout never moves under the pointer
+(F-020).
+
+**Behaviour:** labels stay whole at every text size. The segments' side padding is px
+(`px-[12px]`/`px-[14px]`/`px-[18px]`, the rem values at the default size) and so is the track's
+(`px-[4px]`, `gap-[2px]`), so Dynamic Type spends the width on the label; a segment shrinks only to
+its longest word (`min-w-min`, was `min-w-0`) and a label wraps between words (was
+`wrap-anywhere`, which broke "System" letter by letter at iOS AX5). When the segments still cannot
+fit, the track grows past the control and a new `[data-bf-segmented-scroller]` wrapper
+(`overflow-x-auto`, padded so the focus ring is not clipped) scrolls it sideways; the host gains
+`max-w-full`. On the demo's Theme control the three segments fit side by side at iOS 200 %
+(WCAG 1.4.4) on a 393 px phone, and scroll at 235 %. See Migration 38.
+
+### 0.2.0
+
+Each segment's hit area reaches 44 px through an `::after` extension (`after:-inset-y-1` on md
+36 px, `after:-inset-y-1.5` on sm 32 px); the visual size is unchanged. Labels render in a
+`data-label` span (it wraps, see "Changed" below), and segments are `min-w-0`, so a long label in
+`fullWidth` no longer overflows its share. Disabled: unselected segments take `surface-sunken`, the selected one
+keeps its `surface` pill without the shadow; text `text-disabled` as before.
+
+Fixed: every segment shows a pointer cursor while enabled (`not-allowed` when disabled). The
+active segment now also tints on hover (`enabled:hover:bg-surface-muted`), matching the active
+tab's hover in `bf-tab-bar`.
+
+Added: validation state, mirroring `bf-radio-group`. New `required`, `invalid`, `touched`, `errors`
+and `errorMessage` inputs; once touched and invalid (or with an explicit `errorMessage`) the first
+message renders under the track (`id="{id}-error"`), the radiogroup gets `aria-invalid="true"` and
+`aria-describedby`, and the track a 1.5 px `danger-border` ring; `aria-required` follows
+`required`. A required segmented choice no longer fails silently.
+
+Layout change: the host is now a column (`inline-flex flex-col items-start gap-1.5`) so the message
+sits under the track. Without an error it renders as before; `justify-*` or `items-*` utilities a
+consumer put on the host now act on the column.
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only `select()` and the
+arrow, Home and End keys do nothing, the group carries `aria-readonly="true"`, the tab stop stays
+focusable, and the track rests on `surface-muted` without segment hover (default cursor).
+`ariaLabel` / `ariaLabelledby` name the group when `label` is not set. `focus(options?)` focuses the
+tab-stop segment, so Signal Forms' `focusBoundControl()` works. `name` is documented as bound but
+not rendered (the control has no native form element).
+
+Fixed: under forced colours the selected label is legible. The selected segment adds
+`forced-colors:forced-color-adjust-none` next to `Highlight`/`HighlightText` (Chromium painted a
+Canvas text backplate under `HighlightText`, white on white in light, black on black in dark) and
+a `CanvasText` focus outline; unselected segments repaint in `ButtonText` on a transparent fill.
+
+Changed: a long label wraps instead of truncating. Segments are `min-h-8`/`min-h-9` with `py-1`
+(were fixed `h-8`/`h-9`, `whitespace-nowrap`), the label span is `wrap-anywhere text-center`, so a
+segment grows taller rather than showing "Tages…".
+
+### 0.1.0
+
+New `bf-segmented`: a `role="radiogroup"` control for switching between two to four views, implementing `FormValueControl<string>`. `sm`/`md` (32/36 px) item heights, optional `fullWidth`. Keyboard arrow keys move the roving-tabindex selection and wrap around, skipping disabled options; `Home`/`End` jump to the first/last enabled option. The roving tab stop (`tabStop`) now falls back to the first enabled option when the selected value is missing or disabled, instead of leaving every segment at `tabIndex -1`. A keyboard selection also moves DOM focus to the newly selected button. The active segment's fill is now visible under forced-colors (`forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]`), and the inactive segment explicitly clears its background there.