@bitforgehq/ui 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,97 @@ 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.4.0 (2026-10-29)
+
+### timeline
+
+New: `bf-timeline`, a dated history of events (who did what, and when) for a record's history
+or an audit trail, in both shells. A `role="list"` named by `label`, in the order the consumer
+gives (it never sorts); each event's time is formatted with `Intl.DateTimeFormat` in the app's
+`LOCALE_ID` (`timeFormat`, default a medium date and a short time; `locale` overrides it).
+
+### timeline-event
+
+New: `bf-timeline-event`, one event of a `bf-timeline`: a 10 px marker coloured by `tone`
+(`neutral`, `primary`, `success`, `warning`, `danger`, `info`; new type `BfTimelineTone`) on a
+`border` line that ends at the last event, the event text in the default slot (links in it take
+the link style), then `actor` and `time` (a `Date` or an ISO 8601 string, in a `time` element;
+`timeText` shows a relative text while `datetime` keeps the exact value; an invalid time shows
+nothing). A `bfSlot="end"` action sits at the inline end, or under the text once the event is
+narrow.
+
+### table
+
+New: toggle cells for a settings matrix (rows of alert kinds, columns of channels, a `bf-toggle`
+in each cell), documented with the `table/toggle-matrix` example. `BfTableColumn.align` takes
+`'center'`: the header and each cell's control are centred, and while stacked the control sits at
+the tile's end, centred on its label line. New type `BfTableColumnAlign` (`BfTableAlign` plus
+`'center'`; `BfTableAlign` keeps its two members). A stacked cell of a start or end column keeps
+its baseline alignment. `@bitforgehq/ui/testing`: new `BfTableHarness.getCellHarness(row, column,
+query)` returns the harness of a control in one cell, and `selectRow()`, `getSelectedCount()`
+read only the selection column's checkboxes, never a checkbox or toggle in a custom cell.
+
+### toggle
+
+A label-less `sm` toggle (a table cell) takes a 44 px min-width under a coarse pointer, its track
+centred, so its touch target is 44 × 44 px (it was 40 px wide). Nothing changes under a fine
+pointer or for `md` and `lg`. `@bitforgehq/ui/testing`: new `BfToggleHarness` (`with({ label })`
+by the switch's computed name, `getLabel()`, `isChecked()`, `isDisabled()`, `isReadonly()`,
+`toggle()`, `check()`, `uncheck()`, `getErrorText()`).
+
+### badge
+
+New `emphasis` input (`BfBadgeEmphasis`: `soft`, the default, or `strong`). `strong` is a solid
+fill with contrasting text in every variant, for the one state that must stand out ("Critical");
+`primary` uses the brand fill. A strong count pill takes its fill from `variant` (a soft count pill
+stays primary, as before). In forced colours a strong badge keeps a `CanvasText` outline. Opt-in:
+without `emphasis` nothing changes.
+
+### theme
+
+New strong fill tokens in both modes, for the strong badge: `--color-neutral-strong`,
+`--color-success-strong`, `--color-warning-strong`, `--color-danger-strong` and
+`--color-info-strong`, each with its text token `--color-on-<tone>-strong` (`bg-danger-strong`,
+`text-on-danger-strong`, …). Every pair reaches 4.5:1 and every fill 3:1 on `bg`, `surface` and
+`surface-sunken` in both modes; danger is `#b3261e` / `#ffffff` in light and `#c9372c` /
+`#ffffff` in dark.
+
+New: Ink, an opt-in dark preset, `@bitforgehq/ui/dark-ink.css`. Import it after `theme.css`; it
+redefines tokens under `.dark` only (light mode is untouched): near-black surfaces one small step
+apart (`bg` `#0b0c0e`, `surface` `#121316`), see-through status tints (the tone at 12 %, so they
+sit on any surface; `danger-soft` stays opaque because the danger button writes it as text on
+the danger fill), off-white text, a neutral focus ring and a 1 px edge inside `shadow-raised` and
+`shadow-floating`. It sets every colour and shadow token of the default `.dark` block except the
+brand set, so the app's primary stays; the Theming guide has an optional monochrome primary block.
+Every pair is contrast-checked on `bg`, `surface`, `surface-muted` and `surface-sunken`. Four
+mockup values were lifted to pass: `border-strong`, `control-off` and `chart-axis` `#64676e`
+(3:1 on `surface-muted`), `text-muted` `#90949b` (4.5:1 on `primary-soft`) and `text-subtle`
+`#63676f` (3:1 on `surface-muted`). The default dark palette does not change.
+
+### list-item
+
+New `unread` input (boolean, default false) for a row not yet opened: a `primary` dot at the
+row's inline start on the title line, a bolder title (`font-extrabold`) and a visually hidden
+state read before the title, from the new label key `listItemUnread` ("Unread"). A row's
+`bfAction` link or button then names itself `aria-labelledby="<state> <itself>"` ("Unread,
+Report"; an id is added if it has none, and its own `aria-labelledby` is kept after the state).
+The dot sits in the row's own inline-start padding, so read and unread rows stay aligned. Opt-in: without `unread` nothing
+changes.
+
+### steps
+
+New `bf-steps`: numbered instructions a user follows in order ("Set up the app on your phone"),
+a `role="list"` of `bf-step` items whose markers are joined by a line. `start` (a number, 1 by
+default) continues a list; a continued list sets `aria-posinset` and `aria-setsize` on its steps
+so the announced position matches the visible number.
+
+### step
+
+New `bf-step`: one step of a `bf-steps` list, with `title` (the short instruction, text by
+default; `headingLevel` 2, 3 or 4, a `BfStepHeadingLevel`, makes it a heading) and the details
+in the default slot. Its number is drawn in a `primary-soft` circle and hidden from assistive
+technology, which reads the list position instead.
+
 ## 0.3.3 (2026-10-29)
 
 ### header

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. `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).
+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). For a near-black dark mode, `@bitforgehq/ui/dark-ink.css` (the opt-in Ink preset, imported right after the theme) redefines the dark tokens and leaves light mode and your brand as they are.
 
 - Widgets: `@bitforgehq/ui`
 - Number field: `@bitforgehq/ui/number-input` (`bf-number-input`; loads Angular Forms, peer
@@ -83,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. 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.
+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. For a near-black dark mode, add `@import '@bitforgehq/ui/dark-ink.css';` right after the theme import: the Ink preset, which changes dark mode only.
 
 ```html
 <html lang="en" class="dark">
@@ -140,10 +140,10 @@ 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 43 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`tools/ssr-smoke.ts` renders 45 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
+dialog), and all of them render without an error. 29 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`,

package/ai/MANIFEST.index.json

@@ -550,6 +550,24 @@
       "summary": "One labelled figure with an optional icon tile and a supporting line",
       "since": "0.3.1"
     },
+    {
+      "name": "step",
+      "selector": "bf-step",
+      "className": "BfStepComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "One numbered step of an instruction list, with a title and its details",
+      "since": "0.4.0"
+    },
+    {
+      "name": "steps",
+      "selector": "bf-steps",
+      "className": "BfStepsComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Numbered instruction steps a user follows in order, with joined markers",
+      "since": "0.4.0"
+    },
     {
       "name": "tab",
       "selector": "bf-tab",
@@ -640,6 +658,24 @@
       "summary": "Typed time-of-day field with a popover list of times, valued as an ISO string",
       "since": "0.3.1"
     },
+    {
+      "name": "timeline",
+      "selector": "bf-timeline",
+      "className": "BfTimelineComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Dated list of events with who did what and when, on a vertical line",
+      "since": "0.4.0"
+    },
+    {
+      "name": "timeline-event",
+      "selector": "bf-timeline-event",
+      "className": "BfTimelineEventComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "One timeline event with a coloured marker, its text, actor and time",
+      "since": "0.4.0"
+    },
     {
       "name": "toast",
       "selector": "bf-toast",