@bitforgehq/ui 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -4,6 +4,488 @@ All notable changes to `@bitforgehq/ui`. One `##` section per version; one `###`
 
 The heading for the version being worked on carries `(unreleased)` in place of a date. At release time, that placeholder is replaced with the release date (`## 0.3.1 (unreleased)` becomes `## 0.3.1 (YYYY-MM-DD)`) in the same commit that bumps `projects/ui/package.json`. See "Releasing" in the root `README.md`. 0.3.0 is the first version published to npm; the 0.2.0 and 0.1.0 sections below are the history of versions that were never published.
 
+## 0.3.1 (2026-10-29)
+
+### calendar
+
+New `bf-calendar` in `@bitforgehq/ui`: an inline month calendar for picking one date. The value
+is a plain ISO date string (`'YYYY-MM-DD'`) or `null`, never a `Date`, so no time zone shifts
+the day; `(changed)` emits a new pick and `(picked)` every pick (for a popover to close).
+`[(month)]` (`'YYYY-MM'`) is the month on show. `min`, `max` and `disabledDate`
+(`BfCalendarDisabledDate`) disable dates; `firstDayOfWeek` (`BfCalendarWeekday`) and `locale`
+(default the document's `lang`) set the week and the `Intl` month and weekday names; `today`
+overrides the device's date; `size` sets the cells (32/40/48 px, 44 px under a coarse pointer).
+The header's title opens a month view and then a year view for quick jumps. An ARIA grid with
+roving focus: arrows by day and week (mirrored in RTL), Page Up/Down by month (Shift by year),
+Home/End to the week's ends, Enter/Space picks, Escape leaves the jump views; disabled days stay
+focusable with `aria-disabled`. Signal Forms value contract like `bf-segmented`. New label keys
+`calendarPreviousMonth`, `calendarNextMonth`, `calendarChooseMonth`, `calendarChooseYear`, and
+a `BfCalendarHarness` in `@bitforgehq/ui/testing` (`getMonthLabel()`, `selectDate(iso)`,
+`getSelected()`, `nextMonth()`, `previousMonth()`).
+
+### toolbar
+
+New `bf-toolbar` in `@bitforgehq/ui`: a wrapping `role="group"` row for the search field and
+filters (default slot), a view switch (`bfSlot="view"`) and the trailing actions
+(`bfSlot="actions"`, kept together at the inline end). `label` names the group; `status` renders
+a polite `role="status"` live region for the result count. Its providers set
+`provideBfDefaults({ size: 'sm' })`, so every projected control and field is `sm` unless it sets
+`size` itself. Desktop only; in the Capacitor shell use `bf-header` actions and a `bf-sheet` of
+filters.
+
+### theme name
+
+The README, the package description, `theme.css`, the agent guide and the docs site's Theming
+page now say what the shipped colours are: the Meadow Sage palette with a neutral indigo default
+primary (`#2b26ba`) that is meant to be overridden, so an indigo primary after install is
+expected. The agent guide no longer calls the primary sage green. No token changes.
+
+### tabs
+
+The `## Desktop` docs name the desktop replacement: a `bf-top-nav` or `bf-sidebar` of
+`a[bfNavItem]` links with `routerLinkActive` and `ariaCurrentWhenActive="page"`, driven by the
+same destinations array as the shell's `bf-tab-bar`, with an example. No code change.
+
+### back-button
+
+The `## Desktop` docs and When to use name the desktop replacement, `bf-breadcrumb`, with an
+example. No code change.
+
+### header
+
+The `## Desktop` docs and When to use name the desktop replacement, `bf-page-header` (with
+`bf-breadcrumb` and `bf-toolbar`), with an example. No code change.
+
+### color-scheme
+
+New `provideBfColorScheme()` and `BfColorSchemeService` in `@bitforgehq/ui`, with no Capacitor:
+the System / Light / Dark choice (`BfColorScheme`), toggling `dark` on `<html>`, following
+`prefers-color-scheme` under `system` and storing the choice in `localStorage` under `bf-theme`
+(`BF_COLOR_SCHEME_STORAGE`). Storage and the media query are read in the browser only, so a server
+render starts light and writes nothing. A desktop web app no longer needs its own theme service.
+
+### platform
+
+`BfPlatformService` builds on `BfColorSchemeService`: `theme` and `dark` are its `scheme` and
+`dark` signals, and the shell claims `<html>` through it, so the system bars still follow the
+theme. Its public API, the `bf-theme` key and the in-memory fallback are unchanged;
+`BF_THEME_STORAGE` is now the same token as `BF_COLOR_SCHEME_STORAGE`, so providing either one
+moves the choice for both.
+
+### badge
+
+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.
+
+### theme
+
+New `--color-info` and `--color-info-soft` tokens in both modes (`text-info`, `bg-info-soft`),
+used by the badge's `info` tone.
+
+New `--animate-skeleton-shimmer` and `--animate-skeleton-shimmer-rtl` animations
+(`animate-skeleton-shimmer`, 1.6 s, endless), the sweep of `bf-skeleton`'s shimmer from the
+inline start.
+New `--color-tooltip` and `--color-on-tooltip` tokens in both modes (`bg-tooltip`,
+`text-on-tooltip`; 14.9:1 in light, 13.8:1 in dark), used by `bf-tooltip`.
+New chart tokens in both modes for `@bitforgehq/ui/charts`: `--color-chart-1` … `--color-chart-8`
+(a categorical palette in a fixed order: sage green, indigo, terracotta, teal, ochre, berry, violet,
+olive; each ≥ 3:1 on `surface` and `bg`, adjacent slots distinct under colour vision deficiency),
+`--color-chart-grid` (grid lines) and `--color-chart-axis` (the axis line, ≥ 3:1). New
+`--animate-chart-draw`, `--animate-chart-grow-y`, `--animate-chart-grow-x` and
+`--animate-chart-fade` animations, the charts' enter motion.
+
+### icon
+
+New `filled` input: fills the shape with `currentColor` and keeps the stroke, for a favourite
+heart or a starred item. Only icons whose every shape is closed are filled (`Heart`, `Star`,
+`Bookmark`, …); a stroke icon or an outline holding inner strokes renders as before, so `filled`
+never paints the area a check mark encloses or hides a stroke. Put the state in the control's name
+or `aria-pressed` too.
+
+### list
+
+New opt-in `divided` input: a `border` line between rows instead of a gap, with square rows whose
+hover fill reaches the list's edges. On a card, `<bf-list [inset]="false" divided class="-mx-card">`
+runs the rows edge to edge, and the rows take the card's inline padding so their text stays aligned
+with the card's content. A divided inset list is one rounded `surface`. Lists without `divided`
+look as before. When to use links `bf-table` for data compared across columns.
+
+### icon-button
+
+New `a[bfIconButton]` selector: put `bfIconButton` on your own `<a>` (with `href` or `routerLink`)
+for an icon-only link such as back, open or edit. The `<a>` takes the variant, size, focus ring
+and touch hit area, `label` becomes its `aria-label` (still required), and it behaves as a link
+(Enter, Ctrl/Cmd-click and middle click open it; `clicked` emits on every click). `type` and
+`disabled` do not apply, as on `a[bfButton]`. The `bf-icon-button` element is unchanged.
+
+### button
+
+New `ghost` variant: quiet and neutral (`text-muted` label, no fill at rest, `surface-muted` on
+hover, `surface-pressed` on press), with the `text` variant's sizes, padding and disabled state,
+for secondary toolbar actions and navigation rows. `a[bfButton]` with `aria-current="page"` shows
+the current page: `ghost` and `text` links take the tonal fill, `outline` a primary border, so a
+top nav built with `routerLinkActive` and `ariaCurrentWhenActive="page"` needs no `[variant]`
+switch. `variant` is now typed `BfButtonAppearance` (the five `BfButtonVariant` styles plus
+`ghost`); `BfButtonVariant` keeps its five members, so code that maps over it keeps compiling.
+
+### card
+
+The footer (`bfSlot="footer"`) sits on the card's bottom edge (`mt-auto`), so in a grid of cards
+whose descriptions wrap differently every footer lines up. A card whose footer already followed
+the body directly looks the same unless the card is taller than its content.
+
+### packaging
+
+The `bf-ui` bin entry points at `bin/bf-ui.js` without a leading `./`, the form npm stores, so
+`npm publish` no longer warns that it cleaned the path. The command itself is unchanged.
+
+### page-header
+
+New `bf-page-header` in `@bitforgehq/ui`, the desktop page header: a `breadcrumb` slot above,
+the `title` as an `h1` (`headingLevel` 2 for an `h2`, `BfPageHeaderHeadingLevel`) with an
+optional `subtitle`, a `meta` slot for badges beside the title, a `title` slot for rich title
+content, and an `actions` slot at the inline end that wraps under the title in a narrow window.
+Empty slots take no space. It is a sibling of `bf-header` (`/mobile`), not a shell-aware mode of
+it: no large title, no scroll-under surface, no safe areas.
+
+### table
+
+New `bf-table` and `ng-template[bfTableCell]` (`BfTableCellDirective`) in `@bitforgehq/ui`, a
+data table for desktop pages: `rows`, `columns` (`BfTableColumn`: `key`, `label`, `sortable`,
+`align` of `BfTableAlign`), `rowKey` (`BfTableRowKey`, the row's `id` by default) and a
+visually hidden caption from `label`. Sortable headers set the `sort` model (`BfTableSort`,
+`BfTableSortDirection`) and `aria-sort`; the consumer sorts the rows. `selectable` adds a
+checkbox column bound to the `selection` model of row keys, with a mixed header checkbox named
+by the new `tableSelectAll` label ("Select all rows") or `selectAllLabel`. A `bfTableCell`
+template replaces one column's cells (`BfTableCellContext`; `bfTableCellOf` types the row), the
+`empty` slot shows while there are no rows, `size` follows `controlSize`, and ArrowUp / ArrowDown
+move focus between the controls of a column. New `BfTableHarness` in `@bitforgehq/ui/testing`.
+
+The docs gain a Paging section and a `table/paged` example: one page of rows with a
+`bf-pagination` under the table, back to page 1 on a sort.
+
+### theme-switch
+
+New `bf-theme-switch` in `@bitforgehq/ui`: System, Light and Dark as a three-option
+`bf-segmented`, holding a `BfColorScheme` in `value` (`[(value)]`, `changed`), with `label`,
+`size` and `fullWidth`. It injects no service; bind it to `BfColorSchemeService.scheme`
+(`BfPlatformService.theme` in the shell). New `BfLabels` keys `theme`, `themeSystem`, `themeLight`
+and `themeDark`.
+
+### theme-menu-button
+
+New `bf-theme-menu-button` in `@bitforgehq/ui/overlay`: a `bf-menu-button` whose menu holds
+System, Light and Dark as radio items, for a crowded top bar. Same `value` / `changed` / `label`
+as `bf-theme-switch`, plus `iconOnly`, `variant`, `size`, `placement` (default `'below-end'`) and
+an `icon` slot for the consumer's sun or moon.
+
+### description-list
+
+New: `bf-description-list`, a native `dl` of label-value pairs for the details of one record, in
+both shells. `layout="rows"` (default) divides the pairs with a `border` line and puts the label
+beside the value once the list is 28rem wide (a container query, so a narrow pane stacks them);
+`layout="grid"` lays them out as wrapping tiles. New type `BfDescriptionListLayout`.
+
+### description-item
+
+New: `div[bfDescriptionItem]`, one pair of a `bf-description-list`: its required `label` is the
+`dt`, its content (text, a badge, a link) the `dd`.
+
+### stat
+
+New: `bf-stat`, one labelled figure in its own `dl`, with the value at the `title` size in
+tabular figures, an `icon` slot for a tile at the start and a supporting line in the default slot.
+`variant="card"` gives it the outlined `flat` card surface; `plain` (default) draws none. An
+opt-in trend: `delta` (the formatted change, such as `+12%`; empty shows nothing) with `trend`
+(`up`, `down`, `flat`) renders a pill beside the value with a CSS arrow mark and the direction as a
+hidden word (new labels `statTrendUp`, `statTrendDown`, `statTrendFlat`). `trendIntent`
+(`positive` default, up is good; `negative` when down is good, such as costs) picks `success` or
+`danger`; flat is neutral. New types `BfStatVariant`, `BfStatTrend` and `BfStatTrendIntent`.
+
+### breadcrumb
+
+New `bf-breadcrumb` in `@bitforgehq/ui`, the desktop breadcrumb trail: a `nav` (named by
+`label`, default `provideBfLabels()`'s new `breadcrumb` key, "Breadcrumb") around an `ol` of
+`li[bfBreadcrumbItem]` levels, with CSS chevrons between them that are never announced.
+`maxItems` collapses a longer trail to the first level and the last `maxItems - 1`, behind an
+ellipsis button (the new `breadcrumbExpand` label, "Show 2 more levels") that shows the hidden
+levels in place and focuses the first one; `bfSlot="overflow"` replaces that button with the app's
+own control, such as a `bf-menu-button` of the hidden levels. It replaces the hand-built
+breadcrumb the back-button docs showed.
+
+### breadcrumb-item
+
+New `li[bfBreadcrumbItem]` in `@bitforgehq/ui`: one level of a `bf-breadcrumb` on the app's own
+`<li>`. A projected link takes the muted link look, the hover underline and the focus ring (at
+least 24 px tall, 44 px under a coarse pointer); the last level is the current page, wrapped in
+`aria-current="page"` with no chevron.
+
+### sidebar
+
+New `bf-sidebar`: the vertical navigation of a desktop app, a `nav` landmark with `header`,
+default and `footer` slots, named by `label` (else the new `navigation` label, "Main").
+`collapsed` (a model the app binds to its own toggle button) turns it into an icon rail. Below a
+breakpoint, hide it with `hidden md:flex` and drive a `bf-menu-button` from the same routes.
+
+### top-nav
+
+New `bf-top-nav`: the horizontal navigation of a desktop app with few sections, a `nav` row of
+`a[bfNavItem]` links that wraps in a narrow container, named by `label` (else `navigation`).
+
+### nav-group
+
+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.
+
+### nav-item
+
+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.
+
+### tab-group
+
+New `bf-tab-group`: in-page tabs over the content they switch, in both shells. A `tablist` of
+`button role="tab"` from its `bf-tab-panel` children, the `selected` model of the shown panel's
+`value` with `changed` after a user change (unset or unknown shows the first enabled panel),
+named by `label` (else the new `tabGroup` label, "Tabs"), `size` from `controlSize` (44 px at
+least under a coarse pointer) and `fitted` to share the width. A roving tab stop and automatic
+activation: the arrow keys (mirrored under `dir="rtl"`), Home and End select and focus a tab,
+skipping disabled ones. The selected tab is underlined in `primary`; the row scrolls sideways
+when the tabs do not fit. New `BfTabGroupHarness` in `@bitforgehq/ui/testing` (`getTabLabels()`,
+`getSelectedLabel()`, `selectTab(label)`, `getPanelText()`).
+
+### tab-panel
+
+New `bf-tab-panel`: one tab of a `bf-tab-group` and its content (`role="tabpanel"`,
+`aria-labelledby` its tab, `tabindex="0"`): `value`, `label`, `disabled`, a `badge` count
+announced with `tabBadge(count)` and an `icon` slot shown in the tab. Content in an `ng-template`
+is created only while the panel shows; `keepAlive` keeps it, hidden, once visited.
+
+### docs site
+
+The docs site's initial bundle is 587 kB and the embedded mobile demo's 653 kB, over their 580 kB
+and 650 kB budget warnings: the example registry (one entry per example, in the initial bundle)
+gained about 40 examples for the desktop widgets, and the mobile demo's project page and Me tab now
+render `bf-stat`, `bf-description-list` and `bf-theme-switch`. The `initial` warnings
+(`angular.json`) are now 600 kB (docs) and 670 kB (mobile demo). The web demo's initial bundle (511 kB:
+its stylesheet holds the classes of every library widget, and the desktop frame now uses the side
+panel and tooltips) warns at 540 kB instead of 500 kB. The mobile demo's (677 kB) warns at 690 kB: `BF_DEFAULT_LABELS`
+is one object every app ships, and it gained about 60 keys for the new widgets.
+
+### labels
+
+New keys for the desktop widgets: `navigation` ("Main") and `navBadge(count)` ("{count} new")
+for `bf-sidebar`, `bf-top-nav` and `a[bfNavItem]`; `breadcrumb` ("Breadcrumb") and
+`breadcrumbExpand(count)` ("Show 2 more levels") for `bf-breadcrumb`; `tableSelectAll` ("Select
+all rows") for `bf-table`; `theme`, `themeSystem`, `themeLight` and `themeDark` for
+`bf-theme-switch` and `bf-theme-menu-button`.
+
+New keys for `bf-pagination`: `pagination` ("Pagination"), `previousPage` ("Previous page"),
+`nextPage` ("Next page"), `pageOf(page, count)` ("Page 3 of 12") and `goToPage(page)` ("Page 3").
+
+New keys for the `bf-stat` trend: `statTrendUp` ("Up"), `statTrendDown` ("Down") and
+`statTrendFlat` ("No change"), the hidden direction word before a delta.
+New keys for `@bitforgehq/ui/charts`: `chart` ("Chart"), `chartLegend` ("Legend"), `chartValues`
+("Data points, arrow keys move between them"), `chartShowData` ("Show data"), `chartHideData`
+("Hide data"), `chartCategory` ("Category"), `chartValue` ("Value"), `chartEmpty` ("No data to
+show") and `chartError` ("The data could not be loaded").
+
+### skeleton
+
+New `bf-skeleton` in `@bitforgehq/ui`, a loading placeholder for both shells: `shape` (the new
+`BfSkeletonShape`: `text` lines, a `rect` or a `circle`), `lines` for several text lines with a
+shorter last one, and `width` / `height` as CSS lengths. It draws the `surface-sunken` fill with a
+`surface` shimmer that sweeps from the inline start (hidden under reduced motion) and carries
+`aria-hidden="true"`; the docs mark the loading region with `aria-busy="true"` and show a card and
+a table of skeleton rows.
+
+### pagination
+
+New `bf-pagination` in `@bitforgehq/ui`, page navigation for both shells: a `nav` (named by
+`label`, else the new `pagination` label) with Previous and Next buttons around the page buttons.
+`[(page)]` is 1-based; the count comes from `pageCount`, else `total` over `pageSize` (default 10).
+The row keeps the first and the last page and `siblings` (default 1) on each side of the current
+one, which carries `aria-current="page"`, and turns hidden runs into an `aria-hidden` ellipsis, at
+a constant number of slots. `compact` shows "Page 3 of 12" (`pageOf`) between the arrows as a
+polite live region. At the ends the arrows are `aria-disabled` and stay focusable. `size` follows
+`controlSize`; the chevrons are CSS and mirror under `dir="rtl"`. New `BfPaginationHarness` in
+`@bitforgehq/ui/testing` (`getCurrentPage()`, `getPageCount()`, `getVisiblePages()`, `goTo()`,
+`next()`, `previous()`).
+
+### side-panel
+
+New `BfSidePanelService` and `bf-side-panel` in `@bitforgehq/ui/overlay`: a full-height panel
+that slides in from the inline end edge (the left under `dir="rtl"`; a cross-fade under reduced
+motion). `open(component | template, { data, width, modal, ariaLabel, injector })` returns a
+`BfSidePanelRef<R, C>` (`close(result)`, `afterClosed`, `closed()`, `componentInstance`); the
+content injects it and `BF_SIDE_PANEL_DATA`, and a template gets `{ $implicit: ref, data }`
+(`BfSidePanelTemplateContext`). `width` is a `BfSidePanelWidth`: `sm` 360 px, `md` 480 px
+(default), `lg` 640 px, capped at the viewport. Modal by default (a scrim that closes it, a focus
+trap, an inert page, no page scroll); `modal: false` keeps the page usable beside it, and
+`Escape` closes it only while focus is inside it. `bf-side-panel` renders the `title` as the
+`h2` the panel is labelled by, a close button named by the `close` label (`closeLabel`), a
+scrolling body and a `footer` slot kept at the bottom. New `BfSidePanelHarness` in
+`@bitforgehq/ui/testing` (`getTitle()`, `close()`, `isOpen()`). Desktop only; in the Capacitor
+shell use `bf-sheet` or `bf-modal`.
+
+### overlay core
+
+New `modal` option of `BfOverlayService.open()` (default true): `modal: false` opens an overlay
+with no backdrop, no focus trap and no `aria-modal`, outside `BfOverlayStack` (the page stays
+usable and scrollable); focus moves in, `Escape` closes it only while focus is inside it, and on
+close focus returns to the opener only from inside it. New `position: 'end'` (full height
+against the inline end edge) through the new `BfOverlayPlacement` type
+(`BfOverlayPosition | 'end'`), the type of `BfOverlayOptions.position` now. New motion helpers
+`slideInFromEnd()` and `slideOutToEnd()`, mirrored under `dir="rtl"`.
+
+### tooltip
+
+New `[bfTooltip]` (`BfTooltipDirective`) and its `bf-tooltip` pill (`BfTooltipComponent`) in
+`@bitforgehq/ui/overlay`: a short hint beside a control after a 500 ms hover or at once on keyboard
+focus, hidden on leave, blur and `Escape`, and kept while the pointer moves onto it (WCAG 1.4.13).
+`bfTooltipPlacement` (`BfTooltipPlacement`: `top` default, `bottom`, `start`, `end`, logical)
+flips when it would overflow. While it shows, the control is described by it
+(`aria-describedby`). Nothing shows under a coarse pointer. Fades in over 120 ms, not under
+reduced motion. New `BfTooltipHarness` in `@bitforgehq/ui/testing`.
+
+### popover
+
+New `[bfPopoverTriggerFor]` (`BfPopoverTriggerDirective`, exported as `bfPopoverTrigger`) and the
+`bf-popover` panel (`BfPopoverComponent`) in `@bitforgehq/ui/overlay`: a non-modal `role="dialog"`
+panel anchored to its trigger, for filters, details or a small form. `bfPopoverPlacement`
+(`BfPopoverPlacement`, the menu's four placements), `bfPopoverLabel`, `(bfPopoverOpened)` and
+`(bfPopoverClosed)`, and `open()`, `close()`, `toggle()`, `isOpen()`. The trigger's control gets
+`aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; focus moves in on open, `Tab` is not
+trapped (it closes the panel past either end), and `Escape`, a click outside or a navigation close
+it and return focus. New `BfPopoverHarness` in `@bitforgehq/ui/testing`.
+
+### menu
+
+The menu's positions now come from the anchored-panel positioning the popover and tooltip share.
+No behaviour change.
+
+### combobox
+
+New `bf-combobox` (`BfComboboxComponent<T>`) in `@bitforgehq/ui/overlay`: a text field with a
+list of options that filters as you type, to pick one value (the ARIA 1.2 combobox pattern with a
+list autocomplete). `[(value)]` is `T | null`; `options` are `BfComboboxOption<T>` (`value`,
+`label`, `description`, `disabled`, `group`); `compareWith`, `label`, `ariaLabel`,
+`ariaLabelledby`, `placeholder`, `helpText`, `errorMessage`, `size` (`fieldSize`) and the Signal
+Forms value contract like `bf-select`. Filters by label, ignoring case and accents; `filter`
+(`BfComboboxFilter<T>`) replaces the match, `null` turns local filtering off for server results,
+`(queried)` emits the typed text and `loading` shows a spinner row. Arrow keys open and move
+(wrapping), `Home`/`End`, `Enter` picks, `Escape` closes then drops the typed text, `Tab` picks
+nothing; leaving the field reverts unmatched text to the picked label (emptied text clears the
+value, `(changed)` emits `null`). Grouped options render in named `role="group"` sections. New
+label key `comboboxEmpty` ("No results", or `emptyLabel`) and a `BfComboboxHarness` in
+`@bitforgehq/ui/testing` (`open()`, `type(query)`, `getOptionLabels()`, `selectOption(label)`,
+`getValueText()`, `getChipLabels()`, `removeChip(label)`) for both comboboxes.
+
+### multi-combobox
+
+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`.
+
+### date-input
+
+New `bf-date-input` in `@bitforgehq/ui/overlay`: a date field typed part by part, the day, month
+and year as spinbuttons in the locale's order and separators (`Intl.DateTimeFormat`
+`formatToParts`), with muted placeholders (dd/mm/yyyy). Digits type in and move on by themselves,
+Arrow Up/Down step with wrapping, Backspace clears, Arrow Left/Right move between the parts. The
+value is an ISO date string (`'YYYY-MM-DD'`), `null` while empty or incomplete, and `(changed)`
+emits each user change. `picker` (`BfDateInputPicker`: `'calendar'`, the default, or `'none'`)
+adds a button that opens a `bf-calendar` in an anchored popover; a pick closes it and returns
+focus. `min`, `max` and `disabledDate` bound the calendar and show the field's own error for a
+typed date outside them (as for an incomplete or impossible one). `native` renders
+`input type="date"` under a coarse pointer, for the Capacitor shell. `locale`, `size`
+(`fieldSize`), `openPicker()`, `closePicker()`, `focus()`, and the Signal Forms value contract
+like `bf-input`. New label keys `dateInputDay`, `dateInputMonth`, `dateInputYear`,
+`dateInputOpenCalendar`, `dateInputInvalid` and `dateInputUnavailable`, and a
+`BfDateInputHarness` in `@bitforgehq/ui/testing` (`getValue()`, `setValue(text)`, `clear()`,
+`openPicker()`, `pickDate(iso)`).
+
+### time-input
+
+New `bf-time-input` in `@bitforgehq/ui/overlay`: a time-of-day field typed as hour and minute
+(and second with `seconds`), with an AM/PM part under a 12-hour clock. The clock follows the
+locale; `hourCycle` (`BfTimeInputHourCycle`: `'h12'` or `'h23'`) forces one. The value is an ISO
+time on a 24-hour clock (`'HH:mm'`, `'HH:mm:ss'` with seconds). `picker` (`BfTimeInputPicker`:
+`'list'`, the default, or `'none'`) adds a button that opens a listbox of times every `step`
+minutes (30 by default), scrolled to the value; `min` and `max` disable the times outside them
+and show an error for a typed one. `native` renders `input type="time"` under a coarse pointer.
+New label keys `timeInputHour`, `timeInputMinute`, `timeInputSecond`, `timeInputDayPeriod`,
+`timeInputOpenList`, `timeInputInvalid`, `timeInputMin` and `timeInputMax`, and a
+`BfTimeInputHarness` in `@bitforgehq/ui/testing` (`setValue(text)`, `pickTime(time)`).
+
+### datetime-input
+
+New `bf-datetime-input` in `@bitforgehq/ui/overlay`: the date and the time parts in one field,
+valued as a local ISO date and time without a zone (`'YYYY-MM-DDTHH:mm'`). `picker`
+(`BfDateTimeInputPicker`: `'popover'`, the default, or `'none'`) opens one popover with the
+calendar and a list of times side by side: a day moves focus to the list, a time closes it.
+`min` and `max` bound the calendar and, on their own day, the list. `step`, `hourCycle`,
+`disabledDate`, `native` (`input type="datetime-local"`) and the field contract as on the date
+and time inputs. New `BfDateTimeInputHarness` in `@bitforgehq/ui/testing` (`pickDate(iso)`,
+`pickTime(time)`, `setValue(text)`).
+
+### line-chart
+
+New `bf-line-chart` in the new `@bitforgehq/ui/charts` entry (which imports only Angular core and
+common and the root entry): one or more `series` (`BfChartSeries`: `name`, `values` with `null`
+for a gap) over `categories`, drawn in SVG with the `--color-chart-*` tokens. A value axis of nice
+ticks (1, 2 or 5 × 10ⁿ), a legend that shows and hides series (`aria-pressed`; `legend`:
+`BfChartLegendPosition` `top`, `bottom` or `none`), a crosshair tooltip with markers on hover and
+on keyboard focus (the plot is focusable; the arrow keys, `Home`, `End` and `Escape` move between
+the categories and a polite live region reads each one), and a Show data toggle that shows the data
+as a table. `area` fills under the lines, `curve` (`BfChartCurve`: `linear` or `smooth`, a monotone
+cubic) shapes them, `valueFormat` formats every value (default `Intl.NumberFormat` in the document's
+language), `height` sets the plot's height and the width follows the container (`ResizeObserver`;
+600 px on the server). Lines draw in on the first render and on every data change, not under
+reduced motion; `dir="rtl"` mirrors the category axis.
+New `BfChartHarness` in `@bitforgehq/ui/testing` for the line, bar and donut charts:
+`getLabel()`, `getSeriesNames()`, `isSeriesShown()`, `toggleSeries()` and `showData()` (the data
+table's rows).
+
+### bar-chart
+
+New `bf-bar-chart` in `@bitforgehq/ui/charts`: series over categories as bars from a zero
+baseline, side by side or `stacked`, vertical or `orientation="horizontal"`
+(`BfBarChartOrientation`), with the line chart's value axis, legend, tooltip, keyboard reading and
+data table. Bars grow from the baseline on the first render and on every data change, not under
+reduced motion; `dir="rtl"` mirrors the horizontal axis.
+
+### donut-chart
+
+New `bf-donut-chart` in `@bitforgehq/ui/charts`: `slices` (`BfDonutSlice`: `label`, `value`) as
+the parts of a whole, with a `thickness`, a `center` slot for a total, a legend that hides slices
+(the shares follow), a tooltip with each slice's value and share, keyboard reading and a data
+table. Slices draw in along the ring, not under reduced motion, and run counter-clockwise under
+`dir="rtl"`.
+
+### sparkline
+
+New `bf-sparkline` in `@bitforgehq/ui/charts`: a tiny line of one series with no axes, legend or
+tooltip, for a `bf-stat`'s supporting line or a table cell; `area`, `curve` and `height`, a dot on
+the latest value. With a `label` it is a named image, without one it is decorative.
+
+### chart-card
+
+New `bf-chart-card` in `@bitforgehq/ui/charts`: the `flat` card surface around one chart, with a
+`title` (the chart's name when it has no `label`; `headingLevel`, `BfChartCardHeadingLevel` 2 or
+3), a `period` slot for the range control, the `legend` placement for the chart inside, and
+`loading` (a `bf-skeleton`, `aria-busy`), `empty` and `error` states with slots of the same names
+and the `chartEmpty` and `chartError` labels as fallbacks.
+
 ## 0.3.0 (2026-09-28)
 
 ### Migration

package/README.md

@@ -2,12 +2,16 @@
 
 Bitforge's shared Angular component library: Meadow Sage design, Tailwind CSS v4, signals-first, Angular 22.
 
+The theme is the Meadow Sage palette (warm off-white canvas, white surfaces, sage-tinted neutrals and status colours, pill controls). Its default primary is a neutral indigo (`#2b26ba`), not the design's sage green: it is meant to be overridden with your brand colour (`--color-primary` and its set; the docs site's theme configurator derives them), so an indigo primary after install is expected, not a broken install.
+
 - Widgets: `@bitforgehq/ui`
 - Number field: `@bitforgehq/ui/number-input` (`bf-number-input`; loads Angular Forms, peer
   dependency `@angular/forms`)
 - Icons: `@bitforgehq/ui/icons` (Lucide data, peer dependency `lucide`)
 - Overlay core: `@bitforgehq/ui/overlay` (no Capacitor; peer dependencies `@angular/cdk` and
   `rxjs`)
+- Charts: `@bitforgehq/ui/charts` (line, bar and donut charts, sparklines and the chart card, drawn
+  in SVG with the `--color-chart-*` tokens; no peer dependency beyond the widgets entry)
 - Mobile shell: `@bitforgehq/ui/mobile` (from v0.2)
 - Test support: `@bitforgehq/ui/testing` (jsdom shims, `provideBfTesting()`, CDK component
   harnesses; needs `@angular/cdk` as a dev dependency)
@@ -79,7 +83,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">
@@ -136,15 +140,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.
 
 ## Testing
 
@@ -156,7 +161,8 @@ jsdom lacks them. `provideBfTesting()` passes defaults and labels to the widgets
 overlays and themes leave on the document after each test (when TestBed destroys the test
 environment, so keep its default `teardown: { destroyAfterEach: true }`), and the CDK harnesses
 (`BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`,
-`BfMenuButtonHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfDesktopToastHarness`) drive the
+`BfMenuButtonHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfDesktopToastHarness`,
+`BfTableHarness`, `BfPaginationHarness`, `BfTabGroupHarness`, `BfCalendarHarness`, `BfChartHarness`) drive the
 widgets whose DOM a spec should not query by hand; overlays come from
 `TestbedHarnessEnvironment.documentRootLoader(fixture)`. An app on the mobile shell uses
 `provideBfShellTesting()` from `@bitforgehq/ui/mobile` instead (router, shell, an in-memory theme