@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/toolbar.md

@@ -0,0 +1,289 @@
+# bf-toolbar
+
+Dense row of search, filters, view switch, result count and actions
+
+`BfToolbarComponent` from `@bitforgehq/ui` · Actions · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSegmentedComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSegmentOption,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+type ProjectStatus = 'active' | 'paused' | 'done';
+type StatusFilter = ProjectStatus | 'all';
+type View = 'list' | 'grid';
+
+interface Project {
+  readonly name: string;
+  readonly status: ProjectStatus;
+}
+
+/**
+ * The bf-toolbar overview.
+ *
+ * Live demo of `bf-toolbar`: a search field and a status filter narrow a list of projects, a
+ * view switch lays it out as a list or a grid, the toolbar's status announces the count, and a
+ * primary action adds a project. Every control in the row is `sm` from the toolbar's density.
+ */
+@Component({
+  selector: 'app-example-toolbar-overview',
+  imports: [
+    BfButtonComponent,
+    BfInputComponent,
+    BfSegmentedComponent,
+    BfSelectComponent,
+    BfToolbarComponent,
+  ],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-toolbar label="Project filters" [status]="count()">
+        <bf-input
+          type="search"
+          ariaLabel="Search projects"
+          placeholder="Search projects"
+          class="w-full sm:w-56"
+          [(value)]="query"
+        />
+        <bf-select
+          ariaLabel="Status"
+          class="w-full sm:w-40"
+          [options]="statuses"
+          [(value)]="filter"
+        />
+        <bf-segmented bfSlot="view" label="View" [options]="views" [(value)]="view" />
+        <bf-button bfSlot="actions" (clicked)="add()">New project</bf-button>
+      </bf-toolbar>
+      <ul [class]="view() === 'grid' ? 'grid grid-cols-2 gap-2' : 'flex flex-col gap-1'">
+        @for (project of visible(); track project.name) {
+          <li class="bg-surface rounded-field text-body px-3 py-2">{{ project.name }}</li>
+        }
+      </ul>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ToolbarOverviewExampleComponent {
+  protected readonly query = signal('');
+  protected readonly filter = signal<StatusFilter | null>('all');
+  protected readonly view = signal<View | null>('list');
+  protected readonly projects = signal<readonly Project[]>([
+    { name: 'Atlas rebrand', status: 'active' },
+    { name: 'Billing revamp', status: 'active' },
+    { name: 'Carbon audit', status: 'paused' },
+    { name: 'Docs refresh', status: 'done' },
+    { name: 'Onboarding flow', status: 'active' },
+  ]);
+
+  protected readonly statuses: BfSelectOption<StatusFilter>[] = [
+    { value: 'all', label: 'All statuses' },
+    { value: 'active', label: 'Active' },
+    { value: 'paused', label: 'Paused' },
+    { value: 'done', label: 'Done' },
+  ];
+  protected readonly views: BfSegmentOption<View>[] = [
+    { value: 'list', label: 'List' },
+    { value: 'grid', label: 'Grid' },
+  ];
+
+  protected readonly visible = computed(() => {
+    const query = this.query().trim().toLowerCase();
+    const filter = this.filter() ?? 'all';
+    return this.projects().filter(
+      (p) =>
+        (filter === 'all' || p.status === filter) &&
+        (!query || p.name.toLowerCase().includes(query)),
+    );
+  });
+
+  protected readonly count = computed(() => {
+    const n = this.visible().length;
+    return n === 1 ? '1 project' : `${n} projects`;
+  });
+
+  protected readonly status = computed(
+    () => `Showing ${this.visible().length} of ${this.projects().length} · ${this.view()} view`,
+  );
+
+  protected add(): void {
+    const next = this.projects().length + 1;
+    this.projects.update((list) => [...list, { name: `Project ${next}`, status: 'active' }]);
+  }
+}
+```
+
+## Overview
+
+Row of search, filters, a view switch and trailing actions above a list or table. Every
+control projected into it is `sm` unless it sets `size` itself.
+
+A dense row above a list or table: the search field and filters, a view switch, a live result count and the trailing actions. `bf-toolbar` lays the row out, wraps it in a narrow column and makes every control in it `sm`; the controls themselves are ordinary `bf-input`, `bf-select`, `bf-chip-group`, `bf-segmented` and `bf-button`s.
+
+## When to use
+
+Use `bf-toolbar` on a desktop page for the controls that narrow or act on the collection below it: search, filters, list or grid, "New". Use [bf-action-bar](https://bitforge-ui.web.app/components/action-bar) instead for actions on a selection while it lasts. In the Capacitor shell, put the main action in [bf-header](https://bitforge-ui.web.app/components/header) actions and move filters into a [bf-sheet](https://bitforge-ui.web.app/components/sheet) instead.
+
+## Layout
+
+Project the search field and the filters as content, in the order they read. `bfSlot="view"` takes a view switch after them, and `bfSlot="actions"` the trailing actions, pushed to the inline end. Each field needs its own `ariaLabel` (or `label`), since the row shows no field labels. Bind `status` to the result count.
+
+## Status
+
+`status` renders a polite live region (`role="status"`) after the view switch, in muted caption text. Keep it short and countable ("24 results", "No matches"); it is announced each time it changes, without moving focus. The region is always in the DOM, so the first count after an empty one is announced too; while it is empty it takes no space.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfChipComponent, BfChipGroupComponent, BfToolbarComponent } from '@bitforgehq/ui';
+
+type Filter = 'all' | 'open' | 'done';
+
+interface Task {
+  readonly title: string;
+  readonly done: boolean;
+}
+
+/**
+ * A result count in the status line.
+ *
+ * The toolbar's `status` is a polite live region: picking a filter changes the count, and a
+ * screen reader announces it without moving focus.
+ */
+@Component({
+  selector: 'app-example-toolbar-status',
+  imports: [BfChipComponent, BfChipGroupComponent, BfToolbarComponent],
+  template: `
+    <bf-toolbar label="Task filters" [status]="count()">
+      <bf-chip-group label="Status" [(value)]="filter">
+        <bf-chip variant="ink" value="all">All</bf-chip>
+        <bf-chip variant="ink" value="open">Open</bf-chip>
+        <bf-chip variant="ink" value="done">Done</bf-chip>
+      </bf-chip-group>
+    </bf-toolbar>
+  `,
+})
+export class ToolbarStatusExampleComponent {
+  protected readonly filter = signal<Filter | null>('all');
+  private readonly tasks: readonly Task[] = [
+    { title: 'Draft the brief', done: true },
+    { title: 'Review the logo', done: false },
+    { title: 'Book the venue', done: false },
+  ];
+
+  protected readonly count = computed(() => {
+    const filter = this.filter() ?? 'all';
+    const n = this.tasks.filter((t) => filter === 'all' || t.done === (filter === 'done')).length;
+    return n === 1 ? '1 task' : `${n} tasks`;
+  });
+}
+```
+
+## Wrapping
+
+The row is a wrapping flex row with an 8 px gap between items and between rows. In a narrow column the filters wrap onto new rows, and the actions wrap as one group, kept together at the inline end. Give a search field a width (`class="w-full sm:w-56"`) so it fills a phone-wide row and stays compact on a wide one.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfInputComponent,
+  BfSelectComponent,
+  BfToolbarComponent,
+  type BfSelectOption,
+} from '@bitforgehq/ui';
+
+/**
+ * A toolbar that wraps.
+ *
+ * In a narrow column the filters wrap onto new rows 8 px apart, and the actions move down
+ * together, still at the inline end.
+ */
+@Component({
+  selector: 'app-example-toolbar-wrapping',
+  imports: [BfButtonComponent, BfInputComponent, BfSelectComponent, BfToolbarComponent],
+  template: `
+    <div class="max-w-sm">
+      <bf-toolbar label="Invoice filters" status="18 invoices">
+        <bf-input type="search" ariaLabel="Search invoices" placeholder="Search invoices" />
+        <bf-select ariaLabel="Customer" [options]="customers" value="all" />
+        <bf-select ariaLabel="Period" [options]="periods" value="month" />
+        <bf-button bfSlot="actions" variant="outline">Export</bf-button>
+        <bf-button bfSlot="actions">New invoice</bf-button>
+      </bf-toolbar>
+    </div>
+  `,
+})
+export class ToolbarWrappingExampleComponent {
+  protected readonly customers: BfSelectOption[] = [
+    { value: 'all', label: 'All customers' },
+    { value: 'acme', label: 'Acme' },
+  ];
+  protected readonly periods: BfSelectOption[] = [
+    { value: 'month', label: 'This month' },
+    { value: 'year', label: 'This year' },
+  ];
+}
+```
+
+## Desktop
+
+`bf-toolbar` is a desktop pattern. Every control and field projected into it resolves its unset `size` to `sm` (32 px tall), because its `providers` set `provideBfDefaults({ size: 'sm' })` for its content; a control that sets `size` itself keeps it, and nothing outside the toolbar changes ([density guide](https://bitforge-ui.web.app/density)). Hover, the pointer cursor and the `focus-visible` ring come from each control; the row adds none of its own. Under a fine pointer each control's visual box is its hit area; under a coarse pointer the `sm` touch extensions reach up to 7.5 px past the visual edge, which the 8 px gap keeps off the neighbouring row.
+
+Place it directly under `bf-page-header` and above the `bf-table` or `bf-list` it filters, with the page's own vertical gap (`gap-4`) between them: the page header names the page and holds its page-level actions, the toolbar holds what narrows the collection, and the count in `status` describes the rows below.
+
+## Theming
+
+The row has no surface, border or radius of its own; it sits on the page background, and each projected control themes itself.
+
+- Status text: `text-caption` in `text-muted`.
+- Layout: `gap-2` (8 px) between items and rows, in logical properties, so under `dir="rtl"` the row mirrors and the actions sit at the left end.
+
+## Accessibility
+
+The host is `role="group"`, named by `aria-label` from `label` ("Project filters"). It is a group, not `role="toolbar"`: that role promises arrow-key movement between its controls with one tab stop, and the search field needs the arrow keys to move its caret, so each control keeps its own tab stop and its own keys. Without `label` the group is left unnamed rather than given a generic default: a page has one toolbar under a heading that already names the context, and a stock name such as "Toolbar" would add noise to every focus entry without telling the user anything. Pass a `label` when the page has more than one toolbar.
+
+The `status` element is `role="status"` (an `aria-live="polite"` region), always rendered, so a changed count is read after the user's current input finishes. The toolbar sets no focus and handles no keys; <kbd>Tab</kbd> moves through the projected controls in DOM order (filters, view switch, actions).
+
+## Inputs
+
+| Name     | Type     | Default | Description                                                                            |
+| -------- | -------- | ------- | -------------------------------------------------------------------------------------- |
+| `label`  | `string` | `''`    | The group's accessible name, such as "Project filters"; unnamed when empty.            |
+| `status` | `string` | `''`    | The result count or a short state, such as "24 results", announced politely on change. |
+
+## Slots
+
+- `default`: The search field and the filters (bf-input, bf-select, bf-chip-group), in order.
+- `view`: A view switch after the filters, such as a bf-segmented of list and grid.
+- `actions`: The trailing actions, kept together at the inline end of the row.
+
+## Notes
+
+### Do
+
+- Name each field with `ariaLabel` (or a `label`), and keep the order: search, filters, view, actions.
+- Bind `status` to the number of rows the filters leave, and update it as they change.
+
+### Don't
+
+- Don't put the page's title or page-level actions in it; they belong in `bf-page-header`.
+- Don't use it in the Capacitor shell; use `bf-header` actions and a `bf-sheet` of filters.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-toolbar` in `@bitforgehq/ui`: a wrapping `role="group"` row for the search field and
+filters (default slot), a view switch (`bfSlot="view"`) and the trailing actions
+(`bfSlot="actions"`, kept together at the inline end). `label` names the group; `status` renders
+a polite `role="status"` live region for the result count. Its providers set
+`provideBfDefaults({ size: 'sm' })`, so every projected control and field is `sm` unless it sets
+`size` itself. Desktop only; in the Capacitor shell use `bf-header` actions and a `bf-sheet` of
+filters.

package/ai/components/tooltip.md

@@ -0,0 +1,230 @@
+# bf-tooltip
+
+Short hint beside a control on hover or keyboard focus, for desktop
+
+`BfTooltipComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconButtonComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfTooltipDirective } from '@bitforgehq/ui/overlay';
+import { Bold, Italic, Link, Underline } from 'lucide';
+
+/**
+ * The bf-tooltip overview.
+ *
+ * Live demo of `bfTooltip`: a formatting toolbar of icon buttons, each named by its `label` and
+ * showing the same name, with its keyboard shortcut, in a tooltip on hover or keyboard focus. The
+ * result line reports each press.
+ */
+@Component({
+  selector: 'app-example-tooltip-overview',
+  imports: [BfIconButtonComponent, BfIconComponent, BfTooltipDirective],
+  template: `
+    <div class="flex flex-col gap-3">
+      <div role="group" aria-label="Formatting" class="flex flex-wrap items-center gap-2">
+        <bf-icon-button
+          label="Bold"
+          variant="text"
+          bfTooltip="Bold (Ctrl+B)"
+          (clicked)="press('Bold')"
+        >
+          <bf-icon [icon]="bold" />
+        </bf-icon-button>
+        <bf-icon-button
+          label="Italic"
+          variant="text"
+          bfTooltip="Italic (Ctrl+I)"
+          (clicked)="press('Italic')"
+        >
+          <bf-icon [icon]="italic" />
+        </bf-icon-button>
+        <bf-icon-button
+          label="Underline"
+          variant="text"
+          bfTooltip="Underline (Ctrl+U)"
+          (clicked)="press('Underline')"
+        >
+          <bf-icon [icon]="underline" />
+        </bf-icon-button>
+        <bf-icon-button
+          label="Insert link"
+          variant="text"
+          bfTooltip="Insert link (Ctrl+K)"
+          (clicked)="press('Insert link')"
+        >
+          <bf-icon [icon]="link" />
+        </bf-icon-button>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TooltipOverviewExampleComponent {
+  readonly bold = Bold;
+  readonly italic = Italic;
+  readonly underline = Underline;
+  readonly link = Link;
+  readonly status = signal('Hover or tab to a button for its tooltip.');
+
+  press(label: string): void {
+    this.status.set(`Pressed ${label}.`);
+  }
+}
+```
+
+## Overview
+
+The small dark pill of a tooltip (role `tooltip`). A `[bfTooltip]` directive renders it in the
+CDK overlay beside its element while the pointer rests on it or it has keyboard focus, so you
+rarely place it yourself; the directive is how you add a tooltip.
+
+Short hints for desktop and web apps, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no
+Capacitor). Put `bfTooltip="Text"` on a control and a small dark `bf-tooltip` pill shows beside it
+when a mouse rests on it for half a second, or at once when it gets keyboard focus. It hides when
+the pointer leaves, on blur and on `Escape`. While it shows, the control is described by it
+(`aria-describedby`), so a screen reader reads the hint after the control's name. The pill
+renders in the CDK overlay container, so it works inside a `BfDialogService` dialog.
+
+Import `BfTooltipDirective` from `@bitforgehq/ui/overlay`. You rarely place `bf-tooltip`
+(`BfTooltipComponent`) yourself: the directive renders it.
+
+## When to use
+
+Use a tooltip to repeat the name of an icon-only control (`bf-icon-button`, a collapsed sidebar
+link) for mouse users, or to add a keyboard shortcut to it. A tooltip never holds information
+found nowhere else: touch screens never show it, so the control's own name and the page must say
+everything that matters. Use [bf-popover](https://bitforge-ui.web.app/components/popover) instead for content a user reads at
+length or interacts with (links, fields, buttons), [bf-field](https://bitforge-ui.web.app/components/field) help text for
+guidance on a form field, and in a Capacitor app the control's visible label.
+
+## Placement
+
+`bfTooltipPlacement` puts the tooltip on the `top` (default), `bottom`, `start` or `end` side of
+its element, centred along it, 8 px away. `start` and `end` follow the text direction, so they
+swap sides in right-to-left pages. A tooltip without room on its side flips to the opposite side
+first, then to the other two. The placement is read each time the tooltip shows.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfTooltipDirective, type BfTooltipPlacement } from '@bitforgehq/ui/overlay';
+
+/**
+ * Tooltips on each side of their button.
+ *
+ * `bfTooltipPlacement` puts the tooltip on the `top` (default), `bottom`, `start` or `end` side;
+ * `start` and `end` follow the text direction, and a tooltip without room flips to the other side.
+ */
+@Component({
+  selector: 'app-example-tooltip-placement',
+  imports: [BfButtonComponent, BfTooltipDirective],
+  template: `
+    <div class="flex flex-wrap items-center justify-center gap-3 py-8">
+      @for (side of sides; track side) {
+        <bf-button
+          variant="outline"
+          size="sm"
+          [bfTooltip]="'Shown on the ' + side + ' side'"
+          [bfTooltipPlacement]="side"
+        >
+          {{ side }}
+        </bf-button>
+      }
+    </div>
+  `,
+})
+export class TooltipPlacementExampleComponent {
+  protected readonly sides: readonly BfTooltipPlacement[] = ['top', 'bottom', 'start', 'end'];
+}
+```
+
+## Text
+
+Keep the text to a few words on one line: the name of the control, and maybe its shortcut
+("Bold (Ctrl+B)"). Longer text wraps at 20 rem. A bound text that changes while the tooltip shows
+("Copy link", then "Copied") updates it in place; an empty text shows no tooltip.
+
+On an icon-only `bf-icon-button` the tooltip repeats its `label`: the `label` stays the accessible
+name, and the tooltip describes the button. A collapsed `bf-sidebar` link (`a[bfNavItem]`) shows
+its name in the browser's `title` tooltip; add `bfTooltip` with the same text and
+`bfTooltipPlacement="end"` for a styled one that also shows on keyboard focus. Bind it to an empty
+text while the sidebar is expanded, where the label is visible.
+
+## Desktop
+
+Built for a mouse and a keyboard. Hovering shows the tooltip after a 500 ms rest, so a pointer
+that only passes over a toolbar shows nothing; moving the pointer from the control onto the
+tooltip keeps it open (so it can be read under a magnifier). Keyboard focus (`focus-visible`)
+shows it at once; a mouse click that focuses the control does not. The tooltip fades in over
+120 ms, without the fade when the system asks for reduced motion.
+
+Under a coarse pointer (`(pointer: coarse)`, touch screens and the Capacitor shell) no tooltip
+ever shows: there is no hover there, and a tooltip after a tap would sit under the finger. That
+is why a tooltip never carries information found nowhere else.
+
+## Theming
+
+- Pill: `bg-tooltip` with `text-on-tooltip` (14.9:1 in light, 13.8:1 in dark; the pill is dark
+  on a light page and light on a dark one), `rounded-field`, `shadow-raised`, `text-label-xs`,
+  10 px by 4 px padding, at most 20 rem wide.
+- Under forced colours (Windows High Contrast) the pill drops its fill and draws a 1 px border in
+  the text colour.
+
+## Accessibility
+
+- The pill is `role="tooltip"` with an id. While it shows, the control (the host, or the first
+  control inside it, such as the button of a `bf-icon-button`) gets that id added to its
+  `aria-describedby`, next to any ids it already has; the id is removed when the tooltip hides.
+- A tooltip is a description, never the name: an icon-only button keeps its `label` or
+  `aria-label`.
+- WCAG 1.4.13 (content on hover or focus): the tooltip can be dismissed with `Escape` without
+  moving the pointer or focus, stays while the pointer is over it, and stays until the pointer
+  leaves, focus leaves or `Escape` is pressed.
+- `Escape` goes to the tooltip first: inside a dialog or a popover, the first `Escape` hides the
+  tooltip and the next one closes the dialog.
+- A disabled native button fires no pointer events, so its tooltip never shows; explain why a
+  control is disabled in the page instead.
+
+### Keyboard
+
+| Key                                              | Action                                                   |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Focusing the control shows its tooltip; leaving hides it |
+| <kbd>Escape</kbd>                                | Hides the tooltip, focus stays where it is               |
+
+## Inputs
+
+| Name   | Type     | Default | Description                                                                |
+| ------ | -------- | ------- | -------------------------------------------------------------------------- |
+| `text` | `string` | `''`    | The tooltip's text: a few words that repeat or explain the control's name. |
+
+## Notes
+
+### Do
+
+- Repeat the name of icon-only controls, and add their keyboard shortcut.
+- Keep the text to a few words.
+- Put tooltips on controls that take focus, so keyboard users get them too.
+
+### Don't
+
+- Don't put information only in a tooltip: touch screens never show it.
+- Don't put links, buttons or other controls in a tooltip; use a popover.
+- Don't use a tooltip as the accessible name of a control.
+- Don't add a tooltip that repeats a visible text label word for word.
+
+## Migration notes
+
+### 0.3.1
+
+New `[bfTooltip]` (`BfTooltipDirective`) and its `bf-tooltip` pill (`BfTooltipComponent`) in
+`@bitforgehq/ui/overlay`: a short hint beside a control after a 500 ms hover or at once on keyboard
+focus, hidden on leave, blur and `Escape`, and kept while the pointer moves onto it (WCAG 1.4.13).
+`bfTooltipPlacement` (`BfTooltipPlacement`: `top` default, `bottom`, `start`, `end`, logical)
+flips when it would overflow. While it shows, the control is described by it
+(`aria-describedby`). Nothing shows under a coarse pointer. Fades in over 120 ms, not under
+reduced motion. New `BfTooltipHarness` in `@bitforgehq/ui/testing`.

package/ai/components/top-nav.md

@@ -0,0 +1,159 @@
+# bf-top-nav
+
+Horizontal app navigation, a wrapping row of links for apps with few sections
+
+`BfTopNavComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfTopNavComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-top-nav overview.
+ *
+ * Live demo of `bf-top-nav`: a row of `a[bfNavItem]` router links for an app with few sections.
+ * This page is the current one; in a narrow container the row wraps onto more lines.
+ */
+@Component({
+  selector: 'app-example-top-nav-overview',
+  imports: [RouterLink, RouterLinkActive, BfNavItemComponent, BfTopNavComponent],
+  template: `
+    <bf-top-nav label="Desktop navigation">
+      @for (link of links; track link.path) {
+        <a bfNavItem [routerLink]="link.path" routerLinkActive ariaCurrentWhenActive="page">{{
+          link.label
+        }}</a>
+      }
+    </bf-top-nav>
+  `,
+})
+export class TopNavOverviewExampleComponent {
+  protected readonly links: readonly { path: string; label: string }[] = [
+    { path: '/components/sidebar', label: 'Sidebar' },
+    { path: '/components/top-nav', label: 'Top nav' },
+    { path: '/components/nav-item', label: 'Nav item' },
+    { path: '/components/nav-group', label: 'Nav group' },
+  ];
+}
+```
+
+## Overview
+
+The horizontal navigation of a desktop app with few sections: a `nav` landmark holding a row
+of `a[bfNavItem]` links that wraps onto more lines in a narrow container. Each link marks the
+current page from `aria-current="page"`, as in `bf-sidebar`.
+
+The horizontal navigation of a desktop web app with few sections: a `nav` landmark holding a row of [`a[bfNavItem]`](https://bitforge-ui.web.app/components/nav-item) links, usually in the app's header bar. In a narrow container the row wraps onto more lines. It shares its item with [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar), so the current page, the count badge and the focus ring look the same in both.
+
+## When to use
+
+Use `bf-top-nav` for the two to five top-level destinations of a desktop web app. Use [bf-sidebar](https://bitforge-ui.web.app/components/sidebar) instead for more sections or sections in groups, and [bf-segmented](https://bitforge-ui.web.app/components/segmented) to switch a view in place. 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 `bfNavItem` on your own `<a routerLink routerLinkActive ariaCurrentWhenActive="page">`: the router sets `aria-current="page"` on the current page's link and the item shows it in the tonal fill. Items lay out inline at their own width; an icon in `bfSlot="icon"` and a `badge` work as in the sidebar. Name the landmark with `label` (it falls back to `provideBfLabels()`'s `navigation`, "Main").
+
+## Icons and badges
+
+An icon in `bfSlot="icon"` sits before the label and `badge` adds a count pill, announced as "4 new", as in the sidebar.
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfTopNavComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { ChartColumn, Inbox, LayoutDashboard } from 'lucide';
+
+/**
+ * Icons and a count badge in a top nav.
+ *
+ * Each `a[bfNavItem]` takes an icon in `bfSlot="icon"` and a `badge`, as in the sidebar.
+ */
+@Component({
+  selector: 'app-example-top-nav-icons',
+  imports: [RouterLink, RouterLinkActive, BfIconComponent, BfNavItemComponent, BfTopNavComponent],
+  template: `
+    <bf-top-nav label="Sections with icons">
+      <a bfNavItem routerLink="/components/top-nav" routerLinkActive ariaCurrentWhenActive="page">
+        <bf-icon bfSlot="icon" [icon]="dashboard" />
+        Overview
+      </a>
+      <a
+        bfNavItem
+        routerLink="/components/badge"
+        routerLinkActive
+        ariaCurrentWhenActive="page"
+        [badge]="4"
+      >
+        <bf-icon bfSlot="icon" [icon]="inbox" />
+        Inbox
+      </a>
+      <a bfNavItem routerLink="/density" routerLinkActive ariaCurrentWhenActive="page">
+        <bf-icon bfSlot="icon" [icon]="chart" />
+        Reports
+      </a>
+    </bf-top-nav>
+  `,
+})
+export class TopNavIconsExampleComponent {
+  protected readonly dashboard = LayoutDashboard;
+  protected readonly inbox = Inbox;
+  protected readonly chart = ChartColumn;
+}
+```
+
+## Small screens
+
+The row wraps rather than scrolling sideways. When it would wrap onto too many lines, drive a [`bf-menu-button`](https://bitforge-ui.web.app/components/menu-button) of `a[bfMenuItem]` links below a breakpoint from the same array (`class="hidden md:block"` on `bf-top-nav`, `class="md:hidden"` on the menu button), as the [sidebar's responsive layout](https://bitforge-ui.web.app/components/sidebar) shows.
+
+## Desktop
+
+The top nav is a desktop pattern. Its items take a `surface-muted` fill and the pointer on hover, a `surface-pressed` fill while pressed and the focus ring on keyboard focus only; the current page keeps its tonal fill with its own hover and pressed steps. Item height follows `provideBfDefaults()` (`controlSize`); under a coarse pointer every item is at least 44 px tall. Ctrl/Cmd-click and a middle click open a link in a new tab.
+
+## Theming
+
+- Layout: `flex flex-wrap` with a 4 px gap; no surface of its own, so it sits on the header bar or page behind it.
+- The items' tokens are on the [nav item](https://bitforge-ui.web.app/components/nav-item#theming) page.
+
+## Accessibility
+
+`bf-top-nav` renders a native `<nav>` landmark named by `label`, else `provideBfLabels()`'s `navigation` ("Main"); give each landmark on a page a different name. Its links are plain `<a>` elements in DOM order; the current page is the one with `aria-current="page"`, which screen readers announce ("current page") and which an outline marks under forced colours.
+
+### Keyboard
+
+| Key                                              | Action                   |
+| ------------------------------------------------ | ------------------------ |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves between the links  |
+| <kbd>Enter</kbd>                                 | Follows the focused link |
+
+## Inputs
+
+| Name    | Type     | Default | Description                                                                                                                                                       |
+| ------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label` | `string` | `''`    | Accessible name of the navigation; empty falls back to `provideBfLabels()`'s `navigation` ("Main"). Name each landmark differently when a page has more than one. |
+
+## Slots
+
+- `default`: The destinations, `a[bfNavItem]` links.
+
+## Notes
+
+### Do
+
+- Keep it to a few short labels that fit one line at the usual window width.
+- Mark the current page with `routerLinkActive` and `ariaCurrentWhenActive="page"`.
+
+### Don't
+
+- Don't put more than five or six destinations in it; use a `bf-sidebar`.
+- Don't use it to switch a view inside a page; use a `bf-segmented`.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-top-nav`: the horizontal navigation of a desktop app with few sections, a `nav` row of
+`a[bfNavItem]` links that wraps in a narrow container, named by `label` (else `navigation`).