@bitforgehq/ui 0.4.0 → 0.5.0-next.3

package/ai/UI_GUIDE.md

@@ -147,17 +147,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 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. 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`,
-`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.
 
 ## Keeping this guide in sync
 
@@ -176,6 +176,10 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
 - Number field: `import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';`. It is
   the one widget in its own entry point, because it loads Angular Forms (`@angular/forms`, a
   required peer); `@bitforgehq/ui` itself loads no forms code, so an app without forms ships none.
+- Select: `import { BfSelectComponent } from '@bitforgehq/ui/overlay';` (needs `@angular/cdk`;
+  `BfSelectOption` is also exported from `@bitforgehq/ui`). Under a mouse it opens a styled list,
+  under touch it renders the native `<select>`. Add `provideBfSelect()` to the app's providers so a
+  stacked `bf-table`'s "Sort by" control is the styled select too (without it, the native one).
 - Charts: `import { BfLineChartComponent } from '@bitforgehq/ui/charts';` (also `BfBarChartComponent`,
   `BfDonutChartComponent`, `BfSparklineComponent`, `BfChartCardComponent`). Our own SVG charts,
   themed with the `--color-chart-1` … `--color-chart-8` tokens; pass `series` (`{ name, values }`) and
@@ -186,7 +190,7 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
   `border-border`, `rounded-field`, `shadow-raised`, `text-body`). Never raw palette classes and
   never `dark:` variants; put `dark` on `<html>` and the theme re-colors everything.
 - Forms: `bf-input`, `bf-number-input`, `bf-textarea`, `bf-select`, `bf-checkbox`, `bf-toggle`,
-  `bf-radio-group` and `bf-segmented` expose `value` / `checked` as `model()` and implement
+  `bf-radio-group`, `bf-segmented`, `bf-file-input` and `bf-image-input` expose `value` / `checked` as `model()` and implement
   Signal Forms' `FormValueControl` / `FormCheckboxControl`. Bind either `[formField]="form.field"` or
   `[(value)]` / `[(checked)]`, never both. Import `FormField`, `FormRoot`, `form` and the
   validators from `@angular/forms/signals`. The first error shows once the field is touched: its
@@ -204,6 +208,14 @@ or out of date — wire it into CI so agent guidance never drifts from the insta
   (`number | null`, `null` while empty; `min()`/`max()` reach the native input; unreadable text is
   a `parse` error on the bound field, blocking `submit()`), never to a `string` model on
   `bf-input type="number"`.
+- Files: `bf-file-input` binds a `File[]` (`multiple` for several; `variant="dropzone"` for a drop
+  area) and `bf-image-input` a `File | null` (`[(src)]` shows the saved picture; Remove sets both
+  to null). Both only pick: upload from the form's `submission`. `accept`, `maxSize` and
+  `maxFiles` refuse a file without making the field invalid; read refusals from `(rejected)`
+  (`BfRejectedFile[]`). `required()` does not count an empty `File[]` as empty: add
+  `validate(p.files, ({ value }) => value().length === 0 ? requiredError() : undefined)`. For an
+  image with a `src`, give the marker with `metadata(p.avatar, REQUIRED, () => true)` and a
+  `validate()` that counts `src` too.
 - Reactive Forms work through Angular 22's built-in interop: `[formControl]` and
   `formControlName` bind every form widget above with no `ControlValueAccessor` (never add one).
   Value, touched, dirty, validity, pending, disabled, required and errors flow into the widget;
@@ -242,7 +254,7 @@ you can guess a binding without looking it up:
   spinner, tab bar, progress or icon); every component that renders a native input, select or
   textarea (checkbox and toggle included) also takes `ariaLabel` and `ariaLabelledby` for when no
   visible `label` is shown; a built-in sub-control's name is `<part>Label` (`dismissLabel`,
-  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar`.
+  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar` and `bf-media-card`.
 - Types: every union or object type of an input, model, output, `Bf…Options`/`Bf…Config` property
   or an interface they name is a named type exported from the same entry
   (`BfToggleLabelPosition`, `BfRefresherRefreshEvent`, `BfDialogRole`, …), so type your own state
