@bitforgehq/ui 0.3.3 → 0.5.0-next.3

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/tab-group.md

@@ -148,6 +148,8 @@ export class TabGroupLazyExampleComponent {
 
 `[(selected)]` holds the shown panel's `value`; `(changed)` emits the new value after a user change, never for a write of `selected`. While `selected` matches no panel (unset, or a value that went away), the first enabled panel shows; `selected` itself keeps its value until the user picks a tab.
 
+The underline slides to the newly selected tab, changing width as it goes (200 ms, `--bf-duration-layout`); it lands in place at once on the first render and after a resize, and always under `prefers-reduced-motion`. The panel a user switches to fades in over 200 ms (`animate-panel-in`); the first panel shown, and every panel under reduced motion, appears at once.
+
 ## Sizes and width
 
 `size` sets the tabs' height: `sm` 32 px, `md` 40 px, `lg` 48 px. Unset, it follows `provideBfDefaults()`'s `controlSize`, `md` by default. `fitted` stretches the tabs to share the group's width (two or three tabs on a phone). When the tabs do not fit, the row scrolls sideways; focusing a tab with the keyboard scrolls it into view.
@@ -159,7 +161,7 @@ Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover
 ## Theming
 
 - Tabs: `text-muted` at rest, hover `surface-muted` with `text`, pressed `surface-pressed`; top corners `rounded-tile`.
-- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab).
+- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab). It slides over `--bf-duration-layout` with the `ease-md` curve.
 - Disabled tab: `text-disabled` (never opacity).
 - The row: a 1 px `border` line under the tabs, across the group's width.
 - Badge: `primary` with `on-primary` text, `rounded-control`, `text-micro`.
@@ -168,7 +170,7 @@ Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover
 
 ## Accessibility
 
-The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
+The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. The sliding underline is one decorative `aria-hidden` element of the row. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
 
 ### Keyboard
 
@@ -213,6 +215,20 @@ The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabG
 
 ## Migration notes
 
