@bitforgehq/ui 0.3.1 → 0.3.3

package/ai/components/sidebar.md

@@ -141,9 +141,9 @@ export class SidebarOverviewExampleComponent {
 
 The vertical navigation of a desktop app: a `nav` landmark with a `header` slot (the brand),
 the destinations (`a[bfNavItem]` links, optionally in `bf-nav-group`s) and a `footer` slot.
-`collapsed` turns it into an icon rail; the consumer owns the toggle button and binds
-`[(collapsed)]`. Below a breakpoint hide it (`class="hidden md:flex"`) and drive a
-`bf-menu-button` from the same routes.
+`collapsed` turns it into an icon rail: put a `bf-sidebar-toggle` (`@bitforgehq/ui/overlay`) in
+it, or bind `[(collapsed)]` to your own button. Below a breakpoint hide it
+(`class="hidden md:flex"`) and drive a `bf-menu-button` from the same routes.
 
 The vertical navigation of a desktop web app: a `nav` landmark down the inline-start edge with a `header` slot for the brand, the destinations as [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links (optionally in titled [`bf-nav-group`](https://bitforge-ui.web.app/components/nav-group)s) and a `footer` slot for settings or the account. `collapsed` turns it into an icon rail. Its horizontal sibling for apps with few sections is [`bf-top-nav`](https://bitforge-ui.web.app/components/top-nav); both share the same item, so the current page, the badge and the focus ring look the same in either.
 
@@ -157,11 +157,178 @@ Put `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActiv
 
 ## Collapsing to an icon rail
 
-`collapsed` is a model: bind `[(collapsed)]` to your own toggle button, such as a text `bf-icon-button` in the header whose label says what the next press does ("Collapse sidebar", "Expand sidebar"). The widget has no toggle of its own, because the button needs an icon and a widget never imports one. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+`collapsed` is a model. Put a [`bf-sidebar-toggle`](https://bitforge-ui.web.app/components/sidebar-toggle) (`@bitforgehq/ui/overlay`) in the header or footer: it flips the model, names itself by what the next press does ("Collapse sidebar", "Expand sidebar") and takes its two icons as slots, since a widget never imports one. Bind `[(collapsed)]` to keep the state in your own signal, or bind it to your own button outside the sidebar. Collapsed, every item shows only its icon, centred in a square; its label stays in the DOM as screen-reader text, so its accessible name does not change, and becomes the link's `title`, the tooltip a pointer user sees on hover. A count badge becomes a small dot that is still announced, and the group headings are hidden visually but still name their groups. The width follows the rail (`w-auto`); expanded the sidebar is `w-60` (240 px).
+
+## Remember the collapsed sidebar
+
+`BfSidebarStateService` (from `@bitforgehq/ui`) holds a `collapsed` signal: bind the sidebar's `[(collapsed)]` to it (`sidebarState.collapsed`) and add `provideBfSidebarState()` to the app's providers, and every change is stored under `bf-sidebar-collapsed` (`localStorage` in the browser, `BF_SIDEBAR_STATE_STORAGE` to keep it elsewhere) and read back at the next start, so the app opens as the user left it. Without the provider the signal still holds the state but nothing is stored; on the server it starts expanded and reads nothing. The widget itself injects no service.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { RouterLink, RouterLinkActive, RouterOutlet } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent, BfSidebarStateService } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent } from '@bitforgehq/ui/overlay';
+import { Inbox, PanelLeftClose, PanelLeftOpen } from 'lucide';
+
+/**
+ * A sidebar that opens collapsed or expanded, as the user left it.
+ *
+ * `[(collapsed)]` binds `BfSidebarStateService.collapsed`; with `provideBfSidebarState()` in the
+ * app's providers every change is stored under `bf-sidebar-collapsed` (`localStorage` in the
+ * browser) and read back at the next start.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-sidebar-remembered',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    RouterOutlet,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+  ],
+  template: `
+    <div class="flex min-h-dvh">
+      <bf-sidebar [(collapsed)]="sidebarState.collapsed" class="sticky top-0 h-dvh">
+        <a bfNavItem routerLink="/inbox" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Inbox
+        </a>
+        <bf-sidebar-toggle bfSlot="footer">
+          <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+          <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+        </bf-sidebar-toggle>
+      </bf-sidebar>
+      <main class="min-w-0 flex-1 p-6"><router-outlet /></main>
+    </div>
+  `,
+})
+export class SidebarRememberedExampleComponent {
+  // app.config.ts: providers: [provideBfSidebarState()]
+  protected readonly sidebarState = inject(BfSidebarStateService);
+  protected readonly inbox = Inbox;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
+
+## Footer
+
+The footer slot takes several elements, stacked with a 4 px gap: a Settings link as an `a[bfNavItem]`, a row holding an icon-only text [`bf-theme-menu-button`](https://bitforge-ui.web.app/components/theme-menu-button) and the `bf-sidebar-toggle`, and an optional version line in `text-caption text-text-muted`. Expanded, the row puts the two buttons at either end (`flex items-center justify-between`). As an icon rail every footer element is centred: switch the row to a column (`flex flex-col items-center gap-1`) so both buttons fit the rail, and hide the version line (`[class.hidden]="collapsed()"`), which has no icon to shrink to. Open the theme menu upwards (`placement="above-start"`), since the footer sits at the bottom of the screen.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { type BfColorScheme, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfSidebarToggleComponent, BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import {
+  Inbox,
+  type IconNode,
+  Moon,
+  PanelLeftClose,
+  PanelLeftOpen,
+  Settings,
+  Sun,
+  SunMoon,
+  Users,
+} from 'lucide';
+
+interface NavLink {
+  readonly path: string;
+  readonly label: string;
+  readonly icon: IconNode;
+}
+
+/**
+ * A sidebar footer: settings, theme, toggle and version.
+ *
+ * The footer slot holds a Settings link (`a[bfNavItem]`), a row with an icon-only
+ * `bf-theme-menu-button` and the `bf-sidebar-toggle`, and a version line. Expanded, the two
+ * buttons sit at either end of the row; as an icon rail the row stacks vertically and the version
+ * line hides. The theme binds a local signal so the docs site keeps its theme; an app binds
+ * `BfColorSchemeService.scheme`.
+ */
+@Component({
+  selector: 'app-example-sidebar-footer',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+    BfSidebarToggleComponent,
+    BfThemeMenuButtonComponent,
+  ],
+  template: `
+    <div class="border-border bg-bg rounded-card flex h-[26rem] overflow-hidden border">
+      <bf-sidebar label="Footer demo" [(collapsed)]="collapsed">
+        @for (link of links; track link.path) {
+          <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">
+            <bf-icon bfSlot="icon" [icon]="link.icon" />
+            {{ link.label }}
+          </a>
+        }
+        <a
+          bfSlot="footer"
+          bfNavItem
+          routerLink="/theming"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="settings" />
+          Settings
+        </a>
+        <div bfSlot="footer" [class]="rowClasses()">
+          <bf-theme-menu-button iconOnly variant="text" placement="above-start" [(value)]="scheme">
+            <bf-icon bfSlot="icon" [icon]="themeIcon()" />
+          </bf-theme-menu-button>
+          <bf-sidebar-toggle>
+            <bf-icon bfSlot="collapse-icon" [icon]="panelClose" />
+            <bf-icon bfSlot="expand-icon" [icon]="panelOpen" />
+          </bf-sidebar-toggle>
+        </div>
+        <p bfSlot="footer" class="text-caption text-text-muted ps-3" [class.hidden]="collapsed()">
+          Version 0.3.2
+        </p>
+      </bf-sidebar>
+      <div class="min-w-0 flex-1 p-4">
+        <p data-status aria-live="polite" class="text-caption text-text-muted wrap-anywhere">
+          {{ collapsed() ? 'Icon rail' : 'Expanded' }}, theme {{ scheme() }}.
+        </p>
+      </div>
+    </div>
+  `,
+})
+export class SidebarFooterExampleComponent {
+  readonly collapsed = signal(false);
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+
+  /** Expanded: one row, the buttons at either end. Collapsed: a column in the rail. */
+  protected readonly rowClasses = computed(() =>
+    this.collapsed() ? 'flex flex-col items-center gap-1' : 'flex items-center justify-between',
+  );
+  protected readonly themeIcon = computed(
+    () => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()],
+  );
+  protected readonly links: readonly NavLink[] = [
+    { path: '/components/nav-item', label: 'Inbox', icon: Inbox },
+    { path: '/components/nav-group', label: 'Team', icon: Users },
+  ];
+  protected readonly settings = Settings;
+  protected readonly panelOpen = PanelLeftOpen;
+  protected readonly panelClose = PanelLeftClose;
+}
+```
 
 ## Responsive layouts
 
-Below a breakpoint the sidebar does not turn itself into a menu: a root widget cannot render `bf-menu`. Keep one array of destinations (ideally derived from your route config) and drive every surface from it: the sidebar from `md` up (`class="hidden md:flex"` on `bf-sidebar`; its own `flex` loses to your `hidden`), and below it a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` router links (`class="md:hidden"`, from `@bitforgehq/ui/overlay`). Each surface keeps the router's `routerLinkActive`.
+Below a breakpoint the sidebar does not turn itself into a menu: a root widget cannot render `bf-menu`. Keep one array of destinations (ideally derived from your route config) and drive every surface from it: the sidebar from `md` up (`class="hidden md:flex"` on `bf-sidebar`; its own `flex` loses to your `hidden`), and below it a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` router links (`class="md:hidden"`, from `@bitforgehq/ui/overlay`). Each surface keeps the router's `routerLinkActive`. [`bf-app-frame`](https://bitforge-ui.web.app/components/app-frame) does this layout for you: it shows the sidebar in a sticky column from the breakpoint up and the menu button in a header bar below it.
 
 ```ts
 import { Component } from '@angular/core';
@@ -319,7 +486,7 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 ## Accessibility
 
-`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. The consumer's toggle button is a native button; name it by what it does ("Collapse sidebar") or give it `aria-pressed`, and keep it in the sidebar or right before it.
+`bf-sidebar` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. The header, the destinations and the footer all sit inside it, in that DOM order. The current page is the link the router marks with `aria-current="page"`; the tonal fill is never the only cue under forced colours, where an outline marks it. Collapsing changes only what is visible: every item keeps its label as screen-reader text and each group its name, so the accessible names stay the same. `bf-sidebar-toggle` is a native button named by what it does ("Collapse sidebar"), with `aria-expanded` and `aria-controls` on the `nav`; your own toggle should do the same, and sit in the sidebar or right before it.
 
 ### Keyboard
 
@@ -330,10 +497,10 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 ## Inputs
 
-| Name        | Type      | Default | Description                                                                                                                                                                    |
-| ----------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `label`     | `string`  | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one.              |
-| `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail: items show their icon only, their label stays for screen readers and becomes a tooltip. Bind `[(collapsed)]` to your own toggle button. |
+| Name        | Type      | Default | Description                                                                                                                                                                                                          |
+| ----------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`  | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one.                                                    |
+| `collapsed` | `boolean` | `false` | Collapses the sidebar to an icon rail: items show their icon only, their label stays for screen readers and becomes a tooltip. A `bf-sidebar-toggle` inside flips it; bind `[(collapsed)]` to keep it in your state. |
 
 ## Slots
 
@@ -347,6 +514,7 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 - Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"` on every link.
 - Drive the sidebar, the small-screen menu and the shell's tab bar from one array of destinations.
+- Remember the collapsed state with `BfSidebarStateService` and `provideBfSidebarState()`.
 
 ### Don't
 
@@ -355,6 +523,16 @@ The sidebar is a desktop pattern. Its items take a `surface-muted` fill and the
 
 ## Migration notes
 
+### 0.3.2
+
+New `BfSidebarStateService` (a `collapsed` signal) and `provideBfSidebarState()` in
+`@bitforgehq/ui`: bind the sidebar's `[(collapsed)]` to `sidebarState.collapsed` and the provider
+stores every change under `bf-sidebar-collapsed` in `BF_SIDEBAR_STATE_STORAGE` (`localStorage` in
+the browser, memory elsewhere), read back at the next start; without the provider nothing is
+written, and on the server nothing is read. The sidebar's `nav` now has an id, for a toggle's
+`aria-controls`. The docs gain "Remember the collapsed sidebar" and a "Footer" composition
+(Settings link, theme menu, toggle, version line) that works expanded and as an icon rail.
+
 ### 0.3.1
 
 New `bf-sidebar`: the vertical navigation of a desktop app, a `nav` landmark with `header`,

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,116 @@ 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, since the hidden header's buttons are not shown. Its first option, Not sorted, shows while `sort` is null and sets it back to null; then every sortable column, ascending and descending (`tableSortBy`, `tableSortNone`, `tableSortAscending`, `tableSortDescending` labels). Choosing a column option sets `sort`, as a header click does. In a test, `BfTableHarness.getSortSelect()` returns that select's `BfSelectHarness`.
+
+```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, whose first option, Not sorted, shows while `sort` is
+ * null and clears it. 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 +579,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 +588,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) / ""`, the `content-data-label` utility of `theme.css`), so a screen reader reads the column header once, not the label as well.
+
 ### Keyboard
 
 | Key                                              | Action                                                                                                                                                                      |
@@ -489,6 +600,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 +615,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 +656,48 @@ 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.3
+
+Fix: stacked rows (`stack="narrow"` and `stack="coarse"`) show their column labels again when the
+package is installed from npm. 0.3.2 wrote the label as `content-[attr(data-label)_/_""]`; the
+library build escaped its quotes in the FESM (`\"\"`), so Tailwind built the rule for a class no
+cell carries and every label `::before` computed to `none`. The cells now carry
+`before:content-data-label`, a utility `theme.css` defines (below). Apps that added the
+workaround `@source inline('@max-xl:before:content-[attr(data-label)_/_""] pointer-coarse:before:content-[attr(data-label)_/_""]')`
+can remove it. consumer-smoke now opens a stacked table built from the packed package in
+Chromium, under a fine and a coarse pointer, and fails if any FESM class string holds a
+backslash escape.
+
+The stacked Sort by select's first option is Not sorted (new label key `tableSortNone`, "Not
+sorted"): it shows while `sort` is null, so the select is no longer an empty box, and choosing it
+sets `sort` back to null. New `BfTableHarness.getSortSelect()` returns that select's
+`BfSelectHarness` (`null` when the table cannot stack or has no sortable column).
+
+### 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