@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/description-item.md

@@ -0,0 +1,111 @@
+# div[bfDescriptionItem]
+
+One label and value pair of a description list, label as term, content as value
+
+`BfDescriptionItemComponent` from `@bitforgehq/ui` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfDescriptionItemComponent, BfDescriptionListComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-description-item overview.
+ *
+ * Live demo of `div[bfDescriptionItem]`: three pairs of a recipe, each a label and its value, in a
+ * `bf-description-list`.
+ */
+@Component({
+  selector: 'app-example-description-item-overview',
+  imports: [BfDescriptionItemComponent, BfDescriptionListComponent],
+  template: `
+    <bf-description-list>
+      <div bfDescriptionItem label="Oven">200 °C, fan 180 °C</div>
+      <div bfDescriptionItem label="Keeps">2 days in the fridge</div>
+      <div bfDescriptionItem label="Freezes">Yes, up to 3 months</div>
+    </bf-description-list>
+  `,
+})
+export class DescriptionItemOverviewExampleComponent {}
+```
+
+## Overview
+
+One label-value pair of a `bf-description-list`: the `label` becomes the `dt`, the content the
+`dd`. Put it on a `div` inside the list.
+
+One label-value pair of a [`bf-description-list`](https://bitforge-ui.web.app/components/description-list): put `bfDescriptionItem` on a `div` inside the list, set its `label`, and put the value in its content. The `label` becomes the pair's `dt` and the content its `dd`; the item takes its look (a divided row or a tile) from the list's `layout`. It works the same in both shells.
+
+## When to use
+
+Use `div[bfDescriptionItem]` for each fact inside a `bf-description-list`. Use [bf-list-item](https://bitforge-ui.web.app/components/list-item) instead for a row the user can open or act on, and [bf-stat](https://bitforge-ui.web.app/components/stat) instead for a single headline figure.
+
+## Basic usage
+
+`label` is required; the value is the content, so it can be text, a badge or a link. A class on the item (such as `col-span-full` in the grid layout) is kept alongside the item's own classes.
+
+```ts
+import { Component } from '@angular/core';
+import { BfDescriptionItemComponent, BfDescriptionListComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-description-item overview.
+ *
+ * Live demo of `div[bfDescriptionItem]`: three pairs of a recipe, each a label and its value, in a
+ * `bf-description-list`.
+ */
+@Component({
+  selector: 'app-example-description-item-overview',
+  imports: [BfDescriptionItemComponent, BfDescriptionListComponent],
+  template: `
+    <bf-description-list>
+      <div bfDescriptionItem label="Oven">200 °C, fan 180 °C</div>
+      <div bfDescriptionItem label="Keeps">2 days in the fridge</div>
+      <div bfDescriptionItem label="Freezes">Yes, up to 3 months</div>
+    </bf-description-list>
+  `,
+})
+export class DescriptionItemOverviewExampleComponent {}
+```
+
+## Desktop
+
+The item is not interactive: no hover, no pointer cursor, no focus stop; only a link or button in its value takes focus. It renders the same inside `provideBfShell()`.
+
+## Theming
+
+- Label (`dt`): `text-caption` in `text-muted`. Value (`dd`): `text-body` in `text`; a long value wraps anywhere rather than overflow.
+- In the `rows` layout the item has `py-3` and, from a 28rem wide list, a one-third label column; in the `grid` layout it is a tile with the label over the value.
+
+## Accessibility
+
+The item is the `div` that groups one `dt` with its `dd` inside the list's `dl`, which HTML allows, so the pair is announced as a term and its description. It adds no ARIA.
+
+## Inputs
+
+| Name    | Type     | Default  | Description                          |
+| ------- | -------- | -------- | ------------------------------------ |
+| `label` | `string` | required | The term, shown as the pair's label. |
+
+## Slots
+
+- `default`: The value: text or rich content such as a badge or a link.
+
+## Notes
+
+### Do
+
+- Use one item per fact, with a short noun as the `label`.
+
+### Don't
+
+- Don't use `bfDescriptionItem` outside a `bf-description-list`: without the `dl` around it, its `dt` and `dd` are invalid HTML.
+- Don't put a second term in one item; give each its own.
+
+## Migration notes
+
+### 0.3.1
+
+New: `div[bfDescriptionItem]`, one pair of a `bf-description-list`: its required `label` is the
+`dt`, its content (text, a badge, a link) the `dd`.

package/ai/components/description-list.md

@@ -0,0 +1,160 @@
+# bf-description-list
+
+Native description list of label-value pairs, as divided rows or a tile grid
+
+`BfDescriptionListComponent` from `@bitforgehq/ui` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfBadgeComponent,
+  BfDescriptionItemComponent,
+  BfDescriptionListComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * The bf-description-list overview.
+ *
+ * Live demo of `bf-description-list`: a recipe's details as divided rows, with a badge and a link
+ * as values; the labels move beside the values once the list is wide enough.
+ */
+@Component({
+  selector: 'app-example-description-list-overview',
+  imports: [BfBadgeComponent, BfDescriptionItemComponent, BfDescriptionListComponent],
+  template: `
+    <bf-description-list>
+      <div bfDescriptionItem label="Recipe">Lemon risotto with peas</div>
+      <div bfDescriptionItem label="Cuisine">Italian</div>
+      <div bfDescriptionItem label="Difficulty"><bf-badge variant="success">Easy</bf-badge></div>
+      <div bfDescriptionItem label="Diet">Vegetarian, gluten-free</div>
+      <div bfDescriptionItem label="Source">
+        <a href="#source" class="text-primary underline">Nonna's notebook, page 42</a>
+      </div>
+      <div bfDescriptionItem label="Added">12 October 2026</div>
+    </bf-description-list>
+  `,
+})
+export class DescriptionListOverviewExampleComponent {}
+```
+
+## Overview
+
+A list of label-value pairs, such as a record's details: a native `dl` around
+`div[bfDescriptionItem]`s, as divided rows (label beside value) or a grid of tiles.
+
+A description list shows the details of one record as label-value pairs: a recipe's cuisine and difficulty, an order's status and date, a person's role and email. `bf-description-list` renders the native `dl`; each pair is a [`div[bfDescriptionItem]`](https://bitforge-ui.web.app/components/description-item) whose `label` becomes the `dt` and whose content becomes the `dd`. It works the same in both shells: in the Capacitor shell and in a desktop web app.
+
+## When to use
+
+Use `bf-description-list` for read-only facts about one thing, where the reader looks up a value by its label. Use [bf-list](https://bitforge-ui.web.app/components/list) instead when the rows are actions or links, and [bf-stat](https://bitforge-ui.web.app/components/stat) instead for a few headline figures (a duration, a count, a total) that should read at a glance. A table compares many records across columns; a description list describes one.
+
+## Rows
+
+`layout="rows"` (the default) separates the pairs with a `border` line, as a divided `bf-list`. Once the list is 28rem wide or more, the label sits beside its value in a one-third column; in a narrower list (a phone, a side pane) the label stacks over the value. The width that counts is the list's own (the host is an inline-size container), not the viewport's, so the same list stacks in a narrow pane and sits side by side on a wide page. The value can be rich content: a badge, a link, a short sentence.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfBadgeComponent,
+  BfDescriptionItemComponent,
+  BfDescriptionListComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * The bf-description-list overview.
+ *
+ * Live demo of `bf-description-list`: a recipe's details as divided rows, with a badge and a link
+ * as values; the labels move beside the values once the list is wide enough.
+ */
+@Component({
+  selector: 'app-example-description-list-overview',
+  imports: [BfBadgeComponent, BfDescriptionItemComponent, BfDescriptionListComponent],
+  template: `
+    <bf-description-list>
+      <div bfDescriptionItem label="Recipe">Lemon risotto with peas</div>
+      <div bfDescriptionItem label="Cuisine">Italian</div>
+      <div bfDescriptionItem label="Difficulty"><bf-badge variant="success">Easy</bf-badge></div>
+      <div bfDescriptionItem label="Diet">Vegetarian, gluten-free</div>
+      <div bfDescriptionItem label="Source">
+        <a href="#source" class="text-primary underline">Nonna's notebook, page 42</a>
+      </div>
+      <div bfDescriptionItem label="Added">12 October 2026</div>
+    </bf-description-list>
+  `,
+})
+export class DescriptionListOverviewExampleComponent {}
+```
+
+## Grid
+
+`layout="grid"` lays the pairs out as tiles with the label over the value, in as many columns of at least 10rem as fit, so the tiles wrap on their own without a breakpoint. Use it for short values that read well side by side; a long value belongs in the rows layout.
+
+```ts
+import { Component } from '@angular/core';
+import { BfDescriptionItemComponent, BfDescriptionListComponent } from '@bitforgehq/ui';
+
+/** A recipe's nutrition per serving as a grid of tiles that wraps by itself. */
+@Component({
+  selector: 'app-example-description-list-grid',
+  imports: [BfDescriptionItemComponent, BfDescriptionListComponent],
+  template: `
+    <bf-description-list layout="grid">
+      <div bfDescriptionItem label="Energy">520 kcal</div>
+      <div bfDescriptionItem label="Protein">16 g</div>
+      <div bfDescriptionItem label="Carbohydrates">78 g</div>
+      <div bfDescriptionItem label="Fat">14 g</div>
+      <div bfDescriptionItem label="Note" class="col-span-full">
+        Values per serving, with parmesan.
+      </div>
+    </bf-description-list>
+  `,
+})
+export class DescriptionListGridExampleComponent {}
+```
+
+## Desktop
+
+The list is not interactive: it has no hover, no pointer cursor and no focus stop of its own, and only the links or buttons you put in a value take focus. Its spacing does not follow `provideBfDefaults()`; the rows keep one rhythm on every density. Inside `provideBfShell()` (the Capacitor shell) it renders and behaves exactly the same. Because the host is an inline-size container, give it a width when you place it in a flex row (`flex-1` or a `basis-*`), or it shrinks to nothing.
+
+## Theming
+
+- Label (`dt`): `text-caption` in `text-muted`. Value (`dd`): `text-body` in `text`.
+- `rows`: the lines between the pairs are `border`; each pair has `py-3` (12 px) of block padding.
+- `grid`: `gap-x-6` / `gap-y-4` between the tiles, columns of at least 10rem.
+
+## Accessibility
+
+`bf-description-list` renders a native `dl`, and each `div[bfDescriptionItem]` is a `div` holding one `dt` and one `dd`, which is valid HTML, so screen readers announce a list of terms with their descriptions. The list adds no ARIA. Content in a value carries its own semantics: a badge's text is read with the value, a link stays a link.
+
+## Inputs
+
+| Name     | Type                                           | Default  | Description                                                                                                           |
+| -------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `layout` | `BfDescriptionListLayout` (`'rows' \| 'grid'`) | `'rows'` | `rows` (default): label beside value, divided, stacked in a narrow list; `grid`: tiles with the label over the value. |
+
+## Slots
+
+- `default`: The pairs, each a `div[bfDescriptionItem]`.
+
+## Notes
+
+### Do
+
+- Keep labels short nouns ("Cuisine", "Servings") and put the unit in the value ("45 min").
+- Put a badge or a link in a value when the value is a status or points elsewhere.
+
+### Don't
+
+- Don't put anything but `div[bfDescriptionItem]` pairs in a `bf-description-list`; a `dl` expects term and description groups.
+- Don't use it for rows the user acts on; that is a `bf-list` of `bf-list-item` rows.
+
+## Migration notes
+
+### 0.3.1
+
+New: `bf-description-list`, a native `dl` of label-value pairs for the details of one record, in
+both shells. `layout="rows"` (default) divides the pairs with a `border` line and puts the label
+beside the value once the list is 28rem wide (a container query, so a narrow pane stacks them);
+`layout="grid"` lays them out as wrapping tiles. New type `BfDescriptionListLayout`.

package/ai/components/donut-chart.md

@@ -0,0 +1,169 @@
+# bf-donut-chart
+
+Donut chart of the parts of a whole, with a legend, tooltip and centre slot
+
+`BfDonutChartComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed } from '@angular/core';
+import { BfDonutChartComponent, type BfDonutSlice } from '@bitforgehq/ui/charts';
+
+/**
+ * The bf-donut-chart overview.
+ *
+ * Live demo of `bf-donut-chart`: a month's spending by category with the total in the centre.
+ * Hover a slice, or focus the chart and use the arrow keys; hide a slice in the legend and the
+ * others share the rest.
+ */
+@Component({
+  selector: 'app-example-donut-chart-overview',
+  imports: [BfDonutChartComponent],
+  template: `
+    <bf-donut-chart label="Spending in October" [slices]="slices" [valueFormat]="francs">
+      <span bfSlot="center" class="text-heading text-text">{{ total() }}</span>
+      <span bfSlot="center" class="text-caption text-text-muted">October</span>
+    </bf-donut-chart>
+  `,
+})
+export class DonutChartOverviewExampleComponent {
+  readonly slices: readonly BfDonutSlice[] = [
+    { label: 'Rent', value: 1850 },
+    { label: 'Groceries', value: 640 },
+    { label: 'Transport', value: 310 },
+    { label: 'Leisure', value: 280 },
+    { label: 'Other', value: 170 },
+  ];
+  private readonly format = new Intl.NumberFormat('en', {
+    style: 'currency',
+    currency: 'CHF',
+    maximumFractionDigits: 0,
+  });
+  readonly francs = (value: number): string => this.format.format(value);
+  readonly total = computed(() => this.francs(this.slices.reduce((sum, s) => sum + s.value, 0)));
+}
+```
+
+## Overview
+
+A donut chart of one set of slices, the parts of a whole (a budget by category, traffic by
+source), drawn in SVG with the chart palette: each slice's angle is its share of the total.
+A legend shows and hides slices (the total follows), a tooltip shows a slice's value and share
+on hover and on keyboard focus (Arrow keys move between the slices and a polite live region
+reads each one), and a Show data table lists them. The `center` slot holds a total or a label
+in the ring's hole. Slices draw in on the first render and on every data change, still under
+reduced motion; under `dir="rtl"` the slices run counter-clockwise.
+
+A donut chart shows the parts of one whole: a budget by category, traffic by source, tasks by status. `bf-donut-chart` draws it in SVG from `slices` (each a `label` and a `value`); each slice's angle is its share of the total. A legend shows and hides slices, a tooltip shows a slice's value and share on hover and on keyboard focus, a Show data table lists them, and the `center` slot holds a total in the ring's hole. It lives in `@bitforgehq/ui/charts` (`import { BfDonutChartComponent } from '@bitforgehq/ui/charts'`) and works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-donut-chart` for the shares of one whole with a few parts (two to six read well). Our charts are themed with the `--color-chart-*` tokens and bring their own legend, tooltip, keyboard reading and data table; bring a chart library (themed with the same tokens) only for a form they do not draw. Use [bf-bar-chart](https://bitforge-ui.web.app/components/bar-chart) instead to compare the parts precisely or when there are many, and [bf-stat](https://bitforge-ui.web.app/components/stat) for a single share ("42 % done").
+
+## Centre and thickness
+
+Content with `bfSlot="center"` sits in the ring's hole: the total and a caption, such as `1,800 CHF` over `this month`. Keep it short; it does not take pointer events, so hovering the hole never hides the tooltip of a slice. `thickness` sets the ring's width in px (28 by default); a thickness as large as the radius draws a full pie.
+
+```ts
+import { Component } from '@angular/core';
+import { BfDonutChartComponent, type BfDonutSlice } from '@bitforgehq/ui/charts';
+
+/**
+ * A thin ring and a pie.
+ *
+ * `thickness` sets the ring's width: a thin ring leaves room for the centre, a thickness as large
+ * as the radius draws a full pie. Tasks by status, the legend above the ring.
+ */
+@Component({
+  selector: 'app-example-donut-chart-thickness',
+  imports: [BfDonutChartComponent],
+  template: `
+    <div class="grid w-full grid-cols-[repeat(auto-fit,minmax(min(14rem,100%),1fr))] gap-4">
+      <bf-donut-chart label="Tasks by status" legend="top" [thickness]="12" [slices]="tasks">
+        <span bfSlot="center" class="text-heading text-text">48</span>
+        <span bfSlot="center" class="text-caption text-text-muted">tasks</span>
+      </bf-donut-chart>
+      <bf-donut-chart
+        label="Tasks by status, as a pie"
+        legend="top"
+        [thickness]="200"
+        [slices]="tasks"
+      />
+    </div>
+  `,
+})
+export class DonutChartThicknessExampleComponent {
+  readonly tasks: readonly BfDonutSlice[] = [
+    { label: 'Done', value: 27 },
+    { label: 'In progress', value: 13 },
+    { label: 'Blocked', value: 8 },
+  ];
+}
+```
+
+## Data and formatting
+
+Slices run clockwise from the top in their order (counter-clockwise under `dir="rtl"`), with a 2 px gap between them; a slice of zero or less draws nothing, but stays in the legend and the table. Hiding a slice in the legend removes it from the total, so the other shares grow. `valueFormat` formats the values in the tooltip, the announcement and the table; unset, values use `Intl.NumberFormat` in the document's language, and shares are whole percentages. The slices draw in along the ring on the first render and whenever `slices` change. `height` sets the plot's height in px (220 by default); the ring fits the smaller of it and the container's width.
+
+## Desktop
+
+Under a mouse, hovering a slice thickens it and shows its tooltip; the hole and the space around the ring show none. The plot is one stop in the tab order, with the focus ring on keyboard focus: focusing it shows the first slice. Under a coarse pointer (touch) a tap shows a slice's tooltip, and the legend buttons and the Show data button are at least 44 px tall. Inside `provideBfShell()` it renders and behaves the same.
+
+## Theming
+
+- Slices: `--color-chart-1` … `--color-chart-8` in order (`stroke-chart-n`); the ring's track: `chart-grid`.
+- Tooltip, legend and data table: as in [bf-line-chart](https://bitforge-ui.web.app/components/line-chart).
+- Motion: `--animate-chart-draw` along each slice; the active slice thickens over 150 ms; none under `prefers-reduced-motion`.
+
+## Accessibility
+
+The chart is a native `figure` named by `label` (else the `bf-chart-card` title, else the `chart` label); the SVG is hidden from assistive technology, and the centre slot's text is read as part of the figure. The plot is a focusable `role="group"` named by the `chartValues` label: the arrow keys move between the slices and a polite live region reads each one with its share ("Rent: 900 CHF (50%)"). The legend is a group of toggle buttons (`aria-pressed`); the Show data button (`aria-expanded`) shows the slices as a native `table` (`chartCategory` and `chartValue` headers). Every slice colour is ≥ 3:1 against `surface` and `bg`, and the legend names each one.
+
+### Keyboard
+
+| Key                                              | Action                                                                               |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves through the plot, the legend buttons and the Show data button                  |
+| <kbd>ArrowRight</kbd>                            | Moves to the next slice and reads it (the previous one under `dir="rtl"`)            |
+| <kbd>ArrowLeft</kbd>                             | Moves to the previous slice and reads it (the next one under `dir="rtl"`)            |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Moves to the first / last slice                                                      |
+| <kbd>Escape</kbd>                                | Hides the tooltip                                                                    |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | On a legend button, shows or hides its slice; on Show data, shows or hides the table |
+
+## Inputs
+
+| Name          | Type                                                                              | Default     | Description                                                                                                                    |
+| ------------- | --------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `slices`      | `readonly BfDonutSlice[]`                                                         | required    | The slices, in order clockwise from the top.                                                                                   |
+| `label`       | `string`                                                                          | `''`        | The chart's accessible name; empty falls back to the `bf-chart-card` title, then to `provideBfLabels()`'s `chart` ("Chart").   |
+| `height`      | `number`                                                                          | `220`       | The plot's height in px; the ring fits the smaller of it and the container's width.                                            |
+| `thickness`   | `number`                                                                          | `28`        | The ring's thickness in px (at most the radius, a full pie).                                                                   |
+| `valueFormat` | `BfChartValueFormat \| undefined`                                                 | `undefined` | Formats the values in the tooltip, the announcements and the table; unset uses `Intl.NumberFormat` in the document's language. |
+| `legend`      | `BfChartLegendPosition \| undefined` (`'top' \| 'bottom' \| 'none' \| undefined`) | `undefined` | Where the legend goes; unset follows the `bf-chart-card`, else `bottom`. A single slice draws no legend.                       |
+
+## Slots
+
+- `center`: Content in the ring's hole, such as the total and its label.
+
+## Notes
+
+### Do
+
+- Order the slices from largest to smallest, starting at the top.
+- Put the total in the `center` slot, so the shares have a whole to refer to.
+
+### Don't
+
+- Don't use a donut for more than about six slices or for slices of nearly equal size; use a bar chart.
+- Don't use it for values that do not add up to a whole.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-donut-chart` in `@bitforgehq/ui/charts`: `slices` (`BfDonutSlice`: `label`, `value`) as
+the parts of a whole, with a `thickness`, a `center` slot for a total, a legend that hides slices
+(the shares follow), a tooltip with each slice's value and share, keyboard reading and a data
+table. Slices draw in along the ring, not under reduced motion, and run counter-clockwise under
+`dir="rtl"`.

package/ai/components/header.md

@@ -103,7 +103,7 @@ the collapse is pure CSS and scrolling never schedules Angular change detection.
 
 ## When to use
 
-Use `bf-header` at the top of every `bf-page` in the Capacitor shell: the bar with its start and end actions and the collapsing large title. Use a plain `h1` and a toolbar row of [bf-button](https://bitforge-ui.web.app/components/button)s instead on a desktop web page, and [bf-back-button](https://bitforge-ui.web.app/components/back-button) in its `start` slot on a pushed page.
+Use `bf-header` at the top of every `bf-page` in the Capacitor shell: the bar with its start and end actions and the collapsing large title. Use [bf-page-header](https://bitforge-ui.web.app/components/page-header) instead on a desktop web page, and [bf-back-button](https://bitforge-ui.web.app/components/back-button) in its `start` slot on a pushed page.
 
 ## Basic usage
 
@@ -608,7 +608,67 @@ inside one.
 
 ## Desktop
 
-`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page, give the page a plain `h1` and put its actions in a toolbar row of [bf-button](https://bitforge-ui.web.app/components/button)s and a [bf-menu-button](https://bitforge-ui.web.app/components/menu-button); the large title and the scroll-under surface are phone patterns. Under the shell, a browser window shorter than 500 px gets the compact bar (no large title), as a phone in landscape does.
+`bf-header` is part of the Capacitor shell (`provideBfShell()`), shaped like an iOS or Material app bar. On a desktop web page use [bf-page-header](https://bitforge-ui.web.app/components/page-header): the page's one `h1` (`title`) with an optional `subtitle`, badges in `meta`, and the actions in `actions` (the main action as a primary [bf-button](https://bitforge-ui.web.app/components/button), secondary ones as `ghost` or `outline` buttons, the rest in an icon-only [bf-menu-button](https://bitforge-ui.web.app/components/menu-button) labelled "More actions"); the actions wrap under the title in a narrow window. On a nested page, put a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) in its `breadcrumb` slot, and a [bf-toolbar](https://bitforge-ui.web.app/components/toolbar) under it for search and filters. The two are siblings rather than one shell-aware widget: the large title and the scroll-under surface are phone patterns that depend on `bf-content`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfPageHeaderComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import {
+  BfMenuButtonComponent,
+  BfMenuComponent,
+  BfMenuItemDirective,
+} from '@bitforgehq/ui/overlay';
+import { Ellipsis, Plus } from 'lucide';
+
+/**
+ * The desktop replacement for a header: a bf-page-header.
+ *
+ * The page's `h1` with a subtitle, and its actions in the `actions` slot: a ghost button, the
+ * primary action and a menu button for the rest; the actions wrap under the title in a narrow
+ * window.
+ */
+@Component({
+  selector: 'app-example-header-desktop-header',
+  imports: [
+    BfButtonComponent,
+    BfIconComponent,
+    BfMenuButtonComponent,
+    BfMenuComponent,
+    BfMenuItemDirective,
+    BfPageHeaderComponent,
+  ],
+  template: `
+    <bf-page-header title="Atlas rebrand" subtitle="12 of 18 tasks done · due Friday">
+      <bf-button bfSlot="actions" variant="ghost" (clicked)="status.set('Shared.')"
+        >Share</bf-button
+      >
+      <bf-button bfSlot="actions" (clicked)="status.set('New task.')">
+        <bf-icon bfSlot="icon-start" [icon]="plus" />
+        New task
+      </bf-button>
+      <bf-menu-button bfSlot="actions" [menu]="more" iconOnly label="More actions" variant="text">
+        <bf-icon [icon]="ellipsis" />
+      </bf-menu-button>
+    </bf-page-header>
+    <p aria-live="polite" class="text-caption text-text-muted mt-3">{{ status() }}</p>
+
+    <ng-template #more>
+      <bf-menu>
+        <button bfMenuItem (triggered)="status.set('Renamed.')">Rename</button>
+        <button bfMenuItem (triggered)="status.set('Archived.')">Archive</button>
+      </bf-menu>
+    </ng-template>
+  `,
+})
+export class HeaderDesktopHeaderExampleComponent {
+  protected readonly plus = Plus;
+  protected readonly ellipsis = Ellipsis;
+  protected readonly status = signal('');
+}
+```
+
+Under the shell, a browser window shorter than 500 px gets the compact bar (no large title), as a phone in landscape does.
 
 ## Theming
 
@@ -688,6 +748,11 @@ The title is not in the tab order; after a push, `bf-stack-outlet` focuses it wi
 
 ## Migration notes
 
+### 0.3.1
+
+The `## Desktop` docs and When to use name the desktop replacement, `bf-page-header` (with
+`bf-breadcrumb` and `bf-toolbar`), with an example. No code change.
+
 ### 0.3.0
 
 JSDoc of `header.component.ts` for the API reference: `@slot` docs for `start`, `default`, `end`. No