@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/sparkline.md

@@ -0,0 +1,188 @@
+# bf-sparkline
+
+Tiny trend line with no axes or legend, for stats and table cells
+
+`BfSparklineComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfStatComponent } from '@bitforgehq/ui';
+import { BfSparklineComponent } from '@bitforgehq/ui/charts';
+
+/**
+ * The bf-sparkline overview.
+ *
+ * Live demo of `bf-sparkline`: three stats with a 30-day trend in their supporting line, the
+ * trend also stated in words; the middle one fills its area.
+ */
+@Component({
+  selector: 'app-example-sparkline-overview',
+  imports: [BfStatComponent, BfSparklineComponent],
+  template: `
+    <div class="grid w-full grid-cols-[repeat(auto-fit,minmax(10rem,1fr))] gap-3">
+      <bf-stat label="Revenue" value="CHF 48.2k" variant="card">
+        <span class="flex flex-col gap-1">
+          <bf-sparkline [values]="revenue" />
+          Up 12% in 30 days
+        </span>
+      </bf-stat>
+      <bf-stat label="Sign-ups" value="1,204" variant="card">
+        <span class="flex flex-col gap-1">
+          <bf-sparkline area curve="smooth" [values]="signups" />
+          Up 4% in 30 days
+        </span>
+      </bf-stat>
+      <bf-stat label="Churn" value="2.1%" variant="card">
+        <span class="flex flex-col gap-1">
+          <bf-sparkline [values]="churn" />
+          Down 0.4 points in 30 days
+        </span>
+      </bf-stat>
+    </div>
+  `,
+})
+export class SparklineOverviewExampleComponent {
+  readonly revenue = [31, 34, 33, 36, 35, 39, 42, 41, 45, 48];
+  readonly signups = [980, 1010, 1060, 1040, 1100, 1120, 1150, 1170, 1190, 1204];
+  readonly churn = [2.6, 2.5, 2.6, 2.4, 2.4, 2.3, 2.3, 2.2, 2.2, 2.1];
+}
+```
+
+## Overview
+
+A tiny line of one series with no axes, legend or tooltip, for a trend beside a figure (in a
+`bf-stat`'s supporting line, a table cell). Its scale spans the values' own range, so it shows
+the shape of the trend, not its size; a dot marks the latest value. With a `label` it is an
+image with that name (say what the trend means, such as "Revenue up 12% over 30 days"); without
+one it is decorative and hidden from assistive technology. It draws in on the first render and
+on every data change, still under reduced motion; under `dir="rtl"` it runs from the right.
+
+A sparkline is a word-sized line of one series with no axes, legend or tooltip: the shape of a trend beside a figure. `bf-sparkline` draws it in SVG from `values`, oldest first, scaled to their own range, with a dot on the latest value. It lives in `@bitforgehq/ui/charts` (`import { BfSparklineComponent } from '@bitforgehq/ui/charts'`) and works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-sparkline` in a [bf-stat](https://bitforge-ui.web.app/components/stat)'s supporting line, a table cell or a list row, where the figure carries the number and the line only its direction. Use [bf-line-chart](https://bitforge-ui.web.app/components/line-chart) instead when readers need the values, the axis or more than one series.
+
+## Area and size
+
+`area` fills under the line; `curve="smooth"` draws a monotone curve. `height` sets the height in px (32 by default); the width follows the container, so give the element a width (`class="w-24"`) where it sits in a row. A flat series draws a level line in the middle, and a `null` value leaves a gap. The line draws in on the first render and whenever `values` change.
+
+```ts
+import { Component } from '@angular/core';
+import { BfSparklineComponent } from '@bitforgehq/ui/charts';
+
+interface Region {
+  readonly name: string;
+  readonly total: string;
+  readonly trend: readonly (number | null)[];
+  readonly summary: string;
+}
+
+/**
+ * Sparklines in a table.
+ *
+ * A fixed-width sparkline per row, each named for screen readers by what its trend means; a
+ * `null` leaves a gap where a week was not reported.
+ */
+@Component({
+  selector: 'app-example-sparkline-table',
+  imports: [BfSparklineComponent],
+  template: `
+    <table class="text-label-sm w-full text-start">
+      <caption class="sr-only">
+        Orders by region
+      </caption>
+      <thead>
+        <tr class="border-border border-b">
+          <th scope="col" class="text-label-xs text-text-muted h-8 px-3 text-start">Region</th>
+          <th scope="col" class="text-label-xs text-text-muted h-8 px-3 text-end">Orders</th>
+          <th scope="col" class="text-label-xs text-text-muted h-8 px-3 text-start">8 weeks</th>
+        </tr>
+      </thead>
+      <tbody>
+        @for (region of regions; track region.name) {
+          <tr class="border-divider border-b">
+            <th scope="row" class="text-text h-10 px-3 text-start font-bold">{{ region.name }}</th>
+            <td class="text-text h-10 px-3 text-end tabular-nums">{{ region.total }}</td>
+            <td class="h-10 px-3">
+              <bf-sparkline
+                class="w-24"
+                [height]="24"
+                [values]="region.trend"
+                [label]="region.summary"
+              />
+            </td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  `,
+})
+export class SparklineTableExampleComponent {
+  readonly regions: readonly Region[] = [
+    {
+      name: 'North',
+      total: '1,284',
+      trend: [120, 132, 128, 141, 150, 149, 162, 171],
+      summary: 'Rising',
+    },
+    {
+      name: 'Central',
+      total: '962',
+      trend: [131, 127, 119, null, 112, 118, 109, 104],
+      summary: 'Falling',
+    },
+    {
+      name: 'South',
+      total: '1,047',
+      trend: [128, 131, 126, 133, 129, 132, 130, 131],
+      summary: 'Steady',
+    },
+  ];
+}
+```
+
+## Desktop
+
+A sparkline is not interactive: no hover, no tooltip, no focus stop. Its size does not follow `provideBfDefaults()`. Inside `provideBfShell()` it renders the same.
+
+## Theming
+
+- Line: `--color-chart-1` (`stroke-chart-1`), 2 px; area the same at 16 % (`fill-chart-1/16`); the end dot `fill-chart-1`.
+- Motion: `--animate-chart-draw` and `--animate-chart-fade`; none under `prefers-reduced-motion`.
+
+## Accessibility
+
+With a `label` the SVG is a `role="img"` named by it: say what the trend means ("Revenue up 12% over 30 days"), not that it is a chart. Without one it is decorative and hidden from assistive technology, which is right beside a figure whose supporting text already states the trend. It has no focus stop and no data table; put the values in a table or a `bf-line-chart` when readers need them.
+
+## Inputs
+
+| Name     | Type                                    | Default    | Description                                                                                                    |
+| -------- | --------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| `values` | `readonly (number \| null)[]`           | required   | The values in order, oldest first; `null` leaves a gap.                                                        |
+| `label`  | `string`                                | `''`       | What the trend means, its accessible name ("Revenue up 12% this month"); empty makes the sparkline decorative. |
+| `height` | `number`                                | `32`       | Height in px; the width follows the container.                                                                 |
+| `area`   | `boolean`                               | `false`    | Fills the area under the line.                                                                                 |
+| `curve`  | `BfChartCurve` (`'linear' \| 'smooth'`) | `'linear'` | The line between points: `linear` (default) or `smooth`, a monotone curve.                                     |
+
+## Notes
+
+### Do
+
+- State the trend in words next to it (the stat's supporting line, a `+12%`), so it is never colour or shape alone.
+- Use the same time window for every sparkline in a row.
+
+### Don't
+
+- Don't compare sparklines' heights: each one is scaled to its own range.
+- Don't put a tooltip or a link on a sparkline; link the stat or the row instead.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-sparkline` in `@bitforgehq/ui/charts`: a tiny line of one series with no axes, legend or
+tooltip, for a `bf-stat`'s supporting line or a table cell; `area`, `curve` and `height`, a dot on
+the latest value. With a `label` it is a named image, without one it is decorative.

package/ai/components/stat.md

@@ -0,0 +1,233 @@
+# bf-stat
+
+One labelled figure with an optional icon tile and a supporting line
+
+`BfStatComponent` from `@bitforgehq/ui` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfStatComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Clock, CookingPot, Timer, Users } from 'lucide';
+
+/**
+ * The bf-stat overview.
+ *
+ * Live demo of `bf-stat`: a recipe's prep time, cook time, total time and servings as four card
+ * stats, each with an icon tile, wrapping from four across to two.
+ */
+@Component({
+  selector: 'app-example-stat-overview',
+  imports: [BfStatComponent, BfIconComponent],
+  template: `
+    <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+      <bf-stat label="Prep time" value="15 min" variant="card">
+        <bf-icon bfSlot="icon" [icon]="timer" />
+      </bf-stat>
+      <bf-stat label="Cook time" value="30 min" variant="card">
+        <bf-icon bfSlot="icon" [icon]="cookingPot" />
+      </bf-stat>
+      <bf-stat label="Total time" value="45 min" variant="card">
+        <bf-icon bfSlot="icon" [icon]="clock" />
+      </bf-stat>
+      <bf-stat label="Servings" value="4" variant="card">
+        <bf-icon bfSlot="icon" [icon]="users" />
+      </bf-stat>
+    </div>
+  `,
+})
+export class StatOverviewExampleComponent {
+  protected readonly timer = Timer;
+  protected readonly cookingPot = CookingPot;
+  protected readonly clock = Clock;
+  protected readonly users = Users;
+}
+```
+
+## Overview
+
+One figure with its label, such as a count, a duration or a total: a native `dl` pair with the
+value set large, an optional icon tile at the start and a supporting line under the value.
+
+A `delta` with a `trend` adds a pill beside the value, toned by `trendIntent`.
+
+A stat shows one figure with its label: a recipe's cook time, a project's open tasks, a month's revenue. The value is set large, an optional icon tile sits at the start, a supporting line under the value adds context such as a period or a badge, and an optional delta pill beside the value shows the change and its direction. `bf-stat` renders its own native `dl` with the label as the `dt` and the value as the `dd`. It works the same in both shells: in the Capacitor shell and in a desktop web app.
+
+## When to use
+
+Use `bf-stat` for a few headline figures the reader should take in at a glance, usually in a row or grid of them. Use [bf-description-list](https://bitforge-ui.web.app/components/description-list) instead for many details of one record, and [bf-card](https://bitforge-ui.web.app/components/card) instead when the tile holds more than one figure (a title, a progress bar, actions).
+
+## 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.
+
+```ts
+import { Component } from '@angular/core';
+import { BfStatComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Clock, CookingPot, Timer, Users } from 'lucide';
+
+/**
+ * The bf-stat overview.
+ *
+ * Live demo of `bf-stat`: a recipe's prep time, cook time, total time and servings as four card
+ * stats, each with an icon tile, wrapping from four across to two.
+ */
+@Component({
+  selector: 'app-example-stat-overview',
+  imports: [BfStatComponent, BfIconComponent],
+  template: `
+    <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
+      <bf-stat label="Prep time" value="15 min" variant="card">
+        <bf-icon bfSlot="icon" [icon]="timer" />
+      </bf-stat>
+      <bf-stat label="Cook time" value="30 min" variant="card">
+        <bf-icon bfSlot="icon" [icon]="cookingPot" />
+      </bf-stat>
+      <bf-stat label="Total time" value="45 min" variant="card">
+        <bf-icon bfSlot="icon" [icon]="clock" />
+      </bf-stat>
+      <bf-stat label="Servings" value="4" variant="card">
+        <bf-icon bfSlot="icon" [icon]="users" />
+      </bf-stat>
+    </div>
+  `,
+})
+export class StatOverviewExampleComponent {
+  protected readonly timer = Timer;
+  protected readonly cookingPot = CookingPot;
+  protected readonly clock = Clock;
+  protected readonly users = Users;
+}
+```
+
+## 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`.
+
+```ts
+import { Component } from '@angular/core';
+import { BfBadgeComponent, BfCardComponent, BfStatComponent } from '@bitforgehq/ui';
+
+/** Plain stats on a card, with a trend and a badge as their supporting lines. */
+@Component({
+  selector: 'app-example-stat-plain',
+  imports: [BfBadgeComponent, BfCardComponent, BfStatComponent],
+  template: `
+    <bf-card>
+      <div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-4">
+        <bf-stat label="Recipes saved" value="1,204">+12% this week</bf-stat>
+        <bf-stat label="Average rating" value="4.8">From 312 reviews</bf-stat>
+        <bf-stat label="Shopping list" value="9 items">
+          <bf-badge variant="warning">3 missing</bf-badge>
+        </bf-stat>
+      </div>
+    </bf-card>
+  `,
+})
+export class StatPlainExampleComponent {}
+```
+
+## Trend
+
+`delta` (the change, already formatted, such as `+12%`) and `trend` (`up`, `down` or `flat`) add a pill beside the value; on a narrow stat it wraps under it. The pill carries an arrow mark (a chevron up or down, a dash for no change) and, for screen readers, the direction as a word before the delta ("Up +12%"), so the colour is never the only signal. An empty `delta` shows no pill; a `delta` without a `trend` shows a neutral pill with no mark.
+
+The colour says whether the change is good, which depends on the figure. `trendIntent="positive"` (the default) is for figures where up is good, such as revenue or sign-ups: up is `success`, down is `danger`. `trendIntent="negative"` is for figures where down is good, such as costs, churn or load time: down is `success`, up is `danger`. `flat` is neutral in both. Put the comparison ("vs. last month") in the supporting line.
+
+```ts
+import { Component } from '@angular/core';
+import { BfStatComponent } from '@bitforgehq/ui';
+
+/**
+ * Stats with a trend.
+ *
+ * Revenue up (good), costs down (good, so `trendIntent="negative"`) and churn unchanged, each with
+ * a delta pill beside the value.
+ */
+@Component({
+  selector: 'app-example-stat-trend',
+  imports: [BfStatComponent],
+  template: `
+    <div class="grid grid-cols-[repeat(auto-fit,minmax(11rem,1fr))] gap-3">
+      <bf-stat label="Revenue" value="€48,200" delta="+12%" trend="up" variant="card">
+        vs. last month
+      </bf-stat>
+      <bf-stat
+        label="Costs"
+        value="€12,900"
+        delta="-8%"
+        trend="down"
+        trendIntent="negative"
+        variant="card"
+      >
+        vs. last month
+      </bf-stat>
+      <bf-stat label="Churn" value="2.1%" delta="0%" trend="flat" variant="card">
+        vs. last month
+      </bf-stat>
+    </div>
+  `,
+})
+export class StatTrendExampleComponent {}
+```
+
+## Desktop
+
+A stat is not interactive: no hover, no pointer cursor, no focus stop. Its size does not follow `provideBfDefaults()`; the figure keeps the `title` type on every density. Inside `provideBfShell()` (the Capacitor shell) it renders and behaves exactly the same. A grid of stats wraps by itself with `grid-cols-[repeat(auto-fit,minmax(9rem,1fr))]` on the grid that holds them, so the same row reads as four across on a desktop and two on a phone.
+
+## Theming
+
+- 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.
+- `card`: `surface`, the `card` radius, `--spacing-card` padding (`p-card`) and a 1.5 px `border-strong` edge, as the `flat` `bf-card`.
+
+## Accessibility
+
+`bf-stat` renders a native `dl` holding the label as the `dt`, the value as a `dd` and the supporting line as a second `dd`, so a screen reader announces the label with its value and context. The icon tile sits outside the `dl`; keep the icon decorative (a `bf-icon` without a `label` is hidden from assistive technology). The delta pill sits in the value's `dd`, so it is read with the value; its arrow mark is `aria-hidden`, and a visually hidden word (the `statTrendUp`, `statTrendDown` and `statTrendFlat` labels, "Up", "Down", "No change"; translate them with `provideBfLabels()`) names the direction before the delta. The pill uses the badge's tone pairs, so its text keeps the badge's contrast in both modes; in forced colours the mark still shows, as it is drawn with borders. The stat adds no other ARIA.
+
+## 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).        |
+
+## Slots
+
+- `icon`: The icon in the tile at the start.
+- `default`: A supporting line under the value, such as a trend or a badge.
+
+## Notes
+
+### Do
+
+- Format the value before passing it (`45 min`, `1,204`, `98%`); the stat prints it as given.
+- Keep the supporting line to a few words.
+- Set `trendIntent="negative"` for figures where a fall is good news (costs, churn, errors).
+
+### Don't
+
+- 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.1
+
+New: `bf-stat`, one labelled figure in its own `dl`, with the value at the `title` size in
+tabular figures, an `icon` slot for a tile at the start and a supporting line in the default slot.
+`variant="card"` gives it the outlined `flat` card surface; `plain` (default) draws none. An
+opt-in trend: `delta` (the formatted change, such as `+12%`; empty shows nothing) with `trend`
+(`up`, `down`, `flat`) renders a pill beside the value with a CSS arrow mark and the direction as a
+hidden word (new labels `statTrendUp`, `statTrendDown`, `statTrendFlat`). `trendIntent`
+(`positive` default, up is good; `negative` when down is good, such as costs) picks `success` or
+`danger`; flat is neutral. New types `BfStatVariant`, `BfStatTrend` and `BfStatTrendIntent`.

