@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/UI_GUIDE.md

@@ -72,7 +72,7 @@ In `src/index.html`, give `<body>` the theme background and text colour, so the
 
 ### 7. Switch to dark mode
 
-Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes.
+Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes. To let users choose System, Light or Dark, add `provideBfColorScheme()` to the app providers: it sets the class, follows the OS and remembers the choice.
 
 ```html
 <html lang="en" class="dark">
@@ -138,15 +138,16 @@ Render library components only in the browser, for example in a `@defer` block o
 route. Support will be decided before 1.0.
 
 The one server-side check is a render smoke, not a support test: the library repository's
-`tools/ssr-smoke.ts` renders 28 fixtures with `renderApplication()` (every root widget, `bf-icon`,
-`bf-number-input`, a `/mobile` page with `provideBfShell()`, `bf-page`, `bf-header` and
-`bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay` dialog), and all
-of them render without an error. 19 of them render identically twice. The other 9 number their ids
-differently on every render, from a module-level counter, so they could not hydrate: `bf-checkbox`,
-`bf-input`, `bf-radio-group`, `bf-segmented`, `bf-select`, `bf-textarea`, `bf-toggle`,
-`bf-number-input` and the `/overlay` dialog. Hydration itself is still not supported or tested, and
-more stands in its way: `/mobile` writes to `<html>` and adds a keyboard probe to `<body>`, and an
-`/overlay` dialog renders outside the app root and marks it inert.
+`tools/ssr-smoke.ts` renders 42 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`bf-number-input`, a `/charts` line chart, a `/mobile` page with `provideBfShell()`, `bf-page`,
+`bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay`
+dialog), and all of them render without an error. 27 of them render identically twice. The other 15
+number their ids differently on every render, from a module-level counter, so they could not
+hydrate: `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`, `bf-select`,
+`bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`, `bf-toggle`,
+`bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still not
+supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a keyboard
+probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it inert.
 
 ## Keeping this guide in sync
 
@@ -165,6 +166,11 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
 - Number field: `import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';`. It is
   the one widget in its own entry point, because it loads Angular Forms (`@angular/forms`, a
   required peer); `@bitforgehq/ui` itself loads no forms code, so an app without forms ships none.
+- Charts: `import { BfLineChartComponent } from '@bitforgehq/ui/charts';` (also `BfBarChartComponent`,
+  `BfDonutChartComponent`, `BfSparklineComponent`, `BfChartCardComponent`). Our own SVG charts,
+  themed with the `--color-chart-1` … `--color-chart-8` tokens; pass `series` (`{ name, values }`) and
+  `categories`, and a `label` that names the figure. Prefer them to a chart library unless you need a
+  chart form they do not draw.
 - Layout classes go on the element (`<bf-button class="mt-4">`); never restyle a widget's internals.
 - Colors: use only the semantic tokens (`bg-primary`, `text-text-muted`, `bg-surface`,
   `border-border`, `rounded-field`, `shadow-raised`, `text-body`). Never raw palette classes and
@@ -260,7 +266,7 @@ toolbar or a German settings page); a key you leave out keeps the parent's value
   (hence `fieldSize: 'lg'` for touch). Keep `gap-2` or more between wrapping rows of `sm` controls.
 - `provideBfLabels({ ... })` replaces the built-in English strings (`loading`, `dismiss`, `tabBar`,
   `tabBadge(count)`, `back`, `ok`, `cancel`, `actions`, `sheet`, `modal`, `refreshing`, `close`,
-  `dialog`) and the
+  `dialog`, `theme`, `themeSystem`, `themeLight`, `themeDark`) and the
   default error text per validator kind (`validation`: `required`, `email`, `pattern`, `parse`,
   `min(n)`, `max(n)`, `minLength(n)`, `maxLength(n)`, `minDate(d)`, `maxDate(d)`, `fallback`),
   merged key by key; a key set to `undefined` also keeps the parent's string. Use it for any
@@ -272,7 +278,7 @@ toolbar or a German settings page); a key you leave out keeps the parent's value
   fall back to `sheet`/`modal`.
 - What a component-level `provideBfLabels()` covers: the widgets, form controls and
   `bf-back-button`/`bf-refresher` rendered inside that component (`loading`, `dismiss`, `tabBar`,
-  `tabBadge`, `back`, `refreshing`, `validation`). The overlay services (`BfAlertDialogService`
+  `tabBadge`, `back`, `refreshing`, the `theme…` keys, `validation`). The overlay services (`BfAlertDialogService`
   `ok`, `BfActionSheetService` `cancel`/`actions`, `BfSheetService` `sheet`, `BfModalService`
   `modal`, `BfDialogService` `close`/`dialog`/`ok`/`cancel`, `BfDesktopToastService`
   `notifications`) are root singletons: they read the app-level labels unless the call passes the
