@bitforgehq/ui 0.3.3 → 0.5.0-next.3

package/CHANGELOG.md

@@ -4,6 +4,400 @@ 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.5.0 (unreleased)
+
+### Migration
+
+Breaking changes from 0.4.x, each with its fix:
+
+1. `bf-select` moved to `@bitforgehq/ui/overlay`. Before:
+   `import { BfSelectComponent } from '@bitforgehq/ui'`. After:
+   `import { BfSelectComponent } from '@bitforgehq/ui/overlay'`, which needs `@angular/cdk` and
+   `rxjs` (`bun add @angular/cdk rxjs`). The selector, inputs, outputs and Signal Forms binding
+   are unchanged; `BfSelectOption` is still exported from `@bitforgehq/ui` (and now from
+   `/overlay` too).
+2. Under a mouse `bf-select` is no longer a native `<select>`. `checkValidity()` and the
+   browser's "required" popup do not apply in the styled mode; enforce `required` through Signal
+   Forms. Tests that set a `<select>`'s value directly pick by label with `BfSelectHarness`
+   instead, which drives both modes.
+3. A stacked `bf-table`'s "Sort by" control stays the native select unless the app adds
+   `provideBfSelect()` from `@bitforgehq/ui/overlay` to its providers. Without it, that
+   control's host element changed from `bf-select` to `bf-native-select[data-bf-select]`: update
+   app CSS and DOM queries such as `bf-table bf-select`.
+4. A collapsed `bf-sidebar` is a fixed rail (56, 64 or 72 px for `controlSize` `sm`, `md` and
+   `lg`; 68 px under a coarse pointer for `sm` and `md`) instead of `w-auto`, so its width can
+   animate. Its regions no longer centre their content while collapsed. Before: header or footer
+   content wider than the icons widened the rail, and narrower content was centred. After: the
+   rail keeps its width and clips wider content, and content is aligned to the inline start. Fix:
+   make collapsed header and footer content fit the rail, using `in-data-collapsed:` to show a
+   compact brand and to fade or close the rest (see the sidebar's Motion section), and put
+   stacked icon buttons in a `flex flex-col items-start` column.
+
+### file-input
+
+New: `bf-file-input`, a file picker field. The `field` look (the default) is a tonal "Choose
+file" button inside a field box that also takes dropped files; `variant="dropzone"` is a dashed
+area that is the control as a whole (click, Enter, Space or a drop). The chosen files are listed
+under it with a thumbnail (images) or the extension, the name, the size and a remove button. The
+value is a `File[]` (one file at most without `multiple`), bound with `[(value)]` or
+`[formField]`. `accept` (MIME types, `type/*` and `.ext`, checked on drops too), `maxSize`
+(bytes) and `maxFiles` decide what is added; a file that breaks one never enters the value and
+never sets `invalid`: it shows as a red row with the reason until the next pick and is emitted
+through `rejected` (new types `BfRejectedFile`: `file`, `reason`, `message`; and
+`BfRejectedFileReason`: `'type' | 'size' | 'count'`). It only picks; uploading stays with the app. New type `BfFileInputVariant`, new label
+keys `fileInputChoose`, `fileInputDropHint`, `fileInputDropzone`, `fileInputTapToChoose`,
+`fileInputRemove`, `fileInputDismiss`, `fileInputAdded`, `fileInputNotAdded`,
+`fileInputRemoved`, `fileInputCount`, `fileRejectedType`, `fileRejectedSize` and
+`fileRejectedCount`. `@bitforgehq/ui/testing`: new `BfFileInputHarness` (`addFiles()` drops files
+through the same rules, `getFileNames()`, `getRejected()`, `removeFile()`, `getVariant()`).
+
+### image-input
+
+New: `bf-image-input`, a single-image picker for an avatar, logo or cover: a `round` or `square`
+tile (`shape`, new type `BfImageInputShape`; 64, 96 or 128 px with `size`) that shows the image or
+a camera glyph, with Upload/Replace and Remove beside it. The value is a `File | null`. `src`, a
+two-way `model()`, shows the image the app already has; Remove clears both `value` and `src`, so
+the app can tell a new picture (`value` set), a removed one (both null) and an unchanged one
+(`src` kept, `value` null) apart. `accept` (default `image/*`) and `maxSize` refuse an image
+without touching the current one: the reason shows under the buttons and `rejected` emits it. It
+only picks; uploading stays with the app. New label keys `imageInputChoose`, `imageInputUpload`,
+`imageInputReplace` and `imageInputRemove`. `@bitforgehq/ui/testing`: new `BfImageInputHarness`
+(`addFile()`, `hasPreview()`, `getPreviewSrc()`, `remove()`, `getRejectedMessage()`).
+
+### select
+
+**Breaking:** `bf-select` moved from `@bitforgehq/ui` to `@bitforgehq/ui/overlay` (see
+Migration). Under a fine pointer it now opens a styled list, the combobox's panel without the
+search, exactly as wide as the field: a focusable `role="combobox"` field following the APG
+select-only combobox pattern (Enter, Space, the arrows and Alt+ArrowDown open; the arrows,
+Home/End and PageUp/PageDown move; Enter, Space, Tab or a click pick; Escape closes without
+closing a dialog underneath). Typeahead (500 ms buffer, case and accents ignored) moves the active
+option, open or closed, and never commits on its own. Under a coarse pointer
+(`matchMedia('(pointer: coarse)')`, followed live) it renders the native `<select>` as before;
+on the server it renders the styled field. With `name` set, a hidden input carries the chosen
+option's key, so plain form posts keep working (none while disabled). With a visible `label` the
+field is named by `aria-labelledby` pointing at the label (a `<label for>` cannot name a div);
+`ariaLabel` and `ariaLabelledby` still apply only without one. Under forced colours a disabled
+field shows `GrayText`. `@bitforgehq/ui/testing`: `BfSelectHarness` drives both modes by label,
+and has a new `isOpen()`; in both modes `getOptionLabels()` reads a read-only or disabled
+select's options, and `selectOption()` on a read-only select changes nothing.
+
+The styled list animates open and closed with the popover's motion (180 ms in, 130 ms out). The
+field's `aria-expanded` and focus change at once; the closing list is inert and keeps the options
+it showed until it is gone. Under `prefers-reduced-motion` it only fades. The native select under
+touch is unchanged.
+
+### field
+
+New `labelId`: the label's id (`<controlId>-label`), which the label now carries, for a control
+that names itself with `aria-labelledby`.
+
+The error message fades in when it appears (new `--animate-message-in`, 150 ms of opacity),
+including a message held back during a press, which fades in once the press ends. `bf-toggle` and
+`bf-calendar` messages do the same. It is an opacity fade only, so it stays under reduced motion.
+
+### overlay core
+
+Anchored panels (combobox, select, popover, tooltip, date and time pickers), dialogs, side panels
+and desktop toasts build their CDK overlays with the CDK's standalone factories
+(`createOverlayRef()` and the `create*Strategy()` functions) instead of the `Overlay` service, so
+an app's bundle no longer carries the scroll and position strategies it never uses.
+
+### combobox
+
+The list panel is exactly as wide as the field (it shrank to its content inside the CDK pane).
+
+The list of `bf-combobox` and `bf-multi-combobox` animates open and closed with the popover's
+motion (180 ms in, 130 ms out). `aria-expanded` changes at once; the closing list is inert and
+keeps the options it showed, so a reset query does not reflow it while it fades, and typing or
+`ArrowDown` during the exit opens a fresh list. Under `prefers-reduced-motion` it only fades.
+
+### multi-combobox
+
+The list panel is exactly as wide as the field. The inner text input no longer shows a square
+border and ring on focus in apps that load `@tailwindcss/forms`.
+
+### table
+
+New `BF_TABLE_SORT_SELECT` injection token: the component a stacked table renders as its "Sort
+by" select (`null`, the default, keeps the native one). `provideBfSelect()` from
+`@bitforgehq/ui/overlay` sets it to the styled `bf-select`, so the core entry still never imports
+the CDK. `BfTableHarness.getSortSelect()` returns a working `BfSelectHarness` either way.
+
+### theme
+
+New motion token `--bf-duration-layout` (200 ms) in `:root`, beside `--bf-duration-fast` and
+`--bf-duration-overlay`: the timing of size and position changes (the sidebar's width, sliding
+selection indicators). Use it with `ease-md`, as in
+`transition-[width] duration-(--bf-duration-layout) ease-md motion-reduce:transition-none`.
+
+### sidebar
+
+Collapsing and expanding now animate: the width moves over `--bf-duration-layout` on `ease-md`
+from `w-60` to a fixed rail (see Migration 4), and the content beside it (the `bf-app-frame`
+column) moves with it. Under `prefers-reduced-motion: reduce` it still switches at once. The first
+render never animates, so a collapsed state restored by `provideBfSidebarState()` does not slide
+on load. The host carries `data-collapsed` as before; header and footer content can follow on the
+same timing with `in-data-collapsed:` (new Motion section in the docs).
+
+### nav-item
+
+In a collapsing sidebar the item no longer switches to a centred square: the row keeps its layout
+and its start padding moves so the icon ends centred in the rail without moving, while the label
+fades out (it stays the accessible name; it is no longer `sr-only`). The count pill shrinks away
+while the dot (new element, `[data-badge-dot]`) grows in on the same timing. Each item clips
+what does not fit the rail. No animation under reduced motion or in a top nav.
+
+### nav-group
+
+Collapsed, the heading's row closes and its text fades out on `--bf-duration-layout` instead of
+switching to `sr-only`; it stays in the accessibility tree and still names the group. The heading
+stays on one line and truncates (it wrapped before), so its height does not change while the
+width moves.
+
+### checkbox
+
+The check mark and the dash grow in as they appear and shrink as they go (150 ms on `ease-md`),
+instead of switching opacity at once; under reduced motion they only fade. An error message fades
+in when it appears.
+
+### radio-group
+
+The selected option's dot grows in and the previous one shrinks away (150 ms on `ease-md`);
+under reduced motion they only fade. An error message fades in when it appears.
+
+### popover
+
+The panel animates open and closed. It grows out of the trigger (a fade, a scale from 96 % and a
+4 px slide away from the trigger, 180 ms, ease-out; transform origin on the trigger's corner,
+following a flip above or below) and shrinks back on close (130 ms). Focus, `aria-expanded` and
+`bfPopoverClosed` still change at once; the closing panel stays in the overlay container, inert
+and click-through, until its exit has played, and opening again during the exit replaces it. Under
+`prefers-reduced-motion` it only fades. Where the Web Animations API is missing or stubbed
+(jsdom), the panel is still removed at once.
+
+### menu
+
+The menu animates open: it grows out of its trigger (a fade, a scale from 96 % and a 4 px slide,
+180 ms, ease-out), a submenu out of its item. It still closes at once, because the CDK menu
+removes it immediately. Under `prefers-reduced-motion` it only fades in. `bf-menu-button` and
+`bf-theme-menu-button` get the same enter.
+
+### date-input
+
+The calendar popover of `bf-date-input`, the time list of `bf-time-input` and the popover of
+`bf-datetime-input` animate open and closed with the popover's motion (180 ms in, 130 ms out).
+Focus returns to the button at once; the closing panel is inert until its exit has played. Under
+`prefers-reduced-motion` they only fade.
+
+### motion
+
+New duration utilities in the theme: `duration-fast` (150 ms), `duration-base` (200 ms) and
+`duration-slow` (260 ms), the timings the widgets use (`--transition-duration-*` reading
+`--bf-duration-fast`, `--bf-duration-layout` and `--bf-duration-overlay`, so redefining those
+retimes both). New keyframe utilities for app lists with Angular's `animate.enter` and
+`animate.leave`: `animate-item-enter` (fades and rises in, 200 ms on `ease-settle`) and
+`animate-item-leave` (fades out, 150 ms), used behind `motion-safe:`. New `bfMotionList`
+directive (`BfMotionListDirective`): on a list or grid container it glides items to their new
+place when items are added, removed or reordered (FLIP, 200 ms, none under reduced motion or on a
+resize). New `img[bfFadeIn]` directive (`BfFadeInDirective`): the image stays transparent until it
+loads or fails, then fades in over 260 ms; at once from the cache and under reduced motion. The
+Theming guide has a new Motion section with a live example.
+
+### tab-group
+
+The selected tab's underline is now one indicator element of the row that slides to the newly
+selected tab, changing width as it goes (`--bf-duration-layout`, `ease-md`). The first placement
+and a resize land at once, and so does everything under `prefers-reduced-motion`. It is measured
+from the selected tab's inline-start offset, so it mirrors under `dir="rtl"`, and is re-measured
+on resize and when labels, badges, size or `fitted` change. Until it has been measured (jsdom,
+server render, a hidden group) the tab keeps drawing its own underline, so unit tests and the
+first paint are unchanged. The indicator is `aria-hidden`; roles, keyboard and focus are
+unchanged.
+
+The panel a user switches to fades in (200 ms of opacity, new `--animate-panel-in`, behind
+`motion-safe:`); the panel shown on the first render never does.
+
+### segmented
+
+The selected segment's pill (surface fill, `shadow-segment`, `primary-strong` outline,
+`Highlight` under forced colours) is now one indicator element of the track that slides to the
+newly chosen segment, changing width as it goes (`--bf-duration-layout`, `ease-md`). The first
+placement and a resize land at once, and so does everything under `prefers-reduced-motion`. The
+selected segment's hover and pressed fills move with it. Until it has been measured (jsdom,
+server render, a hidden control) the segment keeps painting its own pill. `bf-theme-switch`
+slides the same way. The indicator is `aria-hidden`; roles, keyboard and focus are unchanged.
+
+### chat-thread
+
+New: `bf-chat-thread` and `bf-chat-message`, the message list of a chat with an assistant. The
+thread is a scrolling `role="log"` (`aria-live="polite"`, named by `label` or the new
+`chatThread` label) that stays pinned to the newest message while text arrives. When the user
+scrolls up it stops following and shows a "Jump to latest" button (new label
+`chatJumpToLatest`, optional `jump-icon` slot), which scrolls back down (smoothly, at once under
+reduced motion) and follows again. While a message streams the log is `aria-busy`, so the reply
+is announced once, when it is complete. Messages added after the first render rise 4 px and fade
+in (new `--animate-chat-message-in`, 200 ms on `--ease-settle`, off under reduced motion). A
+message's `role` (new type `BfChatMessageRole`: `'user' | 'assistant'`) draws a `primary-soft`
+bubble at the inline end or a full-width reply; `author`, `time` and `timeText` fill an optional
+header; `streaming` shows a pulsing caret at the end of the text (new `--animate-chat-caret`,
+static under reduced motion); `status` (new type `BfChatMessageStatus`:
+`'done' | 'stopped' | 'failed'`) adds a status line (new labels `chatMessageStopped`,
+`chatMessageFailed`, or `statusMessage`) with an `action` slot for a Retry button; the `content`
+slot holds cards, images or chips under the text. New directive `bfProse` (`BfProseDirective`)
+styles the app's rendered markdown (headings, lists, links, code, quotes) with the semantic tokens;
+the message body uses it.
+
+### chat-composer
+
+New: `bf-chat-composer` in `@bitforgehq/ui/overlay`, the input row of a chat. A `bf-textarea`
+with `autoResize` grows from one line to `maxRows` (8), then scrolls. `Enter` sends and
+`Shift+Enter` starts a new line; nothing sends during IME composition or with whitespace-only
+text. `value` is a `model()` that clears after a send; `sent` emits the trimmed text, `changed`
+each edit. While `running` the send button is a stop button that emits `stopped`. Icons go in the
+`send-icon` and `stop-icon` slots (the text stays as the button's name, and shows without an
+icon); `start` and `end` slots take extra controls. `disabled` with `disabledReason` shows the
+reason as the button's tooltip (`aria-disabled`, still focusable) and the empty field's
+placeholder. `size` follows `fieldSize`. New labels `chatComposer`, `chatSend` and `chatStop`.
+`@bitforgehq/ui/testing`: new `BfChatComposerHarness` (`setValue()`, `getValue()`, `send()`,
+`pressEnter()`, `stop()`, `isRunning()`, `isDisabled()`, `canAct()`, `getButtonLabel()`).
+
+### media-card
+
+New: `bf-media-card`, a card led by a picture (a game pitch, a generated image). The card renders
+the picture itself from `src` and `alt` in a top area at a fixed `aspect` (new type
+`BfMediaCardAspect`: `'16/9'` (default), `'4/3'`, `'1/1'`, `'3/4'`). While it loads, and while
+`src` is empty but `loading` is set (a picture still being made), the area shows a `bf-skeleton`
+shimmer with an optional `loadingLabel` caption ("Drawing…") and is `aria-busy`. The picture fades
+in over 260 ms (`bfFadeIn`) while the skeleton fades out under it; at once under reduced motion.
+A load error, or `failed` set by the app, shows `failedLabel` (default: the new label
+`imageLoadFailed`) and the `bfSlot="failed-action"` content (Retry); a new `src` starts over.
+`loaded` and `errored` report the image's events. A body slot and a `footer` slot follow. A
+`bfAction` link or button in the title makes the whole card clickable, as on `bf-card` (pointer,
+`shadow-floating` hover, focus ring, fading on `duration-fast`). `selectable` adds a toggle
+button (`aria-pressed`) bound with `[(selected)]` (a `model()`), emitting `changed` on each user
+change: the whole card without a `bfAction`, else a round check button in the image's corner; a
+selected card has a 2 px primary ring and a filled check. `label` names it ("Select" + `label`,
+new label `mediaCardSelect`). `@bitforgehq/ui/testing`: new `BfMediaCardHarness`
+(`getState()`, `loadImage()`, `failImage()`, `getLoadingLabel()`, `getFailedMessage()`,
+`isSelected()`, `toggleSelected()`).
+
+### image-viewer
+
+New: `BfImageViewerService` in `@bitforgehq/ui/overlay`, a full-screen image viewer (lightbox).
+`open({ images: [{ src, label, caption? }], index?, origin?, actions?, ariaLabel?,
+closeOnNavigation?, injector? })` (new types `BfImageViewerOptions`, `BfImageViewerImage`,
+`BfImageViewerOrigin`, `BfImageViewerActionsContext`) renders `bf-image-viewer` over a dark scrim
+and returns a `BfImageViewerRef` (`index()`, `next()`, `previous()`, `goTo()`, `close()`,
+`afterClosed`, `closed()`). Previous and next buttons, the arrow keys (mirrored under rtl), Home
+and End step through the set, wrapping at both ends; a counter shows "2 of 5" and a polite live
+region announces each step. It is a modal dialog: focus moves to its close button and is trapped,
+`Escape`, the close button and a click on the scrim close it, the page behind is `inert`, and
+focus returns to the opener. The `actions` template (context `{ $implicit: image, index, ref }`)
+sits beside the caption. It zooms out of `origin` (the clicked thumbnail, or a function returning
+any image's thumbnail) with a 260 ms FLIP on the overlay curve and zooms back into it on close
+when it is on screen, else fades; images cross-fade on a step; reduced motion only fades. While a
+large image loads it shows the thumbnail and a spinner, then fades the image in. New labels
+`imageViewer`, `imageViewerPrevious`, `imageViewerNext` and `imageViewerPosition`.
+`@bitforgehq/ui/testing`: new `BfImageViewerHarness` (`getIndex()`, `getCount()`,
+`getCounterText()`, `getSrc()`, `getAlt()`, `getCaption()`, `next()`, `previous()`,
+`pressKey()`, `close()`, `loadImage()`, `failImage()`, `isLoaded()`, `hasFailed()`).
+
+## 0.5.0-next.3 (2026-11-07)
+
+Pre-release of 0.5.0: its changes are listed under "0.5.0 (unreleased)" above.
+
+## 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,17 +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 43 fixtures with `renderApplication()` (every root widget, `bf-icon`,
-`bf-number-input`, a `/charts` line chart, a `/mobile` page with `provideBfShell()`, `bf-page`,
-`bf-header` and `bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay`
-dialog), and all of them render without an error. 27 of them render identically twice. The other 16
-number their ids differently on every render, from a module-level counter, so they could not
-hydrate: `bf-app-frame`, `bf-calendar`, `bf-checkbox`, `bf-input`, `bf-radio-group`, `bf-segmented`,
-`bf-select`, `bf-sidebar`, `bf-tab-group`, `bf-table`, `bf-textarea`, `bf-theme-switch`,
-`bf-toggle`, `bf-line-chart`, `bf-number-input` and the `/overlay` dialog. Hydration itself is still
-not supported or tested, and more stands in its way: `/mobile` writes to `<html>` and adds a
-keyboard probe to `<body>`, and an `/overlay` dialog renders outside the app root and marks it
-inert.
+`tools/ssr-smoke.ts` renders 49 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`bf-number-input`, `bf-select` from `/overlay`, 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. 31 of them render
+identically twice. The other 18 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-file-input`, `bf-image-input`, `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
 