@@ -264,7 +276,8 @@ toolbar or a German settings page); a key you leave out keeps the parent's value
 
 - `provideBfDefaults({ size, fieldSize, controlSize })` sets the height step (`BfSize`: `sm` 32,
   `md` 40, `lg` 48 px) a widget uses when its own `size` input is unset. `fieldSize` covers the
-  text fields (`bf-input`, `bf-number-input`, `bf-select`, `bf-textarea`), `controlSize` the
+  text fields (`bf-input`, `bf-number-input`, `bf-select`, `bf-textarea`, and the file pickers
+  `bf-file-input`, `bf-image-input`), `controlSize` the
   actions and choice controls (`bf-button`, `bf-icon-button`, `bf-chip`, `bf-segmented`,
   `bf-checkbox`, `bf-toggle`, `bf-radio-group`); `size` sets both, and an explicit
   `fieldSize`/`controlSize` wins over it. The library default is compact `md` for both (desktop
@@ -386,8 +399,23 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   (text with inline links in the content, a small action in `bfSlot="end"`) for a record's
   history or an audit trail, in the order the app gives; times follow `LOCALE_ID` (`timeFormat`,
   `timeText` for a relative time). Not for navigation or steps.
+- **Chat:** a `bf-chat-thread` (give it `class="flex-1"` or a height) of `bf-chat-message`
+  elements (`role` `user` or `assistant`, `author`, `streaming`, `status`) above a
+  `bf-chat-composer` from `/overlay` (`[(value)]="draft"`, `[running]="replying()"`,
+  `(sent)="ask($event)"`, `(stopped)="cancel()"`). A message's content is the app's rendered,
+  sanitised markdown, styled by the body's `bfProse`; cards and chips go in `bfSlot="content"`,
+  Retry in `bfSlot="action"`; the composer's icons go in `bfSlot="send-icon"` and
+  `bfSlot="stop-icon"`, extra controls in `start` and `end`. The thread follows new text, shows
+  "Jump to latest" when scrolled up and is `aria-busy` while a message streams; never scroll or
+  animate it yourself. Set `streaming` false when the reply ends, stops or fails.
 - **Cards in a grid:** the grid stretches each `bf-card` and its `bfSlot="footer"` sits on the
   bottom edge, so footers line up; put a footer's parts in one element.
+- **Pictures that are slow or can fail:** `bf-media-card` owns the picture (`[src]`, `alt`,
+  `[loading]`, `loadingLabel="Drawing…"`, `[failed]`): a skeleton while it loads (or while `src`
+  is empty and `loading`), a fade when it arrives, a message and `bfSlot="failed-action"` (Retry)
+  when it fails; retry with a changed `src`. Never project your own `<img>` for the main picture.
+  Clickable like `bf-card` (a `bfAction` in the title); `selectable` with `[(selected)]` and
+  `label` for a pick-several grid.
 - **Rows on a card:** `<bf-list [inset]="false" divided class="-mx-card">`, flush to the card's
   edges with lines between the rows.
 - **Theme switch:** `<bf-theme-switch [(value)]="colorScheme.scheme" />` (or
@@ -405,8 +433,8 @@ protected readonly colorScheme = inject(BfColorSchemeService);
   for the platform picker on touch). Values are ISO strings (`'2026-10-28'`, `'14:30'`,
   `'2026-10-28T14:30'`); month and day names come from `Intl` in the document's language.
 - **Picking from many options:** `bf-combobox` (`/overlay`) for one value with search, groups and
-  server search (`queried`, `loading`); `bf-multi-combobox` for tags. `bf-select` stays the choice
-  for a short fixed list.
+  server search (`queried`, `loading`); `bf-multi-combobox` for tags. `bf-select` (`/overlay`
+  too) stays the choice for a short fixed list.
 - **Dashboards:** `bf-stat` with `delta`, `trend` and `trendIntent` for a figure and its change;
   `@bitforgehq/ui/charts` for `bf-line-chart`, `bf-bar-chart`, `bf-donut-chart` and
   `bf-sparkline` inside a `bf-chart-card` (title, period slot, loading, empty and error states),
@@ -462,6 +490,12 @@ injector? })` stacks up to three cards bottom-right (configurable with
 - **Side panel:** `BfSidePanelService.open(component | template, { width, modal, data })` slides a
   full-height `bf-side-panel` in from the inline end: a record's details or edit form beside the
   list. `modal: false` keeps the page usable. In the Capacitor shell use `bf-sheet`/`bf-modal`.
+- **Image viewer:** `BfImageViewerService.open(options)` with `images` (each
+  `{ src, label, caption? }`), `index`, `origin`, `actions` and `injector` shows one image full
+  screen over a dark scrim and steps through the set (buttons, arrow keys, Home/End, wrapping);
+  pass the clicked thumbnail as `origin` (or `(i) => thumbnails[i]`) so it zooms out of it and
+  back. Actions go in an `ng-template` (context `{ $implicit: image, index, ref }`). It returns a
+  `BfImageViewerRef` (`index()`, `next()`, `previous()`, `goTo()`, `close()`, `afterClosed`).
 - **`closeOnNavigation`:** every overlay (`BfDialogConfig`, `confirm()`, and the `/mobile` sheet,
   modal, action sheet and alert options) closes when the URL path changes by default (`true`);
   pass `closeOnNavigation: false` to keep one open across a navigation (e.g. a draft that must
@@ -993,7 +1027,7 @@ describe('bf-button in a consumer app (Vitest)', () => {
 
 ### 6. Drive a form widget through its harness
 
-The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfToggleHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`.
+The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness`, `BfDesktopToastHarness`, `BfTableHarness`, `BfToggleHarness`, `BfPaginationHarness` `BfTabGroupHarness`, `BfCalendarHarness`, `BfFileInputHarness`, `BfImageInputHarness`, `BfMediaCardHarness`, `BfChatComposerHarness` and `BfChartHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`. jsdom has no `URL.createObjectURL`, so after `addFile()` `BfImageInputHarness.hasPreview()` stays false: assert on the bound value, or stub `URL.createObjectURL` to read the preview.
 
 `select-harness.spec.ts`:
 
@@ -1006,7 +1040,7 @@ import { Component, signal } from '@angular/core';
 import { TestBed } from '@angular/core/testing';
 import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
 import { FormField, form, required } from '@angular/forms/signals';
-import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui/overlay';
 import { BfSelectHarness, provideBfTesting } from '@bitforgehq/ui/testing';
 
 @Component({
@@ -1063,7 +1097,7 @@ describe('BfSelectHarness in a consumer app (Vitest)', () => {
 
 ### 7. Drive a dialog from the document root
 
-Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`.
+Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`; `BfImageViewerHarness` drives the image viewer the same way. jsdom never loads images: `BfMediaCardHarness` and `BfImageViewerHarness` fire the `load` and `error` events with `loadImage()` and `failImage()`.
 
 `dialog-harness.spec.ts`:
 
@@ -1220,6 +1254,7 @@ notes.
 | Component           | Entry point                   | Purpose                                                                                     |
 | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
 | `bf-calendar`       | `@bitforgehq/ui`              | Inline month calendar for picking one date, with month and year jumps                       |
+| `bf-chat-composer`  | `@bitforgehq/ui/overlay`      | Chat input that grows with the text and sends on Enter, or stops a reply                    |
 | `bf-checkbox`       | `@bitforgehq/ui`              | Rounded checkbox with an optional label that binds to Signal Forms                          |
 | `bf-chip`           | `@bitforgehq/ui`              | Toggleable filter chip with a check mark when selected, in tonal or ink style               |
 | `bf-chip-group`     | `@bitforgehq/ui`              | Named row of chips that picks one like radios, or groups independent toggles                |
@@ -1227,12 +1262,14 @@ notes.
 | `bf-date-input`     | `@bitforgehq/ui/overlay`      | Typed date field with a calendar popover, valued as an ISO date string                      |
 | `bf-datetime-input` | `@bitforgehq/ui/overlay`      | Typed date and time field with a calendar and time list in one popover                      |
 | `bf-field`          | `@bitforgehq/ui`              | Label, help text and error text wrapper that wires ids for assistive tech                   |
+| `bf-file-input`     | `@bitforgehq/ui`              | File picker field that lists picked or dropped files and checks type, size and count        |
+| `bf-image-input`    | `@bitforgehq/ui`              | Single-image picker with a round or square preview tile and replace or remove               |
 | `bf-input`          | `@bitforgehq/ui`              | Single-line text field with label, help and error text, icon slots and Signal Forms binding |
 | `bf-multi-combobox` | `@bitforgehq/ui/overlay`      | Text field that filters options as you type and picks several as tags                       |
 | `bf-number-input`   | `@bitforgehq/ui/number-input` | Number field that binds number or null, with native min, max and step                       |
 | `bf-radio-group`    | `@bitforgehq/ui`              | Group of radio buttons for choosing one option, with optional per-option descriptions       |
 | `bf-segmented`      | `@bitforgehq/ui`              | Segmented control for switching between two to four views, keyboard-navigable like radios   |
-| `bf-select`         | `@bitforgehq/ui`              | Native single-choice dropdown styled like the text field, with Signal Forms binding         |
+| `bf-select`         | `@bitforgehq/ui/overlay`      | Single-choice dropdown with a styled list, native under touch, with Signal Forms binding    |
 | `bf-textarea`       | `@bitforgehq/ui`              | Multi-line text field with label, help and error text, and Signal Forms binding             |
 | `bf-theme-switch`   | `@bitforgehq/ui`              | Segmented System, Light and Dark switch bound two-way to the app colour scheme              |
 | `bf-time-input`     | `@bitforgehq/ui/overlay`      | Typed time-of-day field with a popover list of times, valued as an ISO string               |
@@ -1247,12 +1284,15 @@ notes.
 | `bf-bar-chart`           | `@bitforgehq/ui/charts` | Bar chart of series over categories, grouped or stacked, vertical or horizontal         |
 | `bf-card`                | `@bitforgehq/ui`        | Content surface with an optional header slot, in four visual styles from raised to flat |
 | `bf-chart-card`          | `@bitforgehq/ui/charts` | Card around one chart with a title, period control and loading, empty and error states  |
+| `bf-chat-message`        | `@bitforgehq/ui`        | One chat message, a user bubble or a full-width assistant reply that can stream         |
+| `bf-chat-thread`         | `@bitforgehq/ui`        | Scrolling chat message log that follows new text and offers a jump to latest            |
 | `div[bfDescriptionItem]` | `@bitforgehq/ui`        | One label and value pair of a description list, label as term, content as value         |
 | `bf-description-list`    | `@bitforgehq/ui`        | Native description list of label-value pairs, as divided rows or a tile grid            |
 | `bf-donut-chart`         | `@bitforgehq/ui/charts` | Donut chart of the parts of a whole, with a legend, tooltip and centre slot             |
 | `bf-line-chart`          | `@bitforgehq/ui/charts` | Line chart of series over categories, with tooltip, legend and data table               |
 | `bf-list`                | `@bitforgehq/ui`        | Container for list rows, inset by default with rounded corners on a warm background     |
 | `bf-list-item`           | `@bitforgehq/ui`        | List row with leading slot, title, subtitle, trailing slot and an optional chevron      |
+| `bf-media-card`          | `@bitforgehq/ui`        | Card with an image that loads, fades in or fails, plus a body and actions               |
 | `bf-progress`            | `@bitforgehq/ui`        | Progress bar in two sizes and four tones for completion, quotas and unknown waits       |
 | `bf-sparkline`           | `@bitforgehq/ui/charts` | Tiny trend line with no axes or legend, for stats and table cells                       |
 | `bf-stat`                | `@bitforgehq/ui`        | One labelled figure with an optional icon tile and a supporting line                    |
@@ -1305,6 +1345,7 @@ notes.
 | `bf-alert-dialog`      | `@bitforgehq/ui/mobile`  | Centred confirmation dialog with a title, message and a row of role-styled buttons            |
 | `bf-desktop-toast`     | `@bitforgehq/ui/overlay` | Desktop notification card in a bottom corner stack of up to three                             |
 | `bf-dialog`            | `@bitforgehq/ui/overlay` | Desktop modal dialog with a title, scrolling body, footer actions and focus trap              |
+| `bf-image-viewer`      | `@bitforgehq/ui/overlay` | Full-screen image viewer that zooms from a thumbnail and steps through a set                  |
 | `bf-menu`              | `@bitforgehq/ui/overlay` | Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus        |
 | `bf-menu-button`       | `@bitforgehq/ui/overlay` | Styled button that opens a menu, with outline, text, tonal and icon-only looks                |
 | `bf-modal`             | `@bitforgehq/ui/mobile`  | Modal overlay shown as an inset card over the scaled-down page, or full screen                |

package/ai/components/app-frame.md

@@ -157,7 +157,7 @@ Use `bf-app-frame` once, at the root of a desktop web app whose top-level destin
 
 ## Slots and layout
 
-Put the `bf-sidebar` in `bfSlot="sidebar"`, the app's name or logo in `bfSlot="brand"`, the narrow-screen `bf-menu-button` of `a[bfMenuItem]` router links in `bfSlot="menu"` and end actions (the theme menu, the account) in `bfSlot="actions"`; everything else is the page. From the breakpoint up the sidebar column sits at the inline start, `sticky top-0` and `h-dvh` tall, and the `bf-sidebar` inside fills it and scrolls its own destinations; the header bar is hidden. Below it the sidebar column is hidden and the header bar (`surface`, a bottom border, sticky at the top) shows the menu at the inline start, then the brand, and the actions at the end: the top app bar convention, and the menu comes first in the tab order too. The order is fixed, whatever order the slots have in your template. Keep the brand in the sidebar's own `header` slot too, for the wide layout.
+Put the `bf-sidebar` in `bfSlot="sidebar"`, the app's name or logo in `bfSlot="brand"`, the narrow-screen `bf-menu-button` of `a[bfMenuItem]` router links in `bfSlot="menu"` and end actions (the theme menu, the account) in `bfSlot="actions"`; everything else is the page. From the breakpoint up the sidebar column sits at the inline start, `sticky top-0` and `h-dvh` tall, and the `bf-sidebar` inside fills it and scrolls its own destinations; the header bar is hidden. Below it the sidebar column is hidden and the header bar (`surface`, a bottom border, sticky at the top) shows the menu at the inline start, then the brand, and the actions at the end: the top app bar convention, and the menu comes first in the tab order too. The order is fixed, whatever order the slots have in your template. Keep the brand in the sidebar's own `header` slot too, for the wide layout. The sidebar column takes the sidebar's width, so when the sidebar collapses or expands the content column moves with its animation instead of jumping.
 
 ## Breakpoint and content width
 

package/ai/components/chat-composer.md

@@ -0,0 +1,357 @@
+# bf-chat-composer
+
+Chat input that grows with the text and sends on Enter, or stops a reply
+
+`BfChatComposerComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.5.0
+
+## Example
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfChatComposerComponent } from '@bitforgehq/ui/overlay';
+import { ArrowUp, Square } from 'lucide';
+
+/* How long the pretend reply runs before it finishes by itself. */
+const REPLY_TIME = 3000;
+
+/**
+ * The bf-chat-composer overview.
+ *
+ * Type and press Enter (Shift+Enter for a new line) or the send button: the text is sent, the
+ * field clears, and the send button turns into Stop while the pretend reply runs. Stop ends it
+ * early. Icons go in the `send-icon` and `stop-icon` slots; their names stay as text.
+ */
+@Component({
+  selector: 'app-example-chat-composer-overview',
+  imports: [BfChatComposerComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-chat-composer
+        placeholder="Ask for ideas"
+        [(value)]="draft"
+        [running]="running()"
+        (sent)="send($event)"
+        (stopped)="finish('Stopped.')"
+      >
+        <bf-icon bfSlot="send-icon" [icon]="arrowUp" />
+        <bf-icon bfSlot="stop-icon" [icon]="square" />
+      </bf-chat-composer>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ChatComposerOverviewExampleComponent {
+  protected readonly arrowUp = ArrowUp;
+  protected readonly square = Square;
+
+  readonly draft = signal('');
+  readonly running = signal(false);
+  readonly status = signal('Nothing sent yet.');
+
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => this.clearTimer());
+  }
+
+  send(text: string): void {
+    this.running.set(true);
+    this.status.set(`Sent: "${text}". Replying...`);
+    this.timer = setTimeout(() => this.finish('Reply done.'), REPLY_TIME);
+  }
+
+  finish(status: string): void {
+    this.clearTimer();
+    this.running.set(false);
+    this.status.set(status);
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}
+```
+
+## Overview
+
+The input row of a chat: a `bf-textarea` that grows with the text (`autoResize`, up to
+`maxRows`, then it scrolls), a start and an end slot for extra controls, and one button that
+sends the text or, while a reply is `running`, stops it. `Enter` sends and `Shift+Enter`
+starts a new line; nothing sends during IME composition or
+when the text is only whitespace. After a send the text clears and focus stays in the field.
+`disabled` with a `disabledReason` shows the reason as the button's tooltip and as the empty
+field's placeholder.
+
+The input row of a chat: a text field that grows with the text, slots for extra controls, and one button that sends the text or stops the running reply. Import it from `@bitforgehq/ui/overlay` (it needs `@angular/cdk` for the disabled reason's tooltip).
+
+## When to use
+
+Use `bf-chat-composer` below a [bf-chat-thread](https://bitforge-ui.web.app/components/chat-thread) to write to an assistant. Use [bf-textarea](https://bitforge-ui.web.app/components/textarea) instead for free text in a form that is saved with the form, such as a comment field.
+
+## Basic usage
+
+Bind the text with `[(value)]` and handle `(sent)`, which emits the trimmed text; the field then clears and keeps focus. <kbd>Enter</kbd> sends and <kbd>Shift</kbd>+<kbd>Enter</kbd> starts a new line. Nothing sends while an input method is composing (Japanese, Chinese or Korean input confirm their text with <kbd>Enter</kbd>), and empty or whitespace-only text never sends: the send button is disabled then. `(changed)` emits the text after each edit by the user.
+
+```ts
+import { Component, DestroyRef, inject, signal } from '@angular/core';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfChatComposerComponent } from '@bitforgehq/ui/overlay';
+import { ArrowUp, Square } from 'lucide';
+
+/* How long the pretend reply runs before it finishes by itself. */
+const REPLY_TIME = 3000;
+
+/**
+ * The bf-chat-composer overview.
+ *
+ * Type and press Enter (Shift+Enter for a new line) or the send button: the text is sent, the
+ * field clears, and the send button turns into Stop while the pretend reply runs. Stop ends it
+ * early. Icons go in the `send-icon` and `stop-icon` slots; their names stay as text.
+ */
+@Component({
+  selector: 'app-example-chat-composer-overview',
+  imports: [BfChatComposerComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-chat-composer
+        placeholder="Ask for ideas"
+        [(value)]="draft"
+        [running]="running()"
+        (sent)="send($event)"
+        (stopped)="finish('Stopped.')"
+      >
+        <bf-icon bfSlot="send-icon" [icon]="arrowUp" />
+        <bf-icon bfSlot="stop-icon" [icon]="square" />
+      </bf-chat-composer>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ChatComposerOverviewExampleComponent {
+  protected readonly arrowUp = ArrowUp;
+  protected readonly square = Square;
+
+  readonly draft = signal('');
+  readonly running = signal(false);
+  readonly status = signal('Nothing sent yet.');
+
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => this.clearTimer());
+  }
+
+  send(text: string): void {
+    this.running.set(true);
+    this.status.set(`Sent: "${text}". Replying...`);
+    this.timer = setTimeout(() => this.finish('Reply done.'), REPLY_TIME);
+  }
+
+  finish(status: string): void {
+    this.clearTimer();
+    this.running.set(false);
+    this.status.set(status);
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+  }
+}
+```
+
+## Send and stop
+
+While `running` is true (the app's reply is streaming) the button is Stop: it emits `(stopped)` and the app ends the reply and sets `running` back to false. <kbd>Enter</kbd> does not send while a reply runs, and the text stays in the field. The button keeps its place and focus while it switches.
+
+## Icons
+
+The `send-icon` and `stop-icon` slots take the button's icons (the library never imports an icon into a widget). With an icon the button is a round icon button and its text ("Send", "Stop", from `chatSend` and `chatStop`) stays as its accessible name; without one the button shows the text.
+
+## Extra controls
+
+The `start` slot (before the field) and the `end` slot (between the field and the button) take controls of the app, such as a preset picker or an attach button. They line up with the bottom of the field as it grows.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfIconButtonComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfChatComposerComponent, BfSelectComponent } from '@bitforgehq/ui/overlay';
+import { Paperclip } from 'lucide';
+
+type Preset = 'names' | 'slogans' | 'menu';
+
+/**
+ * Extra controls in the start and end slots.
+ *
+ * A preset picker in the `start` slot and an attach button in the `end` slot, beside the field;
+ * without icons in its slots the send button shows its text. The sent line names the preset the
+ * message went out with.
+ */
+@Component({
+  selector: 'app-example-chat-composer-slots',
+  imports: [BfChatComposerComponent, BfSelectComponent, BfIconButtonComponent, BfIconComponent],
+  template: `
+    <div class="flex flex-col gap-3">
+      <bf-chat-composer placeholder="Describe the cafe" (sent)="sent.set(preset() + ': ' + $event)">
+        <bf-select
+          bfSlot="start"
+          ariaLabel="Preset"
+          class="w-36"
+          [options]="presets"
+          [(value)]="preset"
+        />
+        <bf-icon-button bfSlot="end" variant="text" label="Attach a file">
+          <bf-icon [icon]="paperclip" />
+        </bf-icon-button>
+      </bf-chat-composer>
+      <p data-sent class="text-caption text-text-muted">{{ sent() || 'Nothing sent yet.' }}</p>
+    </div>
+  `,
+})
+export class ChatComposerSlotsExampleComponent {
+  protected readonly paperclip = Paperclip;
+
+  readonly presets: readonly BfSelectOption<Preset>[] = [
+    { value: 'names', label: 'Names' },
+    { value: 'slogans', label: 'Slogans' },
+    { value: 'menu', label: 'Menu' },
+  ];
+  readonly preset = signal<Preset | null>('names');
+  readonly sent = signal('');
+}
+```
+
+## Growing field
+
+The field is a [bf-textarea](https://bitforge-ui.web.app/components/textarea) with `autoResize`: it starts at one line and grows with the text up to `maxRows` lines (8 by default), then it scrolls. `maxLength` limits the text. A browser without CSS field sizing keeps the one-line field and scrolls inside it.
+
+## Disabled
+
+`disabled` stops typing and sending. With a `disabledReason` (a usage limit, a missing choice) the reason is the empty field's placeholder and the send button's tooltip on hover and keyboard focus; the button then stays focusable, marked `aria-disabled`, so the tooltip can show.
+
+```ts
+import { Component } from '@angular/core';
+import { BfChatComposerComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * Disabled with a reason.
+ *
+ * While nothing can be sent, `disabled` with a `disabledReason` says why: it is the empty
+ * field's placeholder, and the send button's tooltip on hover and keyboard focus (the button
+ * stays focusable for that, marked `aria-disabled`).
+ */
+@Component({
+  selector: 'app-example-chat-composer-disabled',
+  imports: [BfChatComposerComponent],
+  template: `
+    <bf-chat-composer disabled disabledReason="You have used today's 20 messages. More tomorrow." />
+  `,
+})
+export class ChatComposerDisabledExampleComponent {}
+```
+
+## Sizes
+
+`size` sets the field's padding and type and the button's height together: `sm` 32 px, `md` 40 px (default), `lg` 48 px buttons. Unset, it follows `provideBfDefaults()`'s `fieldSize`; a touch app that sets `fieldSize: 'lg'` gets the 48 px composer.
+
+## Desktop
+
+The field shows the text cursor and its focus ring on every focus. The button has bf-button's hover and pressed steps (primary for send, tonal for stop); disabled it shows no hover. With a `disabledReason` its tooltip shows after a 500 ms hover or at once on keyboard focus. Under a coarse pointer the button's hit area grows to 44 px; the field gets no touch extension (set `fieldSize: 'lg'` for touch).
+
+## Theming
+
+- Field: see [bf-textarea](https://bitforge-ui.web.app/components/textarea) (`border-strong`, `primary` focus border, `ring` ring, `text-muted` placeholder).
+- Send button: `primary` with `on-primary` text (`primary-hover`, `primary-pressed`); stop button: `primary-soft` with `primary-strong`; disabled: `surface-sunken` with `text-disabled`.
+- Tooltip: see the `bfTooltip` directive.
+
+## Accessibility
+
+The field is a native `textarea`, named by `label` (visible), else `ariaLabel` or `ariaLabelledby`, else the `chatComposer` label ("Message"). The button is a native `button` whose text is its name, also when an icon shows ("Send", "Stop"); it is natively `disabled` with nothing to send, and `aria-disabled` while disabled with a reason, which the tooltip then describes (`aria-describedby`) when it shows. After a send focus returns to the field. The tooltip shows nothing under a coarse pointer, so the reason is also the placeholder of the empty field.
+
+### Keyboard
+
+| Key                                              | Where    | Action                                                                        |
+| ------------------------------------------------ | -------- | ----------------------------------------------------------------------------- |
+| <kbd>Enter</kbd>                                 | Field    | Sends the text (not while composing, while a reply runs, or when it is empty) |
+| <kbd>Shift</kbd>+<kbd>Enter</kbd>                | Field    | Starts a new line                                                             |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Composer | Moves between the start controls, the field, the end controls and the button  |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Button   | Sends the text, or stops the reply while it runs                              |
+| <kbd>Escape</kbd>                                | Button   | Hides the disabled reason's tooltip                                           |
+
+## Inputs
+
+| Name             | Type                                                        | Default     | Description                                                                                                    |
+| ---------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
+| `running`        | `boolean`                                                   | `false`     | A reply is running: the button stops it (`stopped`) instead of sending.                                        |
+| `disabled`       | `boolean`                                                   | `false`     | Nothing can be written or sent.                                                                                |
+| `disabledReason` | `string`                                                    | `''`        | Why it is disabled, shown as the button's tooltip and the empty field's placeholder.                           |
+| `label`          | `string`                                                    | `''`        | Visible label above the field; usually left empty in a chat.                                                   |
+| `ariaLabel`      | `string`                                                    | `''`        | The field's accessible name without a visible label; empty uses the `chatComposer` label ("Message").          |
+| `ariaLabelledby` | `string`                                                    | `''`        | Id(s) of the element(s) that name the field without a visible label.                                           |
+| `placeholder`    | `string`                                                    | `''`        | Example text shown while the field is empty.                                                                   |
+| `maxRows`        | `number`                                                    | `8`         | The lines the field grows to at most; past them it scrolls.                                                    |
+| `maxLength`      | `number \| undefined`                                       | `undefined` | Maximum number of characters (native `maxlength`).                                                             |
+| `name`           | `string`                                                    | `''`        | Native name attribute of the textarea.                                                                         |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Padding, type and button step: sm, md, lg; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default). |
+| `value`          | `string`                                                    | `''`        | The text being written; two-way bindable. Cleared after a send. Two-way: `[(value)]`.                          |
+
+## Outputs
+
+| Name      | Payload  | Description                                                                          |
+| --------- | -------- | ------------------------------------------------------------------------------------ |
+| `changed` | `string` | Emitted with the new text right after the user changes it (each keystroke or paste). |
+| `sent`    | `string` | Emitted with the trimmed text when the user sends it (Enter or the send button).     |
+| `stopped` | `void`   | Emitted when the user presses the stop button while `running`.                       |
+
+## Slots
+
+- `start`: Controls before the field, such as a preset picker or an attach button.
+- `end`: Controls between the field and the send button.
+- `send-icon`: The send button's icon; without one the button shows its text.
+- `stop-icon`: The stop button's icon; without one the button shows its text.
+
+## Methods
+
+### `send(): void`
+
+Sends the text: emits `sent` with it trimmed, clears the field and keeps focus in it. Does
+nothing while disabled or running, or when the text is only whitespace.
+
+### `focus(): void`
+
+Focuses the text field.
+
+## Notes
+
+### Do
+
+- Set `running` from the app's own reply state and turn it off when the reply ends, stops or fails.
+- Give a `disabledReason` whenever the composer is disabled for a reason the user can act on.
+
+### Don't
+
+- Don't clear the value yourself after `(sent)`: the composer does it.
+- Don't put the reply's progress in the composer; show it in the thread's streaming message.
+
+## Migration notes
+
+### 0.5.0
+
+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()`).