@@ -302,6 +308,83 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
+### Colour scheme
+
+A System / Light / Dark choice needs no code of your own. In a desktop web app add
+`provideBfColorScheme()` to `ApplicationConfig.providers`; `BfColorSchemeService` (both from
+`@bitforgehq/ui`, no Capacitor) then toggles `dark` on `<html>`, follows `prefers-color-scheme`
+while the choice is `system`, and stores the choice in `localStorage` under `bf-theme`
+(`BF_COLOR_SCHEME_STORAGE` moves it elsewhere). Read `dark()`, and switch with
+`scheme.set('dark')`. For the control, bind `bf-theme-switch` (three segments, for a settings page
+or a header row with room) or `bf-theme-menu-button` (`@bitforgehq/ui/overlay`, a menu for a
+crowded top bar, icon in `bfSlot="icon"`) two-way: `[(value)]="colorScheme.scheme"`. Storage and
+the media query are read in the browser only, so a server render starts light and writes nothing.
+A Capacitor app gets the same service from `provideBfShell()`: `BfPlatformService.theme` and
+`dark` are the same signals, and the system bars follow them. Never write your own `matchMedia`
+listener, storage key or `<html>` class toggle.
+
+```ts
+export const appConfig: ApplicationConfig = { providers: [provideBfColorScheme()] };
+// In a settings component:
+protected readonly colorScheme = inject(BfColorSchemeService);
+// <bf-theme-switch [(value)]="colorScheme.scheme" />
+```
+
+## Desktop layout
+
+`bf-tabs`, `bf-back-button` and `bf-header` are Capacitor shell parts. A desktop web app (no
+`provideBfShell()`) uses their desktop counterparts from `@bitforgehq/ui`:
+
+- **Navigation:** `bf-sidebar` (groups in `bf-nav-group`, `[(collapsed)]` for an icon rail; the
+  app owns the toggle button) or `bf-top-nav` for a few sections, holding
+  `<a bfNavItem routerLink="…" routerLinkActive ariaCurrentWhenActive="page">` links with an icon
+  in `bfSlot="icon"` and an optional `[badge]` count. The router sets `aria-current="page"` and
+  the item shows it. Drive the sidebar, a below-`md` `bf-menu-button` of `a[bfMenuItem]` links and,
+  in the shell, the `bf-tab`s of a `bf-tab-bar` from one array of destinations.
+- **Breadcrumb:** `<bf-breadcrumb>` of `<li bfBreadcrumbItem><a routerLink>…</a></li>`, the
+  current page last as plain text (marked `aria-current="page"`); `maxItems` collapses a long
+  trail, and a `bfSlot="overflow"` `bf-menu-button` turns the collapse into a menu. On mobile it is
+  `bf-back-button` in `bf-header`.
+- **Page header:** `<bf-page-header title="…" subtitle="…">` with the breadcrumb in
+  `bfSlot="breadcrumb"`, badges in `bfSlot="meta"` and the actions in `bfSlot="actions"` (the main
+  action a primary `bf-button`, secondary ones `ghost`, the rest in an icon-only `bf-menu-button`).
+  An icon-only link (back, open, edit) is `a[bfIconButton]`.
+- **Toolbar:** `<bf-toolbar label="…" [status]="count">` under the page header: search and filters
+  in the default slot, a view switch in `bfSlot="view"`, actions in `bfSlot="actions"`; its
+  controls default to `sm`, and `status` is a polite live region for the result count.
+- **Table:** `<bf-table [rows] [columns] [(sort)] selectable [(selection)]>` with
+  `ng-template[bfTableCell]` for rich cells and `bfSlot="empty"` for the empty state; the app
+  sorts the rows in a `computed()`, and a selection shows a `bf-action-bar`. Below `md` or on a
+  coarse pointer render the same rows as `bf-list-item`s.
+- **Details:** `bf-description-list` of `div[bfDescriptionItem]` label/value pairs, and `bf-stat`
+  figure tiles in a grid; both work in both shells.
+- **Cards in a grid:** the grid stretches each `bf-card` and its `bfSlot="footer"` sits on the
+  bottom edge, so footers line up; put a footer's parts in one element.
+- **Rows on a card:** `<bf-list [inset]="false" divided class="-mx-card">`, flush to the card's
+  edges with lines between the rows.
+- **Theme switch:** `<bf-theme-switch [(value)]="colorScheme.scheme" />` (or
+  `bf-theme-menu-button` from `/overlay` in a crowded top bar) with `provideBfColorScheme()` (see
+  "Colour scheme").
+- **Tabs in a page:** `<bf-tab-group [(selected)]="tab">` of `<bf-tab-panel value="…" label="…">`
+  (content in an `ng-template` inside renders only while shown). Not `bf-tabs`/`bf-tab-bar` (the
+  shell's bottom tabs), and not for routes (use `bf-top-nav` links).
+- **Paging and loading:** `<bf-pagination [(page)]="page" [total]="count" [pageSize]="20">` under a
+  `bf-table` (the app slices its rows); `bf-skeleton` (`shape` text/rect/circle, `lines`) as the
+  placeholder while data loads, inside a region with `aria-busy="true"`.
+- **Dates and times:** `<bf-calendar [(value)]="date">` for an inline month view;
+  `bf-date-input`, `bf-time-input` and `bf-datetime-input` (`/overlay`) for a field: typed parts
+  in locale order plus a calendar or time-list popover (`picker="none"` for typed only, `native`
+  for the platform picker on touch). Values are ISO strings (`'2026-10-28'`, `'14:30'`,
+  `'2026-10-28T14:30'`); month and day names come from `Intl` in the document's language.
+- **Picking from many options:** `bf-combobox` (`/overlay`) for one value with search, groups and
+  server search (`queried`, `loading`); `bf-multi-combobox` for tags. `bf-select` stays the choice
+  for a short fixed list.
+- **Dashboards:** `bf-stat` with `delta`, `trend` and `trendIntent` for a figure and its change;
+  `@bitforgehq/ui/charts` for `bf-line-chart`, `bf-bar-chart`, `bf-donut-chart` and
+  `bf-sparkline` inside a `bf-chart-card` (title, period slot, loading, empty and error states),
+  themed by the `chart-1`…`chart-8` tokens. Every chart takes a `label` and offers its data as a
+  table.
+
 ## Overlays (`@bitforgehq/ui/overlay`)
 
 A desktop or plain web app (no Capacitor, no router required) installs `@angular/cdk` and `rxjs`
@@ -331,6 +414,13 @@ injector? })` stacks up to three cards bottom-right (configurable with
   keys, arrow navigation with wrap, Home/End, type-ahead, `Escape`/`Tab` close with focus back on
   the trigger, `ArrowRight`/`ArrowLeft` for submenus. A menu opened from inside a `bf-dialog`:
   `Escape` closes only the menu, never the dialog underneath.
+- **Tooltip and popover:** `[bfTooltip]="'Text'"` on a focusable element shows a short hint on
+  hover and keyboard focus (never on touch, never the only place the information lives).
+  `[bfPopoverTriggerFor]="panel"` opens a non-modal `bf-popover` panel anchored to its button
+  (filters, details); focus moves in, `Escape` and an outside click close it.
+- **Side panel:** `BfSidePanelService.open(component | template, { width, modal, data })` slides a
+  full-height `bf-side-panel` in from the inline end: a record's details or edit form beside the
+  list. `modal: false` keeps the page usable. In the Capacitor shell use `bf-sheet`/`bf-modal`.
 - **`closeOnNavigation`:** every overlay (`BfDialogConfig`, `confirm()`, and the `/mobile` sheet,
   modal, action sheet and alert options) closes when the URL path changes by default (`true`);
   pass `closeOnNavigation: false` to keep one open across a navigation (e.g. a draft that must
@@ -862,7 +952,7 @@ describe('bf-button in a consumer app (Vitest)', () => {
 
 ### 6. Drive a form widget through its harness
 
-The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness` and `BfDesktopToastHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`.
+The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`.
 
 `select-harness.spec.ts`:
 
@@ -1048,10 +1138,16 @@ Don't assert on the library's CSS classes or internal markup. They are styling d
 
 ## Design foundations (Meadow Sage)
 
-Warm off-white canvas (`bg-bg`), white surfaces, sage green primary, pill-shaped controls,
+Warm off-white canvas (`bg-bg`), white surfaces, a neutral indigo default primary
+(`#2b26ba`), pill-shaped controls,
 radii 12/16/24 px (`rounded-tile/field/card`), 1.5 px control borders, soft layered shadows
 (`shadow-raised`, `shadow-floating`), Manrope type (`text-display/title/heading/body/caption`).
 
