@bitforgehq/ui 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,122 @@ 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

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+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. `bunx bf-ui theme '#238652' --dark '#5cc48a'` prints the whole set for a brand colour, as a `@theme` and a `.dark` block to paste after the theme import, with every contrast pair's ratio, and exits 1 naming the failing pairs and a shade that passes (the docs site's Theming page has the recipe and a Meadow Sage green worked example).
 
 - Widgets: `@bitforgehq/ui`
 - Number field: `@bitforgehq/ui/number-input` (`bf-number-input`; loads Angular Forms, peer
@@ -140,16 +140,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 42 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`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 15
+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-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.
+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.
 
 ## Testing
 

package/ai/MANIFEST.index.json

@@ -37,6 +37,15 @@
       "summary": "Centred confirmation dialog with a title, message and a row of role-styled buttons",
       "since": "0.2.0"
     },
+    {
+      "name": "app-frame",
+      "selector": "bf-app-frame",
+      "className": "BfAppFrameComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Desktop app frame with skip link, sticky sidebar, narrow header and main content",
+      "since": "0.3.2"
+    },
     {
       "name": "avatar",
       "selector": "bf-avatar",
@@ -487,6 +496,15 @@
       "summary": "Vertical app navigation with brand, grouped links, footer and an icon rail mode",
       "since": "0.3.1"
     },
+    {
+      "name": "sidebar-toggle",
+      "selector": "bf-sidebar-toggle",
+      "className": "BfSidebarToggleComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Icon button inside a sidebar that collapses it to an icon rail and back",
+      "since": "0.3.2"
+    },
     {
       "name": "skeleton",
       "selector": "bf-skeleton",