@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/list.md

@@ -69,7 +69,7 @@ Lists show rows of related items: settings, conversations, people. `bf-list` is
 
 ## When to use
 
-Use `bf-list` for a group of rows of the same kind: settings, conversations, people. Use [bf-card](https://bitforge-ui.web.app/components/card) instead for one piece of content with its own layout, and a native `table` for data the user compares across columns.
+Use `bf-list` for a group of rows of the same kind: settings, conversations, people. Use [bf-card](https://bitforge-ui.web.app/components/card) instead for one piece of content with its own layout, and [bf-table](https://bitforge-ui.web.app/components/table) for data the user compares across columns.
 
 ## Basic usage
 
@@ -128,9 +128,63 @@ import { BfCardComponent, BfListComponent, BfListItemComponent } from '@bitforge
 export class ListPlainExampleComponent {}
 ```
 
+## Divided
+
+`divided` separates the rows with a `border` line instead of a gap and squares off their surfaces, so the hover fill of a navigation or action row reaches the list's edges. It is off by default, so existing lists keep their look. On an inset list the rows become one rounded surface (only the first and last rows keep the card radius); on a plain list they sit flat on whatever holds them.
+
+## On a card
+
+To put rows on a card, use a plain divided list and pull it flush to the card's inline edges with `class="-mx-card"` (the card's `md` padding; `-mx-card-lg` on a `padding="lg"` card). The card stays the only container, the lines run edge to edge, and a row's hover fill reaches the card's edge instead of stopping at the card padding. A plain divided list gives its rows the card's inline padding, so their text stays on the card's content edge, aligned with the heading above.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfActionDirective,
+  BfBadgeComponent,
+  BfCardComponent,
+  BfListComponent,
+  BfListItemComponent,
+} from '@bitforgehq/ui';
+
+/**
+ * A divided list flush to a card's edges.
+ *
+ * `[inset]="false" divided` with `class="-mx-card"`: the lines and the rows' hover fill run to
+ * the card's edges, and the row text stays aligned with the heading.
+ */
+@Component({
+  selector: 'app-example-list-card',
+  imports: [
+    BfActionDirective,
+    BfBadgeComponent,
+    BfCardComponent,
+    BfListComponent,
+    BfListItemComponent,
+  ],
+  template: `
+    <bf-card class="max-w-md">
+      <h3 class="text-heading">Projects</h3>
+      <bf-list [inset]="false" divided class="-mx-card">
+        <bf-list-item subtitle="Due Friday" chevron>
+          <a bfSlot="title" bfAction href="#atlas">Atlas rebrand</a>
+        </bf-list-item>
+        <bf-list-item subtitle="Planning" chevron>
+          <a bfSlot="title" bfAction href="#harbor">Harbor onboarding</a>
+        </bf-list-item>
+        <bf-list-item subtitle="In review" chevron>
+          <a bfSlot="title" bfAction href="#lumen">Lumen reports</a>
+          <bf-badge bfSlot="trailing" variant="warning">2 open</bf-badge>
+        </bf-list-item>
+      </bf-list>
+    </bf-card>
+  `,
+})
+export class ListCardExampleComponent {}
+```
+
 ## Theming
 
-`inset` (default) uses the `bg` background on a `card` radius; `[inset]="false"` is transparent with no radius. The rows' own tokens are on the [`bf-list-item` page](https://bitforge-ui.web.app/components/list-item#theming).
+`inset` (default) uses the `bg` background on a `card` radius; `[inset]="false"` is transparent with no radius. `divided` draws the lines in `border`; a divided inset list is a `surface` with the `card` radius, and a divided plain list pads its rows with `--spacing-card` (`px-card`). The rows' own tokens are on the [`bf-list-item` page](https://bitforge-ui.web.app/components/list-item#theming).
 
 ## Accessibility
 
@@ -138,9 +192,10 @@ export class ListPlainExampleComponent {}
 
 ## Inputs
 
-| Name    | Type      | Default | Description                                                                      |
-| ------- | --------- | ------- | -------------------------------------------------------------------------------- |
-| `inset` | `boolean` | `true`  | Grouped look with the warm container; false renders rows on the page background. |
+| Name      | Type      | Default | Description                                                                                                                      |
+| --------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `inset`   | `boolean` | `true`  | Grouped look with the warm container; false renders rows on the page background.                                                 |
+| `divided` | `boolean` | `false` | Separates the rows with a `border` line instead of a gap, with square rows whose hover reaches the list's edges. Off by default. |
 
 ## Slots
 
@@ -151,15 +206,24 @@ export class ListPlainExampleComponent {}
 ### Do
 
 - Group rows that belong together in one `bf-list`; start a new list under a heading for a new group.
-- Use `[inset]="false"` on a card, so the card is the only container.
+- Use `[inset]="false"` on a card, so the card is the only container; add `divided` and `class="-mx-card"` for rows that run edge to edge.
 
 ### Don't
 
 - Don't put anything but `bf-list-item` rows in a `bf-list`; its `role="list"` expects list items.
 - Don't nest a `bf-list` inside a row.
+- Don't add your own borders or padding to the rows to separate them; use `divided`.
 
 ## Migration notes
 
+### 0.3.1
+
+New opt-in `divided` input: a `border` line between rows instead of a gap, with square rows whose
+hover fill reaches the list's edges. On a card, `<bf-list [inset]="false" divided class="-mx-card">`
+runs the rows edge to edge, and the rows take the card's inline padding so their text stays aligned
+with the card's content. A divided inset list is one rounded `surface`. Lists without `divided`
+look as before. When to use links `bf-table` for data compared across columns.
+
 ### 0.3.0
 
 JSDoc of `list.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.

package/ai/components/menu.md

@@ -619,6 +619,11 @@ From the [APG menu button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
 
 ## Migration notes
 
+### 0.3.1
+
+The menu's positions now come from the anchored-panel positioning the popover and tooltip share.
+No behaviour change.
+
 ### 0.3.0
 
 New `changed` output on `bfMenuItemCheckbox`: the new `checked` state right after the user toggles

package/ai/components/multi-combobox.md

@@ -0,0 +1,257 @@
+# bf-multi-combobox
+
+Text field that filters options as you type and picks several as tags
+
+`BfMultiComboboxComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfMultiComboboxComponent, type BfComboboxOption } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-multi-combobox overview.
+ *
+ * Live demo of `bf-multi-combobox`: tag a task with labels. Typing filters the labels, `Enter` or
+ * a click adds the active one as a tag (or removes it when it is a tag already) and the list
+ * stays open for the next; each tag's button removes it, and `Backspace` in the empty field
+ * removes the last one. The result line lists the labels.
+ */
+@Component({
+  selector: 'app-example-multi-combobox-overview',
+  imports: [BfMultiComboboxComponent],
+  template: `
+    <div class="flex max-w-md flex-col gap-3">
+      <bf-multi-combobox
+        label="Labels"
+        placeholder="Add labels"
+        [options]="labels"
+        [(value)]="picked"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class MultiComboboxOverviewExampleComponent {
+  protected readonly labels: readonly BfComboboxOption[] = [
+    { value: 'bug', label: 'Bug' },
+    { value: 'design', label: 'Design' },
+    { value: 'docs', label: 'Documentation' },
+    { value: 'perf', label: 'Performance' },
+    { value: 'a11y', label: 'Accessibility' },
+    { value: 'security', label: 'Security' },
+  ];
+  readonly picked = signal<readonly string[]>(['design']);
+
+  readonly status = computed(() => {
+    const names = this.labels.filter((l) => this.picked().includes(l.value)).map((l) => l.label);
+    return names.length ? `Labels: ${names.join(', ')}.` : 'No labels.';
+  });
+}
+```
+
+## Overview
+
+Text field with a filtered list of options to pick several values from, shown as removable tags
+inside the field (the ARIA combobox pattern with a multi-select listbox). Typing filters the
+list by label, ignoring case and accents; `Enter` or a click adds or removes the active option
+and the list stays open. Generic over the option value (a string by default); the value is an
+array, empty while nothing is picked. For one value use `bf-combobox`.
+
+A text field with a list of options that filters as you type, to pick several values, shown as
+removable tags inside the field: labels for a task, reviewers, skills. The same
+[ARIA 1.2 combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) pattern as `bf-combobox`,
+with a multi-select listbox: the list stays open after each pick, and picked options carry a check
+mark. Its value is an array (`readonly T[]`, empty while nothing is picked), bound with
+`[(value)]` or `[formField]`.
+
+Import `BfMultiComboboxComponent` and `BfComboboxOption` from `@bitforgehq/ui/overlay` (needs
+`@angular/cdk`).
+
+## When to use
+
+Use `bf-multi-combobox` to pick any number of values from a list long enough to search. Use
+[bf-combobox](https://bitforge-ui.web.app/components/combobox) instead for one value, [bf-chip](https://bitforge-ui.web.app/components/chip) filter
+chips for a few options shown all at once, and checkboxes in a
+[bf-popover](https://bitforge-ui.web.app/components/popover) for a short list of filters. Both work in both shells; in a
+Capacitor app set `provideBfDefaults({ fieldSize: 'lg' })` for 48 px fields.
+
+## Tags
+
+Each picked value is a tag before the text, in the order it was picked. A tag's button (named
+"Remove …" by the `comboboxRemove` label) removes it and puts focus back in the field, and
+`Backspace` in the empty field removes the last tag. `(changed)` emits the new array after each
+add and remove. The field grows in height as the tags wrap, and the open list follows its bottom
+edge. While `disabled` or `readonly` the tags have no remove buttons.
+
+## Typing and picking
+
+Typing filters the options by label, ignoring case and accents, and opens the list. `Enter` or a
+click on the active option adds it, or removes it when it is a tag already; the typed text clears
+and the list stays open for the next pick. `Escape` closes the list, a second `Escape` drops the
+typed text, and leaving the field drops it too. Options take a `description`, `disabled` and
+`group` (listed under a heading), as on `bf-combobox`.
+
+`filter`, `(queried)`, `loading` and `[filter]="null"` work as on `bf-combobox` for a server
+search; the field keeps the labels of picked values that later results no longer hold.
+
+## With Signal Forms
+
+Model the field as `readonly T[]`, starting at `[]`, and bind it with `[formField]`. `placeholder`
+shows while nothing is picked. For object values pass `compareWith`, as on `bf-combobox`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form } from '@angular/forms/signals';
+import { BfMultiComboboxComponent, type BfComboboxOption } from '@bitforgehq/ui/overlay';
+
+interface Person {
+  id: number;
+  name: string;
+}
+
+/**
+ * A multi combobox bound to a Signal Forms field.
+ *
+ * The field holds an array of objects, starting with one reviewer; `compareWith` matches them to
+ * the options by id, so reviewers reloaded from a server still show as tags and check marks.
+ */
+@Component({
+  selector: 'app-example-multi-combobox-forms',
+  imports: [BfMultiComboboxComponent, FormField],
+  template: `
+    <bf-multi-combobox
+      class="max-w-md"
+      label="Reviewers"
+      placeholder="Add reviewers"
+      helpText="Each reviewer gets a notification."
+      [options]="people"
+      [compareWith]="sameId"
+      [formField]="review.reviewers"
+    />
+  `,
+})
+export class MultiComboboxFormsExampleComponent {
+  protected readonly people: readonly BfComboboxOption<Person>[] = [
+    { value: { id: 1, name: 'Ada' }, label: 'Ada Lovelace' },
+    { value: { id: 2, name: 'Grace' }, label: 'Grace Hopper' },
+    { value: { id: 3, name: 'Katherine' }, label: 'Katherine Johnson' },
+  ];
+  protected readonly sameId = (a: Person, b: Person): boolean => a.id === b.id;
+  private readonly model = signal<{ reviewers: readonly Person[] }>({
+    reviewers: [{ id: 2, name: 'Grace' }],
+  });
+  protected readonly review = form(this.model);
+}
+```
+
+## Desktop
+
+The field keeps focus while the arrow keys move through the list; the pointer moving over an
+option makes it the active one. A press anywhere on the field's box (around the tags) puts the
+caret in the field and opens the list. Under a fine pointer a tag's remove button is 24 px; under a
+coarse pointer its hit area grows to 44 px and every option row is at least 44 px tall.
+
+## Theming
+
+- Field: the `bf-input` tokens on the box around the tags: `border-strong` border
+  (`danger-border` on error), `primary` border and `ring` ring while the field has focus,
+  `surface-muted` while read-only or disabled, a `text-subtle` chevron.
+- Tags: `primary-soft` with `primary-strong` text (the selected tonal chip's colours);
+  the remove button hovers `primary-soft-hover` and presses `primary-soft-pressed`.
+- List: as on `bf-combobox`, with a check mark on each picked option.
+
+## Accessibility
+
+- The input is `role="combobox"` with `aria-autocomplete="list"`, `aria-expanded`,
+  `aria-controls` and `aria-activedescendant`, as on `bf-combobox`; the listbox has
+  `aria-multiselectable="true"` and every picked option `aria-selected="true"`.
+- Each tag's remove button is a native button named "Remove" plus the tag's label, in the tab
+  order before the input.
+- Labels, help and error text, `aria-describedby`, `aria-invalid` and `aria-errormessage` follow
+  `bf-select`. `required` sets the native attribute only while no tag is picked.
+
+### Keyboard
+
+| Key                                                  | Where         | Action                                                          |
+| ---------------------------------------------------- | ------------- | --------------------------------------------------------------- |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>            | Field         | Opens the list on the first tag's option (else first / last)    |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>            | Open list     | Next / previous enabled option, wrapping at the ends            |
+| <kbd>Home</kbd> / <kbd>End</kbd>                     | Open list     | First / last enabled option                                     |
+| <kbd>Enter</kbd>                                     | Open list     | Adds the active option, or removes it; the list stays open      |
+| <kbd>Backspace</kbd>                                 | Empty field   | Removes the last tag                                            |
+| <kbd>Escape</kbd>                                    | Open list     | Closes the list                                                 |
+| <kbd>Escape</kbd>                                    | Field         | Drops the typed text                                            |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd>     | Field         | Moves on (or back to the tags' remove buttons); the list closes |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                  | Remove button | Removes that tag                                                |
+| <kbd>A</kbd>–<kbd>Z</kbd>, <kbd>0</kbd>–<kbd>9</kbd> | Field         | Filters the list and opens it                                   |
+
+## Inputs
+
+| Name             | Type                                                        | Default         | Description                                                                                                                                                                |
+| ---------------- | ----------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | `readonly BfComboboxOption<T>[]`                            | required        | The options to choose from; with server search, the latest results.                                                                                                        |
+| `compareWith`    | `BfCompareWith<T>`                                          | `Object.is`     | Equality for matching `value` to an option (default `Object.is`); pass one for object values.                                                                              |
+| `filter`         | `BfComboboxFilter<T> \| null`                               | `labelContains` | Whether an option matches the typed text (default: its label contains it, ignoring case and accents); `null` shows `options` unfiltered, for results filtered by a server. |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined`     | Height step of the field (its minimum height): sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                 |
+| `label`          | `string`                                                    | `''`            | Visible label above the field.                                                                                                                                             |
+| `ariaLabel`      | `string`                                                    | `''`            | Accessible name when no visible label is rendered. Ignored when `label` is set.                                                                                            |
+| `ariaLabelledby` | `string`                                                    | `''`            | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                                                |
+| `placeholder`    | `string`                                                    | `''`            | Hint text shown while nothing is picked.                                                                                                                                   |
+| `helpText`       | `string`                                                    | `''`            | Helper text under the field.                                                                                                                                               |
+| `errorMessage`   | `string`                                                    | `''`            | Explicit error text; takes precedence over Signal Forms errors.                                                                                                            |
+| `emptyLabel`     | `string`                                                    | `''`            | Text of the list's row when no option matches; empty uses the `comboboxEmpty` label.                                                                                       |
+| `loading`        | `boolean`                                                   | `false`         | Shows a loading row in the list, while a server search for the typed text runs.                                                                                            |
+| `disabled`       | `boolean`                                                   | `false`         | Disables the field and its tags. Set by `[formField]`; do not bind it yourself.                                                                                            |
+| `readonly`       | `boolean`                                                   | `false`         | Shows the tags but blocks changes: no remove buttons, and the list never opens. Set by `[formField]`; do not bind it yourself.                                             |
+| `required`       | `boolean`                                                   | `false`         | Marks the field required (at least one value). Set by `[formField]`; do not bind it yourself.                                                                              |
+| `invalid`        | `boolean`                                                   | `false`         | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                           |
+| `touched`        | `boolean`                                                   | `false`         | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                                                        |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`            | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                        |
+| `name`           | `string`                                                    | `''`            | Native name attribute of the text input. Set by `[formField]`; do not bind it yourself.                                                                                    |
+| `id`             | `string`                                                    | `generated`     | Input id; generated when not set.                                                                                                                                          |
+| `value`          | `readonly T[]`                                              | `[]`            | The picked options' values in the order they were picked, empty while nothing is picked; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.                |
+
+## Outputs
+
+| Name      | Payload        | Description                                                                                               |
+| --------- | -------------- | --------------------------------------------------------------------------------------------------------- |
+| `changed` | `readonly T[]` | Emitted with the new values after the user adds or removes one.                                           |
+| `queried` | `string`       | Emitted with the typed text each time the user changes it (`''` once it is cleared), for a server search. |
+| `focused` | `FocusEvent`   | Emitted when the input gains focus.                                                                       |
+| `blurred` | `FocusEvent`   | Emitted when the input loses focus.                                                                       |
+| `touch`   | `void`         | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself.   |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the input; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Keep tag labels short; long ones truncate with an ellipsis.
+- Show the picked values somewhere else too when the field is narrow and many are picked.
+
+### Don't
+
+- Don't use it for one value; use `bf-combobox`.
+- Don't make it the only way to see a long list of picks; tags wrap but get hard to scan.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-multi-combobox` (`BfMultiComboboxComponent<T>`) in `@bitforgehq/ui/overlay`: the
+combobox for several values, `[(value)]` a `readonly T[]`. Picked values are tags inside the
+field, each with a remove button named by the new `comboboxRemove(label)` label ("Remove
+Design"); `Backspace` in the empty field removes the last tag, the list stays open after a pick
+and picked options carry a check mark (`aria-multiselectable`, `aria-selected`). Same options,
+filtering, server search and Signal Forms contract as `bf-combobox`.

package/ai/components/nav-group.md

@@ -0,0 +1,178 @@
+# bf-nav-group
+
+A titled group of sidebar links with a small heading that names it
+
+`BfNavGroupComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavGroupComponent, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-nav-group overview.
+ *
+ * Live demo of `bf-nav-group`: two titled groups of `a[bfNavItem]` router links in a sidebar;
+ * each heading names its group for screen readers.
+ */
+@Component({
+  selector: 'app-example-nav-group-overview',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfNavGroupComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <bf-sidebar label="Component groups">
+      <bf-nav-group label="Navigation">
+        <a
+          bfNavItem
+          routerLink="/components/nav-group"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+          >Nav group</a
+        >
+        <a bfNavItem routerLink="/components/nav-item" routerLinkActive ariaCurrentWhenActive="page"
+          >Nav item</a
+        >
+      </bf-nav-group>
+      <bf-nav-group label="Data display">
+        <a bfNavItem routerLink="/components/list" routerLinkActive ariaCurrentWhenActive="page"
+          >List</a
+        >
+        <a bfNavItem routerLink="/components/card" routerLinkActive ariaCurrentWhenActive="page"
+          >Card</a
+        >
+      </bf-nav-group>
+    </bf-sidebar>
+  `,
+})
+export class NavGroupOverviewExampleComponent {}
+```
+
+## Overview
+
+A titled group of `a[bfNavItem]` links inside a `bf-sidebar`: `label` is shown as a small
+heading above them and names the group (`role="group"`) for screen readers, also while the
+sidebar is collapsed and the heading is hidden.
+
+A titled group of [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links inside a [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar): its `label` is a small heading above the links and the group's accessible name.
+
+## When to use
+
+Use `bf-nav-group` to split a long sidebar into sections, such as Workspace and Admin. Leave a short sidebar ungrouped, with the links straight in `bf-sidebar`. 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.
+
+## Basic usage
+
+Put the group's links in its default slot and its name in `label`. Groups stack with 24 px between them.
+
+## In a collapsed sidebar
+
+While the sidebar is collapsed to an icon rail the heading is hidden visually (`sr-only`), so only the icons show, and it still names the group for screen readers.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavGroupComponent, BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Layers, LayoutList, PanelTop, SquareStack } from 'lucide';
+
+/**
+ * Groups in a collapsed sidebar.
+ *
+ * The headings are hidden visually and still name their groups for screen readers; the items
+ * show their icons only.
+ */
+@Component({
+  selector: 'app-example-nav-group-collapsed',
+  imports: [
+    RouterLink,
+    RouterLinkActive,
+    BfIconComponent,
+    BfNavGroupComponent,
+    BfNavItemComponent,
+    BfSidebarComponent,
+  ],
+  template: `
+    <bf-sidebar label="Component groups, collapsed" [collapsed]="true">
+      <bf-nav-group label="Navigation">
+        <a
+          bfNavItem
+          routerLink="/components/nav-group"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="layers" />
+          Nav group
+        </a>
+        <a bfNavItem routerLink="/components/sidebar" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="panelTop" />
+          Sidebar
+        </a>
+      </bf-nav-group>
+      <bf-nav-group label="Data display">
+        <a bfNavItem routerLink="/components/list" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="list" />
+          List
+        </a>
+        <a bfNavItem routerLink="/components/card" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="card" />
+          Card
+        </a>
+      </bf-nav-group>
+    </bf-sidebar>
+  `,
+})
+export class NavGroupCollapsedExampleComponent {
+  protected readonly layers = Layers;
+  protected readonly panelTop = PanelTop;
+  protected readonly list = LayoutList;
+  protected readonly card = SquareStack;
+}
+```
+
+## Desktop
+
+The group itself is static; its links carry the hover, pressed and focus styles described on the [nav item](https://bitforge-ui.web.app/components/nav-item) page.
+
+## Theming
+
+- Heading: `text-caption` in `text-muted`, inset 12 px to line up with the item labels.
+- Items: 4 px apart.
+
+## Accessibility
+
+The host has `role="group"` and `aria-labelledby` pointing at its heading, so a screen reader announces the group's name when focus enters it ("Workspace, group"). The heading is text, not a heading element, so it does not add to the page outline. Collapsed, the heading is `sr-only` and keeps naming the group.
+
+## Inputs
+
+| Name    | Type     | Default  | Description                                                   |
+| ------- | -------- | -------- | ------------------------------------------------------------- |
+| `label` | `string` | required | The group's heading and accessible name, such as "Workspace". |
+
+## Slots
+
+- `default`: The group's `a[bfNavItem]` links.
+
+## Notes
+
+### Do
+
+- Give each group a short noun as its label.
+- Keep the links of one area together in a group.
+
+### Don't
+
+- Don't nest groups; a sidebar has one level of groups.
+- Don't put a group in a `bf-top-nav`; a top nav is a single row.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-nav-group`: a titled group of sidebar links, `role="group"` named by its small heading,
+which stays the group's name (hidden visually) while the sidebar is collapsed.