@bitforgehq/ui 0.3.1 → 0.3.2

package/ai/components/stat.md

@@ -61,7 +61,7 @@ Use `bf-stat` for a few headline figures the reader should take in at a glance,
 
 ## Cards
 
-`variant="card"` gives each stat its own outlined tile, the `flat` card surface. In a grid the cards stretch to the row's height, so a row of stats lines up even when one has a supporting line and another has none. Put an icon in the `icon` slot (`bfSlot="icon"`, a `bf-icon`) to show what the figure is about.
+`variant="card"` gives each stat its own outlined tile, the `flat` card surface, for stats that sit on the page itself; inside a raised card use `tile` instead. In a grid the cards stretch to the row's height, so a row of stats lines up even when one has a supporting line and another has none. Put an icon in the `icon` slot (`bfSlot="icon"`, a `bf-icon`) to show what the figure is about.
 
 ```ts
 import { Component } from '@angular/core';
@@ -103,6 +103,60 @@ export class StatOverviewExampleComponent {
 }
 ```
 
+## Tiles
+
+`variant="tile"` is a sunken, borderless tile (`surface-sunken`, the `card` radius and padding) for a row of stats inside a raised [bf-card](https://bitforge-ui.web.app/components/card): a raised card holds sunken tiles, never outlined ones. On a tile the icon tile turns `surface`, so it still shows. Keep one surface style per level of a dashboard: raised cards on the page, tiles in each card.
+
+```ts
+import { Component } from '@angular/core';
+import { BfCardComponent, BfStatComponent } from '@bitforgehq/ui';
+
+/**
+ * A dashboard with one surface per level.
+ *
+ * The page holds raised cards, and every card holds sunken stat tiles: each level has one surface
+ * style, so the eye reads the cards as the groups and the tiles as their figures.
+ */
+@Component({
+  selector: 'app-example-stat-dashboard',
+  imports: [BfCardComponent, BfStatComponent],
+  template: `
+    <div class="grid gap-4 @lg:grid-cols-2">
+      <bf-card>
+        <h3 class="text-heading">Sales</h3>
+        <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+          <bf-stat label="Revenue" value="€48,200" variant="tile" delta="+12%" trend="up">
+            vs. last month
+          </bf-stat>
+          <bf-stat label="Orders" value="1,204" variant="tile" delta="+3%" trend="up">
+            vs. last month
+          </bf-stat>
+        </div>
+      </bf-card>
+      <bf-card>
+        <h3 class="text-heading">Support</h3>
+        <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+          <bf-stat
+            label="Open tickets"
+            value="18"
+            variant="tile"
+            delta="-4"
+            trend="down"
+            trendIntent="negative"
+          >
+            vs. last week
+          </bf-stat>
+          <bf-stat label="First reply" value="2 h" variant="tile" delta="0" trend="flat">
+            vs. last week
+          </bf-stat>
+        </div>
+      </bf-card>
+    </div>
+  `,
+})
+export class StatDashboardExampleComponent {}
+```
+
 ## Plain
 
 `variant="plain"` (the default) draws no surface, for stats that sit on a card or a page section of their own. The default slot is the supporting line under the value: a short trend ("+12% this week") or a `bf-badge`.
@@ -182,8 +236,9 @@ A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size
 - Label (`dt`): `text-caption` in `text-muted`. Value (`dd`): `text-title` in `text`, with tabular figures (`tabular-nums`) so numbers line up across stats.
 - Supporting line: `text-caption` in `text-muted`.
 - Delta pill: the badge's label shape (`control` radius, `text-micro` bold, tabular figures); good changes `success-soft` with `success` text, bad ones `danger-soft` with `danger` text, flat or no trend `neutral-soft` with `neutral` text. The arrow mark is drawn with borders in `currentColor`, so it takes the pill's text colour.
-- Icon tile: `surface-sunken` background, `text-muted` icon, `tile` radius, 40 px.
+- Icon tile: `surface-sunken` background (`surface` on a `tile` stat), `text-muted` icon, `tile` radius, 40 px.
 - `card`: `surface`, the `card` radius, `--spacing-card` padding (`p-card`) and a 1.5 px `border-strong` edge, as the `flat` `bf-card`.
+- `tile`: `surface-sunken`, the `card` radius and `--spacing-card` padding, no border.
 
 ## Accessibility
 
@@ -191,14 +246,14 @@ A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size
 
 ## Inputs
 
-| Name          | Type                                                                 | Default      | Description                                                                              |
-| ------------- | -------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------- |
-| `label`       | `string`                                                             | required     | What the figure measures, shown above it.                                                |
-| `value`       | `string`                                                             | required     | The figure, already formatted (`45 min`, `1,204`, `98%`).                                |
-| `variant`     | `BfStatVariant` (`'plain' \| 'card'`)                                | `'plain'`    | Surface: plain (default) on its container, or card, an outlined tile of its own.         |
-| `delta`       | `string`                                                             | `''`         | A change shown in a pill beside the value, already formatted (`+12%`); empty shows none. |
-| `trend`       | `BfStatTrend \| undefined` (`'up' \| 'down' \| 'flat' \| undefined`) | `undefined`  | The delta's direction: an arrow mark and a hidden word; left unset, the pill is neutral. |
-| `trendIntent` | `BfStatTrendIntent` (`'positive' \| 'negative'`)                     | `'positive'` | Whether up is good (positive, default) or down is good (negative, such as costs).        |
+| Name          | Type                                                                 | Default      | Description                                                                                     |
+| ------------- | -------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| `label`       | `string`                                                             | required     | What the figure measures, shown above it.                                                       |
+| `value`       | `string`                                                             | required     | The figure, already formatted (`45 min`, `1,204`, `98%`).                                       |
+| `variant`     | `BfStatAppearance` (`'plain' \| 'card' \| 'tile'`)                   | `'plain'`    | Surface: plain (default) on its container, card (an outlined tile) or tile (sunken, no border). |
+| `delta`       | `string`                                                             | `''`         | A change shown in a pill beside the value, already formatted (`+12%`); empty shows none.        |
+| `trend`       | `BfStatTrend \| undefined` (`'up' \| 'down' \| 'flat' \| undefined`) | `undefined`  | The delta's direction: an arrow mark and a hidden word; left unset, the pill is neutral.        |
+| `trendIntent` | `BfStatTrendIntent` (`'positive' \| 'negative'`)                     | `'positive'` | Whether up is good (positive, default) or down is good (negative, such as costs).               |
 
 ## Slots
 
@@ -215,12 +270,21 @@ A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size
 
 ### Don't
 
+- Don't put `card` stats (outlined) inside a raised `bf-card`; use `tile`.
 - Don't use a stat for a value the user edits or acts on; give it its own control.
 - Don't put long text in `value`; it is set at the `title` size for a short figure.
 - Don't put the comparison period in `delta`; keep it to the change (`+12%`) and say "vs. last month" in the supporting line.
 
 ## Migration notes
 
+### 0.3.2
+
+New `variant="tile"`: a sunken, borderless tile (`surface-sunken`, the `card` radius and
+padding) for a row of stats inside a raised `bf-card`; on it the icon tile turns `surface`.
+`variant` now takes the new named type `BfStatAppearance` (`BfStatVariant | 'tile'`); the
+released `BfStatVariant` keeps its two members, so `Record`s over it keep compiling. New
+`stat/dashboard` example with one surface per level.
+
 ### 0.3.1
 
 New: `bf-stat`, one labelled figure in its own `dl`, with the value at the `title` size in

package/ai/components/table.md

@@ -103,13 +103,14 @@ export class TableOverviewExampleComponent {
 
 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`.
+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. 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.
+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
 
@@ -400,9 +401,115 @@ export class TablePagedExampleComponent {
 
 `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. 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.
+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';
@@ -471,6 +578,7 @@ A selectable table tints a row `surface-muted` while hovered (a selected row `pr
 - 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.
@@ -479,6 +587,8 @@ Put the table on a `bf-card` (or another surface) yourself; it has no background
 
 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                                                                                                                                                                      |
@@ -489,6 +599,8 @@ A native `table` with a visually hidden `caption` from `label`, `th scope="col"`
 | <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
@@ -502,6 +614,7 @@ Text fields, selects and composite widgets (radios, comboboxes, sliders) in a ce
 | `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)]`.                                                                                       |
 
@@ -542,15 +655,31 @@ Selects or clears one row.
 
 - 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.
+- 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; use the list.
+- 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

package/ai/components/tabs.md

@@ -194,7 +194,7 @@ 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 [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.
+`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). Wrap the desktop app in a [bf-app-frame](https://bitforge-ui.web.app/components/app-frame): it holds the sidebar from `md` up and, below it, a header bar with that menu button. Inside the shell under a mouse, the tab links take the `bf-tab` hover and focus styles.
 
 ```ts
 import { Component } from '@angular/core';
@@ -365,6 +365,10 @@ content to the top.
 
 ## Migration notes
 
+### 0.3.2
+
+The `## Desktop` docs point at `bf-app-frame` for the frame around the desktop navigation.
+
 ### 0.3.1
 
 The `## Desktop` docs name the desktop replacement: a `bf-top-nav` or `bf-sidebar` of

package/ai/components/toolbar.md

@@ -187,7 +187,7 @@ export class ToolbarStatusExampleComponent {
 
 ## Wrapping
 
-The row is a wrapping flex row with an 8 px gap between items and between rows. In a narrow column the filters wrap onto new rows, and the actions wrap as one group, kept together at the inline end. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
+The row is a wrapping flex row with an 8 px gap between items and between rows. The status and the actions are one group that takes the rest of the last row: on a wide row the status follows the view switch and the actions sit at the inline end; when the group no longer fits beside the filters, it wraps onto a row of its own as a whole, with the status at the start and the actions at the end. So the actions never end up alone on a row, and they stay on the last filter row whenever the group fits there. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
 
 ```ts
 import { Component } from '@angular/core';
@@ -202,8 +202,8 @@ import {
 /**
  * A toolbar that wraps.
  *
- * In a narrow column the filters wrap onto new rows 8 px apart, and the actions move down
- * together, still at the inline end.
+ * In a narrow column the filters wrap onto new rows 8 px apart, and the status and the actions
+ * move down together: the count at the start of the last row, the actions at the inline end.
  */
 @Component({
   selector: 'app-example-toolbar-wrapping',
@@ -232,6 +232,63 @@ export class ToolbarWrappingExampleComponent {
 }
 ```
 
+## Phone width
+
+At phone width (in a desktop web app's narrow window or a narrow column) the search takes a row, the filters share the next, and the status and actions share the last row. A toolbar without actions keeps the status as a plain item after the filters.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+/**
+ * A toolbar at phone width.
+ *
+ * In a phone-wide column the search fills its own row, the two filters share the next one, and
+ * the status and the Refresh action share the last row: the count at the start, the action at the
+ * end, never alone on a row of its own.
+ */
+@Component({
+  selector: 'app-example-toolbar-narrow',
+  imports: [BfButtonComponent, BfInputComponent, BfSelectComponent, BfToolbarComponent],
+  template: `
+    <div class="max-w-xs">
+      <bf-toolbar label="Order filters" [status]="count()">
+        <bf-input
+          type="search"
+          ariaLabel="Search orders"
+          placeholder="Search orders"
+          class="w-full"
+        />
+        <bf-select ariaLabel="Status" [options]="statuses" value="open" />
+        <bf-select ariaLabel="Period" [options]="periods" value="week" />
+        <bf-button bfSlot="actions" variant="outline" (clicked)="refresh()">Refresh</bf-button>
+      </bf-toolbar>
+    </div>
+  `,
+})
+export class ToolbarNarrowExampleComponent {
+  protected readonly count = signal('12 orders');
+  protected readonly statuses: BfSelectOption[] = [
+    { value: 'open', label: 'Open' },
+    { value: 'shipped', label: 'Shipped' },
+  ];
+  protected readonly periods: BfSelectOption[] = [
+    { value: 'week', label: 'This week' },
+    { value: 'month', label: 'This month' },
+  ];
+
+  protected refresh(): void {
+    this.count.set('12 orders, updated');
+  }
+}
+```
+
 ## Desktop
 
 `bf-toolbar` is a desktop pattern. Every control and field projected into it resolves its unset `size` to `sm` (32 px tall), because its `providers` set `provideBfDefaults({ size: 'sm' })` for its content; a control that sets `size` itself keeps it, and nothing outside the toolbar changes ([density guide](https://bitforge-ui.web.app/density)). Hover, the pointer cursor and the `focus-visible` ring come from each control; the row adds none of its own. Under a fine pointer each control's visual box is its hit area; under a coarse pointer the `sm` touch extensions reach up to 7.5 px past the visual edge, which the 8 px gap keeps off the neighbouring row.
@@ -262,7 +319,7 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 - `default`: The search field and the filters (bf-input, bf-select, bf-chip-group), in order.
 - `view`: A view switch after the filters, such as a bf-segmented of list and grid.
-- `actions`: The trailing actions, kept together at the inline end of the row.
+- `actions`: The trailing actions, kept together at the inline end of the row, beside the status.
 
 ## Notes
 
@@ -278,6 +335,14 @@ The `status` element is `role="status"` (an `aria-live="polite"` region), always
 
 ## Migration notes
 
+### 0.3.2
+
+On a narrow row the actions no longer end up alone on a row of their own: the status and the
+actions are now one group that takes the rest of the last row and wraps as a whole, with the
+status at the start and the actions at the inline end. The wide layout is unchanged, and a
+toolbar without actions keeps the status as a plain item of the row. New `toolbar/narrow`
+example at phone width.
+
 ### 0.3.1
 
 New `bf-toolbar` in `@bitforgehq/ui`: a wrapping `role="group"` row for the search field and

package/ai/reference/bf-app-frame-breakpoint.md

@@ -0,0 +1,27 @@
+# BfAppFrameBreakpoint
+
+The breakpoint where an app frame switches from its header bar to the sidebar
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The viewport width from which `bf-app-frame` shows its sidebar column instead of the narrow
+header bar: Tailwind's `md` (768 px) or `lg` (1024 px).
+
+```ts
+import { type BfAppFrameBreakpoint } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameBreakpoint = 'md' | 'lg'
+```
+
+## Values
+
+- `md`
+- `lg`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)

package/ai/reference/bf-app-frame-content-width.md

@@ -0,0 +1,29 @@
+# BfAppFrameContentWidth
+
+The maximum width of an app frame's content column, from medium to full
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The maximum width of `bf-app-frame`'s content column: `md` 48rem, `lg` 64rem, `xl` 80rem, or
+`full` for no limit.
+
+```ts
+import { type BfAppFrameContentWidth } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfAppFrameContentWidth = 'md' | 'lg' | 'xl' | 'full'
+```
+
+## Values
+
+- `md`
+- `lg`
+- `xl`
+- `full`
+
+## Used by
+
+- [bf-app-frame](../components/app-frame.md)

package/ai/reference/bf-empty-state-heading-level.md

@@ -23,4 +23,4 @@ type BfEmptyStateHeadingLevel = 2 | 3
 
 ## Used by
 
-- [bf-empty-state](../components/empty-state.md)
+- [BfEmptyStateHeading](bf-empty-state-heading.md)

package/ai/reference/bf-empty-state-heading.md

@@ -0,0 +1,33 @@
+# BfEmptyStateHeading
+
+The heading level of an empty state title, one for a whole page
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The heading level a `bf-empty-state` title takes: a `BfEmptyStateHeadingLevel`, or `1` when the
+empty state is the page itself (a not-found or no-access page). A new type, so `Record`s over
+the released `BfEmptyStateHeadingLevel` keep compiling.
+
+```ts
+import { type BfEmptyStateHeading } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfEmptyStateHeading = BfEmptyStateHeadingLevel | 1
+```
+
+## Values
+
+- `2`
+- `3`
+- `1`
+
+## Uses
+
+- [BfEmptyStateHeadingLevel](bf-empty-state-heading-level.md)
+
+## Used by
+
+- [bf-empty-state](../components/empty-state.md)

package/ai/reference/bf-labels.md

@@ -32,6 +32,9 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `dialog`                | `string`                                      | `'Dialog'`                                                                       | A dialog's or side panel's name without an ariaLabel, a title or a heading.                                    |
 | `notifications`         | `string`                                      | `'Notifications'`                                                                | The desktop toast stack's region name.                                                                         |
 | `tableSelectAll`        | `string`                                      | `'Select all rows'`                                                              | bf-table's header checkbox, which selects or clears every row.                                                 |
+| `tableSortBy`           | `string`                                      | `'Sort by'`                                                                      | The label of a stacked bf-table's sort select.                                                                 |
+| `tableSortAscending`    | `(column: string) => string`                  | `` (column) => `${column}, ascending` ``                                         | A stacked bf-table's sort option for a column in ascending order.                                              |
+| `tableSortDescending`   | `(column: string) => string`                  | `` (column) => `${column}, descending` ``                                        | A stacked bf-table's sort option for a column in descending order.                                             |
 | `theme`                 | `string`                                      | `'Theme'`                                                                        | bf-theme-switch's and bf-theme-menu-button's name without a label.                                             |
 | `themeSystem`           | `string`                                      | `'System'`                                                                       | The theme choice that follows the system's colour scheme.                                                      |
 | `themeLight`            | `string`                                      | `'Light'`                                                                        | The theme choice that forces the light colour scheme.                                                          |
@@ -40,6 +43,9 @@ import { type BfLabels } from '@bitforgehq/ui';
 | `breadcrumbExpand`      | `(count: number) => string`                   | ``(count) => (count === 1 ? 'Show 1 more level' : `Show ${count} more levels`)`` | bf-breadcrumb's ellipsis button, which shows the levels a `maxItems` trail hides.                              |
 | `navigation`            | `string`                                      | `'Main'`                                                                         | bf-sidebar's and bf-top-nav's navigation name.                                                                 |
 | `navBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                  | a[bfNavItem]'s announcement of its count badge.                                                                |
+| `sidebarCollapse`       | `string`                                      | `'Collapse sidebar'`                                                             | bf-sidebar-toggle's name and tooltip while the sidebar is expanded.                                            |
+| `sidebarExpand`         | `string`                                      | `'Expand sidebar'`                                                               | bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail.                                        |
+| `skipToContent`         | `string`                                      | `'Skip to main content'`                                                         | bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content.                   |
 | `pagination`            | `string`                                      | `'Pagination'`                                                                   | bf-pagination's navigation name.                                                                               |
 | `previousPage`          | `string`                                      | `'Previous page'`                                                                | bf-pagination's button to the previous page.                                                                   |
 | `nextPage`              | `string`                                      | `'Next page'`                                                                    | bf-pagination's button to the next page.                                                                       |

package/ai/reference/bf-sidebar-state-service.md

@@ -0,0 +1,21 @@
+# BfSidebarStateService
+
+The sidebar's collapsed state, kept in storage between visits of the app
+
+Service from `@bitforgehq/ui` · since 0.3.2
+
+Whether the app's `bf-sidebar` is collapsed to an icon rail, remembered between visits: the app
+binds the sidebar's `[(collapsed)]` to `sidebarState.collapsed`. With `provideBfSidebarState()`
+every change is stored in `BF_SIDEBAR_STATE_STORAGE` under `bf-sidebar-collapsed`; without it
+the signal still holds the state but nothing is written. Storage is read in the browser only, so a
+server render starts expanded and writes nothing. The widgets never inject it.
+
+```ts
+import { BfSidebarStateService } from '@bitforgehq/ui';
+```
+
+## Properties
+
+| Name        | Type                      | Default | Description                                                                                                                   |
+| ----------- | ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `collapsed` | `WritableSignal<boolean>` |         | Whether the sidebar is collapsed: the stored state in the browser, else false. Bind it two-way to `bf-sidebar`'s `collapsed`. |

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

@@ -0,0 +1,32 @@
+# BfSidebarToggleHarness
+
+Test harness for a sidebar toggle: reads and flips the collapsed sidebar
+
+Class from `@bitforgehq/ui/testing` · since 0.3.2
+
+Harness for `bf-sidebar-toggle`, the button that collapses a `bf-sidebar` to an icon rail. Its
+`label` filter matches the button's name ("Collapse sidebar" or "Expand sidebar").
+
+```ts
+import { BfSidebarToggleHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfSidebarToggleHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The button's name, which says what the next press does.
+
+### `isExpanded(): Promise<boolean>`
+
+Whether the sidebar is at full width (`aria-expanded`).
+
+### `toggle(): Promise<void>`
+
+Flips the sidebar with a click.