+### 0.5.0
+
+The selected tab's underline is now one indicator element of the row that slides to the newly
+selected tab, changing width as it goes (`--bf-duration-layout`, `ease-md`). The first placement
+and a resize land at once, and so does everything under `prefers-reduced-motion`. It is measured
+from the selected tab's inline-start offset, so it mirrors under `dir="rtl"`, and is re-measured
+on resize and when labels, badges, size or `fitted` change. Until it has been measured (jsdom,
+server render, a hidden group) the tab keeps drawing its own underline, so unit tests and the
+first paint are unchanged. The indicator is `aria-hidden`; roles, keyboard and focus are
+unchanged.
+
+The panel a user switches to fades in (200 ms of opacity, new `--animate-panel-in`, behind
+`motion-safe:`); the panel shown on the first render never does.
+
 ### 0.3.1
 
 New `bf-tab-group`: in-page tabs over the content they switch, in both shells. A `tablist` of

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.
@@ -405,11 +489,12 @@ export class TablePagedExampleComponent {
 
 `stack` lets the table itself fit a narrow space. With `stack="narrow"` it stacks while the table is narrower than 36rem (576 px at the default root size, Tailwind's `xl` container size): a container query on the table's own width, so a table in a narrow column or a side panel stacks even on a wide screen. The host is then a size container (`container-type: inline-size`), so give the table its width from its parent (a block or `w-full` / `flex-1`), not from its columns. With `stack="coarse"` it stacks under a coarse pointer at any width (phones, tablets, the Capacitor shell). The default `never` keeps the table as it is.
 
-Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`.
+Stacked, each row is a sunken tile (`surface-sunken`, `rounded-tile`, the tile a raised card holds; a selected row keeps `primary-soft`). Its checkbox and first cell head the tile in bold; every other cell shows its column label at the start and its value at the end. The header row is visually hidden, and a bar above the tiles holds a labelled Select all checkbox (with `selectable`) and a Sort by select, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. The Sort by select is a native `<select>` unless the app adds `provideBfSelect()` from `@bitforgehq/ui/overlay` to its providers: then it is the styled [bf-select](https://bitforge-ui.web.app/components/select) (still native under touch), through the `BF_TABLE_SORT_SELECT` token, so `@bitforgehq/ui` itself never loads the CDK. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`, in either form.
 
 ```ts
 import { Component, computed, signal } from '@angular/core';
 import {
+  BF_TABLE_SORT_SELECT,
   BfBadgeComponent,
   BfSegmentedComponent,
   BfTableCellDirective,
@@ -418,6 +503,7 @@ import {
   type BfTableColumn,
   type BfTableSort,
 } from '@bitforgehq/ui';
+import { BfSelectComponent } from '@bitforgehq/ui/overlay';
 
 interface Task {
   id: string;
@@ -442,10 +528,16 @@ type Width = 'phone' | 'full';
  * than 36rem: the selection checkbox and the first cell head the tile, and a bar above the tiles
  * holds Select all and a Sort by select, whose first option, Not sorted, shows while `sort` is
  * null and clears it. Switch the box between phone width and full width.
+ *
+ * The Sort by select is the styled `bf-select`. In an app, add `provideBfSelect()` from
+ * `@bitforgehq/ui/overlay` to `app.config.ts` once; this page provides `BF_TABLE_SORT_SELECT`
+ * on the example instead, so the docs site loads the select only with this example.
  */
 @Component({
   selector: 'app-example-table-stacked',
   imports: [BfTableComponent, BfTableCellDirective, BfBadgeComponent, BfSegmentedComponent],
+  // In an app: provideBfSelect() in app.config.ts (see the comment above).
+  providers: [{ provide: BF_TABLE_SORT_SELECT, useValue: BfSelectComponent }],
   template: `
     <!-- A stacking table is a size container: its width comes from its parent, never its columns. -->
     <div class="flex w-152 max-w-full flex-col gap-3">
@@ -586,7 +678,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.
 
@@ -600,7 +692,7 @@ A table that can stack (`stack` other than `never`) sets explicit `table`, `rowg
 | <kbd>Space</kbd>                                 | Toggles the focused checkbox, or sorts by the focused header                                                                                                                |
 | <kbd>Enter</kbd>                                 | Sorts by the focused header                                                                                                                                                 |
 
-A stacked table's Sort by select is a native select with its own keys.
+A stacked table's Sort by select has its own keys: the native select's, or with `provideBfSelect()` those of [bf-select](https://bitforge-ui.web.app/components/select#keyboard).
 
 Text fields, selects and composite widgets (radios, comboboxes, sliders) in a cell keep their own arrow keys.
 
@@ -655,6 +747,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 +759,24 @@ Selects or clears one row.
 
 ## Migration notes
 
+### 0.5.0
+
+New `BF_TABLE_SORT_SELECT` injection token: the component a stacked table renders as its "Sort
+by" select (`null`, the default, keeps the native one). `provideBfSelect()` from
+`@bitforgehq/ui/overlay` sets it to the styled `bf-select`, so the core entry still never imports
+the CDK. `BfTableHarness.getSortSelect()` returns a working `BfSelectHarness` either way.
+
+### 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

package/ai/components/theme-menu-button.md

@@ -127,6 +127,7 @@ The button consumes `bf-menu-button`'s tokens (`bf-button`'s, or `bf-icon-button
 - The three items are `role="menuitemradio"` with `aria-checked`, so a screen reader announces the current choice. The dot is drawn in CSS and adds nothing to the name.
 - Choosing an item closes the menu and returns focus to the button.
 - Hit area: at least 32 px, 44 px under a coarse pointer, as `bf-menu-button`.
+- Motion: the menu fades and grows out of the button as it opens, and closes at once. Under `prefers-reduced-motion` it only fades in.
 
 ### Keyboard
 

package/ai/components/time-input.md

@@ -138,6 +138,8 @@ The field shows the `primary` border and focus ring while any part has focus, th
 
 The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`); each part is a `role="spinbutton"` named from the `timeInputHour`, `timeInputMinute`, `timeInputSecond` and `timeInputDayPeriod` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and `aria-valuetext` (the AM or PM name), and the field's `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled`. The clock button is named by `timeInputOpenList`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. The list is a `role="listbox"` named by the same label, its times `role="option"` with `aria-selected` and `aria-disabled`; focus stays on the list and `aria-activedescendant` names the active time.
 
+Motion: the list grows out of the field as it opens (a fade, a slight scale and a 4 px slide, 180 ms) and fades back as it closes (130 ms). Focus returns at once and the closing list is inert. Under `prefers-reduced-motion` it only fades.
+
 ### Keyboard
 
 | Key                                              | Where | Action                                                   |

package/ai/components/timeline-event.md

@@ -0,0 +1,144 @@
+# bf-timeline-event
+
+One timeline event with a coloured marker, its text, actor and time
+
+`BfTimelineEventComponent` from `@bitforgehq/ui` · Data display · since 0.4.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-timeline-event overview.
+ *
+ * Live demo of `bf-timeline-event`: one event per tone in a `bf-timeline`, with and without an
+ * actor, one with a link in its text and one with a relative `timeText`.
+ */
+@Component({
+  selector: 'app-example-timeline-event-overview',
+  imports: [RouterLink, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="Event tones" class="max-w-xl">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="primary">
+        Opened
+        <a routerLink="/components/timeline" fragment="links-in-events">CVE-2026-1234</a>
+      </bf-timeline-event>
+      <bf-timeline-event actor="CI" time="2026-10-28T15:10:00Z" tone="success">
+        All checks passed
+      </bf-timeline-event>
+      <bf-timeline-event actor="Dependency bot" time="2026-10-28T14:00:00Z" tone="warning">
+        Found an outdated base image
+      </bf-timeline-event>
+      <bf-timeline-event actor="CI" time="2026-10-28T13:05:00Z" tone="danger">
+        CI failed on the security scan
+      </bf-timeline-event>
+      <bf-timeline-event time="2026-10-28T12:00:00Z" timeText="4 hours ago" tone="info">
+        A new advisory was published
+      </bf-timeline-event>
+      <bf-timeline-event actor="Jonas Keller" time="2026-10-27T16:02:00Z">
+        Assigned the finding to Lena Meier
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineEventOverviewExampleComponent {}
+```
+
+## Overview
+
+One event of a `bf-timeline`: a marker coloured by `tone`, the event text (the default slot,
+which may hold links), then who did it (`actor`) and when (`time`, in a `time` element).
+
+One event of a [`bf-timeline`](https://bitforge-ui.web.app/components/timeline): a marker coloured by `tone`, the event text from the default slot, then a meta line with `actor` and `time`. Place events in a `bf-timeline`, which gives them the list semantics and the time format; the line between the markers ends at the last event.
+
+## When to use
+
+Use `bf-timeline-event` for each dated entry of a `bf-timeline`: a change, a comment, a CI run. Use [bf-list-item](https://bitforge-ui.web.app/components/list-item) instead for a row the user opens or acts on.
+
+## Basic usage
+
+`actor`, `time` (a `Date` or an ISO 8601 string) and `tone` are inputs; the text is the content and may hold links, which take the link style. `timeText` replaces the formatted time with your own text while the `datetime` keeps the exact value. `bfSlot="end"` holds a small action, at the inline end on a wide timeline and below the text on a narrow one.
+
+```ts
+import { Component } from '@angular/core';
+import { BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+/**
+ * An event's actor, time and tone.
+ *
+ * Two events of a CVE side panel: one by a person with an exact time, one by a bot with a relative
+ * `timeText` whose `datetime` keeps the exact value.
+ */
+@Component({
+  selector: 'app-example-timeline-event-basic',
+  imports: [BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="CVE history" class="max-w-sm">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="warning">
+        Accepted the risk until the next release
+      </bf-timeline-event>
+      <bf-timeline-event
+        actor="Advisory bot"
+        time="2026-10-28T10:00:00Z"
+        timeText="6 hours ago"
+        tone="info"
+      >
+        Imported the advisory
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineEventBasicExampleComponent {}
+```
+
+## Desktop
+
+An event has no hover and no focus stop of its own; only the links in its text and the controls in its `end` slot are interactive. It renders the same inside `provideBfShell()`.
+
+## Theming
+
+- Marker: `text-subtle`, `primary`, `success`, `warning`, `danger` or `info`; `CanvasText` under forced colours. Line: `border`.
+- Text `text-body` in `text`, links `primary-text`; meta line `text-caption` in `text-muted`.
+
+## Accessibility
+
+Inside a `bf-timeline` the event is a `listitem`; on its own it has no role. The marker is `aria-hidden`; the time is a `time` element with an ISO `datetime`, and the separator between actor and time is hidden from assistive technology.
+
+## Inputs
+
+| Name       | Type                                                                                        | Default     | Description                                                                                                        |
+| ---------- | ------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| `actor`    | `string`                                                                                    | `''`        | Who did it, such as a person or a bot; empty for a system event.                                                   |
+| `time`     | `Date \| string \| null`                                                                    | `null`      | When it happened: a Date or an ISO 8601 string; empty or invalid shows no time.                                    |
+| `timeText` | `string`                                                                                    | `''`        | Shown in place of the formatted time, such as "vor 2 Std."; the `time` element's `datetime` keeps the exact value. |
+| `tone`     | `BfTimelineTone` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`) | `'neutral'` | The marker's colour.                                                                                               |
+
+## Slots
+
+- `default`: The event text; links in it take the link style.
+- `end`: Content at the inline end on a wide timeline and below the text on a narrow one, such as a button.
+
+## Notes
+
+### Do
+
+- Write the text as what happened ("Assigned to Lena Meier"), and link the object it names.
+
+### Don't
+
+- Don't put more than one small action in the `end` slot; open the details elsewhere.
+
+## Migration notes
+
+### 0.4.0
+
+New: `bf-timeline-event`, one event of a `bf-timeline`: a 10 px marker coloured by `tone`
+(`neutral`, `primary`, `success`, `warning`, `danger`, `info`; new type `BfTimelineTone`) on a
+`border` line that ends at the last event, the event text in the default slot (links in it take
+the link style), then `actor` and `time` (a `Date` or an ISO 8601 string, in a `time` element;
+`timeText` shows a relative text while `datetime` keeps the exact value; an invalid time shows
+nothing). A `bfSlot="end"` action sits at the inline end, or under the text once the event is
+narrow.