@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/table.md

@@ -0,0 +1,568 @@
+# bf-table
+
+Desktop data table with sortable headers, row selection, custom cells and an empty slot
+
+`BfTableComponent` from `@bitforgehq/ui` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfActionBarComponent,
+  BfButtonComponent,
+  BfTableComponent,
+  type BfTableColumn,
+  type BfTableSort,
+} from '@bitforgehq/ui';
+
+interface Task {
+  id: string;
+  title: string;
+  project: string;
+  hours: number;
+}
+
+const TASKS: readonly Task[] = [
+  { id: 'brief', title: 'Write the brief', project: 'Atlas', hours: 3 },
+  { id: 'moodboard', title: 'Bloom moodboard', project: 'Bloom', hours: 6 },
+  { id: 'deck', title: 'Pitch deck', project: 'Atlas', hours: 9 },
+  { id: 'copy', title: 'Copy review', project: 'Cedar', hours: 2 },
+];
+
+/**
+ * The bf-table overview.
+ *
+ * Live demo of `bf-table`: sortable Task and Hours headers, row selection and a `bf-action-bar`
+ * that acts on the selected rows. The table sets `sort`; the page sorts the rows.
+ */
+@Component({
+  selector: 'app-example-table-overview',
+  imports: [BfTableComponent, BfActionBarComponent, BfButtonComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-table
+        label="Tasks"
+        selectable
+        [rows]="rows()"
+        [columns]="columns"
+        [(sort)]="sort"
+        [(selection)]="selection"
+      />
+      @if (selection().length > 0) {
+        <bf-action-bar class="self-center" [label]="selection().length + ' selected'">
+          <bf-button variant="text" size="sm" (clicked)="selection.set([])">Clear</bf-button>
+          <bf-button size="sm" (clicked)="markDone()">Mark done</bf-button>
+        </bf-action-bar>
+      }
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TableOverviewExampleComponent {
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Task', sortable: true },
+    { key: 'project', label: 'Project' },
+    { key: 'hours', label: 'Hours', sortable: true, align: 'end' },
+  ];
+  readonly tasks = signal<readonly Task[]>(TASKS);
+  readonly sort = signal<BfTableSort | null>(null);
+  readonly selection = signal<readonly string[]>([]);
+  readonly done = signal(0);
+
+  /** The table never sorts: the page sorts its rows from `sort`. */
+  readonly rows = computed(() => {
+    const sort = this.sort();
+    if (!sort) {
+      return this.tasks();
+    }
+    const factor = sort.direction === 'ascending' ? 1 : -1;
+    return [...this.tasks()].sort((a, b) =>
+      sort.column === 'hours'
+        ? (a.hours - b.hours) * factor
+        : a.title.localeCompare(b.title) * factor,
+    );
+  });
+
+  readonly status = computed(() => {
+    const sort = this.sort();
+    const sorted = sort ? `Sorted by ${sort.column}, ${sort.direction}` : 'Unsorted';
+    return `${sorted} · ${this.selection().length} selected · ${this.done()} done.`;
+  });
+
+  markDone(): void {
+    const selected = new Set(this.selection());
+    this.tasks.update((tasks) => tasks.filter((task) => !selected.has(task.id)));
+    this.done.update((done) => done + selected.size);
+    this.selection.set([]);
+  }
+}
+```
+
+## Overview
+
+Data table for desktop: column headers that set a sort, optional row selection with
+checkboxes, custom cells from `bfTableCell` templates and an empty slot. It never sorts or
+filters itself; the consumer sorts the rows in a `computed()` from `sort`.
+
+A data table for desktop pages: rows of records the user compares across columns, with headers that sort, an optional checkbox column that selects rows, custom cells and an empty state. `bf-table` is data-driven: you pass `rows` and `columns`, and it never sorts or filters the rows itself. Its headers set the `sort` model and you sort the rows in a `computed()`, on the client or on the server.
+
+## When to use
+
+Use `bf-table` on a desktop page for records the user scans and compares column by column: tasks, invoices, members. On a phone or in the Capacitor shell use [bf-list](https://bitforge-ui.web.app/components/list) rows instead. Use a [bf-list](https://bitforge-ui.web.app/components/list) on desktop too when each record is one line of text with a status, and a description list for the fields of a single record.
+
+## 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.
+
+`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.
+
+`label` names the table. It renders as a visually hidden `caption`, so a screen reader announces it when entering the table; the page's visible heading stays yours. Give every table a `label`.
+
+## Sorting
+
+A `sortable` column's header is a button. The first click sets `sort` to `{ column, direction: 'ascending' }`, the next one to `descending`, then ascending again; clicking another column starts it ascending. The sorted header carries `aria-sort` and a small CSS arrow (up while ascending, down while descending). The table never reorders the rows: bind `[(sort)]` and sort the rows in a `computed()` from it, so a server-side sort works the same way. `sort` is `null` until the user sorts, or set it to start sorted.
+
+## Selection
+
+`selectable` adds a first column of `bf-checkbox`es; `selection` is a `model` of the selected rows' keys, so bind `[(selection)]`. The header checkbox selects or clears every row shown (keys of rows filtered out stay as they are) and shows the mixed state while only some are selected. Selected rows take the `primary-soft` fill. A selection drives a [bf-action-bar](https://bitforge-ui.web.app/components/action-bar) with the count and the actions on the selected rows, as in the overview above. Clear the selection after an action that removes its rows.
+
+## Custom cells
+
+An `ng-template[bfTableCell]` replaces the default text of one column with your own markup: a title with a subtitle, an avatar, a badge, a link or a row action. `bfTableCell` names the column's `key`, `let-row` is the row and `let-i="index"` its position. Bind `[bfTableCellOf]` to the same rows as the table so the template's row is typed (without it the row is `unknown`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfAvatarComponent,
+  BfBadgeComponent,
+  BfButtonComponent,
+  BfTableCellDirective,
+  BfTableComponent,
+  type BfBadgeAppearance,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+
+interface Task {
+  id: string;
+  title: string;
+  project: string;
+  owner: string;
+  initials: string;
+  status: 'Open' | 'Review' | 'Done';
+}
+
+const TONE: Record<Task['status'], BfBadgeAppearance> = {
+  Open: 'neutral',
+  Review: 'warning',
+  Done: 'success',
+};
+
+/**
+ * Custom cells.
+ *
+ * Each `ng-template[bfTableCell]` replaces the text of one column: a title with its project, an
+ * avatar, a status badge and a row action. `[bfTableCellOf]` types `let-task` as a `Task`.
+ */
+@Component({
+  selector: 'app-example-table-custom-cells',
+  imports: [
+    BfTableComponent,
+    BfTableCellDirective,
+    BfAvatarComponent,
+    BfBadgeComponent,
+    BfButtonComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-table label="Tasks" [rows]="tasks" [columns]="columns">
+        <ng-template bfTableCell="title" [bfTableCellOf]="tasks" let-task>
+          <span class="flex flex-col">
+            <span class="font-bold">{{ task.title }}</span>
+            <span class="text-caption text-text-muted">{{ task.project }}</span>
+          </span>
+        </ng-template>
+        <ng-template bfTableCell="owner" [bfTableCellOf]="tasks" let-task>
+          <span class="flex items-center gap-2">
+            <bf-avatar size="sm" [initials]="task.initials" />
+            {{ task.owner }}
+          </span>
+        </ng-template>
+        <ng-template bfTableCell="status" [bfTableCellOf]="tasks" let-task>
+          <bf-badge [variant]="tone[task.status]">{{ task.status }}</bf-badge>
+        </ng-template>
+        <ng-template bfTableCell="open" [bfTableCellOf]="tasks" let-task>
+          <bf-button variant="text" size="sm" (clicked)="opened.set(task.title)">Open</bf-button>
+        </ng-template>
+      </bf-table>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        {{ opened() ? 'Opened ' + opened() + '.' : 'Open a task.' }}
+      </p>
+    </div>
+  `,
+})
+export class TableCustomCellsExampleComponent {
+  readonly tone = TONE;
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Task' },
+    { key: 'owner', label: 'Owner' },
+    { key: 'status', label: 'Status' },
+    { key: 'open', label: 'Actions', align: 'end' },
+  ];
+  readonly tasks: readonly Task[] = [
+    {
+      id: 'brief',
+      title: 'Write the brief',
+      project: 'Atlas',
+      owner: 'Lena Meier',
+      initials: 'LM',
+      status: 'Review',
+    },
+    {
+      id: 'deck',
+      title: 'Pitch deck',
+      project: 'Atlas',
+      owner: 'Jonas Keller',
+      initials: 'JK',
+      status: 'Open',
+    },
+    {
+      id: 'copy',
+      title: 'Copy review',
+      project: 'Cedar',
+      owner: 'Lena Meier',
+      initials: 'LM',
+      status: 'Done',
+    },
+  ];
+  readonly opened = signal('');
+}
+```
+
+## 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.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfEmptyStateComponent,
+  BfTableComponent,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ListTodo } from 'lucide';
+
+interface Task {
+  id: string;
+  title: string;
+  hours: number;
+}
+
+/**
+ * An empty table with an empty state.
+ *
+ * While `rows` is empty the table shows one full-width row holding the `empty` slot, here a
+ * `bf-empty-state` whose action adds the first row.
+ */
+@Component({
+  selector: 'app-example-table-empty',
+  imports: [BfTableComponent, BfEmptyStateComponent, BfButtonComponent, BfIconComponent],
+  template: `
+    <bf-table label="Tasks" [rows]="tasks()" [columns]="columns">
+      <bf-empty-state
+        bfSlot="empty"
+        title="No tasks yet"
+        description="Add a task and it shows up here."
+        [headingLevel]="3"
+      >
+        <bf-icon bfSlot="icon" [icon]="listTodo" size="lg" />
+        <bf-button bfSlot="actions" (clicked)="add()">New task</bf-button>
+      </bf-empty-state>
+    </bf-table>
+  `,
+})
+export class TableEmptyExampleComponent {
+  readonly listTodo = ListTodo;
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Task' },
+    { key: 'hours', label: 'Hours', align: 'end' },
+  ];
+  readonly tasks = signal<readonly Task[]>([]);
+
+  add(): void {
+    this.tasks.update((tasks) => [...tasks, { id: 'brief', title: 'Write the brief', hours: 3 }]);
+  }
+}
+```
+
+## Paging
+
+A long table shows one page of rows at a time with a [bf-pagination](https://bitforge-ui.web.app/components/pagination) under it. Bind its `[(page)]` and give it the `total` row count and the `pageSize`; the table gets only the current page's rows, sliced in a `computed()` from the sorted rows (or fetched from the server for that page). Sorting goes back to page 1, so the user starts at the top of the new order. Name the pagination after the table ("Invoice pages"), so its landmark says what it pages.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfPaginationComponent,
+  BfTableComponent,
+  type BfTableColumn,
+  type BfTableSort,
+} from '@bitforgehq/ui';
+
+interface Invoice {
+  id: string;
+  client: string;
+  amount: number;
+}
+
+const CLIENTS = ['Atlas', 'Bloom', 'Cedar', 'Delta', 'Ember'];
+const INVOICES: readonly Invoice[] = Array.from({ length: 23 }, (_, i) => ({
+  id: `INV-${String(1001 + i)}`,
+  client: CLIENTS[i % CLIENTS.length] ?? 'Atlas',
+  amount: 120 + ((i * 37) % 90) * 10,
+}));
+const PAGE_SIZE = 5;
+
+/**
+ * A paged table.
+ *
+ * Twenty-three invoices, five per page: the table shows the current page's rows, sliced in a
+ * `computed()` from the sorted rows, and a `bf-pagination` under it binds the page with `total`
+ * and `pageSize`. Sorting goes back to page 1.
+ */
+@Component({
+  selector: 'app-example-table-paged',
+  imports: [BfTableComponent, BfPaginationComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-table
+        label="Invoices"
+        [rows]="pageRows()"
+        [columns]="columns"
+        [sort]="sort()"
+        (sortChange)="sortBy($event)"
+      />
+      <bf-pagination
+        class="self-end"
+        label="Invoice pages"
+        [(page)]="page"
+        [total]="invoices.length"
+        [pageSize]="pageSize"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TablePagedExampleComponent {
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'id', label: 'Invoice', sortable: true },
+    { key: 'client', label: 'Client' },
+    { key: 'amount', label: 'Amount', sortable: true, align: 'end' },
+  ];
+  readonly invoices = INVOICES;
+  readonly pageSize = PAGE_SIZE;
+  readonly page = signal(1);
+  readonly sort = signal<BfTableSort | null>(null);
+
+  readonly sorted = computed(() => {
+    const sort = this.sort();
+    if (!sort) {
+      return this.invoices;
+    }
+    const factor = sort.direction === 'ascending' ? 1 : -1;
+    return [...this.invoices].sort((a, b) =>
+      sort.column === 'amount' ? (a.amount - b.amount) * factor : a.id.localeCompare(b.id) * factor,
+    );
+  });
+
+  /** The current page's rows: the table never sees the others. */
+  readonly pageRows = computed(() => {
+    const start = (this.page() - 1) * PAGE_SIZE;
+    return this.sorted().slice(start, start + PAGE_SIZE);
+  });
+
+  readonly status = computed(() => {
+    const start = (this.page() - 1) * PAGE_SIZE + 1;
+    const end = Math.min(start + PAGE_SIZE - 1, this.invoices.length);
+    return `Invoices ${start}–${end} of ${this.invoices.length}.`;
+  });
+
+  /** A new sort starts at the top of the new order: back to page 1. */
+  sortBy(sort: BfTableSort | null): void {
+    this.sort.set(sort);
+    this.page.set(1);
+  }
+}
+```
+
+## Density
+
+`size` sets the row height: `sm` 40 px, `md` 48 px (default), `lg` 56 px, with a 32, 40 or 48 px header. Unset, it follows `provideBfDefaults()`'s `controlSize`, so `{ size: 'sm' }` in a page's `providers` makes a dense table. The checkboxes take the same step. Under a coarse pointer every row is at least 44 px tall, and the sortable header buttons are 44 px targets; a cell grows to fit its content and is never covered by a hit-area extension.
+
+## Narrow screens and touch
+
+A table needs width. Below the `md` breakpoint, render the same rows as a divided `bf-list` of `bf-list-item`s (a `md:hidden` wrapper) and the table only from `md` up (a `hidden md:block` wrapper), from the one `rows` array. Inside the Capacitor shell use the list alone. The table's wrapper scrolls sideways when its columns cannot fit, but that is a last resort, not a layout for phones.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfListComponent,
+  BfListItemComponent,
+  BfTableComponent,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+
+interface Task {
+  id: string;
+  title: string;
+  project: string;
+  hours: number;
+}
+
+/**
+ * The same rows as a list on narrow screens.
+ *
+ * One `rows` array drives both: the table from the `md` breakpoint up (a `hidden md:block`
+ * wrapper), a divided `bf-list` of `bf-list-item` rows below it (`md:hidden`), so a phone never
+ * scrolls a table sideways.
+ */
+@Component({
+  selector: 'app-example-table-narrow-fallback',
+  imports: [BfTableComponent, BfListComponent, BfListItemComponent],
+  template: `
+    <div class="hidden md:block">
+      <bf-table label="Tasks" [rows]="tasks" [columns]="columns" />
+    </div>
+    <div class="md:hidden">
+      <bf-list divided>
+        @for (task of tasks; track task.id) {
+          <bf-list-item [title]="task.title" [subtitle]="task.project">
+            <span bfSlot="trailing" class="text-caption text-text-muted tabular-nums">
+              {{ task.hours }} h
+            </span>
+          </bf-list-item>
+        }
+      </bf-list>
+    </div>
+  `,
+})
+export class TableNarrowFallbackExampleComponent {
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Task' },
+    { key: 'project', label: 'Project' },
+    { key: 'hours', label: 'Hours', align: 'end' },
+  ];
+  readonly tasks: readonly Task[] = [
+    { id: 'brief', title: 'Write the brief', project: 'Atlas', hours: 3 },
+    { id: 'moodboard', title: 'Bloom moodboard', project: 'Bloom', hours: 6 },
+    { id: 'copy', title: 'Copy review', project: 'Cedar', hours: 2 },
+  ];
+}
+```
+
+## Desktop
+
+A selectable table tints a row `surface-muted` while hovered (a selected row `primary-soft-hover`); a table without selection does not, because its rows are not targets. Sortable headers darken from `text-muted` to `text` on hover and show the pointer. Hover styles apply only on devices that can hover. The focus ring shows on keyboard focus only, on the header button, the checkbox or the control in a custom cell. Desktop density is the default `md` step; `sm` suits a dense admin page ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Header: `text-label-xs`, bold, `text-muted`; a sortable header's hover `text`. A `border` line under the header row.
+- Rows: `text` on the page's surface, divided by `border` lines; hover (selectable only) `surface-muted`; selected `primary-soft`, hover `primary-soft-hover`.
+- Sort arrow: a 1.5 px CSS chevron in the header's text colour.
+- Focus ring: `ring`. Header buttons: `rounded-field`.
+- Text: `text-body` (`text-label-sm` at `sm`), `tabular-nums` in `end` columns.
+
+Put the table on a `bf-card` (or another surface) yourself; it has no background or border of its own.
+
+## 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.
+
+### Keyboard
+
+| Key                                              | Action                                                                                                                                                                      |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the header buttons, checkboxes and the controls in custom cells in document order                                                                             |
+| <kbd>ArrowDown</kbd>                             | On a button, link or checkbox in a row (or the header): moves focus to the control at the same place in the nearest row below that has one; nothing happens at the last row |
+| <kbd>ArrowUp</kbd>                               | The same, upwards, up to the header row                                                                                                                                     |
+| <kbd>Space</kbd>                                 | Toggles the focused checkbox, or sorts by the focused header                                                                                                                |
+| <kbd>Enter</kbd>                                 | Sorts by the focused header                                                                                                                                                 |
+
+Text fields, selects and composite widgets (radios, comboboxes, sliders) in a cell keep their own arrow keys.
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                                                                                 |
+| ---------------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rows`           | `readonly T[]`                                              | required    | The rows to show, already sorted and filtered by the consumer.                                                                                                              |
+| `columns`        | `readonly BfTableColumn[]`                                  | required    | The columns, in order.                                                                                                                                                      |
+| `rowKey`         | `BfTableRowKey<T>`                                          | `idRowKey`  | The unique string key of a row, used for `selection` and to track rows; by default the row's `id` (a string or a number), else its index.                                   |
+| `label`          | `string`                                                    | `''`        | The table's name, rendered as a visually hidden `caption`.                                                                                                                  |
+| `selectable`     | `boolean`                                                   | `false`     | Adds a first column of checkboxes that select rows.                                                                                                                         |
+| `selectAllLabel` | `string`                                                    | `''`        | Accessible name of the header checkbox; empty falls back to `provideBfLabels()`'s `tableSelectAll` ("Select all rows").                                                     |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Row height step: sm 40, md 48, lg 56 px (the header 32/40/48; at least 44 px under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `sort`           | `BfTableSort \| null`                                       | `null`      | The sorted column and direction, `null` while unsorted; two-way bindable. A sortable header sets it, and the consumer sorts `rows` from it. Two-way: `[(sort)]`.            |
+| `selection`      | `readonly string[]`                                         | `[]`        | The keys (`rowKey`) of the selected rows; two-way bindable. Two-way: `[(selection)]`.                                                                                       |
+
+## Slots
+
+- `empty`: Shown in one full-width row while `rows` is empty, such as a `bf-empty-state`.
+
+## Methods
+
+### `sortBy(key: string): void`
+
+Sorts by the column with this key: ascending first, then descending and ascending again.
+
+| Parameter | Type     | Description         |
+| --------- | -------- | ------------------- |
+| `key`     | `string` | The column's `key`. |
+
+### `selectAll(selected: boolean): void`
+
+Selects or clears every row; keys of rows not shown stay as they are.
+
+| Parameter  | Type      | Description                                    |
+| ---------- | --------- | ---------------------------------------------- |
+| `selected` | `boolean` | True to select every row, false to clear them. |
+
+### `selectRow(key: string, selected: boolean): void`
+
+Selects or clears one row.
+
+| Parameter  | Type      | Description                           |
+| ---------- | --------- | ------------------------------------- |
+| `key`      | `string`  | The row's key.                        |
+| `selected` | `boolean` | True to select it, false to clear it. |
+
+## Notes
+
+### Do
+
+- Give every table a `label`, and every sortable column a short header.
+- Sort and filter the rows in a `computed()` from `sort` and your filters.
+- Render the rows as `bf-list-item`s below `md` and inside the Capacitor shell.
+
+### Don't
+
+- Don't put a table on a phone screen that scrolls sideways; use the list.
+- Don't make a whole row clickable; put a link or button in a custom cell.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-table` and `ng-template[bfTableCell]` (`BfTableCellDirective`) in `@bitforgehq/ui`, a
+data table for desktop pages: `rows`, `columns` (`BfTableColumn`: `key`, `label`, `sortable`,
+`align` of `BfTableAlign`), `rowKey` (`BfTableRowKey`, the row's `id` by default) and a
+visually hidden caption from `label`. Sortable headers set the `sort` model (`BfTableSort`,
+`BfTableSortDirection`) and `aria-sort`; the consumer sorts the rows. `selectable` adds a
+checkbox column bound to the `selection` model of row keys, with a mixed header checkbox named
+by the new `tableSelectAll` label ("Select all rows") or `selectAllLabel`. A `bfTableCell`
+template replaces one column's cells (`BfTableCellContext`; `bfTableCellOf` types the row), the
+`empty` slot shows while there are no rows, `size` follows `controlSize`, and ArrowUp / ArrowDown
+move focus between the controls of a column. New `BfTableHarness` in `@bitforgehq/ui/testing`.
+
+The docs gain a Paging section and a `table/paged` example: one page of rows with a
+`bf-pagination` under the table, back to page 1 on a sort.

package/ai/components/tabs.md

@@ -79,7 +79,7 @@ else the current tab route), the bar hides while the soft keyboard is open, and
 
 ## When to use
 
-Use `bf-tabs` for the tab root of a Capacitor app: one navigation stack per tab behind a floating [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar). Use [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet) instead for an app with one stack and no tabs, and a sidebar of links on desktop.
+Use `bf-tabs` for the tab root of a Capacitor app: one navigation stack per tab behind a floating [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar). Use [bf-stack-outlet](https://bitforge-ui.web.app/components/stack-outlet) instead for an app with one stack and no tabs, and on desktop a [bf-sidebar](https://bitforge-ui.web.app/components/sidebar) or a [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) of `a[bfNavItem]` links over a plain `router-outlet`.
 
 ## Basic usage
 
@@ -194,7 +194,41 @@ fires no keyboard event).
 
 ## Desktop
 
-`bf-tabs` is part of the Capacitor shell (`provideBfShell()`). On a desktop web app put the top-level destinations in a sidebar or a top `nav` of links with `routerLinkActive`, and a plain `router-outlet`. Inside the shell under a mouse, the tab links take the `bf-tab` hover and focus styles.
+`bf-tabs` is part of the Capacitor shell (`provideBfShell()`). On a desktop web app, put the top-level destinations in a [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) (a few sections) or a [bf-sidebar](https://bitforge-ui.web.app/components/sidebar) (more, in groups, collapsible to an icon rail) of `a[bfNavItem]` links, each with `routerLink`, `routerLinkActive` and `ariaCurrentWhenActive="page"`, above a plain `router-outlet`. The router sets `aria-current="page"` on the link of the current route and the item shows it. Drive both from one array of destinations: inside the shell the same array feeds the `bf-tab`s of a [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar), and below a breakpoint a [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` links (see bf-sidebar, Responsive). Inside the shell under a mouse, the tab links take the `bf-tab` hover and focus styles.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfTopNavComponent } from '@bitforgehq/ui';
+
+/**
+ * The desktop replacement for tabs: a bf-top-nav.
+ *
+ * `a[bfNavItem]` links with `routerLinkActive` and `ariaCurrentWhenActive="page"`: the router marks
+ * the current page and the item shows it; a plain `router-outlet` below renders the page. With
+ * more sections, the same links go in a `bf-sidebar`.
+ */
+@Component({
+  selector: 'app-example-tabs-desktop-nav',
+  imports: [RouterLink, RouterLinkActive, BfNavItemComponent, BfTopNavComponent],
+  template: `
+    <bf-top-nav label="Navigation components">
+      @for (link of links; track link.path) {
+        <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">{{
+          link.label
+        }}</a>
+      }
+    </bf-top-nav>
+  `,
+})
+export class TabsDesktopNavExampleComponent {
+  protected readonly links: readonly { path: string; label: string }[] = [
+    { path: '/components/tabs', label: 'Tabs' },
+    { path: '/components/tab-bar', label: 'Tab bar' },
+    { path: '/components/stack-outlet', label: 'Stack outlet' },
+  ];
+}
+```
 
 ## Theming
 
@@ -331,6 +365,12 @@ content to the top.
 
 ## Migration notes
 
+### 0.3.1
+
+The `## Desktop` docs name the desktop replacement: a `bf-top-nav` or `bf-sidebar` of
+`a[bfNavItem]` links with `routerLinkActive` and `ariaCurrentWhenActive="page"`, driven by the
+same destinations array as the shell's `bf-tab-bar`, with an example. No code change.
+
 ### 0.3.0
 
 **Breaking:** (ARIA contract) `bf-tabs` provides `BF_TAB_LINKS`, so the `bf-tab-bar` projected