package/ai/components/tab-group.md

@@ -0,0 +1,226 @@
+# bf-tab-group
+
+In-page tabs that switch between content panels, with keyboard navigation and badges
+
+`BfTabGroupComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTabGroupComponent, BfTabPanelComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-tab-group overview.
+ *
+ * Live demo of `bf-tab-group`: a project's Overview, Activity and Settings sections, Activity with
+ * a count badge; click a tab, or focus one and use the arrow keys, Home and End.
+ */
+@Component({
+  selector: 'app-example-tab-group-overview',
+  imports: [BfTabGroupComponent, BfTabPanelComponent],
+  template: `
+    <bf-tab-group label="Project sections" [(selected)]="tab">
+      <bf-tab-panel value="overview" label="Overview">
+        <p class="text-body">Atlas ships the new onboarding flow in March.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="activity" label="Activity" [badge]="3">
+        <ng-template>
+          <p class="text-body">Mara commented on the brief, and two tasks were closed.</p>
+        </ng-template>
+      </bf-tab-panel>
+      <bf-tab-panel value="settings" label="Settings">
+        <ng-template>
+          <p class="text-body">Only owners can change the project settings.</p>
+        </ng-template>
+      </bf-tab-panel>
+    </bf-tab-group>
+    <p data-status aria-live="polite" class="text-caption text-text-muted mt-3">
+      Selected tab: {{ tab() }}
+    </p>
+  `,
+})
+export class TabGroupOverviewExampleComponent {
+  readonly tab = signal('overview');
+}
+```
+
+## Overview
+
+In-page tabs: a row of tabs over the content they switch, one `bf-tab-panel` per tab. The
+`selected` model holds the shown panel's `value`; unset or unknown, the first enabled panel
+shows. Selection follows focus: the arrow keys (mirrored under `dir="rtl"`), Home and End move
+to a tab and show its panel. When the tabs do not fit, the row scrolls sideways.
+
+In-page tabs: a row of tabs over the content they switch, such as Overview / Activity / Settings on a project's detail page. `bf-tab-group` holds the row and the selection; each tab and its content is a [`bf-tab-panel`](https://bitforge-ui.web.app/components/tab-panel). It works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-tab-group` to split one page's content into a few sections that the user switches in place, without leaving the page. In the Capacitor shell use [bf-tabs](https://bitforge-ui.web.app/components/tabs) with [bf-tab-bar](https://bitforge-ui.web.app/components/tab-bar) instead for the app's top-level destinations at the bottom of the screen: those are routes, these are sections of one page. Use [bf-top-nav](https://bitforge-ui.web.app/components/top-nav) with `a[bfNavItem]` links instead when each tab is its own route (a URL to share or open in a new tab): links are navigation, tabs switch content in place. Use [bf-segmented](https://bitforge-ui.web.app/components/segmented) for a two-to-four-way switch of one view, such as a chart's range.
+
+## Badges and icons
+
+A panel's `badge` adds a count pill after its tab's label, announced as "3 new"; an icon in the panel's `bfSlot="icon"` shows in the tab before the label. A `disabled` panel's tab cannot be picked.
+
+```ts
+import { Component } from '@angular/core';
+import { BfTabGroupComponent, BfTabPanelComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Activity, FileText, LayoutDashboard, Lock } from 'lucide';
+
+/**
+ * Tabs with icons, a count badge and a disabled tab.
+ *
+ * Each panel's `bfSlot="icon"` shows in its tab before the label; `badge` adds an announced
+ * count, and `disabled` takes a tab out of the selection and the keyboard navigation.
+ */
+@Component({
+  selector: 'app-example-tab-group-badges-and-icons',
+  imports: [BfTabGroupComponent, BfTabPanelComponent, BfIconComponent],
+  template: `
+    <bf-tab-group label="Project with icons">
+      <bf-tab-panel value="overview" label="Overview">
+        <bf-icon bfSlot="icon" [icon]="dashboard" />
+        <p class="text-body">The project at a glance.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="activity" label="Activity" [badge]="12">
+        <bf-icon bfSlot="icon" [icon]="activity" />
+        <p class="text-body">12 updates since your last visit.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="files" label="Files">
+        <bf-icon bfSlot="icon" [icon]="files" />
+        <p class="text-body">The brief and two mock-ups.</p>
+      </bf-tab-panel>
+      <bf-tab-panel value="billing" label="Billing" [disabled]="true">
+        <bf-icon bfSlot="icon" [icon]="lock" />
+        <p class="text-body">Billing is managed by the workspace owner.</p>
+      </bf-tab-panel>
+    </bf-tab-group>
+  `,
+})
+export class TabGroupBadgesAndIconsExampleComponent {
+  protected readonly dashboard = LayoutDashboard;
+  protected readonly activity = Activity;
+  protected readonly files = FileText;
+  protected readonly lock = Lock;
+}
+```
+
+## Lazy content
+
+Put a panel's content in an `ng-template` inside it and the content is created only while its tab is selected, and destroyed when another tab shows: a heavy chart or a feed costs nothing until it is opened. `keepAlive` keeps it in the DOM, hidden, once it has been shown, so its scroll position and form input survive switching tabs. Plain content (not in an `ng-template`) renders at once and is only hidden.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfInputComponent, BfTabGroupComponent, BfTabPanelComponent } from '@bitforgehq/ui';
+
+/**
+ * Lazy panels, one kept alive.
+ *
+ * Each panel's content is an `ng-template`, created when its tab shows. Notes is `keepAlive`:
+ * type in it, switch tabs and come back, and the text is still there; Comments is created anew
+ * each time.
+ */
+@Component({
+  selector: 'app-example-tab-group-lazy',
+  imports: [BfInputComponent, BfTabGroupComponent, BfTabPanelComponent],
+  template: `
+    <bf-tab-group label="Task details" [(selected)]="tab">
+      <bf-tab-panel value="notes" label="Notes" keepAlive>
+        <ng-template>
+          <bf-input label="Note" placeholder="Type, then switch tabs" />
+        </ng-template>
+      </bf-tab-panel>
+      <bf-tab-panel value="comments" label="Comments">
+        <ng-template>
+          <bf-input label="Comment" placeholder="Cleared when you leave this tab" />
+        </ng-template>
+      </bf-tab-panel>
+    </bf-tab-group>
+  `,
+})
+export class TabGroupLazyExampleComponent {
+  readonly tab = signal('notes');
+}
+```
+
+## Selection
+
+`[(selected)]` holds the shown panel's `value`; `(changed)` emits the new value after a user change, never for a write of `selected`. While `selected` matches no panel (unset, or a value that went away), the first enabled panel shows; `selected` itself keeps its value until the user picks a tab.
+
+## Sizes and width
+
+`size` sets the tabs' height: `sm` 32 px, `md` 40 px, `lg` 48 px. Unset, it follows `provideBfDefaults()`'s `controlSize`, `md` by default. `fitted` stretches the tabs to share the group's width (two or three tabs on a phone). When the tabs do not fit, the row scrolls sideways; focusing a tab with the keyboard scrolls it into view.
+
+## Desktop
+
+Under a mouse an unselected tab takes a `surface-muted` fill and `text` on hover, with the pointer cursor, and `surface-pressed` while pressed; a disabled tab shows `not-allowed` and does not react. The focus ring shows on keyboard focus only, on the tab and on the panel (which is in the tab order so its content can be reached and scrolled by keyboard). Under a fine pointer the tab's visual box is its hit area; under a coarse pointer (touch) every tab is at least 44 px tall. Desktop density is the default `md` step; `provideBfDefaults({ controlSize: 'sm' })` in a component's `providers` makes a dense sub-tree ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Tabs: `text-muted` at rest, hover `surface-muted` with `text`, pressed `surface-pressed`; top corners `rounded-tile`.
+- Selected tab: `primary-text` with a 2 px `primary` underline on its bottom edge, so the selection never rests on colour alone (`CanvasText` under forced colours; `text-disabled` on a disabled selected tab).
+- Disabled tab: `text-disabled` (never opacity).
+- The row: a 1 px `border` line under the tabs, across the group's width.
+- Badge: `primary` with `on-primary` text, `rounded-control`, `text-micro`.
+- Focus ring: `ring`, on the tabs and on the panel (`rounded-tile`).
+- Type: `text-label-xs` / `text-label-sm` / `text-label` for `sm` / `md` / `lg`, bold.
+
+## Accessibility
+
+The row is a `role="tablist"` named by `label`, else `provideBfLabels()`'s `tabGroup` ("Tabs"); give each group on a page its own `label`. Each tab is a native `<button role="tab">` with `aria-selected` and `aria-controls` naming its panel; each `bf-tab-panel` is a `role="tabpanel"` with `aria-labelledby` naming its tab and `tabindex="0"`, and an unselected panel is `hidden`. Only the selected tab is in the tab order (a roving tab stop), so <kbd>Tab</kbd> moves from it into the panel. Selection follows focus (automatic activation): the arrow keys, <kbd>Home</kbd> and <kbd>End</kbd> move to a tab and show its panel at once, so keep a panel's first render quick. A disabled tab is native-disabled and skipped. A badge's pill is `aria-hidden`; its count is read after the label from visually hidden text (`tabBadge(n)`, "3 new").
+
+### Keyboard
+
+| Key                                              | Action                                                                                               |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus to the selected tab, then into the shown panel, and out again                            |
+| <kbd>ArrowRight</kbd>                            | Selects and focuses the next enabled tab, wrapping at the end (the previous one under `dir="rtl"`)   |
+| <kbd>ArrowLeft</kbd>                             | Selects and focuses the previous enabled tab, wrapping at the start (the next one under `dir="rtl"`) |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Selects and focuses the first / last enabled tab                                                     |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Selects the focused tab (it is already selected after an arrow key)                                  |
+
+## Inputs
+
+| Name       | Type                                                        | Default     | Description                                                                                                                                                                  |
+| ---------- | ----------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`    | `string`                                                    | `''`        | Accessible name of the tablist; empty falls back to `provideBfLabels()`'s `tabGroup` ("Tabs").                                                                               |
+| `size`     | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step of the tabs: sm 32, md 40, lg 48 px (at least 44 px under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default).               |
+| `fitted`   | `boolean`                                                   | `false`     | Stretches the tabs to share the group's width.                                                                                                                               |
+| `selected` | `string`                                                    | `''`        | The shown panel's `value`; two-way bindable. Unset or unknown shows the first enabled panel (the model keeps its value until the user picks a tab). Two-way: `[(selected)]`. |
+
+## Outputs
+
+| Name      | Payload  | Description                                                          |
+| --------- | -------- | -------------------------------------------------------------------- |
+| `changed` | `string` | Emitted with the newly selected panel's `value` after a user change. |
+
+## Slots
+
+- `default`: The panels, each a `bf-tab-panel`.
+
+## Notes
+
+### Do
+
+- Keep tab labels to one or two short words, and the tabs to a handful that fit the usual width.
+- Put heavy content in an `ng-template` so it renders only when its tab is opened.
+
+### Don't
+
+- Don't use tabs to navigate between pages; use `bf-top-nav` links, which the router and the browser understand.
+- Don't nest a tab group in another tab group's panel; split the page instead.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-tab-group`: in-page tabs over the content they switch, in both shells. A `tablist` of
+`button role="tab"` from its `bf-tab-panel` children, the `selected` model of the shown panel's
+`value` with `changed` after a user change (unset or unknown shows the first enabled panel),
+named by `label` (else the new `tabGroup` label, "Tabs"), `size` from `controlSize` (44 px at
+least under a coarse pointer) and `fitted` to share the width. A roving tab stop and automatic
+activation: the arrow keys (mirrored under `dir="rtl"`), Home and End select and focus a tab,
+skipping disabled ones. The selected tab is underlined in `primary`; the row scrolls sideways
+when the tabs do not fit. New `BfTabGroupHarness` in `@bitforgehq/ui/testing` (`getTabLabels()`,
+`getSelectedLabel()`, `selectTab(label)`, `getPanelText()`).