@bitforgehq/ui 0.3.3 → 0.4.0

package/ai/components/list-item.md

@@ -100,6 +100,7 @@ export class ListItemOverviewExampleComponent {
 One row of a list: leading slot (avatar, icon tile), title and subtitle, trailing slot
 (time, toggle, badge) and an optional chevron for rows that navigate. A navigation row puts a
 `bfAction` link in the `title` slot, so the row stays a list item and the link covers it.
+`unread` marks a row not yet opened with a dot and a bolder title.
 
 A row of a list: a leading slot (an avatar, an icon), the title and subtitle, a trailing slot (a time, a toggle, a chip) and an optional chevron. Place rows in a [`bf-list`](https://bitforge-ui.web.app/components/list), which gives them the list semantics and the inset container; a row can also stand alone. A row is static text, a navigation link or an action button, never more than one of them.
 
@@ -230,6 +231,87 @@ export class ListItemActionsExampleComponent {
 }
 ```
 
+## Unread rows
+
+`unread` marks a row the user has not opened yet, such as a new message or notification: a small `primary` dot at the row's inline start, on the title line, and the title in a bolder weight. It is not colour alone: the row also reads a visually hidden state before the title, from the `listItemUnread` label ("Unread"; set it with `provideBfLabels({ listItemUnread: 'Ungelesen' })` in a German app), so a screen reader says "Unread, Scan finished". The dot sits in the row's own inline-start padding (or the gap after a leading avatar or icon), so read and unread rows keep their text aligned and nothing moves when a row is marked read; without `unread` nothing changes. Clear `unread` when the row is opened.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfActionDirective, BfListComponent, BfListItemComponent } from '@bitforgehq/ui';
+
+interface Notice {
+  readonly id: string;
+  readonly title: string;
+  readonly subtitle: string;
+  readonly time: string;
+  readonly unread: boolean;
+}
+
+/**
+ * An inbox with unread rows.
+ *
+ * Each title is a stretched `<button bfAction>`; opening a row marks it read.
+ */
+@Component({
+  selector: 'app-example-list-item-unread',
+  imports: [BfActionDirective, BfListComponent, BfListItemComponent],
+  template: `
+    <bf-list>
+      @for (notice of notices(); track notice.id) {
+        <bf-list-item [unread]="notice.unread" [subtitle]="notice.subtitle">
+          <button bfSlot="title" bfAction type="button" class="text-start" (click)="open(notice)">
+            {{ notice.title }}
+          </button>
+          <span bfSlot="trailing" class="text-caption text-text-muted">{{ notice.time }}</span>
+        </bf-list-item>
+      }
+    </bf-list>
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+  `,
+})
+export class ListItemUnreadExampleComponent {
+  protected readonly notices = signal<readonly Notice[]>([
+    {
+      id: 'scan',
+      title: 'Scan finished',
+      subtitle: '3 new findings on api.example.com',
+      time: '9:41',
+      unread: true,
+    },
+    {
+      id: 'cert',
+      title: 'Certificate expires soon',
+      subtitle: 'shop.example.com, in 12 days',
+      time: '8:15',
+      unread: true,
+    },
+    {
+      id: 'report',
+      title: 'Weekly report',
+      subtitle: 'Ready to download',
+      time: 'Mon',
+      unread: false,
+    },
+  ]);
+  private readonly opened = signal('');
+
+  protected readonly status = computed(() => {
+    const unread = this.notices().filter((notice) => notice.unread).length;
+    const opened = this.opened();
+    return opened ? `${unread} unread · Opened: ${opened}` : `${unread} unread`;
+  });
+
+  protected open(notice: Notice): void {
+    this.opened.set(notice.title);
+    this.notices.update((list) =>
+      list.map((item) => (item.id === notice.id ? { ...item, unread: false } : item)),
+    );
+  }
+}
+```
+
+With a `bfAction` link or button in the `title` slot, the state becomes part of that element's accessible name: the directive sets `aria-labelledby` to the state text and the element itself (it gives the element an id if it has none, and keeps an `aria-labelledby` of its own after the state), so the link reads "Unread, Scan finished" when tabbed to or listed, and the state text is hidden from the tree so it is read once. An `interactive` row holds the state text inside its button, so its name starts with it too.
+
 ## Desktop
 
 An `interactive` row and a row holding a `bfAction` link take a `surface-muted` fill and the pointer cursor while hovered; a static row has none. Hover styles apply only on devices that can hover, so a tap never leaves one stuck. The ring is drawn around the row on keyboard focus only. A navigation row keeps the browser's link behaviour: Ctrl/Cmd-click and a middle click open it in a new tab. The trailing slot sits above the stretched link, so a toggle or button there takes its own click. Rows have one height; they do not follow `provideBfDefaults()`.
@@ -240,10 +322,11 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 - Text: the title, the title slot and the subtitle wrap (`wrap-anywhere`); with `truncate` each keeps one line (`truncate`).
 - `interactive` rows and rows holding a `bfAction` link add a pointer, a `surface-muted` hover, a `surface-pressed` fill while pressed (the row's action, for a `bfAction` row) and a `ring` focus ring; `interactive` rows dim to `text-disabled` when `disabled` and have no pressed state then.
 - The `chevron` mark uses `text-subtle`.
+- `unread`: the dot is `primary` (`CanvasText` in forced colours), `rounded-full` and 8 px (`size-2`); the title turns `font-extrabold`.
 
 ## Accessibility
 
-`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree.
+`bf-list-item` sets `role="listitem"` on its host only inside a `bf-list`; a standalone row has no role, so it never claims a list parent that is not there. A non-interactive row is a plain `<div>`, while `[interactive]="true"` renders it as a native `<button>` so it gets keyboard activation and the button role for free. A navigation row's `bfAction` link in the `title` slot is a real `<a>` inside the list item ([WAI-ARIA APG link pattern](https://www.w3.org/WAI/ARIA/apg/patterns/link/)): exposed as `link` with the title as its name, reached with Tab (in Safari and iOS WKWebView, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise); VoiceOver and Full Keyboard Access are unaffected), followed with Enter (not Space), opened in a new tab with Ctrl/Cmd-click; under forced colours a system-coloured outline around the whole row marks the focused link. Making the host itself a link would take the row out of the list's `listitem` structure, so the link lives inside it. `chevron` is a purely visual CSS mark (an `::after` pseudo-element), so it adds nothing to the accessibility tree. An `unread` row's dot carries a visually hidden (`sr-only`) state text from the `listItemUnread` label, read before the title ("Unread, Scan finished"); on a row with a `bfAction` the text is `aria-hidden` and the action names itself with `aria-labelledby` from it and its own content, so the state is part of the link's or button's name and is read once. The row stays a `listitem`.
 
 ### Keyboard
 
@@ -255,14 +338,15 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 
 ## Inputs
 
-| Name          | Type      | Default | Description                                                                                                                                           |
-| ------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `title`       | `string`  | `''`    | Primary text. For a navigation row, project an `<a bfSlot="title" bfAction>` instead.                                                                 |
-| `subtitle`    | `string`  | `''`    | Secondary text under the title.                                                                                                                       |
-| `interactive` | `boolean` | `false` | Render the row as a button that emits `clicked` (an action row; a row that navigates puts a `bfAction` link in the `title` slot instead).             |
-| `chevron`     | `boolean` | `false` | Show a trailing chevron (navigation rows).                                                                                                            |
-| `disabled`    | `boolean` | `false` | Disable an interactive row.                                                                                                                           |
-| `truncate`    | `boolean` | `false` | Keep the title, the title slot and the subtitle on one line each, cut with an ellipsis. By default they wrap, so nothing is lost at large text sizes. |
+| Name          | Type      | Default | Description                                                                                                                                               |
+| ------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`  | `''`    | Primary text. For a navigation row, project an `<a bfSlot="title" bfAction>` instead.                                                                     |
+| `subtitle`    | `string`  | `''`    | Secondary text under the title.                                                                                                                           |
+| `interactive` | `boolean` | `false` | Render the row as a button that emits `clicked` (an action row; a row that navigates puts a `bfAction` link in the `title` slot instead).                 |
+| `chevron`     | `boolean` | `false` | Show a trailing chevron (navigation rows).                                                                                                                |
+| `disabled`    | `boolean` | `false` | Disable an interactive row.                                                                                                                               |
+| `truncate`    | `boolean` | `false` | Keep the title, the title slot and the subtitle on one line each, cut with an ellipsis. By default they wrap, so nothing is lost at large text sizes.     |
+| `unread`      | `boolean` | `false` | Mark the row as not yet opened: a dot at the inline start, a bolder title and a visually hidden state (the `listItemUnread` label) read before the title. |
 
 ## Outputs
 
@@ -283,14 +367,26 @@ An `interactive` row and a row holding a `bfAction` link take a `surface-muted`
 
 - Keep titles short; a long one wraps. Add `truncate` only where one line per row is the pattern (a mail list).
 - Make a row that navigates a `bfAction` link in the `title` slot, and a row that acts on the page `interactive`; put secondary actions in the trailing slot.
+- Set `unread` on rows not yet opened (messages, notifications) and clear it when the row is opened.
 
 ### Don't
 
 - Don't nest interactive controls inside an `interactive` row (it is one button); use a navigation row with a trailing control instead.
 - Don't wrap a `bf-list-item` in an `<a>`, and don't navigate from an `interactive` row's `(clicked)`.
+- Don't mark unread rows with a coloured title or a badge of your own; `unread` gives the dot, the weight and the screen-reader state together.
 
 ## Migration notes
 
+### 0.4.0
+
+New `unread` input (boolean, default false) for a row not yet opened: a `primary` dot at the
+row's inline start on the title line, a bolder title (`font-extrabold`) and a visually hidden
+state read before the title, from the new label key `listItemUnread` ("Unread"). A row's
+`bfAction` link or button then names itself `aria-labelledby="<state> <itself>"` ("Unread,
+Report"; an id is added if it has none, and its own `aria-labelledby` is kept after the state).
+The dot sits in the row's own inline-start padding, so read and unread rows stay aligned. Opt-in: without `unread` nothing
+changes.
+
 ### 0.3.0
 
 **Behaviour:** logical properties: text aligns to the inline start and the chevron sits at the

package/ai/components/step.md

@@ -0,0 +1,112 @@
+# bf-step
+
+One numbered step of an instruction list, with a title and its details
+
+`BfStepComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** Steps with a short instruction as the title and the details in the content. */
+@Component({
+  selector: 'app-example-step-overview',
+  imports: [BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Export your contacts"
+        >In your old app, choose Export and save the file.</bf-step
+      >
+      <bf-step title="Import the file">
+        Pick the file you saved. Contacts that are already in your address book are merged, not
+        added twice.
+      </bf-step>
+      <bf-step title="Check the result" />
+    </bf-steps>
+  `,
+})
+export class StepOverviewExampleComponent {}
+```
+
+## Overview
+
+One step of a `bf-steps` list: a numbered marker, a short instruction as its title and the
+step's details in the content.
+
+One step of a [`bf-steps`](https://bitforge-ui.web.app/components/steps) list: `title` is the step's short instruction and the content holds its details (text, a code to type, an image or a button). The list numbers the steps by position; the step draws the numbered circle and the line to the next one. It works the same in both shells.
+
+## When to use
+
+Use `bf-step` for each instruction inside a `bf-steps` list. Use [bf-list-item](https://bitforge-ui.web.app/components/list-item) instead for a row the user opens or acts on, and [bf-description-list](https://bitforge-ui.web.app/components/description-list) for facts with no order.
+
+## Headings
+
+The title is text by default, which suits short steps. For a long guide whose steps hold screenshots or code, set `headingLevel` (`2`, `3` or `4`, a `BfStepHeadingLevel`) to the level that fits the page outline, so a screen-reader user can move from step to step by heading. The look does not change.
+
+```ts
+import { Component } from '@angular/core';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** Long steps with level 3 headings, so a screen-reader user can move between them. */
+@Component({
+  selector: 'app-example-step-headings',
+  imports: [BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Create an API key" [headingLevel]="3">
+        In the console, open Settings, then API keys, and choose New key. Give it a name that says
+        where it is used, such as "CI pipeline", and copy it: it is shown only once.
+      </bf-step>
+      <bf-step title="Store the key as a secret" [headingLevel]="3">
+        Add it to your CI provider's secrets as BITFORGE_API_KEY. Never commit it to the repository.
+      </bf-step>
+    </bf-steps>
+  `,
+})
+export class StepHeadingsExampleComponent {}
+```
+
+## Desktop
+
+A step is not interactive: no hover, no pointer cursor, no focus stop; only a link or button in its content takes focus. It renders the same inside `provideBfShell()`.
+
+## Theming
+
+- Marker: `bg-primary-soft` / `text-primary-strong`, `text-label-sm` bold, a 24 px `rounded-full` circle; the line under it is `border-border`, hidden on the last step.
+- Title: `text-label` bold in `text`, wrapping anywhere; content: `text-body` in `text-secondary`.
+
+## Accessibility
+
+Inside `bf-steps` the host is a `role="listitem"`, so its position is announced ("2 of 3"); the visible number is `aria-hidden`. The title is a `p`, or an `h2`, `h3` or `h4` with `headingLevel`. Outside `bf-steps` the host claims no role.
+
+## Inputs
+
+| Name           | Type                                                           | Default     | Description                                                                                 |
+| -------------- | -------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------- |
+| `title`        | `string`                                                       | `''`        | The step's short instruction ("Install the app"), shown next to the number.                 |
+| `headingLevel` | `BfStepHeadingLevel \| undefined` (`2 \| 3 \| 4 \| undefined`) | `undefined` | Renders the title as a heading of this level instead of text; leave it off for short steps. |
+
+## Slots
+
+- `default`: The step's details: text, a code snippet, an image or a button.
+
+## Notes
+
+### Do
+
+- Keep the title to one instruction and put everything else in the content.
+
+### Don't
+
+- Don't use `bf-step` outside a `bf-steps` list: it then has no number to show but 1.
+
+## Migration notes
+
+### 0.4.0
+
+New `bf-step`: one step of a `bf-steps` list, with `title` (the short instruction, text by
+default; `headingLevel` 2, 3 or 4, a `BfStepHeadingLevel`, makes it a heading) and the details
+in the default slot. Its number is drawn in a `primary-soft` circle and hidden from assistive
+technology, which reads the list position instead.

package/ai/components/steps.md

@@ -0,0 +1,124 @@
+# bf-steps
+
+Numbered instruction steps a user follows in order, with joined markers
+
+`BfStepsComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** Setting up the app on a phone, in four numbered steps with a code to type and a link. */
+@Component({
+  selector: 'app-example-steps-overview',
+  imports: [RouterLink, BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Install the app">
+        Download Bitforge Guard from the App Store or Google Play.
+      </bf-step>
+      <bf-step title="Sign in">Use your work email address and the password you chose.</bf-step>
+      <bf-step title="Pair your phone">
+        Open Settings, then Devices, and enter this code:
+        <code
+          class="rounded-tile bg-surface-sunken text-label-sm text-text mt-2 block w-fit px-3 py-1.5 font-mono"
+          >K7F-29Q</code
+        >
+      </bf-step>
+      <bf-step title="Turn on notifications">
+        Allow them when the app asks, or later in
+        <a routerLink="/components/steps" class="text-primary-text underline"
+          >notification settings</a
+        >.
+      </bf-step>
+    </bf-steps>
+  `,
+})
+export class StepsOverviewExampleComponent {}
+```
+
+## Overview
+
+Numbered instructions a user follows in order, such as setting up an app on a phone: an
+ordered list of `bf-step` items, each with a numbered marker joined to the next by a line.
+
+Numbered instructions a user follows in order: a `bf-steps` list of `bf-step` items, each with a numbered circle, a short instruction as its title and the details under it, the circles joined by a thin line. It works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-steps` for instructions the user carries out in order, outside the app or across it: "Set up the app on your phone", "Connect your domain". It is static content, not a wizard: a multi-page stepper that holds state and moves the user from step to step is a flow of pages (in the Capacitor shell, pages pushed in [bf-tabs](https://bitforge-ui.web.app/components/tabs) stacks), and a progress figure for such a flow is a [bf-progress](https://bitforge-ui.web.app/components/progress). Use [bf-list](https://bitforge-ui.web.app/components/list) instead for items that have no order.
+
+## Continued lists
+
+`start` sets the number of the first step, for a list continued after a paragraph or on another part of the page: `start="3"` numbers the steps 3, 4, 5. It takes a number or a plain attribute.
+
+```ts
+import { Component } from '@angular/core';
+import { BfStepComponent, BfStepsComponent } from '@bitforgehq/ui';
+
+/** A list continued after a paragraph: the second list starts at 3. */
+@Component({
+  selector: 'app-example-steps-continued',
+  imports: [BfStepComponent, BfStepsComponent],
+  template: `
+    <bf-steps>
+      <bf-step title="Open the admin console">Sign in with an administrator account.</bf-step>
+      <bf-step title="Add your domain">Enter it without https:// in front.</bf-step>
+    </bf-steps>
+    <p class="text-body text-text-muted my-4">The console now shows a TXT record for the domain.</p>
+    <bf-steps start="3">
+      <bf-step title="Add the TXT record">Paste it at your DNS provider.</bf-step>
+      <bf-step title="Verify the domain">Changes can take up to an hour to arrive.</bf-step>
+    </bf-steps>
+  `,
+})
+export class StepsContinuedExampleComponent {}
+```
+
+## Desktop
+
+Steps are not interactive: no hover, no pointer cursor and no focus stop of their own; only a link or button in a step's content takes focus, with its own focus ring. They render the same at every width: the marker column keeps its 24 px and the content wraps (a long word or URL breaks anywhere), so nothing scrolls sideways at 320 px. Put a code snippet that must not wrap in its own `overflow-x-auto` block.
+
+## Theming
+
+- Marker: `bg-primary-soft` / `text-primary-strong` (the tonal pair, ≥ 4.5:1 in both modes), `text-label-sm` bold in a 24 px circle (`size-6`, `rounded-full`); a `CanvasText` outline in forced colours.
+- Line: `border-border`, 1 px, hidden after the last step.
+- Title: `text-label` bold in `text`; content: `text-body` in `text-secondary`; `pb-6` between steps.
+
+## Accessibility
+
+`bf-steps` renders a `role="list"` container and each `bf-step` host is a `role="listitem"` directly inside it, so a screen reader announces the list and each step's position ("1 of 3"). The visible number is `aria-hidden`, so it is not read twice. A list with a `start` other than 1 also sets `aria-posinset` and `aria-setsize` on each step (the size counts the earlier steps too: steps 3 to 5 read "3 of 5"), so the announcement matches the number on screen. The title is text by default; give long steps `headingLevel` on `bf-step` so users can move between them by heading. A lone `bf-step` outside `bf-steps` claims no role.
+
+## Inputs
+
+| Name    | Type     | Default | Description                                                             |
+| ------- | -------- | ------- | ----------------------------------------------------------------------- |
+| `start` | `number` | `1`     | The number of the first step, for a list continued from an earlier one. |
+
+## Slots
+
+- `default`: The steps, each a `bf-step`.
+
+## Notes
+
+### Do
+
+- Start each title with a verb and keep it to one instruction ("Install the app").
+- Put the details, a code to type or a link to open, in the step's content.
+
+### Don't
+
+- Don't use steps for a multi-page flow that tracks where the user is; that is a set of pages.
+- Don't number steps yourself in the title; the marker shows the number.
+
+## Migration notes
+
+### 0.4.0
+
+New `bf-steps`: numbered instructions a user follows in order ("Set up the app on your phone"),
+a `role="list"` of `bf-step` items whose markers are joined by a line. `start` (a number, 1 by
+default) continues a list; a continued list sets `aria-posinset` and `aria-setsize` on its steps
+so the announced position matches the visible number.

package/ai/components/table.md

@@ -114,7 +114,7 @@ Use `bf-table` on a desktop page for records the user scans and compares column
 
 ## Columns and rows
 
-`columns` is an array of `BfTableColumn`: the row property `key`, the header `label`, `sortable` and `align`. A default cell shows the row's `key` property as text when it is a string, a number or a boolean, and is empty otherwise (`null`, `undefined`, an object): render a date or an object with a custom cell. `align: 'end'` lines the header and cells up at the inline end and sets tabular figures, for numbers and amounts.
+`columns` is an array of `BfTableColumn`: the row property `key`, the header `label`, `sortable` and `align`. A default cell shows the row's `key` property as text when it is a string, a number or a boolean, and is empty otherwise (`null`, `undefined`, an object): render a date or an object with a custom cell. `align: 'end'` lines the header and cells up at the inline end and sets tabular figures, for numbers and amounts; `align: 'center'` centres the header and each cell's control, for a column of toggles or checkboxes (see Toggle cells). `BfTableColumn.align` is a `BfTableColumnAlign`, the released `BfTableAlign` (`start`, `end`) plus `center`.
 
 `rowKey` returns the string that identifies a row in `selection` and keeps each row's DOM when the rows change. By default it reads the row's `id` (a string or a number), and falls back to the row's index when a row has none; pass `[rowKey]="byEmail"` when the key is another property.
 
@@ -240,6 +240,90 @@ export class TableCustomCellsExampleComponent {
 }
 ```
 
+## Toggle cells
+
+A settings matrix is a table of switches: rows are what the setting applies to (alert kinds), columns are the options (channels: Email, Push, Slack), and each cell is a `bf-toggle` from a `bfTableCell` template. Keep the row label as the first column, and give the toggle columns `align: 'center'`, which centres the header and the switch in each cell. A toggle in a cell shows no label of its own, so name each one after its column and row with `ariaLabel` (`[ariaLabel]="channel.label + ', ' + alert.label"`, "Push, New CVE"); a screen reader also announces the column header as it moves across. Write the change back from `(changed)` and save it right away, as for any toggle. With `stack="narrow"` (or `coarse` in the Capacitor shell) a phone shows each alert as a tile with the channel labels at the start and the toggles at the end, centred on their label line. In a test, `BfTableHarness.getCellHarness(row, 'Push', BfToggleHarness)` returns a cell's toggle.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfTableCellDirective,
+  BfTableComponent,
+  BfToggleComponent,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+
+type Channel = 'email' | 'push' | 'slack';
+
+interface AlertSetting {
+  id: string;
+  label: string;
+  email: boolean;
+  push: boolean;
+  slack: boolean;
+}
+
+const CHANNELS: readonly { key: Channel; label: string }[] = [
+  { key: 'email', label: 'Email' },
+  { key: 'push', label: 'Push' },
+  { key: 'slack', label: 'Slack' },
+];
+
+/**
+ * A settings matrix of toggle cells.
+ *
+ * Rows are alert kinds and columns are channels, each cell a `bf-toggle` named after its column
+ * and row ("Push, New CVE") with `ariaLabel`, in centred columns (`align: 'center'`). The row label
+ * stays the first column, and `stack="narrow"` turns each row into a tile with the toggles at its
+ * end in a narrow panel or on a phone.
+ */
+@Component({
+  selector: 'app-example-table-toggle-matrix',
+  imports: [BfTableComponent, BfTableCellDirective, BfToggleComponent],
+  template: `
+    <div class="flex w-152 max-w-full flex-col gap-3">
+      <bf-table label="Alert channels" stack="narrow" [rows]="alerts()" [columns]="columns">
+        @for (channel of channels; track channel.key) {
+          <ng-template [bfTableCell]="channel.key" [bfTableCellOf]="alerts()" let-alert>
+            <bf-toggle
+              [ariaLabel]="channel.label + ', ' + alert.label"
+              [checked]="alert[channel.key]"
+              (changed)="set(alert, channel.key, $event)"
+            />
+          </ng-template>
+        }
+      </bf-table>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TableToggleMatrixExampleComponent {
+  readonly channels = CHANNELS;
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'label', label: 'Alert' },
+    ...CHANNELS.map((channel): BfTableColumn => ({ ...channel, align: 'center' })),
+  ];
+  readonly alerts = signal<readonly AlertSetting[]>([
+    { id: 'critical', label: 'Critical finding', email: true, push: true, slack: true },
+    { id: 'cve', label: 'New CVE', email: true, push: false, slack: true },
+    { id: 'ci', label: 'Failed CI run', email: false, push: false, slack: true },
+    { id: 'digest', label: 'Weekly digest', email: true, push: false, slack: false },
+  ]);
+  readonly status = signal('No change yet.');
+
+  /** Writes one cell back; a real app saves the setting right away. */
+  set(alert: AlertSetting, channel: Channel, on: boolean): void {
+    this.alerts.update((rows) =>
+      rows.map((row) => (row.id === alert.id ? { ...row, [channel]: on } : row)),
+    );
+    const name = CHANNELS.find((c) => c.key === channel)?.label ?? channel;
+    this.status.set(`${name} for ${alert.label} turned ${on ? 'on' : 'off'}.`);
+  }
+}
+```
+
+Under a coarse pointer every toggle is a 44 px target inside its own cell (a row grows to fit it), and a cell's horizontal padding keeps neighbouring toggles apart, so no two hit areas overlap. A `sm` toggle (40 px wide) takes a 44 px width under touch as well. ArrowUp and ArrowDown move between the toggles of one column.
+
 ## Empty state
 
 While `rows` is empty the table shows one full-width row that holds the `empty` slot, such as a `bf-empty-state` with the action that creates the first record. The header stays, so the user still sees what the table holds.
@@ -586,7 +670,7 @@ Put the table on a `bf-card` (or another surface) yourself; it has no background
 
 ## Accessibility
 
-A native `table` with a visually hidden `caption` from `label`, `th scope="col"` headers and one `tr` per row. A sorted column's `th` carries `aria-sort="ascending"` or `"descending"`; the others carry none. A sortable header is a native `button` inside the `th`, so its name is the column label; the arrow is `aria-hidden`. The header checkbox is named by `selectAllLabel`, else `provideBfLabels()`'s `tableSelectAll` ("Select all rows"), and is mixed (`indeterminate`) while some rows are selected. Each row checkbox is named by the row's first data cell through `aria-labelledby`, so it reads as the row's title. The empty row's cell spans every column.
+A native `table` with a visually hidden `caption` from `label`, `th scope="col"` headers and one `tr` per row. A sorted column's `th` carries `aria-sort="ascending"` or `"descending"`; the others carry none. A sortable header is a native `button` inside the `th`, so its name is the column label; the arrow is `aria-hidden`. The header checkbox is named by `selectAllLabel`, else `provideBfLabels()`'s `tableSelectAll` ("Select all rows"), and is mixed (`indeterminate`) while some rows are selected. Each row checkbox is named by the row's first data cell through `aria-labelledby`, so it reads as the row's title. A control in a custom cell brings its own name: give a label-less one (a toggle in a settings matrix) `ariaLabel` from its column and row, such as "Email, Critical finding", so it is named the same in the table and in a stacked tile. The empty row's cell spans every column.
 
 A table that can stack (`stack` other than `never`) sets explicit `table`, `rowgroup`, `row`, `columnheader` and `cell` roles and names the table from its caption with `aria-labelledby`, because Safari and some screen readers drop a table's semantics once CSS changes its display; so a stacked table still reads as a table with its column headers. Stacked, the header row is visually hidden but stays in the accessibility tree; its sort buttons and checkbox are hidden (a plain label takes a sortable header's place), so no control is focusable where nobody can see it, and the bar's Select all checkbox and Sort by select replace them. A cell's visible label is CSS generated content with empty alternative text (`content: attr(data-label) / ""`, the `content-data-label` utility of `theme.css`), so a screen reader reads the column header once, not the label as well.
 
@@ -655,6 +739,7 @@ Selects or clears one row.
 ### Do
 
 - Give every table a `label`, and every sortable column a short header.
+- In a settings matrix, keep the row label as the first column, centre the toggle columns and name every toggle after its column and row.
 - Sort and filter the rows in a `computed()` from `sort` and your filters.
 - Use `stack="narrow"` for a table that may sit in a narrow column, or `stack="coarse"` in the Capacitor shell; otherwise render the rows as `bf-list-item`s below `md`.
 
@@ -666,6 +751,17 @@ Selects or clears one row.
 
 ## Migration notes
 
+### 0.4.0
+
+New: toggle cells for a settings matrix (rows of alert kinds, columns of channels, a `bf-toggle`
+in each cell), documented with the `table/toggle-matrix` example. `BfTableColumn.align` takes
+`'center'`: the header and each cell's control are centred, and while stacked the control sits at
+the tile's end, centred on its label line. New type `BfTableColumnAlign` (`BfTableAlign` plus
+`'center'`; `BfTableAlign` keeps its two members). A stacked cell of a start or end column keeps
+its baseline alignment. `@bitforgehq/ui/testing`: new `BfTableHarness.getCellHarness(row, column,
+query)` returns the harness of a control in one cell, and `selectRow()`, `getSelectedCount()`
+read only the selection column's checkboxes, never a checkbox or toggle in a custom cell.
+
 ### 0.3.3
 
 Fix: stacked rows (`stack="narrow"` and `stack="coarse"`) show their column labels again when the