@@ -163,7 +163,7 @@ overlays and themes leave on the document after each test (when TestBed destroys
 environment, so keep its default `teardown: { destroyAfterEach: true }`), and the CDK harnesses
 (`BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`,
 `BfMenuButtonHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfDesktopToastHarness`,
-`BfTableHarness`, `BfPaginationHarness`, `BfTabGroupHarness`, `BfCalendarHarness`, `BfChartHarness`) drive the
+`BfTableHarness`, `BfPaginationHarness`, `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfImageViewerHarness`, `BfChatComposerHarness`, `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

package/ai/MANIFEST.index.json

@@ -136,6 +136,33 @@
       "summary": "Card around one chart with a title, period control and loading, empty and error states",
       "since": "0.3.1"
     },
+    {
+      "name": "chat-composer",
+      "selector": "bf-chat-composer",
+      "className": "BfChatComposerComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Chat input that grows with the text and sends on Enter, or stops a reply",
+      "since": "0.5.0"
+    },
+    {
+      "name": "chat-message",
+      "selector": "bf-chat-message",
+      "className": "BfChatMessageComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "One chat message, a user bubble or a full-width assistant reply that can stream",
+      "since": "0.5.0"
+    },
+    {
+      "name": "chat-thread",
+      "selector": "bf-chat-thread",
+      "className": "BfChatThreadComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Scrolling chat message log that follows new text and offers a jump to latest",
+      "since": "0.5.0"
+    },
     {
       "name": "checkbox",
       "selector": "bf-checkbox",
@@ -262,6 +289,15 @@
       "summary": "Label, help text and error text wrapper that wires ids for assistive tech",
       "since": "0.1.0"
     },
+    {
+      "name": "file-input",
+      "selector": "bf-file-input",
+      "className": "BfFileInputComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "File picker field that lists picked or dropped files and checks type, size and count",
+      "since": "0.5.0"
+    },
     {
       "name": "header",
       "selector": "bf-header",
@@ -289,6 +325,24 @@
       "summary": "Round icon-only button for toolbars and rows, with a required accessible label",
       "since": "0.1.0"
     },
+    {
+      "name": "image-input",
+      "selector": "bf-image-input",
+      "className": "BfImageInputComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Single-image picker with a round or square preview tile and replace or remove",
+      "since": "0.5.0"
+    },
+    {
+      "name": "image-viewer",
+      "selector": "bf-image-viewer",
+      "className": "BfImageViewerComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Full-screen image viewer that zooms from a thumbnail and steps through a set",
+      "since": "0.5.0"
+    },
     {
       "name": "input",
       "selector": "bf-input",
@@ -325,6 +379,15 @@
       "summary": "List row with leading slot, title, subtitle, trailing slot and an optional chevron",
       "since": "0.1.0"
     },
+    {
+      "name": "media-card",
+      "selector": "bf-media-card",
+      "className": "BfMediaCardComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Card with an image that loads, fades in or fails, plus a body and actions",
+      "since": "0.5.0"
+    },
     {
       "name": "menu",
       "selector": "bf-menu",
@@ -465,8 +528,8 @@
       "selector": "bf-select",
       "className": "BfSelectComponent",
       "category": "Forms",
-      "entryPoint": "@bitforgehq/ui",
-      "summary": "Native single-choice dropdown styled like the text field, with Signal Forms binding",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Single-choice dropdown with a styled list, native under touch, with Signal Forms binding",
       "since": "0.1.0"
     },
     {
@@ -550,6 +613,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 +721,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",