+The palette is Meadow Sage, but the primary is not its sage green: the indigo default is neutral
+on purpose and meant to be overridden with the app's brand colour (`--color-primary` and the rest
+of its set, in `@theme` and `.dark`). An indigo primary right after install is expected; it does
+not mean the theme failed to load.
+
 ### Type and spacing scale
 
 - Type (rem tokens; px at a 16 px root): `text-display` 40, `text-title` 28, `text-heading` 18,
@@ -1076,33 +1172,50 @@ notes.
 | `bf-action-bar`  | `@bitforgehq/ui` | Floating pill of contextual actions that appears while items are selected      |
 | `bf-button`      | `@bitforgehq/ui` | Pill-shaped action button with five variants, three sizes and a loading state  |
 | `bf-icon-button` | `@bitforgehq/ui` | Round icon-only button for toolbars and rows, with a required accessible label |
+| `bf-toolbar`     | `@bitforgehq/ui` | Dense row of search, filters, view switch, result count and actions            |
 
 ### Forms
 
-| Component         | Entry point                   | Purpose                                                                                     |
-| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
-| `bf-checkbox`     | `@bitforgehq/ui`              | Rounded checkbox with an optional label that binds to Signal Forms                          |
-| `bf-chip`         | `@bitforgehq/ui`              | Toggleable filter chip with a check mark when selected, in tonal or ink style               |
-| `bf-chip-group`   | `@bitforgehq/ui`              | Named row of chips that picks one like radios, or groups independent toggles                |
-| `bf-field`        | `@bitforgehq/ui`              | Label, help text and error text wrapper that wires ids for assistive tech                   |
-| `bf-input`        | `@bitforgehq/ui`              | Single-line text field with label, help and error text, icon slots and Signal Forms binding |
-| `bf-number-input` | `@bitforgehq/ui/number-input` | Number field that binds number or null, with native min, max and step                       |
-| `bf-radio-group`  | `@bitforgehq/ui`              | Group of radio buttons for choosing one option, with optional per-option descriptions       |
-| `bf-segmented`    | `@bitforgehq/ui`              | Segmented control for switching between two to four views, keyboard-navigable like radios   |
-| `bf-select`       | `@bitforgehq/ui`              | Native single-choice dropdown styled like the text field, with Signal Forms binding         |
-| `bf-textarea`     | `@bitforgehq/ui`              | Multi-line text field with label, help and error text, and Signal Forms binding             |
-| `bf-toggle`       | `@bitforgehq/ui`              | On/off switch for settings that apply immediately, with Signal Forms binding                |
+| Component           | Entry point                   | Purpose                                                                                     |
+| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
+| `bf-calendar`       | `@bitforgehq/ui`              | Inline month calendar for picking one date, with month and year jumps                       |
+| `bf-checkbox`       | `@bitforgehq/ui`              | Rounded checkbox with an optional label that binds to Signal Forms                          |
+| `bf-chip`           | `@bitforgehq/ui`              | Toggleable filter chip with a check mark when selected, in tonal or ink style               |
+| `bf-chip-group`     | `@bitforgehq/ui`              | Named row of chips that picks one like radios, or groups independent toggles                |
+| `bf-combobox`       | `@bitforgehq/ui/overlay`      | Text field that filters a list of options as you type and picks one                         |
+| `bf-date-input`     | `@bitforgehq/ui/overlay`      | Typed date field with a calendar popover, valued as an ISO date string                      |
+| `bf-datetime-input` | `@bitforgehq/ui/overlay`      | Typed date and time field with a calendar and time list in one popover                      |
+| `bf-field`          | `@bitforgehq/ui`              | Label, help text and error text wrapper that wires ids for assistive tech                   |
+| `bf-input`          | `@bitforgehq/ui`              | Single-line text field with label, help and error text, icon slots and Signal Forms binding |
+| `bf-multi-combobox` | `@bitforgehq/ui/overlay`      | Text field that filters options as you type and picks several as tags                       |
+| `bf-number-input`   | `@bitforgehq/ui/number-input` | Number field that binds number or null, with native min, max and step                       |
+| `bf-radio-group`    | `@bitforgehq/ui`              | Group of radio buttons for choosing one option, with optional per-option descriptions       |
+| `bf-segmented`      | `@bitforgehq/ui`              | Segmented control for switching between two to four views, keyboard-navigable like radios   |
+| `bf-select`         | `@bitforgehq/ui`              | Native single-choice dropdown styled like the text field, with Signal Forms binding         |
+| `bf-textarea`       | `@bitforgehq/ui`              | Multi-line text field with label, help and error text, and Signal Forms binding             |
+| `bf-theme-switch`   | `@bitforgehq/ui`              | Segmented System, Light and Dark switch bound two-way to the app colour scheme              |
+| `bf-time-input`     | `@bitforgehq/ui/overlay`      | Typed time-of-day field with a popover list of times, valued as an ISO string               |
+| `bf-toggle`         | `@bitforgehq/ui`              | On/off switch for settings that apply immediately, with Signal Forms binding                |
 
 ### Data display
 
