@bitforgehq/ui 0.3.0 → 0.3.1

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.

package/ai/components/nav-item.md

@@ -0,0 +1,210 @@
+# a[bfNavItem]
+
+Navigation link for a sidebar or top nav, with icon, label and count
+
+`BfNavItemComponent` from `@bitforgehq/ui` · Navigation · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink, RouterLinkActive } from '@angular/router';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Bell, Inbox, ListTodo } from 'lucide';
+
+/**
+ * The a[bfNavItem] overview.
+ *
+ * Live demo of `a[bfNavItem]`: router links with an icon, the current page (this one) in the
+ * tonal fill, a count badge and the sm, md and lg heights; then the same links in a collapsed
+ * sidebar, icon only, the badge a dot and the label a tooltip.
+ */
+@Component({
+  selector: 'app-example-nav-item-overview',
+  imports: [RouterLink, RouterLinkActive, BfIconComponent, BfNavItemComponent, BfSidebarComponent],
+  template: `
+    <div class="flex flex-wrap items-start gap-4">
+      <bf-sidebar label="Nav items">
+        <a
+          bfNavItem
+          routerLink="/components/nav-item"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="listTodo" />
+          Nav item
+        </a>
+        <a
+          bfNavItem
+          routerLink="/components/badge"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+          [badge]="12"
+        >
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Badge
+        </a>
+        <a bfNavItem size="sm" routerLink="/density" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="bell" />
+          Small · 32
+        </a>
+        <a bfNavItem size="lg" routerLink="/density" routerLinkActive ariaCurrentWhenActive="page">
+          <bf-icon bfSlot="icon" [icon]="bell" />
+          Large · 48
+        </a>
+      </bf-sidebar>
+      <bf-sidebar label="Nav items, collapsed" [collapsed]="true">
+        <a
+          bfNavItem
+          routerLink="/components/nav-item"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+        >
+          <bf-icon bfSlot="icon" [icon]="listTodo" />
+          Nav item
+        </a>
+        <a
+          bfNavItem
+          routerLink="/components/badge"
+          routerLinkActive
+          ariaCurrentWhenActive="page"
+          [badge]="12"
+        >
+          <bf-icon bfSlot="icon" [icon]="inbox" />
+          Badge
+        </a>
+      </bf-sidebar>
+    </div>
+  `,
+})
+export class NavItemOverviewExampleComponent {
+  protected readonly listTodo = ListTodo;
+  protected readonly inbox = Inbox;
+  protected readonly bell = Bell;
+}
+```
+
+## Overview
+
+One destination of a `bf-sidebar` or `bf-top-nav`: put `bfNavItem` on your own `<a>` with
+`routerLink`, `routerLinkActive` and `ariaCurrentWhenActive="page"`, and the item shows the
+current page from `aria-current`. An icon goes in the `icon` slot, the label in the default
+slot; `badge` adds a count. In a collapsed sidebar only the icon shows, the label stays for
+screen readers and becomes the `title` tooltip.
+
+One destination of a [`bf-sidebar`](https://bitforge-ui.web.app/components/sidebar) or a [`bf-top-nav`](https://bitforge-ui.web.app/components/top-nav): put `bfNavItem` on your own `<a>` with `routerLink`, `routerLinkActive` and `ariaCurrentWhenActive="page"`. An icon goes in `bfSlot="icon"`, the label in the default slot, and `badge` adds a count. The item reads its layout from its container: a full-width row in a sidebar, an inline item in a top nav, an icon in a collapsed sidebar.
+
+## When to use
+
+Use `a[bfNavItem]` for each link of a `bf-sidebar` or `bf-top-nav`. Use [`a[bfButton]`](https://bitforge-ui.web.app/components/button) with `variant="ghost"` instead for a link that is not part of the app's navigation, and [bf-list-item](https://bitforge-ui.web.app/components/list-item) with a `bfAction` link for a row of a list. 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
+
+The router sets `aria-current="page"` on the current page's link (`routerLinkActive` with `ariaCurrentWhenActive="page"`), and the item shows it in the tonal fill (`primary-soft`, the same as an `a[bfButton]` ghost link); the widget never imports the router. Other items are neutral (`text-muted`) until hovered. The label truncates with an ellipsis in a narrow sidebar.
+
+## Count badge
+
+`badge` takes a number and shows it as a pill at the inline end; `null` (the default) shows none. The pill is hidden from screen readers and the count is announced after the label with `provideBfLabels()`'s `navBadge(count)` ("3 new"), so the link's name is "Inbox 3 new".
+
+## Collapsed
+
+In a collapsed `bf-sidebar` the item shows only its icon in a square of its height step. The label stays in the DOM as screen-reader text, so the link's name does not change, and becomes the link's `title` (the tooltip on hover, kept up to date when the label changes); your own `title` comes back when the sidebar expands. The badge becomes a small dot on the icon's corner and is still announced. Give every item an icon, or it shows nothing while collapsed. For a styled tooltip that also shows on keyboard focus, add `bfTooltip` from `@bitforgehq/ui/overlay` with the label's text while collapsed (an empty text while expanded shows none) and `bfTooltipPlacement="end"` (see [bf-tooltip](https://bitforge-ui.web.app/components/tooltip)).
+
+## Sizes
+
+`size` sets the height: `sm` 32, `md` 40, `lg` 48 px. Unset, it follows `provideBfDefaults()` (`controlSize`, `md` by default). The height is a minimum, so a label at a large text size grows the item instead of clipping it.
+
+```ts
+import { Component } from '@angular/core';
+import { BfNavItemComponent, BfSidebarComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { Bell } from 'lucide';
+
+/**
+ * The three heights of a nav item.
+ *
+ * `size` sets 32, 40 or 48 px; unset, the item follows `provideBfDefaults()`'s `controlSize`.
+ */
+@Component({
+  selector: 'app-example-nav-item-sizes',
+  imports: [BfIconComponent, BfNavItemComponent, BfSidebarComponent],
+  template: `
+    <bf-sidebar label="Nav item sizes">
+      <a bfNavItem size="sm" href="#sizes">
+        <bf-icon bfSlot="icon" [icon]="bell" />
+        Small · 32
+      </a>
+      <a bfNavItem size="md" href="#sizes">
+        <bf-icon bfSlot="icon" [icon]="bell" />
+        Medium · 40
+      </a>
+      <a bfNavItem size="lg" href="#sizes">
+        <bf-icon bfSlot="icon" [icon]="bell" />
+        Large · 48
+      </a>
+    </bf-sidebar>
+  `,
+})
+export class NavItemSizesExampleComponent {
+  protected readonly bell = Bell;
+}
+```
+
+## Desktop
+
+Hover gives a `surface-muted` fill with the `text` colour and the pointer; pressing gives `surface-pressed`. The current page keeps its tonal fill, one step darker on hover and again while pressed. The focus ring shows on keyboard focus only (`focus-visible`). Under a fine pointer the item's box is its hit area; under a coarse pointer (a touchscreen laptop) it grows to at least 44 px tall (`pointer-coarse:min-h-hit`) instead of extending an invisible hit area over its neighbours, because it holds your label. A link keeps the browser's behaviour: Ctrl/Cmd-click and a middle click open it in a new tab.
+
+## Theming
+
+- Rest: transparent with `text-muted`; hover `surface-muted` with `text`; pressed `surface-pressed`.
+- Current page (`aria-current="page"`): `primary-soft` with `primary-strong`, hover `primary-soft-hover`, pressed `primary-soft-pressed`; under forced colours a `LinkText` outline.
+- Shape: `rounded-control`; label `font-bold`, `text-label-xs` / `text-label-sm` / `text-label` by size.
+- Badge: `primary` with `on-primary`, `text-micro`; collapsed, a `primary` dot (`CanvasText` under forced colours).
+- Focus: `ring` (4 px).
+
+## Accessibility
+
+The item is the consumer's native `<a>`: exposed as a link, reached with Tab and followed with Enter, its name being its label (plus the badge announcement). The current page carries `aria-current="page"`, which screen readers announce; the fill is not the only cue, as an outline marks it under forced colours. The icon slot is decorative (a `bf-icon` is `aria-hidden` by default). Collapsed, the label is visually hidden but still the name, and `title` adds a pointer tooltip only; the badge dot is `aria-hidden`, its count announced through the screen-reader text. In Safari, Tab reaches links only when the user turns on "Press Tab to highlight each item" (Option+Tab otherwise).
+
+### Keyboard
+
+| Key              | Action                                            |
+| ---------------- | ------------------------------------------------- |
+| <kbd>Tab</kbd>   | Moves focus to the link                           |
+| <kbd>Enter</kbd> | Follows the link; a link ignores <kbd>Space</kbd> |
+
+## Inputs
+
+| Name    | Type                                                        | Default     | Description                                                                                                                                             |
+| ------- | ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size`  | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px (44 px at least under a coarse pointer); unset follows `provideBfDefaults()` (`controlSize`, `md` by default).      |
+| `badge` | `number \| null`                                            | `null`      | A count shown as a pill at the inline end (a dot while collapsed), announced with `provideBfLabels()`'s `navBadge(count)` ("3 new"); `null` shows none. |
+
+## Slots
+
+- `icon`: An icon before the label, a `bf-icon`; the only thing shown while collapsed.
+- `default`: The label.
+
+## Notes
+
+### Do
+
+- Put `routerLinkActive` and `ariaCurrentWhenActive="page"` on every item, so the current page shows.
+- Give every item in a collapsible sidebar an icon.
+
+### Don't
+
+- Don't put `bfNavItem` on a `<button>`; a destination is a link, and an action belongs in the header or footer as a button.
+- Don't set `aria-current` yourself on more than one item.
+
+## Migration notes
+
+### 0.3.1
+
+New `a[bfNavItem]`: one destination of a `bf-sidebar` or `bf-top-nav` on the app's own
+`<a routerLink routerLinkActive ariaCurrentWhenActive="page">`. Neutral at rest, the tonal fill
+for the current page from `aria-current="page"` (as an `a[bfButton]` ghost link), an `icon` slot,
+`size` from `controlSize` (44 px at least under a coarse pointer) and a `badge` count announced
+with the new `navBadge(count)` label ("3 new"). In a collapsed sidebar it shows its icon only,
+keeps its label as screen-reader text and as its `title`, and turns the badge into a dot.