@bitforgehq/ui 0.3.3 → 0.4.0

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.

package/ai/components/timeline.md

@@ -0,0 +1,201 @@
+# bf-timeline
+
+Dated list of events with who did what and when, on a vertical line
+
+`BfTimelineComponent` 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 overview.
+ *
+ * Live demo of `bf-timeline`: the history of a security finding, newest first. A system event has
+ * no actor, the pull request is a link in the event text, the failed CI run is `danger` and the
+ * fix `success`.
+ */
+@Component({
+  selector: 'app-example-timeline-overview',
+  imports: [RouterLink, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <bf-timeline label="Finding history" class="max-w-xl">
+      <bf-timeline-event actor="Lena Meier" time="2026-10-28T15:40:00Z" tone="success">
+        Marked the finding as fixed
+      </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 actor="Jonas Keller" time="2026-10-28T11:20:00Z" tone="primary">
+        Linked
+        <a routerLink="." fragment="links-in-events">PR #123</a>
+        to the finding
+      </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-event time="2026-10-27T08:14:00Z">
+        Created by the nightly dependency scan
+      </bf-timeline-event>
+    </bf-timeline>
+  `,
+})
+export class TimelineOverviewExampleComponent {}
+```
+
+## Overview
+
+A dated history of events, newest first or oldest first as the consumer orders them: who did
+what and when, each event a `bf-timeline-event` with a marker on a vertical line.
+
+A timeline shows the history of one thing as dated events: who did what, and when. Each event is a [`bf-timeline-event`](https://bitforge-ui.web.app/components/timeline-event) with a coloured marker on a vertical line, its text (which may link the objects it names), then the actor and the time. The timeline shows the events in the order you give them, newest first or oldest first; it never sorts. It works the same in a desktop web app, a narrow side panel and the Capacitor shell.
+
+## When to use
+
+Use `bf-timeline` for a record's history or an audit trail: a finding that was created, assigned, linked to a pull request and fixed; the changes in a CVE side panel; who changed a setting. Use [bf-list](https://bitforge-ui.web.app/components/list) instead for items the user opens or acts on, and for navigation; a timeline is not a stepper through a process either, nor a feed the user scrolls for new items. For the details of one record, use a [bf-description-list](https://bitforge-ui.web.app/components/description-list).
+
+## Events and tones
+
+`actor` names who did it (leave it empty for a system event), `time` says when (a `Date` or an ISO 8601 string), and the content is the event text. `tone` colours the marker: `neutral` (the default) for routine events, `primary` for the current or most important one, `success` (fixed, merged), `warning`, `danger` (CI failed, a regression) and `info`. The colour only supports the text, so say what happened in words ("CI failed"), never by the colour alone. The line runs from each marker to the next and ends at the last event.
+
+## Links in events
+
+The event text is the default slot, so the objects it names can be links: a pull request, a repository, a CVE. Put a plain `<a href>` (or `<a routerLink>`) inline in the text; the event styles every link in its text in `primary-text`, underlined, with a thicker underline on hover and the focus ring on keyboard focus. Keep the link text the object's name ("PR #123"), not "here".
+
+## Time format
+
+The time is formatted with `Intl.DateTimeFormat` in the app's `LOCALE_ID`: a medium date and a short time by default (`28 Oct 2026, 14:30` in `en-GB`, `28.10.2026, 14:30` in `de-CH`), in the browser's time zone. `timeFormat` on the timeline takes any `Intl.DateTimeFormatOptions` for all its events (`{ dateStyle: 'short' }`, or a `timeZone`), and `locale` overrides the language for one timeline. `timeText` on an event shows your own text in place of the formatted time, such as a relative "vor 2 Std."; the `time` element's `datetime` keeps the exact value. An empty or invalid `time` shows no time, and a locale or options the browser refuses fall back to the defaults, so a bad value never throws.
+
+## Audit trail
+
+An audit trail is actor-heavy: every event names a person or a bot. The `end` slot holds a small action for one event, such as a Show diff button: it sits at the inline end while the timeline is wide, and wraps under the text in a narrow side panel or on a phone (once the text would get narrower than 16rem). It takes no space while empty.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfTimelineComponent, BfTimelineEventComponent } from '@bitforgehq/ui';
+
+interface AuditEntry {
+  id: string;
+  actor: string;
+  action: string;
+  time: string;
+  ago: string;
+  diff: boolean;
+}
+
+const ENTRIES: readonly AuditEntry[] = [
+  {
+    id: 'severity',
+    actor: 'Lena Meier',
+    action: 'Raised the severity from Medium to High',
+    time: '2026-10-28T14:10:00Z',
+    ago: '2 hours ago',
+    diff: true,
+  },
+  {
+    id: 'policy',
+    actor: 'Policy bot',
+    action: 'Applied the "Critical CVEs block releases" policy',
+    time: '2026-10-28T09:30:00Z',
+    ago: '7 hours ago',
+    diff: true,
+  },
+  {
+    id: 'owner',
+    actor: 'Jonas Keller',
+    action: 'Set the owner to the Platform team',
+    time: '2026-10-27T16:45:00Z',
+    ago: 'Yesterday',
+    diff: false,
+  },
+];
+
+/**
+ * An audit trail with relative times and an action per event.
+ *
+ * Every event names its actor, `timeText` shows a relative time while `datetime` keeps the exact
+ * one, and the `end` slot holds a Show diff button: at the inline end while the timeline is wide,
+ * under the text in a narrow panel.
+ */
+@Component({
+  selector: 'app-example-timeline-audit',
+  imports: [BfButtonComponent, BfTimelineComponent, BfTimelineEventComponent],
+  template: `
+    <div class="flex max-w-xl flex-col gap-3">
+      <bf-timeline label="Audit trail">
+        @for (entry of entries; track entry.id) {
+          <bf-timeline-event [actor]="entry.actor" [time]="entry.time" [timeText]="entry.ago">
+            {{ entry.action }}
+            @if (entry.diff) {
+              <bf-button bfSlot="end" variant="outline" size="sm" (clicked)="showDiff(entry)">
+                Show diff
+              </bf-button>
+            }
+          </bf-timeline-event>
+        }
+      </bf-timeline>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TimelineAuditExampleComponent {
+  readonly entries = ENTRIES;
+  readonly status = signal('No diff open.');
+
+  /** A real app would open the change in a side panel. */
+  showDiff(entry: AuditEntry): void {
+    this.status.set(`Diff of "${entry.action}" by ${entry.actor}.`);
+  }
+}
+```
+
+## Desktop
+
+The timeline itself is not interactive: no hover, no pointer cursor, no focus stop. Only the links in the event text and the controls in an `end` slot take focus, with their own hover and focus ring. Its spacing does not follow `provideBfDefaults()`: the events keep one rhythm at every density, and it has no `size`. Inside `provideBfShell()` it renders and behaves the same; the `end` slot's buttons bring their own 44 px touch height.
+
+## Theming
+
+- Marker: a 10 px dot (`rounded-control`) in `text-subtle` (neutral), `primary`, `success`, `warning`, `danger` or `info`; `CanvasText` under forced colours.
+- Line: a 1 px `border` line from marker to marker.
+- Text: `text-body` in `text`; links `primary-text`, underlined, `ring` on keyboard focus. Meta line: `text-caption` in `text-muted`.
+- Spacing: 12 px between the marker and the text, 20 px between events.
+
+## Accessibility
+
+The timeline is a list (`role="list"`, named by `label` through `aria-label`) and each event inside it a `listitem`, so a screen reader announces the number of events and the position of each. An event outside a `bf-timeline` claims no role. The marker and the line are `aria-hidden`; the tone is decoration, so the text must say what happened. The time is a `time` element whose `datetime` is the ISO value, and the separator between actor and time is hidden from assistive technology. Links and `end` slot controls are native elements in reading order.
+
+## Inputs
+
+| Name         | Type                         | Default                | Description                                                                                                                                   |
+| ------------ | ---------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`                     | `''`                   | The list's accessible name, such as "History"; empty leaves the list unnamed (a visible heading above it already names the section).          |
+| `timeFormat` | `Intl.DateTimeFormatOptions` | `TIMELINE_TIME_FORMAT` | `Intl.DateTimeFormat` options of every event's time; by default a medium date and a short time (`dateStyle: 'medium'`, `timeStyle: 'short'`). |
+| `locale`     | `string`                     | `''`                   | BCP 47 locale of the times, such as `de-CH`; empty follows the app's `LOCALE_ID`.                                                             |
+
+## Slots
+
+- `default`: The events, each a `bf-timeline-event`, in the order to show them.
+
+## Notes
+
+### Do
+
+- Give the timeline a `label` when no visible heading names it, and keep one order (newest first) across the app.
+- Name the actor and the object in every event; link the object.
+
+### Don't
+
+- Don't use a timeline for navigation or for steps the user still has to take.
+- Don't carry meaning in the tone alone; say "CI failed", not just a red dot.
+
+## Migration notes
+
+### 0.4.0
+
+New: `bf-timeline`, a dated history of events (who did what, and when) for a record's history
+or an audit trail, in both shells. A `role="list"` named by `label`, in the order the consumer
+gives (it never sorts); each event's time is formatted with `Intl.DateTimeFormat` in the app's
+`LOCALE_ID` (`timeFormat`, default a medium date and a short time; `locale` overrides it).

package/ai/components/toggle.md

@@ -130,9 +130,11 @@ export class ToggleListRowExampleComponent {
 }
 ```
 
+In a table of switches (a settings matrix: alert kinds by channel), each cell's toggle is named after its column and row with `ariaLabel`; see [bf-table](https://bitforge-ui.web.app/components/table)'s Toggle cells.
+
 ## Sizes
 
-`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px. The knob travels to the inline end, so it moves left under `dir="rtl"`.
+`sm` (32 px row, 24×40 track), `md` (default, 40 px row, 28×48 track), `lg` (48 px row, 32×56 track). Unset, `size` follows `provideBfDefaults()`'s `controlSize`, `md` by default (`provideBfDefaults({ size: 'lg' })` enlarges every control of a Capacitor app; `{ size: 'sm' }` in a component's `providers` makes a dense sub-tree). Under a fine pointer the row is the hit area (32 px and up, above the 24 px of WCAG 2.5.8); under a coarse pointer (touch) `sm` and `md` rows grow to 44 px, and a label-less `sm` switch (40 px wide) also takes a 44 px width, its track centred. The knob travels to the inline end, so it moves left under `dir="rtl"`.
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -325,6 +327,14 @@ Focuses the native switch; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.4.0
+
+A label-less `sm` toggle (a table cell) takes a 44 px min-width under a coarse pointer, its track
+centred, so its touch target is 44 × 44 px (it was 40 px wide). Nothing changes under a fine
+pointer or for `md` and `lg`. `@bitforgehq/ui/testing`: new `BfToggleHarness` (`with({ label })`
+by the switch's computed name, `getLabel()`, `isChecked()`, `isDisabled()`, `isReadonly()`,
+`toggle()`, `check()`, `uncheck()`, `getErrorText()`).
+
 ### 0.3.0
 
 New `ariaLabelledby` input: the id of the element that names the switch when no visible `label`

package/ai/reference/bf-action-directive.md

@@ -12,7 +12,9 @@ exposed: the heading stays a heading and the accessible name is the title alone.
 with the nearest card or row, which then draws the pointer, the hover and, while the action has
 keyboard focus, the focus ring; a card is never lit by the actions of rows nested in it. Give
 secondary controls inside the surface `class="relative z-1"` so they stay clickable above the
-stretched area.
+stretched area. When the surface marks a state that belongs in the name (an `unread` list
+row), the directive names the element `aria-labelledby="<state id> <own id>"`, so the link reads
+"Unread, Account", and restores the element's own `aria-labelledby` when the state goes.
 
 ```ts
 import { BfActionDirective } from '@bitforgehq/ui';

package/ai/reference/bf-badge-emphasis.md

@@ -0,0 +1,27 @@
+# BfBadgeEmphasis
+
+The two badge emphases, the soft tint or the solid strong fill
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+How loud a `bf-badge` is: `soft`, a pale tint with tinted text (the default), or `strong`, a
+solid fill with contrasting text for the one state that must stand out, such as "Critical".
+
+```ts
+import { type BfBadgeEmphasis } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfBadgeEmphasis = 'soft' | 'strong'
+```
+
+## Values
+
+- `soft`
+- `strong`
+
+## Used by
+
+- [bf-badge](../components/badge.md)

package/ai/reference/bf-labels.md

@@ -85,6 +85,7 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `chartValue`            | `string`                                      | `'Value'`                                                                        | The value column header of a bf-donut-chart's data table.                                                      |
 | `chartEmpty`            | `string`                                      | `'No data to show'`                                                              | bf-chart-card's text when it has no data and no `empty` slot.                                                  |
 | `chartError`            | `string`                                      | `'The data could not be loaded'`                                                 | bf-chart-card's text when its data failed to load and it has no `error` slot.                                  |
+| `listItemUnread`        | `string`                                      | `'Unread'`                                                                       | bf-list-item's visually hidden state text before the title of an `unread` row.                                 |
 | `validation`            | `BfValidationMessages`                        | required                                                                         | Default error text per validator kind (see `BfValidationMessages`).                                            |
 
 ## Uses

package/ai/reference/bf-step-heading-level.md

@@ -0,0 +1,28 @@
+# BfStepHeadingLevel
+
+The heading level a step title can take, two, three or four
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+The heading level of a `bf-step` title, for a guide whose steps hold enough content (screenshots,
+code) that a screen-reader user moves between them by heading.
+
+```ts
+import { type BfStepHeadingLevel } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfStepHeadingLevel = 2 | 3 | 4
+```
+
+## Values
+
+- `2`
+- `3`
+- `4`
+
+## Used by
+
+- [bf-step](../components/step.md)

package/ai/reference/bf-table-align.md

@@ -23,4 +23,4 @@ type BfTableAlign = 'start' | 'end'
 
 ## Used by
 
-- [BfTableColumn](bf-table-column.md)
+- [BfTableColumnAlign](bf-table-column-align.md)

package/ai/reference/bf-table-column-align.md

@@ -0,0 +1,33 @@
+# BfTableColumnAlign
+
+The inline alignment of a table column: start, end, or centred for controls
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+Where a `bf-table` column lines up its header and cells: a `BfTableAlign`, or `center` for a
+column of controls such as the toggles of a settings matrix. A new type, so `Record`s over the
+released `BfTableAlign` keep compiling.
+
+```ts
+import { type BfTableColumnAlign } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTableColumnAlign = BfTableAlign | 'center'
+```
+
+## Values
+
+- `start`
+- `end`
+- `center`
+
+## Uses
+
+- [BfTableAlign](bf-table-align.md)
+
+## Used by
+
+- [BfTableColumn](bf-table-column.md)

package/ai/reference/bf-table-column.md

@@ -12,16 +12,16 @@ import { type BfTableColumn } from '@bitforgehq/ui';
 
 ## Properties
 
-| Name       | Type                                | Default   | Description                                                                           |
-| ---------- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------- |
-| `key`      | `string`                            | required  | The row property the default cell shows; also the key a `bfTableCell` template names. |
-| `label`    | `string`                            | required  | The header text.                                                                      |
-| `sortable` | `boolean`                           | `false`   | Whether the header is a button that sets the table's `sort`.                          |
-| `align`    | `BfTableAlign` (`'start' \| 'end'`) | `'start'` | The inline alignment of the header and cells; `end` also sets tabular figures.        |
+| Name       | Type                                                  | Default   | Description                                                                                                                                            |
+| ---------- | ----------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `key`      | `string`                                              | required  | The row property the default cell shows; also the key a `bfTableCell` template names.                                                                  |
+| `label`    | `string`                                              | required  | The header text.                                                                                                                                       |
+| `sortable` | `boolean`                                             | `false`   | Whether the header is a button that sets the table's `sort`.                                                                                           |
+| `align`    | `BfTableColumnAlign` (`'start' \| 'end' \| 'center'`) | `'start'` | The inline alignment of the header and cells; `end` also sets tabular figures, `center` centres a cell's control (a toggle, a checkbox) in the column. |
 
 ## Uses
 
-- [BfTableAlign](bf-table-align.md)
+- [BfTableColumnAlign](bf-table-column-align.md)
 
 ## Used by
 

package/ai/reference/bf-table-harness.md

@@ -41,6 +41,18 @@ The text of one cell.
 | `row`     | `number` | The row's position, from 0. |
 | `column`  | `string` | The column's header text.   |
 
+### `getCellHarness<T extends ComponentHarness>(row: number, column: string, query: HarnessQuery<T>): Promise<T>`
+
+A harness for a control in one cell, such as a `bf-toggle` of a settings matrix or a
+`bf-select` in a custom cell. Throws for an unknown row or column, or when the cell holds no
+matching control.
+
+| Parameter | Type              | Description                                         |
+| --------- | ----------------- | --------------------------------------------------- |
+| `row`     | `number`          | The row's position, from 0.                         |
+| `column`  | `string`          | The column's header text.                           |
+| `query`   | `HarnessQuery<T>` | The harness type, or a predicate from its `with()`. |
+
 ### `sortBy(column: string): Promise<void>`
 
 Clicks a sortable column's header, as a user would: ascending first, then descending.

package/ai/reference/bf-timeline-tone.md

@@ -0,0 +1,31 @@
+# BfTimelineTone
+
+The marker colour of a timeline event, neutral, primary or a status
+
+Type from `@bitforgehq/ui` · since 0.4.0
+
+The colour of a `bf-timeline-event`'s marker: `neutral` (the default), `primary`, or a status
+(`success`, `warning`, `danger`, `info`), such as danger for a failed CI run.
+
+```ts
+import { type BfTimelineTone } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfTimelineTone = 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info'
+```
+
+## Values
+
+- `neutral`
+- `primary`
+- `success`
+- `warning`
+- `danger`
+- `info`
+
+## Used by
+
+- [bf-timeline-event](../components/timeline-event.md)

package/ai/reference/bf-toggle-harness.md

@@ -0,0 +1,55 @@
+# BfToggleHarness
+
+Test harness for the toggle: reads its name and state and switches it
+
+Class from `@bitforgehq/ui/testing` · since 0.4.0
+
+Harness for `bf-toggle`. Its `label` filter matches the switch's name: the text of the elements
+`ariaLabelledby` names, else `ariaLabel`, else the visible label, so a label-less switch in a
+table cell or a list row is found the same way.
+
+```ts
+import { BfToggleHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfToggleHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The switch's name, as the browser computes it: the text of the elements `ariaLabelledby`
+names, else `ariaLabel`, else the visible label (the `label` text and the default slot).
+
+### `isChecked(): Promise<boolean>`
+
+Whether the switch is on.
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the switch is disabled.
+
+### `isReadonly(): Promise<boolean>`
+
+Whether the switch is read-only (`aria-readonly`): it shows its state but a click does nothing.
+
+### `toggle(): Promise<void>`
+
+Clicks the switch, as a user would, so it turns on or off. Throws while it is disabled (a
+user's click would do nothing); a read-only switch takes the click and stays as it is.
+
+### `check(): Promise<void>`
+
+Turns the switch on with a click; an on switch stays on. Throws while it is disabled.
+
+### `uncheck(): Promise<void>`
+
+Turns the switch off with a click; an off switch stays off. Throws while it is disabled.
+
+### `getErrorText(): Promise<string>`
+
+The error text under the switch.

package/ai/reference/provide-bf-labels.md

@@ -17,7 +17,7 @@ every string. In a component's `providers` it covers that sub-tree's widgets and
 `dateInputUnavailable`, `timeInputHour`, `timeInputMinute`, `timeInputSecond`,
 `timeInputDayPeriod`, `timeInputOpenList`, `timeInputInvalid`, `timeInputMin`, `timeInputMax`,
 `chart`, `chartLegend`, `chartValues`, `chartShowData`, `chartHideData`, `chartCategory`,
-`chartValue`, `chartEmpty`, `chartError`, `validation`); the overlay services (`ok`, `cancel`,
+`chartValue`, `chartEmpty`, `chartError`, `listItemUnread`, `validation`); the overlay services (`ok`, `cancel`,
 `actions`, `sheet`, `modal`, `close`, `expand`, `collapse`, `sheetPosition`, `dialog`,
 `notifications`) are root singletons and pick it up only when the caller passes its injector:
 `open(…, { injector: inject(Injector) })`.