-| Component      | Entry point      | Purpose                                                                                 |
-| -------------- | ---------------- | --------------------------------------------------------------------------------------- |
-| `bf-avatar`    | `@bitforgehq/ui` | Round avatar showing a photo or initials, in three sizes and four color variants        |
-| `bf-badge`     | `@bitforgehq/ui` | Small status label in semantic tones, or a compact numeric pill for counts              |
-| `bf-card`      | `@bitforgehq/ui` | Content surface with an optional header slot, in four visual styles from raised to flat |
-| `bf-list`      | `@bitforgehq/ui` | Container for list rows, inset by default with rounded corners on a warm background     |
-| `bf-list-item` | `@bitforgehq/ui` | List row with leading slot, title, subtitle, trailing slot and an optional chevron      |
-| `bf-progress`  | `@bitforgehq/ui` | Progress bar in two sizes and four tones for completion, quotas and unknown waits       |
+| Component                | Entry point             | Purpose                                                                                 |
+| ------------------------ | ----------------------- | --------------------------------------------------------------------------------------- |
+| `bf-avatar`              | `@bitforgehq/ui`        | Round avatar showing a photo or initials, in three sizes and four color variants        |
+| `bf-badge`               | `@bitforgehq/ui`        | Small status label in semantic tones, or a compact numeric pill for counts              |
+| `bf-bar-chart`           | `@bitforgehq/ui/charts` | Bar chart of series over categories, grouped or stacked, vertical or horizontal         |
+| `bf-card`                | `@bitforgehq/ui`        | Content surface with an optional header slot, in four visual styles from raised to flat |
+| `bf-chart-card`          | `@bitforgehq/ui/charts` | Card around one chart with a title, period control and loading, empty and error states  |
+| `div[bfDescriptionItem]` | `@bitforgehq/ui`        | One label and value pair of a description list, label as term, content as value         |
+| `bf-description-list`    | `@bitforgehq/ui`        | Native description list of label-value pairs, as divided rows or a tile grid            |
+| `bf-donut-chart`         | `@bitforgehq/ui/charts` | Donut chart of the parts of a whole, with a legend, tooltip and centre slot             |
+| `bf-line-chart`          | `@bitforgehq/ui/charts` | Line chart of series over categories, with tooltip, legend and data table               |
+| `bf-list`                | `@bitforgehq/ui`        | Container for list rows, inset by default with rounded corners on a warm background     |
+| `bf-list-item`           | `@bitforgehq/ui`        | List row with leading slot, title, subtitle, trailing slot and an optional chevron      |
+| `bf-progress`            | `@bitforgehq/ui`        | Progress bar in two sizes and four tones for completion, quotas and unknown waits       |
+| `bf-sparkline`           | `@bitforgehq/ui/charts` | Tiny trend line with no axes or legend, for stats and table cells                       |
+| `bf-stat`                | `@bitforgehq/ui`        | One labelled figure with an optional icon tile and a supporting line                    |
+| `bf-table`               | `@bitforgehq/ui`        | Desktop data table with sortable headers, row selection, custom cells and an empty slot |
 
 ### Feedback
 
