@bitforgehq/ui 0.3.0

package/ai/components/radio-group.md

@@ -0,0 +1,432 @@
+# bf-radio-group
+
+Group of radio buttons for choosing one option, with optional per-option descriptions
+
+`BfRadioGroupComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfRadioGroupComponent, type BfRadioOption } from '@bitforgehq/ui';
+
+/**
+ * The bf-radio-group overview.
+ *
+ * Live demo of `bf-radio-group`: a vertical group with a description, and a horizontal one with
+ * number values that starts at `null`; then the sm, md and lg sizes in a row.
+ */
+@Component({
+  selector: 'app-example-radio-group-overview',
+  imports: [BfRadioGroupComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <bf-radio-group label="Plan" [options]="plans" [(value)]="plan" />
+      <bf-radio-group label="Seats" orientation="horizontal" [options]="seats" [(value)]="seat" />
+      <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-radio-group size="sm" label="sm · 32 px" [options]="sizeOptions" value="a" />
+        <bf-radio-group label="md · 40 px" [options]="sizeOptions" value="a" />
+        <bf-radio-group size="lg" label="lg · 48 px" [options]="sizeOptions" value="a" />
+      </div>
+    </div>
+  `,
+})
+export class RadioGroupOverviewExampleComponent {
+  readonly plan = signal('team');
+  readonly plans: BfRadioOption[] = [
+    { value: 'solo', label: 'Solo', description: 'For a single workspace' },
+    { value: 'team', label: 'Team', description: 'Shared projects and roles' },
+    { value: 'org', label: 'Organisation', description: 'Talk to sales', disabled: true },
+  ];
+
+  /** Number values; `null` until a seat count is picked. */
+  readonly seat = signal<number | null>(null);
+  /** The size row's options. */
+  readonly sizeOptions: BfRadioOption[] = [
+    { value: 'a', label: 'Option A' },
+    { value: 'b', label: 'Option B' },
+  ];
+  readonly seats: BfRadioOption<number>[] = [
+    { value: 1, label: '1 seat' },
+    { value: 5, label: '5 seats' },
+    { value: 10, label: '10 seats' },
+  ];
+
+  readonly status = computed(() => `Plan: ${this.plan()} · Seats: ${this.seat() ?? 'none'}`);
+}
+```
+
+## Overview
+
+A group of radio buttons for choosing one of a few options, with an optional description per
+option. Implements the Signal Forms value contract; generic over the option value (a string by
+default), `null` while nothing is selected.
+
+Radio buttons for picking exactly one of a few visible options. Use it when the options need to be read side by side; use `bf-select` when the list is long, and `bf-segmented` when the choice switches a view.
+
+## When to use
+
+Use `bf-radio-group` to choose exactly one of two to six options that should be read side by side, optionally with a description each. Use [bf-select](https://bitforge-ui.web.app/components/select) instead for a longer list, [bf-segmented](https://bitforge-ui.web.app/components/segmented) for a compact switch between views, and [bf-checkbox](https://bitforge-ui.web.app/components/checkbox) when several may be chosen.
+
+## Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfRadioOption, BfRadioGroupComponent } from '@bitforgehq/ui';
+
+/** A radio group of views, one with a description. */
+@Component({
+  selector: 'app-example-radio-group-basic',
+  imports: [BfRadioGroupComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-radio-group label="View" [options]="views" [(value)]="view" />
+      <p class="text-caption text-text-muted">view: {{ view() }}</p>
+    </div>
+  `,
+})
+export class RadioGroupBasicExampleComponent {
+  readonly views: BfRadioOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week', description: 'Seven days at a glance' },
+  ];
+  readonly view = signal<string | null>('day');
+}
+```
+
+`value` is `null` while nothing is checked. `(changed)` emits the chosen value after a user change.
+
+## Typed values
+
+The group is generic over the option value: numbers, ids and objects bind directly.
+`BfRadioOption` 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 BfRadioOption, BfRadioGroupComponent } from '@bitforgehq/ui';
+
+/** A radio group of numbers: the bound value is a `number | null`. */
+@Component({
+  selector: 'app-example-radio-group-typed',
+  imports: [BfRadioGroupComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-radio-group label="Seats" [options]="seats" [(value)]="seat" />
+      <p class="text-caption text-text-muted">seat: {{ seat() ?? 'null' }}</p>
+    </div>
+  `,
+})
+export class RadioGroupTypedExampleComponent {
+  readonly seats: BfRadioOption<number>[] = [
+    { value: 1, label: '1 seat' },
+    { value: 5, label: '5 seats' },
+  ];
+  readonly seat = signal<number | null>(null);
+}
+```
+
+Options are matched to `value` with `Object.is`; for object values that are equal but not the same
+instance, pass `compareWith`, e.g. `[compareWith]="byCode"` with
+`byCode = (a: Plan, b: Plan) => a.code === b.code` (called as `compareWith(optionValue, value)`).
+A string, number or boolean option value is also the radio's native `value`; an object option's is
+its index. A choice is mapped back by position, so the model always gets the option's real 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 checked" is `null` (it was `''`); type bound signals and fields
+`T | null` and compare against `null`, or listen to `(changed)`.
+
+## Horizontal
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { type BfRadioOption, BfRadioGroupComponent } from '@bitforgehq/ui';
+
+/** A horizontal radio group bound to a Signal Forms field. */
+@Component({
+  selector: 'app-example-radio-group-horizontal',
+  imports: [FormField, BfRadioGroupComponent],
+  template: `
+    <bf-radio-group
+      label="Priority"
+      orientation="horizontal"
+      [options]="priorities"
+      [formField]="task.priority"
+    />
+  `,
+})
+export class RadioGroupHorizontalExampleComponent {
+  protected readonly priorities: BfRadioOption[] = [
+    { value: 'low', label: 'Low' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'high', label: 'High' },
+  ];
+  private readonly model = signal<{ priority: string | null }>({ priority: 'medium' });
+  protected readonly task = form(this.model);
+}
+```
+
+## Sizes
+
+`sm` (32 px rows, 18 px ring, 14 px label), `md` (default, 40 px rows, 22 px ring), `lg` (48 px rows, 24 px ring); the dot scales with the ring. 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 the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfRadioOption, BfRadioGroupComponent } from '@bitforgehq/ui';
+
+/** A small radio group for a dense panel. */
+@Component({
+  selector: 'app-example-radio-group-sizes',
+  imports: [BfRadioGroupComponent],
+  template: `
+    <bf-radio-group size="sm" label="Density" [options]="densities" [(value)]="density" />
+  `,
+})
+export class RadioGroupSizesExampleComponent {
+  protected readonly densities: BfRadioOption[] = [
+    { value: 'compact', label: 'Compact' },
+    { value: 'comfortable', label: 'Comfortable' },
+  ];
+  protected readonly density = signal<string | null>('compact');
+}
+```
+
+## Read-only
+
+`readonly` shows the choice but blocks changes: clicks, Space and the arrow keys do nothing, and
+the options stay in the tab order on the muted surface. Native radios move focus and selection
+together on the arrow keys, so cancelling them also keeps focus on the checked option: a keyboard
+user tabs to the group and hears the current choice, but cannot walk the other options. Signal
+Forms binds it from `readonly()` rules.
+
+```ts
+import { Component } from '@angular/core';
+import { type BfRadioOption, BfRadioGroupComponent } from '@bitforgehq/ui';
+
+/** A read-only radio group: it shows the plan and blocks changes. */
+@Component({
+  selector: 'app-example-radio-group-readonly',
+  imports: [BfRadioGroupComponent],
+  template: `<bf-radio-group label="Plan" [options]="plans" [readonly]="true" [value]="plan" />`,
+})
+export class RadioGroupReadonlyExampleComponent {
+  protected readonly plans: BfRadioOption[] = [
+    { value: 'starter', label: 'Starter' },
+    { value: 'team', label: 'Team' },
+  ];
+  protected readonly plan = 'team';
+}
+```
+
+## Without a visible label
+
+When a heading or table cell already names the choice, skip `label` and give the group `ariaLabel`,
+or `ariaLabelledby` pointing at that element. A group without a visible label needs one of the two.
+Both are ignored while `label` is set.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfRadioOption, BfRadioGroupComponent } from '@bitforgehq/ui';
+
+/** A radio group named by the heading above it. */
+@Component({
+  selector: 'app-example-radio-group-unlabelled',
+  imports: [BfRadioGroupComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <h3 id="radio-plan-heading" class="text-heading">Plan</h3>
+      <bf-radio-group ariaLabelledby="radio-plan-heading" [options]="plans" [(value)]="plan" />
+    </div>
+  `,
+})
+export class RadioGroupUnlabelledExampleComponent {
+  protected readonly plans: BfRadioOption[] = [
+    { value: 'starter', label: 'Starter' },
+    { value: 'team', label: 'Team' },
+  ];
+  protected readonly plan = signal<string | null>('starter');
+}
+```
+
+## 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, BfRadioGroupComponent, type BfRadioOption } from '@bitforgehq/ui';
+
+/**
+ * A required radio group with the default message.
+ *
+ * `required(p.view)` has no message, so a submit with nothing chosen shows "Fill in this field".
+ */
+@Component({
+  selector: 'app-example-radio-group-validation',
+  imports: [FormField, FormRoot, BfButtonComponent, BfRadioGroupComponent],
+  template: `
+    <form [formRoot]="prefs" class="flex flex-col items-start gap-3">
+      <bf-radio-group label="View" [options]="options" [formField]="prefs.view" />
+      <bf-button type="submit">Save</bf-button>
+    </form>
+  `,
+})
+export class RadioGroupValidationExampleComponent {
+  protected readonly options: BfRadioOption[] = [
+    { value: 'day', label: 'Day' },
+    { value: 'week', label: 'Week' },
+  ];
+  private readonly model = signal<{ view: string | null }>({ view: null });
+  protected readonly prefs = form(
+    this.model,
+    (p) => {
+      required(p.view);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Desktop
+
+Hovering an unselected, enabled option darkens its ring (`text-muted`) with the pointer cursor; a read-only group has no hover. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring shows around the radio on keyboard focus only. Under a fine pointer the row is the hit area, at least 24 × 24 px; `sm` (32 px rows) suits dense desktop forms and tables; set it with `provideBfDefaults({ size: 'sm' })` ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Ring: `border-strong` unchecked → `primary` checked; error, unchecked: `danger-border`. Dot: `primary-strong` (≥ 3:1 in its `surface` ring for any configured primary; falls back to `CanvasText` under `forced-colors`, e.g. Windows high-contrast).
+- Hover over an unselected, enabled option (pointer cursor): ring `text-muted` (`danger` on error).
+- Pressed (an option held down): its ring border turns `text`; not while disabled or read-only.
+- Disabled: ring border `surface-sunken`, background `surface-muted`; option label `text-disabled`, description `text-muted`.
+- Read-only: ring background `surface-muted`, no hover, default cursor.
+- Legend: `text-muted`. Error text: `danger`. Focus ring: `ring`.
+
+The legend, the options and the error text sit 6 px apart; each ring sits 10 px from its label.
+
+## Accessibility
+
+A `<fieldset role="radiogroup">` with the `label` as its `<legend>`; each option is a native `<input type="radio">`, visually hidden and sharing one `name`, so keyboard behaviour (arrow keys move the selection) comes for free. The fieldset carries `aria-required`, and once touched and invalid `aria-invalid` with `aria-describedby` and `aria-errormessage` pointing at the error text (an explicit `errorMessage` shows immediately). Without a `label`, `aria-label` and `aria-labelledby` carry `ariaLabel` and `ariaLabelledby`. Read-only: `aria-readonly="true"` on the group; the radios stay focusable, and clicks (which Space also triggers) and arrow keys are cancelled, so the value never changes. `focus()` focuses the checked radio, else the first enabled one; Signal Forms calls it from `focusBoundControl()`. A disabled option's label dims to `text-disabled`. Each option row is only as wide as its content, so a click on empty space beside it selects nothing.
+
+### Keyboard
+
+The options are native radio buttons, so these are the browser's radio-group keys; under `dir="rtl"` the browser swaps <kbd>ArrowLeft</kbd> and <kbd>ArrowRight</kbd> to follow the text direction.
+
+| Key                                              | Action                                                                                          |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus into and out of the group: one tab stop, on the checked option when there is one    |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowRight</kbd>     | Checks and focuses the next enabled option, wrapping at the end; nothing while `readonly`       |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowLeft</kbd>        | Checks and focuses the previous enabled option, wrapping at the start; nothing while `readonly` |
+| <kbd>Space</kbd>                                 | Checks the focused option; nothing while `readonly`                                             |
+
+## Inputs
+
+| Name             | Type                                                        | Default      | Description                                                                                                                                                               |
+| ---------------- | ----------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | `readonly BfRadioOption<T>[]`                               | required     | The options to choose from.                                                                                                                                               |
+| `compareWith`    | `BfCompareWith<T>`                                          | `Object.is`  | Equality for matching `value` to an option (default `Object.is`); pass one for object values.                                                                             |
+| `label`          | `string`                                                    | `''`         | Group label, rendered as the fieldset legend.                                                                                                                             |
+| `ariaLabel`      | `string`                                                    | `''`         | Accessible name of the group when no visible `label` is rendered. Ignored when `label` is set.                                                                            |
+| `ariaLabelledby` | `string`                                                    | `''`         | Id(s) of the element(s) that name the group when no visible `label` is rendered. Ignored when `label` is set.                                                             |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined`  | Height step of the option row: sm 32, md 40, lg 48 px (44 px under a coarse pointer for sm and md); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `orientation`    | `BfRadioGroupOrientation` (`'vertical' \| 'horizontal'`)    | `'vertical'` | Stack the options vertically (default) or in a row.                                                                                                                       |
+| `disabled`       | `boolean`                                                   | `false`      | Disables every option. Set by `[formField]`; do not bind it yourself.                                                                                                     |
+| `readonly`       | `boolean`                                                   | `false`      | Shows the choice but blocks changes; the options stay focusable and the group exposes `aria-readonly`. Set by `[formField]`; do not bind it yourself.                     |
+| `required`       | `boolean`                                                   | `false`      | Marks the group required. 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. Set by `[formField]`; do not bind it yourself.                                                                                       |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`         | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                       |
+| `errorMessage`   | `string`                                                    | `''`         | Explicit error text; takes precedence over Signal Forms errors.                                                                                                           |
+| `name`           | `string`                                                    | `generated`  | Shared name of the radio inputs; generated when not set. 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 checked radio, else the first enabled one; Signal Forms calls it from
+`focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Give a description when the label alone is ambiguous.
+- Preselect a value when there is a sensible default; otherwise make the group required.
+
+### Don't
+
+- Don't offer more than five or six options; use `bf-select`.
+
+## Migration notes
+
+### 0.3.0
+
+New exported `BfRadioGroupOrientation` (`'vertical' | 'horizontal'`), the type of `orientation`
+(was an inline union with the same values).
+
+**Breaking:** typed values. `BfRadioGroupComponent<T = string>` is generic over the option value
+(`BfRadioOption<T = string>`); `value` is `T | null` and defaults to `null` (was `''`), with
+nothing checked; `changed` emits `T` (was `string`). New `compareWith` (default `Object.is`)
+matches `value` to an option. A radio's native `value` is its option value for a string, number
+or boolean and its index for an object. See Migration 6, 7 and 9.
+
+**Behaviour:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): rows
+are `sm` 32, `md` 40 (default), `lg` 48 px under a fine pointer, and at least 44 px under a coarse
+pointer (was 44 px everywhere); the ring is 18 / 22 / 24 px with a matching dot.
+
+**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 dot is `primary-strong` (was `primary`), so it reaches 3:1 in its `surface`
+ring for any configured primary.
+
+JSDoc of `radio-group.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 option's ring border turns `text` while the option is 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).
+
+### 0.2.0
+
+The legend, the options and the error text sit 6 px apart (legend `mb-1.5`, fieldset `gap-1.5`;
+the legend was 4 px above the options and the error 8 px below them).
+
+Fixed: hovering an enabled, unselected option darkens its ring (`text-muted`, `danger` on
+error).
+
+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 clicks (and Space)
+and arrow keys are cancelled, the fieldset carries `aria-readonly="true"`, the radios stay
+focusable, and the rings rest on `surface-muted` without hover. `ariaLabel` / `ariaLabelledby` name
+a group without a visible `label`. `focus(options?)` focuses the checked radio, else the first
+enabled one, so Signal Forms' `focusBoundControl()` works.
+
+Fixed: a disabled option's label dims to `text-disabled` (`has-[input:disabled]:text-text-disabled`
+on the row; `peer-disabled:` could not reach the text through its wrapper span). Vertical option
+rows are `items-start`, so a click on empty space beside an option no longer selects it.
+
+### 0.1.0
+
+The fieldset now carries `role="radiogroup"`. The ring's focus ring clears in forced-colors mode and the selected dot renders in `CanvasText` under forced colors. The host no longer reflects a static `id` attribute onto `<bf-radio-group>`; the id lands on the `<fieldset>`. Each option's label now carries `min-h-11 items-center`, so a stacked row is itself at least 44 px tall and is its own hit area, rather than a `::after` pseudo-element that overlapped into the neighbouring row's 10px gap and stole its clicks near the boundary; the vertical option list's gap tightened from `gap-2.5` to `gap-1` to match the now taller rows.