@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/table.md

@@ -0,0 +1,697 @@
+# 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`. With `stack` it
+renders each row as a tile of label/value pairs in a narrow space or under touch.
+
+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, or let the table stack its rows into tiles with `stack` (see Stacked rows). 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.
+
+## Stacked rows
+
+`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 of every sortable column, ascending and descending (`tableSortBy`, `tableSortAscending`, `tableSortDescending` labels), since the hidden header's buttons are not shown. Choosing an option sets `sort`, as a header click does.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfBadgeComponent,
+  BfSegmentedComponent,
+  BfTableCellDirective,
+  BfTableComponent,
+  type BfSegmentOption,
+  type BfTableColumn,
+  type BfTableSort,
+} from '@bitforgehq/ui';
+
+interface Task {
+  id: string;
+  title: string;
+  project: string;
+  status: 'Open' | 'Done';
+  hours: number;
+}
+
+const TASKS: readonly Task[] = [
+  { id: 'brief', title: 'Write the brief', project: 'Atlas', status: 'Done', hours: 3 },
+  { id: 'moodboard', title: 'Bloom moodboard', project: 'Bloom', status: 'Open', hours: 6 },
+  { id: 'deck', title: 'Pitch deck', project: 'Atlas', status: 'Open', hours: 9 },
+];
+
+type Width = 'phone' | 'full';
+
+/**
+ * Stacked rows on a narrow table.
+ *
+ * `stack="narrow"` turns each row into a tile of label/value pairs while the table is narrower
+ * 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. Switch the box between phone width and full width.
+ */
+@Component({
+  selector: 'app-example-table-stacked',
+  imports: [BfTableComponent, BfTableCellDirective, BfBadgeComponent, BfSegmentedComponent],
+  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">
+      <bf-segmented label="Box width" [options]="widths" [(value)]="width" />
+      <div [class]="width() === 'phone' ? 'w-full max-w-sm' : 'w-full'">
+        <bf-table
+          label="Stacked tasks"
+          stack="narrow"
+          selectable
+          [rows]="rows()"
+          [columns]="columns"
+          [(sort)]="sort"
+          [(selection)]="selection"
+        >
+          <ng-template bfTableCell="status" [bfTableCellOf]="rows()" let-task>
+            <bf-badge [variant]="task.status === 'Done' ? 'success' : 'neutral'">
+              {{ task.status }}
+            </bf-badge>
+          </ng-template>
+        </bf-table>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TableStackedExampleComponent {
+  readonly widths: BfSegmentOption<Width>[] = [
+    { value: 'phone', label: 'Phone' },
+    { value: 'full', label: 'Full width' },
+  ];
+  readonly width = signal<Width | null>('phone');
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Task', sortable: true },
+    { key: 'project', label: 'Project' },
+    { key: 'status', label: 'Status' },
+    { key: 'hours', label: 'Hours', sortable: true, align: 'end' },
+  ];
+  readonly sort = signal<BfTableSort | null>(null);
+  readonly selection = signal<readonly string[]>([]);
+
+  /** The table never sorts: the page sorts its rows from `sort`. */
+  readonly rows = computed(() => {
+    const sort = this.sort();
+    if (!sort) {
+      return TASKS;
+    }
+    const factor = sort.direction === 'ascending' ? 1 : -1;
+    return [...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.`;
+  });
+}
+```
+
+## Narrow screens and touch
+
+A table needs width. When stacked tiles are not what a phone should show (long records, a summary per row), render the same rows as a divided `bf-list` of `bf-list-item`s below the `md` breakpoint (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, or a table with `stack="coarse"`. 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`.
+- Stacked rows: tiles on `surface-sunken` with `rounded-tile`, labels `text-label-xs` bold in `text-muted`.
+- 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.
+
+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) / ""`), so a screen reader reads the column header once, not the label as well.
+
+### 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                                                                                                                                                 |
+
+A stacked table's Sort by select is a native select with its own keys.
+
+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). |
+| `stack`          | `BfTableStack` (`'never' \| 'narrow' \| 'coarse'`)          | `'never'`   | When the rows render as cards of label/value pairs: `never`, `narrow` (the table is narrower than 36rem) or `coarse` (under a coarse pointer, at any width).                |
+| `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.
+- 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`.
+
+### Don't
+
+- Don't put a table on a phone screen that scrolls sideways; stack it or use the list.
+- Don't put a stacking table in a parent that sizes it from its content: the container query needs a width from outside.
+- Don't make a whole row clickable; put a link or button in a custom cell.
+
+## Migration notes
+
+### 0.3.2
+
+New opt-in `stack` input (`BfTableStack`: `'never'` by default, so existing tables do not
+change, `'narrow'` or `'coarse'`): while the table is narrower than 36rem (a container query on
+the host, which then gets `@container`) or, for `'coarse'`, under a coarse pointer at any width,
+each body row renders as a sunken tile of label/value pairs. The markup stays a `table` with
+explicit `table`, `rowgroup`, `row`, `columnheader` and `cell` roles (some browsers drop a
+table's semantics once its display changes), the header row is visually hidden but still read,
+the selection checkbox and the first cell head each tile, and every other cell shows its column
+label (`data-label`, a `::before` with empty alternative text, so it is not read twice). A bar
+above the tiles holds a labelled Select all checkbox and a Sort by `bf-select`, since the hidden
+header's controls are not shown. New label keys `tableSortBy` ("Sort by"), `tableSortAscending`
+and `tableSortDescending` (`"Hours, ascending"`). `BfTableHarness` reads and drives a stacked
+table the same way. New `table/stacked` example and a Stacked rows docs section.
+
+### 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.