@bitforgehq/ui 0.3.0 → 0.3.2

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">
@@ -117,7 +117,12 @@ the widgets style their native controls themselves.
 Optional per-app overrides go after the import. A brand colour is a set: override
 `--color-primary` together with `--color-primary-text` (primary as text, ≥ 4.5:1 on `bg` and
 `surface`) and the rest of the `--color-primary-*` tokens, in `@theme` and in `.dark`; the docs
-site's theme configurator derives the whole contrast-checked set from one colour.
+site's theme configurator derives the whole contrast-checked set from one colour. From a
+terminal, `bunx bf-ui theme '<hex>' [--dark '<hex>']` prints the set (`primary`, its hover,
+pressed, soft and strong steps, `on-primary`, `primary-text`, `selected`, `ring`) as a `@theme`
+and a `.dark` block with each contrast pair's ratio, and exits 1 naming the pairs below their
+minimum and a shade that passes; paste its output, never hand-pick the steps. Example (the
+Meadow Sage green): `bunx bf-ui theme '#238652' --dark '#5cc48a'`.
 `--radius-control` (`9999px`, pills) reshapes buttons, chips, badges, segmented, the tab bar, the
 action bar and toggles at once:
 
@@ -138,15 +143,17 @@ 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 43 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 16
+number their ids differently on every render, from a module-level counter, so they could not
+hydrate: `bf-app-frame`, `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 +172,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 +272,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 +284,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 +314,101 @@ 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`:
+
+- **App frame:** wrap the whole app in `<bf-app-frame>` (never build the frame by hand): the
+  `bf-sidebar` in `bfSlot="sidebar"` (sticky, full height, from `md` up), and below the
+  breakpoint a header bar with `bfSlot="brand"`, `bfSlot="menu"` (a `bf-menu-button` of
+  `a[bfMenuItem]` links from the same destinations array) and `bfSlot="actions"` (the theme
+  menu); the router outlet is the content. It brings the skip link and the focusable main
+  landmark; `breakpoint` and `contentWidth` adjust it. Desktop only: never inside
+  `provideBfShell()`.
+- **Sidebar collapse:** `<bf-sidebar-toggle>` (`/overlay`, icons in `bfSlot="collapse-icon"` and
+  `bfSlot="expand-icon"`) in the sidebar footer beside the icon-only theme menu; with
+  `provideBfSidebarState()` bind `[(collapsed)]="sidebarState.collapsed"`
+  (`BfSidebarStateService`) so the choice is remembered.
+- **Navigation:** `bf-sidebar` (groups in `bf-nav-group`, `[(collapsed)]` for an icon rail) 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`. `stack="narrow"`
+  (below 36rem of its own width) or `stack="coarse"` turns each row into a label/value tile with
+  a sort and select bar; in the Capacitor shell use `bf-list-item` rows instead.
+- **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.
+- **Surfaces:** one surface style per level. A raised `bf-card` holds sunken tiles
+  (`bf-stat variant="tile"`), never an outlined surface (`variant="card"` or a `flat` card) inside
+  a raised one; next to raised cards on a dashboard, use raised cards.
+- **Empty pages:** a 404, "no access" or "nothing here yet" page is a `bf-empty-state` with
+  `headingLevel` 1, centred in the content area, with the main action and an optional link.
+- **Toolbar on a phone:** `bf-toolbar` keeps its status and actions together on the last row.
+
 ## Overlays (`@bitforgehq/ui/overlay`)
 
 A desktop or plain web app (no Capacitor, no router required) installs `@angular/cdk` and `rxjs`
@@ -331,6 +438,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 +976,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 +1162,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 +1196,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 +1247,52 @@ 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-app-frame`         | `@bitforgehq/ui`         | Desktop app frame with skip link, sticky sidebar, narrow header and main content            |
+| `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-sidebar-toggle`    | `@bitforgehq/ui/overlay` | Icon button inside a sidebar that collapses it to an icon rail and back                     |
+| `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