@bitforgehq/ui 0.3.0

package/ai/components/checkbox.md

@@ -0,0 +1,418 @@
+# bf-checkbox
+
+Rounded checkbox with an optional label that binds to Signal Forms
+
+`BfCheckboxComponent` from `@bitforgehq/ui` · Forms · since 0.1.0
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-checkbox overview.
+ *
+ * Live demo of `bf-checkbox`: unchecked, checked and indeterminate boxes, all bound to signals; then the sm, md and lg sizes in a row.
+ */
+@Component({
+  selector: 'app-example-checkbox-overview',
+  imports: [BfCheckboxComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-checkbox [(checked)]="subscribe">Subscribe to updates</bf-checkbox>
+      <bf-checkbox [(checked)]="agree">I agree to the terms</bf-checkbox>
+      <bf-checkbox [(checked)]="selectAll" [(indeterminate)]="mixed">
+        Select all (starts indeterminate)
+      </bf-checkbox>
+      <bf-checkbox [disabled]="true">Disabled</bf-checkbox>
+      <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-checkbox size="sm" [checked]="true">sm · 32 px</bf-checkbox>
+        <bf-checkbox [checked]="true">md · 40 px</bf-checkbox>
+        <bf-checkbox size="lg" [checked]="true">lg · 48 px</bf-checkbox>
+      </div>
+    </div>
+  `,
+})
+export class CheckboxOverviewExampleComponent {
+  readonly subscribe = signal(false);
+  readonly agree = signal(true);
+  readonly selectAll = signal(false);
+  readonly mixed = signal(true);
+
+  readonly status = computed(() => {
+    const checked = [
+      this.subscribe() ? 'Subscribe' : '',
+      this.agree() ? 'Agree' : '',
+      this.mixed() ? 'Select all (mixed)' : this.selectAll() ? 'Select all' : '',
+    ].filter(Boolean);
+    return checked.length > 0 ? `Checked: ${checked.join(', ')}.` : 'Nothing checked.';
+  });
+}
+```
+
+## Overview
+
+Checkbox with a 22 px rounded box and an optional label, implementing the Signal Forms
+checkbox contract so `[formField]` binds `checked`.
+
+A checkbox for yes/no choices and multi-select lists. The native input stays in the DOM (visually hidden) so keyboard, screen readers and forms work as expected; the visible 22 px box is drawn with tokens.
+
+## When to use
+
+Use `bf-checkbox` for a yes/no choice that takes effect when the form is submitted, and for picking several items of a list. Use [bf-toggle](https://bitforge-ui.web.app/components/toggle) instead for a setting that applies at once, and [bf-radio-group](https://bitforge-ui.web.app/components/radio-group) when exactly one option may be chosen.
+
+## Basic usage
+
+Put the label in the default slot or in `label`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/** A checkbox with its label in the default slot. */
+@Component({
+  selector: 'app-example-checkbox-basic',
+  imports: [BfCheckboxComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-checkbox [(checked)]="agree">I agree to the terms</bf-checkbox>
+      <p class="text-caption text-text-muted">{{ agree() ? 'Agreed.' : 'Not agreed yet.' }}</p>
+    </div>
+  `,
+})
+export class CheckboxBasicExampleComponent {
+  protected readonly agree = signal(false);
+}
+```
+
+## With Signal Forms
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/** A checkbox bound to a Signal Forms field. */
+@Component({
+  selector: 'app-example-checkbox-signal-forms',
+  imports: [FormField, BfCheckboxComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-checkbox label="Send me the weekly summary" [formField]="prefs.weekly" />
+      <p class="text-caption text-text-muted">weekly: {{ prefs.weekly().value() }}</p>
+    </div>
+  `,
+})
+export class CheckboxSignalFormsExampleComponent {
+  private readonly model = signal({ weekly: true });
+  protected readonly prefs = form(this.model);
+}
+```
+
+## Sizes
+
+`sm` (32 px row, 18 px box, 14 px label), `md` (default, 40 px row, 22 px box), `lg` (48 px row, 24 px box); the check mark scales with the box. 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, at least 24×24 px (WCAG 2.5.8) even for a label-less box with only `ariaLabel`; under a coarse pointer (touch) `sm` and `md` rows grow to 44 px.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/** The sm, md and lg checkbox sizes. */
+@Component({
+  selector: 'app-example-checkbox-sizes',
+  imports: [BfCheckboxComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-checkbox size="sm" [(checked)]="compact">Compact rows</bf-checkbox>
+      <bf-checkbox [(checked)]="agree">I agree to the terms</bf-checkbox>
+      <bf-checkbox size="lg" [(checked)]="notify">Notify me</bf-checkbox>
+    </div>
+  `,
+})
+export class CheckboxSizesExampleComponent {
+  protected readonly compact = signal(true);
+  protected readonly agree = signal(false);
+  protected readonly notify = signal(true);
+}
+```
+
+## Indeterminate
+
+Use for a "select all" control while only some items are selected. `indeterminate` is a model: a click clears it (as the native checkbox does) and writes `false` back through `[(indeterminate)]`, so the dash, the check mark and `aria-checked` always agree.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/**
+ * A select-all checkbox over three tasks.
+ *
+ * It shows the dash while only some tasks are checked; a click selects or clears them all.
+ */
+@Component({
+  selector: 'app-example-checkbox-indeterminate',
+  imports: [BfCheckboxComponent],
+  template: `
+    <div class="flex flex-col gap-2">
+      <bf-checkbox
+        label="All tasks"
+        [checked]="allSelected()"
+        [(indeterminate)]="someSelected"
+        (changed)="toggleAll($event)"
+      />
+      <div class="flex flex-col gap-2 ps-8">
+        @for (task of tasks(); track task.name; let i = $index) {
+          <bf-checkbox [label]="task.name" [checked]="task.done" (changed)="toggle(i, $event)" />
+        }
+      </div>
+    </div>
+  `,
+})
+export class CheckboxIndeterminateExampleComponent {
+  protected readonly tasks = signal([
+    { name: 'Brief', done: true },
+    { name: 'Moodboard', done: false },
+    { name: 'Deck', done: false },
+  ]);
+  protected readonly allSelected = computed(() => this.tasks().every((t) => t.done));
+  protected readonly someSelected = signal(true);
+
+  protected toggleAll(checked: boolean): void {
+    this.tasks.update((tasks) => tasks.map((t) => ({ ...t, done: checked })));
+    this.someSelected.set(false);
+  }
+
+  protected toggle(index: number, checked: boolean): void {
+    this.tasks.update((tasks) => tasks.map((t, i) => (i === index ? { ...t, done: checked } : t)));
+    const done = this.tasks().filter((t) => t.done).length;
+    this.someSelected.set(done > 0 && done < this.tasks().length);
+  }
+}
+```
+
+## In a selectable row
+
+Skip the visible `label` when the row itself already shows the name, and give the box an `ariaLabel` instead so assistive tech still gets a name, or `ariaLabelledby` with the id(s) of the element(s) that already show it (a table's column header and row title).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/**
+ * A checkbox in a selectable row.
+ *
+ * The row shows the name, so the box takes an `ariaLabel` instead of a visible label.
+ */
+@Component({
+  selector: 'app-example-checkbox-row',
+  imports: [BfCheckboxComponent],
+  template: `
+    <div class="bg-surface rounded-card flex items-center gap-3 p-3">
+      <bf-checkbox ariaLabel="Select Atlas rebrand" [(checked)]="selected" />
+      <span class="text-body">Atlas rebrand</span>
+    </div>
+  `,
+})
+export class CheckboxRowExampleComponent {
+  protected readonly selected = signal(false);
+}
+```
+
+## Read-only
+
+`readonly` shows the state but blocks changes: clicks and Space do nothing, the box stays in the
+tab order, and the box rests on the muted surface without the hover tint, like a read-only radio.
+A checked box keeps a `primary` border and mark instead of the filled box. Signal Forms binds it
+from `readonly()` rules.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCheckboxComponent } from '@bitforgehq/ui';
+
+/** A read-only checkbox: it shows its state and blocks changes. */
+@Component({
+  selector: 'app-example-checkbox-readonly',
+  imports: [BfCheckboxComponent],
+  template: `<bf-checkbox label="Terms accepted" [readonly]="true" [checked]="accepted" />`,
+})
+export class CheckboxReadonlyExampleComponent {
+  protected readonly accepted = true;
+}
+```
+
+## 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, BfCheckboxComponent } from '@bitforgehq/ui';
+
+/**
+ * A required checkbox with the default message.
+ *
+ * `required(p.terms)` has no message, so a submit shows "Fill in this field".
+ */
+@Component({
+  selector: 'app-example-checkbox-validation',
+  imports: [FormField, FormRoot, BfButtonComponent, BfCheckboxComponent],
+  template: `
+    <form [formRoot]="signup" class="flex flex-col items-start gap-3">
+      <bf-checkbox label="I accept the terms" [formField]="signup.terms" />
+      <bf-button type="submit">Sign up</bf-button>
+    </form>
+  `,
+})
+export class CheckboxValidationExampleComponent {
+  private readonly model = signal({ terms: false });
+  protected readonly signup = form(
+    this.model,
+    (p) => {
+      required(p.terms);
+    },
+    { submission: { action: () => Promise.resolve(undefined) } },
+  );
+}
+```
+
+## Desktop
+
+Hovering the row (box and label) darkens the box border, or the checked fill, with the pointer cursor; a read-only box has no hover and the default cursor. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring shows around the box 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
+
+- Unchecked box: `border-strong` border, `surface` background; checked (or indeterminate): `primary` background with an `on-primary` mark.
+- Error, unchecked: border switches to `danger-border`. Error text: `danger`.
+- Hover over the row (pointer cursor): unchecked border `text-muted` (`danger` on error); checked box `primary-hover`.
+- Pressed (the row held down): the box border turns `text`; not while disabled or read-only.
+- Disabled: border `surface-sunken`, background `surface-muted`; label text `text-disabled`.
+- Read-only: `surface-muted` background, no hover, default cursor; unchecked keeps the `border-strong` border, checked (or indeterminate) a `primary` border and mark (≥ 4.8:1 on `surface-muted` in both themes).
+- Focus ring (on the visually hidden native input): `ring`.
+
+The box sits 10 px from the label and the error text 6 px under the row, indented to the label (logical padding, so it follows `dir="rtl"`).
+
+## Accessibility
+
+Native `<input type="checkbox">`, visually hidden (`sr-only`) and wrapped in a `<label>` so the whole row is tappable. Keyboard: native checkbox behaviour — Space toggles it while focused. `indeterminate` sets the native DOM property, which assistive tech reads as "mixed" without any extra ARIA; a user change clears it, so the visual and the reported state agree. The label row is only as wide as its content, so a click on empty space beside it does nothing. `aria-label` carries `ariaLabel` and `aria-labelledby` carries `ariaLabelledby` when there is no visible `label`; `aria-invalid`, `aria-describedby` and `aria-errormessage` point at the error text once the field is touched and invalid (an explicit `errorMessage` shows immediately). Read-only: `aria-readonly="true"`, still focusable; the click (which Space also triggers) is cancelled, so the state never changes. `focus()` focuses the native checkbox; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+| Key                                              | Action                                                                        |
+| ------------------------------------------------ | ----------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus to and from the checkbox; a `readonly` one stays in the tab order |
+| <kbd>Space</kbd>                                 | Toggles it and clears `indeterminate`; nothing while `readonly`               |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                                                                                |
+| ---------------- | ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`          | `string`                                                    | `''`        | Label text; the default slot works too.                                                                                                                                                                    |
+| `ariaLabel`      | `string`                                                    | `''`        | Accessible name when there is no visible `label`, e.g. a row-selection box.                                                                                                                                |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the control when no visible label is rendered (e.g. a table column header).                                                                                              |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step of the 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).                                         |
+| `disabled`       | `boolean`                                                   | `false`     | Disables the control. Set by `[formField]`; do not bind it yourself.                                                                                                                                       |
+| `readonly`       | `boolean`                                                   | `false`     | Shows the state but blocks changes; the box stays focusable and exposes `aria-readonly`. Set by `[formField]`; do not bind it yourself.                                                                    |
+| `required`       | `boolean`                                                   | `false`     | Marks the control 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`                                                    | `''`        | Native name attribute. Set by `[formField]`; do not bind it yourself.                                                                                                                                      |
+| `id`             | `string`                                                    | `generated` | Control id; generated when not set.                                                                                                                                                                        |
+| `checked`        | `boolean`                                                   | `false`     | Whether the box is checked; two-way bindable and bound by `[formField]`. Two-way: `[(checked)]`.                                                                                                           |
+| `indeterminate`  | `boolean`                                                   | `false`     | Shows the mixed state (e.g. "select all" with some rows selected); two-way bindable. A user change clears it, like the native checkbox, so the box and `aria-checked` agree. Two-way: `[(indeterminate)]`. |
+
+## Outputs
+
+| Name      | Payload   | Description                                                                                             |
+| --------- | --------- | ------------------------------------------------------------------------------------------------------- |
+| `changed` | `boolean` | Emitted with the new checked state after a user change.                                                 |
+| `touch`   | `void`    | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself. |
+
+## Slots
+
+- `default`: Rich label content next to the box, before the `label` text.
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the native checkbox; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Use a checkbox when the choice takes effect on submit; use `bf-toggle` when it applies immediately.
+- Keep labels positive ("Send notifications", not "Don't send").
+
+### Don't
+
+- Don't use a lone checkbox for a required agreement without an error message.
+
+## Migration notes
+
+### 0.3.0
+
+New `ariaLabelledby` input: the id(s) of the element(s) that name the box when no visible `label`
+is shown (a table's column header and row title), set as the native checkbox's `aria-labelledby`.
+Additive.
+
+**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 box is 18 / 22 / 24 px with a matching check mark, and the error
+text's indent is logical (`ps-*`). The row is at least 24 px wide (`min-w-6`), so a label-less box
+with only `ariaLabel` still meets the 24×24 px target size of WCAG 2.5.8 under a fine pointer.
+
+**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.
+
+JSDoc of `checkbox.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs;
+template handlers and framework hooks marked `@internal`, so the reference leaves them out. No
+behaviour change.
+
+**Behaviour:** a pressed state (F-045): the box border turns `text` while the row 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 error text sits 6 px under the row (`gap-1.5`, was 4 px), the label-to-message spacing of the
+other form widgets.
+
+Fixed: hovering an enabled row tints the box (unchecked border `text-muted`, `danger` on error;
+checked `primary-hover`); the label was already `cursor-pointer`.
+
+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 the click (which
+Space also triggers) is cancelled, `aria-readonly="true"` is set, the box stays focusable, and the
+box rests on `surface-muted` without hover (default cursor), like a read-only radio; a checked box
+keeps a `primary` border and mark instead of the fill. `focus(options?)` focuses the
+native control, so Signal Forms' `focusBoundControl()` and "focus the first invalid field" on submit
+now work (they were no-ops).
+
+Behaviour change (breaking for a bare attribute): `indeterminate` is now a `model(false)` (it was an
+`input` with `booleanAttribute`). A user change clears it and writes `false` back, so after a click
+the box shows the check mark that assistive tech reports instead of a stale dash; the "select all"
+pattern needs no `(changed)` handler to reset it. Migration: `[indeterminate]="expr"` still works
+one-way and `[(indeterminate)]` binds both ways; a bare `indeterminate` attribute no longer compiles,
+so write `[indeterminate]="true"`.
+
+Fixed: the column is `items-start`, so the label row is only as wide as its content and a click on
+empty space beside it no longer toggles the box.
+
+### 0.1.0
+
+The label's cursor styling is now a computed `labelClasses`. The redundant `[attr.aria-checked]` binding was removed from the native checkbox; the native `checked`/`indeterminate` state already conveys it to assistive tech. The focus ring now clears in forced-colors mode. The host no longer reflects a static `id` attribute onto `<bf-checkbox>`. Fixed the checked box never showing its fill: `bg-surface`/`after:opacity-0` and the "on" branch's `bg-primary`/`after:opacity-100` were both present at once, and Tailwind's stylesheet order let `bg-surface` win, leaving a checked box white with an invisible check mark. The base class list and the on/off branches now each emit exactly one background and one after-opacity utility. The label's clickable hit area is now `min-h-11 items-center` instead of a `::after` pseudo-element; a `::after` extension over projected content (the label text) is the wrong tool — `min-h-11` gets the same ≥ 44 px target without an overlay. Dropped the box's `mt-0.5` top-margin nudge; with the row already `min-h-11 items-center`, the box centres on the label line on its own. Added `ariaLabel` (mirrors `bf-toggle`) for an accessible name when there's no visible `label`, e.g. a row-selection box; the label `<span>` no longer renders when `label` is empty, so an `ariaLabel`-only checkbox has no empty gap next to the box. Projected label content and the `label` input share one styled text span, which hides itself when both are empty (`empty:hidden`).

package/ai/components/chip-group.md

@@ -0,0 +1,205 @@
+# bf-chip-group
+
+Named row of chips that picks one like radios, or groups independent toggles
+
+`BfChipGroupComponent` from `@bitforgehq/ui` · Forms · since 0.3.0
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfChipComponent, BfChipGroupComponent } from '@bitforgehq/ui';
+
+type Status = 'all' | 'open' | 'done';
+
+/**
+ * The bf-chip-group overview.
+ *
+ * Live demo of `bf-chip-group`: a single-choice status row that reads as radio buttons, with an
+ * arrow-key tab stop, and a multiple-choice tag row of independent toggles; the choices are echoed
+ * underneath.
+ */
+@Component({
+  selector: 'app-example-chip-group-overview',
+  imports: [BfChipComponent, BfChipGroupComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-chip-group label="Status" [(value)]="status">
+        <bf-chip variant="ink" value="all">All</bf-chip>
+        <bf-chip variant="ink" value="open">Open</bf-chip>
+        <bf-chip variant="ink" value="done">Done</bf-chip>
+      </bf-chip-group>
+      <bf-chip-group mode="multiple" label="Tags">
+        <bf-chip [(selected)]="design">Design</bf-chip>
+        <bf-chip [(selected)]="copy">Copy</bf-chip>
+        <bf-chip disabled>Archived</bf-chip>
+      </bf-chip-group>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Status: {{ status() }} · Tags: {{ tags() }}
+      </p>
+    </div>
+  `,
+})
+export class ChipGroupOverviewExampleComponent {
+  protected readonly status = signal<Status | null>('all');
+  protected readonly design = signal(true);
+  protected readonly copy = signal(false);
+
+  protected tags(): string {
+    const tags = [this.design() ? 'Design' : '', this.copy() ? 'Copy' : ''].filter(Boolean);
+    return tags.length > 0 ? tags.join(', ') : 'none';
+  }
+}
+```
+
+## Overview
+
+A named row of `bf-chip`s. In `single` mode (the default) the chips are a radio group: the
+group owns the selected chip's `value`, one chip is the tab stop and the arrow keys move the
+selection. In `multiple` mode the chips stay independent toggles and the group only names them.
+Not a Signal Forms control: for a form field use `bf-segmented` or `bf-radio-group`.
+
+A chip group names a row of `bf-chip`s and, in `single` mode, turns them into a radio group: one chip is selected, the group holds its `value`, and assistive tech announces each chip as "radio, 1 of 3, selected". In `multiple` mode the chips stay independent toggles and the group only names the row.
+
+## When to use
+
+Use `bf-chip-group` for a row of filter chips that belong together: one status out of "All", "Open", "Done" (`single`), or any number of tags (`multiple`). Use [bf-segmented](https://bitforge-ui.web.app/components/segmented) or [bf-radio-group](https://bitforge-ui.web.app/components/radio-group) instead for a choice in a form that is submitted: the chip group is not a Signal Forms control. Use [bf-chip](https://bitforge-ui.web.app/components/chip) on its own for a single toggle.
+
+## Single choice
+
+Give every chip a `value` and bind the group's `[(value)]`. The chip whose `value` matches (compared with `Object.is`) is selected; a click, <kbd>Space</kbd> or <kbd>Enter</kbd> selects another one and `(changed)` emits its value. There is no deselect: clicking the selected chip keeps it, as with radio buttons. `value` is `null` while nothing is selected. Inside a `single` group the group's `value` decides which chip is selected, so the chips' own `selected` is ignored. A programmatic write to `value` does not emit.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfChipComponent, BfChipGroupComponent } from '@bitforgehq/ui';
+
+type View = 'all' | 'open' | 'done';
+
+/**
+ * A single-choice filter row.
+ *
+ * The group holds the selected chip's value and makes the row one radio group: Tab reaches the
+ * selected chip, the arrow keys move the selection.
+ */
+@Component({
+  selector: 'app-example-chip-group-single',
+  imports: [BfChipComponent, BfChipGroupComponent],
+  template: `
+    <bf-chip-group label="View" [(value)]="view">
+      <bf-chip value="all">All</bf-chip>
+      <bf-chip value="open">Open</bf-chip>
+      <bf-chip value="done">Done</bf-chip>
+    </bf-chip-group>
+  `,
+})
+export class ChipGroupSingleExampleComponent {
+  protected readonly view = signal<View | null>('open');
+}
+```
+
+## Multiple choice
+
+With `mode="multiple"` each chip keeps its own `[(selected)]` and `(changed)` and announces as a toggle button (`aria-pressed`); the group adds the `group` role and its name. The group's `value` is unused.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfChipComponent, BfChipGroupComponent } from '@bitforgehq/ui';
+
+/**
+ * A multiple-choice tag row.
+ *
+ * `mode="multiple"` names the row and leaves each chip an independent toggle with its own
+ * `[(selected)]`.
+ */
+@Component({
+  selector: 'app-example-chip-group-multiple',
+  imports: [BfChipComponent, BfChipGroupComponent],
+  template: `
+    <bf-chip-group mode="multiple" label="Tags">
+      <bf-chip [(selected)]="design">Design</bf-chip>
+      <bf-chip [(selected)]="development">Development</bf-chip>
+      <bf-chip [(selected)]="research">Research</bf-chip>
+    </bf-chip-group>
+  `,
+})
+export class ChipGroupMultipleExampleComponent {
+  protected readonly design = signal(true);
+  protected readonly development = signal(false);
+  protected readonly research = signal(true);
+}
+```
+
+## Desktop
+
+The chips keep their own hover (a darker border unselected, a deeper tint selected), pointer cursor and pressed fill. In `single` mode the whole row is one tab stop and the arrow keys move through it, so a keyboard user reaches the next control with one <kbd>Tab</kbd>. The row wraps with 8 px between chips and rows. Density follows the chips' `size` (`sm` 32 px for a toolbar or table filter, [density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+The group draws nothing itself: every colour comes from its chips (see [bf-chip](https://bitforge-ui.web.app/components/chip)), selected chips `primary-soft` / `primary-strong` (`tonal`) or `text` / `bg` (`ink`). The host is a wrapping flex row with an 8 px gap (`gap-2`); add classes to the element to change the layout.
+
+## Accessibility
+
+`single`: the host is `role="radiogroup"` named by `label` (`aria-label`) or `ariaLabelledby`; each chip's button is `role="radio"` with `aria-checked` and no `aria-pressed`. Only the selected chip (else the first enabled one) sits in the tab order, the others carry `tabindex="-1"`, and selection follows focus, as in `bf-segmented`. Disabled chips, and every chip of a `disabled` group, get the native `disabled` attribute and are skipped. `multiple`: the host is `role="group"` with the same name, and the chips stay `aria-pressed` toggle buttons in the normal tab order. Give the group a `label` or `ariaLabelledby`: it is the only name of the row.
+
+### Keyboard
+
+| Key                                              | Where      | Action                                                                                                                        |
+| ------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | `single`   | Moves focus into and out of the group: one tab stop, on the selected chip (else the first enabled one)                        |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowDown</kbd>     | `single`   | Selects and focuses the next enabled chip in DOM order, wrapping at the end; not mirrored under `dir="rtl"` yet (a known gap) |
+| <kbd>ArrowLeft</kbd> / <kbd>ArrowUp</kbd>        | `single`   | Selects and focuses the previous enabled chip in DOM order, wrapping at the start; not mirrored under `dir="rtl"` yet         |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | `single`   | Selects and focuses the first / last enabled chip                                                                             |
+| <kbd>Space</kbd> / <kbd>Enter</kbd>              | `single`   | Selects the focused chip                                                                                                      |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | `multiple` | Moves focus from chip to chip                                                                                                 |
+| <kbd>Space</kbd> / <kbd>Enter</kbd>              | `multiple` | Toggles the focused chip                                                                                                      |
+
+## Inputs
+
+| Name             | Type                                         | Default    | Description                                                                                                                                                                                                     |
+| ---------------- | -------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`           | `BfChipGroupMode` (`'single' \| 'multiple'`) | `'single'` | `single` (default): one chip selected, radio semantics; `multiple`: independent toggles.                                                                                                                        |
+| `label`          | `string`                                     | `''`       | Accessible name of the group (required unless `ariaLabelledby` is set).                                                                                                                                         |
+| `ariaLabelledby` | `string`                                     | `''`       | Id(s) of the element(s) that name the group (e.g. a visible heading) when `label` is not set.                                                                                                                   |
+| `disabled`       | `boolean`                                    | `false`    | Disables every chip of the group.                                                                                                                                                                               |
+| `value`          | `T \| null`                                  | `null`     | single: the selected chip's value (`null` = none); ignored in multiple mode. Two-way. Every chip of a single-mode group needs a `value` (of type `T`); one without it cannot be selected. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload     | Description                                                   |
+| --------- | ----------- | ------------------------------------------------------------- |
+| `changed` | `T \| null` | Emitted with the new value after a user change (single mode). |
+
+## Slots
+
+- `default`: The `bf-chip`s of the group, each with its `value`.
+
+## Notes
+
+### Do
+
+- Give every chip of a `single` group a distinct `value` of the group's value type. A chip without a `value` cannot be selected: it never matches, and a click on it changes nothing.
+- Name the group with `label`, or `ariaLabelledby` pointing at a visible heading.
+
+### Don't
+
+- Don't bind `[formField]` to a chip group; use `bf-segmented` or `bf-radio-group` in a form.
+- Don't nest other interactive controls between the chips of a `single` group; the arrow keys move between chips only.
+
+## Migration notes
+
+### 0.3.0
+
+New `bf-chip-group` (`BfChipGroupComponent<T>`, `BfChipGroupMode` `'single' | 'multiple'`, root
+entry, F-038): a named row of `bf-chip`s. `single` (default): the host is `role="radiogroup"`
+named by `label` or `ariaLabelledby`, the chips are `role="radio"` with `aria-checked`, one roving
+tab stop (the selected chip, else the first enabled), and the arrow keys (wrapping, skipping
+disabled chips), `Home` and `End` move focus and the selection, as in `bf-segmented`; `Space` and
+`Enter` select, there is no deselect. `[(value)]` holds the selected chip's `value` (`null` for
+none) and `(changed)` emits it after a user change. `multiple`: the host is `role="group"` and the
+chips stay independent `aria-pressed` toggles with their own `[(selected)]`. `disabled` disables
+every chip. It is not a Signal Forms control; for a form field use `bf-segmented` or
+`bf-radio-group`.
+
+A chip without a `value` inside a `single` group never matches the group's value and cannot be
+selected, so chips that all leave it unset never read as selected together; give every chip a
+`value`.