@bitforgehq/ui 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,604 @@ 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.2 (2026-10-29)
+
+### docs site
+
+The docs initial bundle (620 kB) warns at 640 kB instead of 600 kB: the example registry ships in
+the initial bundle and gained this release's examples (moving it into a lazy chunk is the lasting
+fix). The web demo loads its app frame lazily, like its pages, and its initial bundle (542 kB, the
+stylesheet with every widget's classes) warns at 560 kB instead of 540 kB.
+
+### tabs
+
+The `## Desktop` docs point at `bf-app-frame` for the frame around the desktop navigation.
+
+### header
+
+The `## Desktop` docs say `bf-app-frame` supplies the app-level header bar below its breakpoint.
+
+### app-frame
+
+New `bf-app-frame` in `@bitforgehq/ui`: the frame of a desktop web app. Slots `sidebar` (a
+`bf-sidebar`, in a column that sticks to the viewport at full height from the breakpoint up),
+`brand`, `menu` (the narrow-screen `bf-menu-button`) and `actions` (the header bar shown below
+the breakpoint) and the default slot (the page, in the `main` landmark). `breakpoint`
+(`BfAppFrameBreakpoint`: `'md'` default, `'lg'`), `contentWidth` (`BfAppFrameContentWidth`:
+`'md'` 48rem, `'lg'` 64rem, `'xl'` 80rem default, `'full'`) and `mainId`. A skip link, first in
+the tab order and hidden until focused, moves focus to the main landmark by script, so it works
+under `<base href="/">`; new label key `skipToContent` ("Skip to main content"). Inside another
+`main` landmark the content drops its `main` role. Desktop only: the Capacitor shell keeps
+`bf-tabs`.
+
+### toolbar
+
+On a narrow row the actions no longer end up alone on a row of their own: the status and the
+actions are now one group that takes the rest of the last row and wraps as a whole, with the
+status at the start and the actions at the inline end. The wide layout is unchanged, and a
+toolbar without actions keeps the status as a plain item of the row. New `toolbar/narrow`
+example at phone width.
+
+### stat
+
+New `variant="tile"`: a sunken, borderless tile (`surface-sunken`, the `card` radius and
+padding) for a row of stats inside a raised `bf-card`; on it the icon tile turns `surface`.
+`variant` now takes the new named type `BfStatAppearance` (`BfStatVariant | 'tile'`); the
+released `BfStatVariant` keeps its two members, so `Record`s over it keep compiling. New
+`stat/dashboard` example with one surface per level.
+
+### card
+
+New "Nesting surfaces" docs section: a raised card holds sunken tiles, never an outlined
+surface (`flat`, a `card` stat), and each level of a dashboard keeps one surface style. New
+`card/nesting` example. No code change.
+
+### empty-state
+
+`headingLevel` now takes the new named type `BfEmptyStateHeading` (`BfEmptyStateHeadingLevel |
+1`): `1` renders the title as the page's `h1`, for an empty state that is the page (a not-found
+or no-access page). The released `BfEmptyStateHeadingLevel` keeps its two members, so `Record`s
+over it keep compiling. New "As the page" docs section with the `empty-state/page` example
+(centred in a tall area, a primary action and a secondary link) and the code-only
+`empty-state/not-found-page`.
+
+### table
+
+New opt-in `stack` input (`BfTableStack`: `'never'` by default, so existing tables do not
+change, `'narrow'` or `'coarse'`): while the table is narrower than 36rem (a container query on
+the host, which then gets `@container`) or, for `'coarse'`, under a coarse pointer at any width,
+each body row renders as a sunken tile of label/value pairs. The markup stays a `table` with
+explicit `table`, `rowgroup`, `row`, `columnheader` and `cell` roles (some browsers drop a
+table's semantics once its display changes), the header row is visually hidden but still read,
+the selection checkbox and the first cell head each tile, and every other cell shows its column
+label (`data-label`, a `::before` with empty alternative text, so it is not read twice). A bar
+above the tiles holds a labelled Select all checkbox and a Sort by `bf-select`, since the hidden
+header's controls are not shown. New label keys `tableSortBy` ("Sort by"), `tableSortAscending`
+and `tableSortDescending` (`"Hours, ascending"`). `BfTableHarness` reads and drives a stacked
+table the same way. New `table/stacked` example and a Stacked rows docs section.
+
+### sidebar-toggle
+
+New `bf-sidebar-toggle` in `@bitforgehq/ui/overlay`: a text icon button placed inside a
+`bf-sidebar` (header or footer) that flips the sidebar between full width and an icon rail by
+writing its `collapsed` model, so `[(collapsed)]` sees every press. Its name and `bfTooltip` say
+what the next press does (new label keys `sidebarCollapse` "Collapse sidebar" and `sidebarExpand`
+"Expand sidebar"); `aria-expanded` follows the sidebar and `aria-controls` points at its `nav`.
+Icons are the `collapse-icon` and `expand-icon` slots, only the matching one shown; `size` as
+`bf-icon-button`. Outside a sidebar (in a `bf-top-nav`, or alone) it renders nothing. A
+`BfSidebarToggleHarness` in `@bitforgehq/ui/testing` (`getLabel()`, `isExpanded()`, `toggle()`).
+
+### sidebar
+
+New `BfSidebarStateService` (a `collapsed` signal) and `provideBfSidebarState()` in
+`@bitforgehq/ui`: bind the sidebar's `[(collapsed)]` to `sidebarState.collapsed` and the provider
+stores every change under `bf-sidebar-collapsed` in `BF_SIDEBAR_STATE_STORAGE` (`localStorage` in
+the browser, memory elsewhere), read back at the next start; without the provider nothing is
+written, and on the server nothing is read. The sidebar's `nav` now has an id, for a toggle's
+`aria-controls`. The docs gain "Remember the collapsed sidebar" and a "Footer" composition
+(Settings link, theme menu, toggle, version line) that works expanded and as an icon rail.
+
+### theme
+
+Decision: the default primary stays indigo (`#2b26ba`). Making the Meadow Sage green the default
+would recolour every app that relies on the indigo, a breaking change; a brand override recipe
+gives a new app the green (or any brand) on day one instead. No token changes.
+
+New `bf-ui theme <hex> [--dark <hex>]` command in the package's CLI (no new dependencies): it
+derives the brand set (`--color-primary`, `-hover`, `-pressed`, `-soft`, `-soft-hover`,
+`-soft-pressed`, `-strong`, `--color-on-primary`, `--color-primary-text`, `--color-selected`,
+`--color-ring`) for light and dark mode with the docs configurator's OKLCH steps, keeping white
+text on the brand in light mode; `--dark` sets the dark-mode primary (else the brand is lifted to
+OKLCH lightness 0.76). It prints a `@theme` and a `.dark` block to paste after the theme import,
+with every brand contrast pair's ratio in a comment (the pairs of the theme's contrast test, plus
+`primary` at 3:1 on `bg` and `surface`), and exits 1 naming each pair below its minimum and the
+nearest darker (light) or lighter (dark) shade that passes. The docs Theming page gains a "Brand
+colour: the recipe" section (each token, how it is derived in light and dark, and why) with a
+Meadow Sage green worked example (`bf-ui theme '#238652' --dark '#5cc48a'`; the design's
+`#2f8f5b` gives white text only 4.04:1), and the agent guide and README point to the command.
+
+## 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