@@ -1110,35 +1223,50 @@ notes.
 | ---------------- | ---------------- | ---------------------------------------------------------------------------------- |
 | `bf-alert`       | `@bitforgehq/ui` | Inline status message in four tones with a title and an optional dismiss button    |
 | `bf-empty-state` | `@bitforgehq/ui` | Placeholder for an empty screen or list with icon, title, message and action       |
+| `bf-skeleton`    | `@bitforgehq/ui` | Loading placeholder shaped as text lines, a rectangle or a circle, with a shimmer  |
 | `bf-spinner`     | `@bitforgehq/ui` | Indeterminate loading spinner in three sizes that inherits its parent's text color |
 
 ### Navigation
 
-| Component         | Entry point             | Purpose                                                                                     |
-| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
-| `bf-back-button`  | `@bitforgehq/ui/mobile` | Header back button that pops the page stack or falls back to a default route                |
-| `bf-content`      | `@bitforgehq/ui/mobile` | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
-| `bf-header`       | `@bitforgehq/ui/mobile` | Page header toolbar with a large title that collapses into the toolbar on scroll            |
-| `bf-page`         | `@bitforgehq/ui/mobile` | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
-| `bf-refresher`    | `@bitforgehq/ui/mobile` | Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull |
-| `bf-stack-outlet` | `@bitforgehq/ui/mobile` | Router outlet keeping a live page stack with slide transitions and iOS swipe back           |
-| `bf-tab`          | `@bitforgehq/ui`        | One tab bar destination with an icon, a label and an optional count badge                   |
-| `bf-tab-bar`      | `@bitforgehq/ui`        | Floating pill tab bar for mobile apps with arrow-key selection and count badges             |
-| `bf-tabs`         | `@bitforgehq/ui/mobile` | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
+| Component              | Entry point             | Purpose                                                                                     |
+| ---------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `bf-back-button`       | `@bitforgehq/ui/mobile` | Header back button that pops the page stack or falls back to a default route                |
+| `bf-breadcrumb`        | `@bitforgehq/ui`        | Desktop breadcrumb trail of links to the current page, with optional collapsing             |
+| `li[bfBreadcrumbItem]` | `@bitforgehq/ui`        | One level of a breadcrumb trail: a link, or the current page as text                        |
+| `bf-content`           | `@bitforgehq/ui/mobile` | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
+| `bf-header`            | `@bitforgehq/ui/mobile` | Page header toolbar with a large title that collapses into the toolbar on scroll            |
+| `bf-nav-group`         | `@bitforgehq/ui`        | A titled group of sidebar links with a small heading that names it                          |
+| `a[bfNavItem]`         | `@bitforgehq/ui`        | Navigation link for a sidebar or top nav, with icon, label and count                        |
+| `bf-page`              | `@bitforgehq/ui/mobile` | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
+| `bf-page-header`       | `@bitforgehq/ui`        | Desktop page header with breadcrumb, title, subtitle, badges and a row of actions           |
+| `bf-pagination`        | `@bitforgehq/ui`        | Previous, next and numbered page buttons for a long list or table                           |
+| `bf-refresher`         | `@bitforgehq/ui/mobile` | Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull |
+| `bf-sidebar`           | `@bitforgehq/ui`        | Vertical app navigation with brand, grouped links, footer and an icon rail mode             |
+| `bf-stack-outlet`      | `@bitforgehq/ui/mobile` | Router outlet keeping a live page stack with slide transitions and iOS swipe back           |
+| `bf-tab`               | `@bitforgehq/ui`        | One tab bar destination with an icon, a label and an optional count badge                   |
+| `bf-tab-bar`           | `@bitforgehq/ui`        | Floating pill tab bar for mobile apps with arrow-key selection and count badges             |
+| `bf-tab-group`         | `@bitforgehq/ui`        | In-page tabs that switch between content panels, with keyboard navigation and badges        |
+| `bf-tab-panel`         | `@bitforgehq/ui`        | One tab of a tab group with its label, badge, icon and lazy content                         |
+| `bf-tabs`              | `@bitforgehq/ui/mobile` | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
+| `bf-top-nav`           | `@bitforgehq/ui`        | Horizontal app navigation, a wrapping row of links for apps with few sections               |
 
 ### Overlays
 
