@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/stat.md

@@ -0,0 +1,297 @@
+# 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, 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';
+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;
+}
+```
+
+## 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`.
+
+```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 (`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
+
+`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`     | `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
+
+- `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 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
+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()`).