@bitforgehq/ui 0.3.0 → 0.3.2

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/empty-state.md

@@ -98,6 +98,89 @@ export class EmptyStateActionExampleComponent {
 
 Set `headingLevel` to `3` when the empty state sits inside a section that already opened with an `h2`, so the page outline stays in order.
 
+## As the page
+
+When the empty state is the whole page (a not-found page, a no-access page, an app's first run), its title is the page's heading: set `headingLevel` to `1` so it renders the `h1`, and give the page no other `h1`. Centre it in the content area: a column with a minimum height (`min-h-[60vh]`) and `justify-center`. Put the primary action first in the `actions` slot (a `bfButton` link home) and an optional secondary link after it (a `text` `bfButton`, such as "Contact support").
+
+The preview below sits inside this docs page, which already has its `h1`, so it keeps `headingLevel` 2 in a shorter area; a real page uses `1`, as in the code-only example after it.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileQuestionMark } from 'lucide';
+
+/**
+ * An empty state as a whole page.
+ *
+ * Centred in a tall content area, with a primary action and a secondary link. This preview sits
+ * inside a docs page that has its own `h1`, so it uses `headingLevel` 2; on a real not-found page
+ * the empty state is the page, so set it to 1 (see the next example).
+ */
+@Component({
+  selector: 'app-example-empty-state-page',
+  imports: [RouterLink, BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <div class="flex min-h-96 flex-col justify-center">
+      <bf-empty-state
+        title="Page not found"
+        description="The page may have moved, or the link has a typo."
+        [headingLevel]="2"
+      >
+        <bf-icon bfSlot="icon" [icon]="fileQuestion" size="lg" />
+        <a bfSlot="actions" bfButton routerLink="/">Go to the home page</a>
+        <a bfSlot="actions" bfButton variant="text" href="mailto:support@example.com">
+          Contact support
+        </a>
+      </bf-empty-state>
+    </div>
+  `,
+})
+export class EmptyStatePageExampleComponent {
+  protected readonly fileQuestion = FileQuestionMark;
+}
+```
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfButtonComponent, BfEmptyStateComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { FileQuestionMark } from 'lucide';
+
+/**
+ * A not-found page whose empty state is the page heading.
+ *
+ * The route's whole content: `headingLevel` 1 renders the title as the page's `h1`, and the
+ * `min-h-[60vh]` area centres the empty state vertically in the content column.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-empty-state-not-found-page',
+  imports: [RouterLink, BfButtonComponent, BfEmptyStateComponent, BfIconComponent],
+  template: `
+    <div class="flex min-h-[60vh] flex-col justify-center">
+      <bf-empty-state
+        title="Page not found"
+        description="The page may have moved, or the link has a typo."
+        [headingLevel]="1"
+      >
+        <bf-icon bfSlot="icon" [icon]="fileQuestion" size="lg" />
+        <a bfSlot="actions" bfButton routerLink="/">Go to the home page</a>
+        <a bfSlot="actions" bfButton variant="text" href="mailto:support@example.com">
+          Contact support
+        </a>
+      </bf-empty-state>
+    </div>
+  `,
+})
+export class EmptyStateNotFoundPageExampleComponent {
+  protected readonly fileQuestion = FileQuestionMark;
+}
+```
+
 ## Theming
 
 - Icon tile: `surface-sunken` background, `text-muted` icon color, `tile` radius.
@@ -105,15 +188,15 @@ Set `headingLevel` to `3` when the empty state sits inside a section that alread
 
 ## Accessibility
 
-The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `3`, so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
+The title renders as an `<h2>` by default, an `<h3>` when `headingLevel` is `3` and an `<h1>` when it is `1` (only when the empty state is the page and the page has no other `h1`), so it slots into the surrounding page outline instead of always claiming the top level. The icon and action slots carry their own accessibility — an icon should stay decorative, and the action needs its own accessible name.
 
 ## Inputs
 
-| Name           | Type                                  | Default  | Description                                                          |
-| -------------- | ------------------------------------- | -------- | -------------------------------------------------------------------- |
-| `title`        | `string`                              | required | What is missing, as a short title.                                   |
-| `description`  | `string`                              | `''`     | One sentence on how to fill it.                                      |
-| `headingLevel` | `BfEmptyStateHeadingLevel` (`2 \| 3`) | `2`      | Heading level of the title so the empty state fits the page outline. |
+| Name           | Type                                  | Default  | Description                                                                                 |
+| -------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
+| `title`        | `string`                              | required | What is missing, as a short title.                                                          |
+| `description`  | `string`                              | `''`     | One sentence on how to fill it.                                                             |
+| `headingLevel` | `BfEmptyStateHeading` (`2 \| 3 \| 1`) | `2`      | Heading level of the title so the empty state fits the page outline; 1 when it is the page. |
 
 ## Slots
 
@@ -129,10 +212,20 @@ The title renders as an `<h2>` by default and an `<h3>` when `headingLevel` is `
 
 ### Don't
 
+- Don't set `headingLevel` to `1` on an empty state inside a page that already has its own `h1`.
 - Don't use `bf-empty-state` for a loading screen; that is `bf-spinner`.
 
 ## Migration notes
 
+### 0.3.2
+
+`headingLevel` now takes the new named type `BfEmptyStateHeading` (`BfEmptyStateHeadingLevel |
+1`): `1` renders the title as the page's `h1`, for an empty state that is the page (a not-found
+or no-access page). The released `BfEmptyStateHeadingLevel` keeps its two members, so `Record`s
+over it keep compiling. New "As the page" docs section with the `empty-state/page` example
+(centred in a tall area, a primary action and a secondary link) and the code-only
+`empty-state/not-found-page`.
+
 ### 0.3.0
 
 New exported `BfEmptyStateHeadingLevel` (`2 | 3`), the type of `headingLevel` (was an inline union