-| Component          | Entry point              | Purpose                                                                                       |
-| ------------------ | ------------------------ | --------------------------------------------------------------------------------------------- |
-| `bf-action-sheet`  | `@bitforgehq/ui/mobile`  | Bottom panel of labelled actions with a separate cancel button, destructive ones shown in red |
-| `bf-alert-dialog`  | `@bitforgehq/ui/mobile`  | Centred confirmation dialog with a title, message and a row of role-styled buttons            |
-| `bf-desktop-toast` | `@bitforgehq/ui/overlay` | Desktop notification card in a bottom corner stack of up to three                             |
-| `bf-dialog`        | `@bitforgehq/ui/overlay` | Desktop modal dialog with a title, scrolling body, footer actions and focus trap              |
-| `bf-menu`          | `@bitforgehq/ui/overlay` | Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus        |
-| `bf-menu-button`   | `@bitforgehq/ui/overlay` | Styled button that opens a menu, with outline, text, tonal and icon-only looks                |
-| `bf-modal`         | `@bitforgehq/ui/mobile`  | Modal overlay shown as an inset card over the scaled-down page, or full screen                |
-| `bf-sheet`         | `@bitforgehq/ui/mobile`  | Bottom sheet with snap points, drag to dismiss and a backdrop                                 |
-| `bf-toast`         | `@bitforgehq/ui/mobile`  | Passive status pill with an optional action that never steals focus                           |
+| Component              | Entry point              | Purpose                                                                                       |
+| ---------------------- | ------------------------ | --------------------------------------------------------------------------------------------- |
+| `bf-action-sheet`      | `@bitforgehq/ui/mobile`  | Bottom panel of labelled actions with a separate cancel button, destructive ones shown in red |
+| `bf-alert-dialog`      | `@bitforgehq/ui/mobile`  | Centred confirmation dialog with a title, message and a row of role-styled buttons            |
+| `bf-desktop-toast`     | `@bitforgehq/ui/overlay` | Desktop notification card in a bottom corner stack of up to three                             |
+| `bf-dialog`            | `@bitforgehq/ui/overlay` | Desktop modal dialog with a title, scrolling body, footer actions and focus trap              |
+| `bf-menu`              | `@bitforgehq/ui/overlay` | Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus        |
+| `bf-menu-button`       | `@bitforgehq/ui/overlay` | Styled button that opens a menu, with outline, text, tonal and icon-only looks                |
+| `bf-modal`             | `@bitforgehq/ui/mobile`  | Modal overlay shown as an inset card over the scaled-down page, or full screen                |
+| `bf-popover`           | `@bitforgehq/ui/overlay` | Anchored, non-modal panel for filters, details or a small form                                |
+| `bf-sheet`             | `@bitforgehq/ui/mobile`  | Bottom sheet with snap points, drag to dismiss and a backdrop                                 |
+| `bf-side-panel`        | `@bitforgehq/ui/overlay` | Desktop panel sliding in from the end edge, with a title, body and footer actions             |
+| `bf-theme-menu-button` | `@bitforgehq/ui/overlay` | Menu button with System, Light and Dark radio items bound to the colour scheme                |
+| `bf-toast`             | `@bitforgehq/ui/mobile`  | Passive status pill with an optional action that never steals focus                           |
+| `bf-tooltip`           | `@bitforgehq/ui/overlay` | Short hint beside a control on hover or keyboard focus, for desktop                           |
 
 ### Icons
 

package/ai/components/back-button.md

@@ -81,7 +81,7 @@ and its anatomy follows the shell mode (`provideBfShell({ mode })`, the platform
 
 ## When to use
 
-Use `bf-back-button` in the `start` slot of a pushed page's [bf-header](https://bitforge-ui.web.app/components/header) in the Capacitor shell. Use the browser's own back button and a breadcrumb instead on a desktop web page, and a [bf-button](https://bitforge-ui.web.app/components/button) link (`a[bfButton]`) for a named way back.
+Use `bf-back-button` in the `start` slot of a pushed page's [bf-header](https://bitforge-ui.web.app/components/header) in the Capacitor shell. Use the browser's own back button and a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) instead on a desktop web page, and a [bf-button](https://bitforge-ui.web.app/components/button) link (`a[bfButton]`) for a named way back.
 
 ## Basic usage
 
@@ -171,7 +171,42 @@ export class BackButtonLabelExampleComponent {}
 
 ## Desktop
 
-`bf-back-button` is part of the Capacitor shell (`provideBfShell()`). On a desktop web page the browser's back button and history already go back; add a breadcrumb or a named link instead. Inside the shell under a mouse, the iOS form darkens to `primary-strong` on hover and the Material form is a `text` icon button; both show the pointer cursor and a focus ring on keyboard focus only.
+`bf-back-button` is part of the Capacitor shell (`provideBfShell()`). On a desktop web page the browser's back button and history already go back; show where the page sits with a [bf-breadcrumb](https://bitforge-ui.web.app/components/breadcrumb) instead, or give a named way back with `a[bfButton]` (or an icon-only `a[bfIconButton]`, [bf-icon-button](https://bitforge-ui.web.app/components/icon-button)). Each level up is a `li[bfBreadcrumbItem]` holding the app's own `routerLink`; the breadcrumb draws the separators (never announced), marks the last item, the current page, with `aria-current="page"`, and collapses a long trail with `maxItems`. Put it in the `breadcrumb` slot of a [bf-page-header](https://bitforge-ui.web.app/components/page-header).
+
+```ts
+import { Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import { BfBreadcrumbComponent, BfBreadcrumbItemComponent } from '@bitforgehq/ui';
+
+/**
+ * The desktop replacement for a back button: a bf-breadcrumb.
+ *
+ * Every level up is the app's own `routerLink`; the last item is the current page, which the
+ * breadcrumb marks with `aria-current="page"`.
+ */
+@Component({
+  selector: 'app-example-back-button-breadcrumb',
+  imports: [RouterLink, BfBreadcrumbComponent, BfBreadcrumbItemComponent],
+  template: `
+    <bf-breadcrumb label="Back button breadcrumb">
+      @for (crumb of trail; track crumb.path) {
+        <li bfBreadcrumbItem>
+          <a [routerLink]="crumb.path">{{ crumb.label }}</a>
+        </li>
+      }
+      <li bfBreadcrumbItem>Back button</li>
+    </bf-breadcrumb>
+  `,
+})
+export class BackButtonBreadcrumbExampleComponent {
+  protected readonly trail: readonly { path: string; label: string }[] = [
+    { path: '/', label: 'Docs' },
+    { path: '/components', label: 'Components' },
+  ];
+}
+```
+
+Inside the shell under a mouse, the iOS form darkens to `primary-strong` on hover and the Material form is a `text` icon button; both show the pointer cursor and a focus ring on keyboard focus only.
 
 ## Theming
 
@@ -232,6 +267,11 @@ Goes back one page, or to `defaultHref` when the stack has none to go back to.
 
 ## Migration notes
 
+### 0.3.1
+
+The `## Desktop` docs and When to use name the desktop replacement, `bf-breadcrumb`, with an
+example. No code change.
+
 ### 0.3.0
 
 **Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `back` ("Back"),

package/ai/components/badge.md

@@ -43,13 +43,13 @@ Use `bf-badge` for a read-only status or count next to what it describes: "At ri
 
 ## Status labels
 
-The variant carries the meaning: `success`, `warning`, `danger`, `primary` or the default `neutral`.
+The variant carries the meaning: `success`, `warning`, `danger`, `primary`, `info` or the default `neutral`. `info` is for an informational label that is not a status, such as a category ("Design", "Billing"); it is a calm blue, distinct from the brand `primary`, so a category never reads as the selected or main thing. `variant` takes a `BfBadgeAppearance` (the five `BfBadgeVariant` tones plus `info`).
 
 ```ts
 import { Component } from '@angular/core';
 import { BfBadgeComponent } from '@bitforgehq/ui';
 
-/** Status badges in the four tones. */
+/** Status badges in the four status tones, and an informational info label. */
 @Component({
   selector: 'app-example-badge-status',
   imports: [BfBadgeComponent],
@@ -59,6 +59,7 @@ import { BfBadgeComponent } from '@bitforgehq/ui';
       <bf-badge variant="warning">At risk</bf-badge>
       <bf-badge variant="danger">Blocked</bf-badge>
       <bf-badge>Draft</bf-badge>
+      <bf-badge variant="info">Design</bf-badge>
     </div>
   `,
 })
@@ -125,6 +126,7 @@ Consumes tokens by variant, background then text:
 - `success`: `success-soft` / `success`
 - `warning`: `warning-soft` / `warning`
 - `danger`: `danger-soft` / `danger`
+- `info`: `info-soft` / `info` (≥ 4.5:1 in both modes; it is not derived from the primary, so a custom brand colour leaves it unchanged)
 - Count pill (`count` set): `primary` / `on-primary`, ignoring `variant`
 - Shape (label and count pill): `rounded-control` (`--radius-control`, `9999px` by default).
 
@@ -134,11 +136,11 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 ## Inputs
 
-| Name         | Type                                                                              | Default     | Description                                                                                                                                          |
-| ------------ | --------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `variant`    | `BfBadgeVariant` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger'`) | `'neutral'` | Tint for the label style. Ignored when `count` is set.                                                                                               |
-| `count`      | `number \| undefined`                                                             | `undefined` | Switches to the count pill; values above 99 render as "99+".                                                                                         |
-| `countLabel` | `string`                                                                          | `''`        | What the count counts ("unread messages"), read by assistive tech after the number ("99+ unread messages"); visually hidden. Only used with `count`. |
+| Name         | Type                                                                                           | Default     | Description                                                                                                                                          |
+| ------------ | ---------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`    | `BfBadgeAppearance` (`'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`) | `'neutral'` | Tint for the label style: neutral, primary, success, warning, danger or info. Ignored when `count` is set.                                           |
+| `count`      | `number \| undefined`                                                                          | `undefined` | Switches to the count pill; values above 99 render as "99+".                                                                                         |
+| `countLabel` | `string`                                                                                       | `''`        | What the count counts ("unread messages"), read by assistive tech after the number ("99+ unread messages"); visually hidden. Only used with `count`. |
 
 ## Slots
 
@@ -155,9 +157,17 @@ A badge is a plain `<span>` with no role or ARIA attributes; its text is read as
 
 - Don't use a badge as a button; it has no interactive states.
 - Don't invent new colors on it; pick the variant that matches the meaning.
+- Don't use `primary` or `success` for a category; use `info`, so the status tones keep their meaning.
 
 ## Migration notes
 
+### 0.3.1
+
+New `info` tone for informational labels such as a category, on the new `info` / `info-soft`
+tokens (7.7:1 in light, 7.2:1 in dark; not derived from the primary). `variant` is now typed
+`BfBadgeAppearance` (the five `BfBadgeVariant` tones plus `info`); `BfBadgeVariant` keeps its five
+members, so code that maps over it keeps compiling.
+
 ### 0.3.0
 
 **Behaviour:** the label and the count pill use `rounded-control` (`--radius-control`, `9999px` by