@bitforgehq/ui 0.4.0 → 0.5.0-next.4

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()`).

package/ai/components/chat-message.md

@@ -0,0 +1,251 @@
+# bf-chat-message
+
+One chat message, a user bubble or a full-width assistant reply that can stream
+
+`BfChatMessageComponent` from `@bitforgehq/ui` · Data display · since 0.5.0
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfChatMessageComponent, BfChatThreadComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-chat-message overview.
+ *
+ * A user message is a tinted bubble at the inline end and an assistant message spans the row
+ * with no bubble. Each one names its author and time in a small header; the time is a `time`
+ * element with the exact value, shown as hours and minutes or as `timeText`.
+ */
+@Component({
+  selector: 'app-example-chat-message-overview',
+  imports: [BfChatThreadComponent, BfChatMessageComponent],
+  template: `
+    <bf-chat-thread label="Two messages">
+      <bf-chat-message role="user" author="You" time="2026-11-06T09:30:00Z" timeText="9:30">
+        What should the cafe's first menu board say?
+      </bf-chat-message>
+      <bf-chat-message author="Assistant" time="2026-11-06T09:30:00Z" timeText="9:30">
+        <p>
+          Keep it to five lines: the coffee, the tea, one cake, one sandwich and the price of a
+          refill.
+        </p>
+        <p>Write it by hand. Regulars read a hand-written board as a sign that someone cares.</p>
+      </bf-chat-message>
+    </bf-chat-thread>
+  `,
+})
+export class ChatMessageOverviewExampleComponent {}
+```
+
+## Overview
+
+One message of a `bf-chat-thread`. A `user` message is a tinted bubble at the inline end; an
+`assistant` message is full width with no bubble. The default slot is the message text, styled
+as prose (`bfProse`) for markdown the app renders. An optional header names the `author` and
+the `time`. While `streaming`, a caret pulses at the end of the text and the message is
+`aria-busy`, so the thread announces it once, when it is done. A `stopped` or `failed` message
+shows a short status line, with the `action` slot beside it (a Retry button).
+
+One message of a [bf-chat-thread](https://bitforge-ui.web.app/components/chat-thread): a tinted bubble for the user, a full-width reply without a bubble for the assistant, with an optional header, a streaming caret and a status line.
+
+## When to use
+
+Use `bf-chat-message` inside a [bf-chat-thread](https://bitforge-ui.web.app/components/chat-thread), one per message. Use [bf-timeline-event](https://bitforge-ui.web.app/components/timeline-event) instead for an event in a history, and [bf-alert](https://bitforge-ui.web.app/components/alert) for a message from the app itself rather than from a conversation.
+
+## Basic usage
+
+`role` is `assistant` (the default: full width, no bubble) or `user` (a `primary-soft` bubble at the inline end, up to 85 % of the row). The default slot is the text: plain text, paragraphs, or the app's rendered markdown. `author` and `time` (a Date or an ISO 8601 string, shown as hours and minutes in the app's locale, or as `timeText`) fill a small header above the message; leave both empty for none.
+
+```ts
+import { Component } from '@angular/core';
+import { BfChatMessageComponent, BfChatThreadComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-chat-message overview.
+ *
+ * A user message is a tinted bubble at the inline end and an assistant message spans the row
+ * with no bubble. Each one names its author and time in a small header; the time is a `time`
+ * element with the exact value, shown as hours and minutes or as `timeText`.
+ */
+@Component({
+  selector: 'app-example-chat-message-overview',
+  imports: [BfChatThreadComponent, BfChatMessageComponent],
+  template: `
+    <bf-chat-thread label="Two messages">
+      <bf-chat-message role="user" author="You" time="2026-11-06T09:30:00Z" timeText="9:30">
+        What should the cafe's first menu board say?
+      </bf-chat-message>
+      <bf-chat-message author="Assistant" time="2026-11-06T09:30:00Z" timeText="9:30">
+        <p>
+          Keep it to five lines: the coffee, the tea, one cake, one sandwich and the price of a
+          refill.
+        </p>
+        <p>Write it by hand. Regulars read a hand-written board as a sign that someone cares.</p>
+      </bf-chat-message>
+    </bf-chat-thread>
+  `,
+})
+export class ChatMessageOverviewExampleComponent {}
+```
+
+## Streaming
+
+Set `streaming` while the reply's text is still arriving and append the text as it comes. A caret pulses at the end of the text (after bare text, inside the last paragraph or list item, also one wrapper deep), and the message and the thread are `aria-busy`, so a screen reader reads the reply once, when `streaming` goes back to false. An empty streaming message shows the caret alone, as a "thinking" cue.
+
+## Stopped and failed
+
+`status` is `done` (the default), `stopped` (a muted "Stopped" line) or `failed` (a "Something went wrong" line in the danger colour). `statusMessage` replaces the built-in line, such as with the error the server returned. The `action` slot sits beside the line, for a Retry button.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfButtonComponent,
+  BfChatMessageComponent,
+  BfChatThreadComponent,
+  type BfChatMessageStatus,
+} from '@bitforgehq/ui';
+
+/**
+ * Stopped and failed messages.
+ *
+ * A reply the user stopped shows "Stopped" under its text; a reply that failed shows "Something
+ * went wrong" in the danger colour, with a Retry button in the message's `action` slot. Retry
+ * here answers at once; a real app would ask its model again.
+ */
+@Component({
+  selector: 'app-example-chat-thread-states',
+  imports: [BfChatThreadComponent, BfChatMessageComponent, BfButtonComponent],
+  template: `
+    <bf-chat-thread label="Message states" class="max-h-[24rem]">
+      <bf-chat-message role="user">Write a slogan for the cafe.</bf-chat-message>
+      <bf-chat-message status="stopped">
+        <p>Good coffee, slow mornings and a</p>
+      </bf-chat-message>
+      <bf-chat-message role="user">Try a shorter one.</bf-chat-message>
+      <bf-chat-message [status]="status()">
+        @if (status() === 'done') {
+          <p>Stay for the second cup.</p>
+        }
+        @if (status() === 'failed') {
+          <bf-button bfSlot="action" variant="text" size="sm" (clicked)="retry()">Retry</bf-button>
+        }
+      </bf-chat-message>
+    </bf-chat-thread>
+  `,
+})
+export class ChatThreadStatesExampleComponent {
+  readonly status = signal<BfChatMessageStatus>('failed');
+
+  retry(): void {
+    this.status.set('done');
+  }
+}
+```
+
+## Rich content
+
+The body is a `bfProse` element: headings, lists, links, inline code, code blocks, quotes and rules in the library tokens. The `content` slot below it holds inline content the prose styles leave alone, such as cards, images or chips.
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  BfCardComponent,
+  BfChatMessageComponent,
+  BfChatThreadComponent,
+  BfChipComponent,
+} from '@bitforgehq/ui';
+
+/* The app renders its markdown to HTML (and sanitises it) itself; the message styles it. */
+const REPLY_HTML = `
+  <h3>Three name ideas</h3>
+  <ol>
+    <li><strong>Ember and Oat</strong>: warm and rustic.</li>
+    <li><strong>Second Cup</strong>: playful, for regulars.</li>
+    <li><strong>Field Notes</strong>: quiet and bookish.</li>
+  </ol>
+  <p>Check the domain with <code>whois embersandoat.com</code> before you print the menus.</p>
+  <blockquote>A short name is easier to say out loud and to find.</blockquote>
+`;
+
+/**
+ * Rendered markdown and inline content.
+ *
+ * The reply's body is the app's rendered markdown, styled as prose: a heading, a numbered list,
+ * inline code and a quote. Below it, the `content` slot holds a card and chips the user can pick
+ * from, outside the prose styling.
+ */
+@Component({
+  selector: 'app-example-chat-thread-rich-content',
+  imports: [BfChatThreadComponent, BfChatMessageComponent, BfCardComponent, BfChipComponent],
+  template: `
+    <bf-chat-thread label="Rich reply" class="max-h-[30rem]">
+      <bf-chat-message role="user" author="You">Name ideas, with a logo mood?</bf-chat-message>
+      <bf-chat-message author="Assistant">
+        <div [innerHTML]="replyHtml"></div>
+        <bf-card bfSlot="content" variant="tint" class="w-64">
+          <p class="text-label text-text font-bold">Logo mood</p>
+          <p class="text-caption text-text-muted">Hand-drawn, charcoal on oat paper</p>
+        </bf-card>
+        <div bfSlot="content" class="flex flex-wrap gap-2">
+          @for (name of names; track name) {
+            <bf-chip [selected]="picked() === name" (changed)="picked.set($event ? name : '')">{{
+              name
+            }}</bf-chip>
+          }
+        </div>
+      </bf-chat-message>
+    </bf-chat-thread>
+  `,
+})
+export class ChatThreadRichContentExampleComponent {
+  readonly replyHtml = REPLY_HTML;
+  readonly names = ['Ember and Oat', 'Second Cup', 'Field Notes'];
+  readonly picked = signal('');
+}
+```
+
+## Desktop
+
+A message has no hover or pointer state of its own; links in the prose underline more thickly on hover and show the focus ring on keyboard focus, and code blocks scroll sideways with the trackpad. The user bubble stops at 42rem on a wide window.
+
+## Theming
+
+- User bubble: `primary-soft` background, `text` text, `rounded-field` corners. Assistant reply: no surface.
+- Header: `text-muted` (the time), `text-secondary` (the author), the caption step.
+- Prose: `text` body and headings, `primary-text` links with a `ring` focus ring, `surface-muted` inline code, `surface` code blocks with a `border` edge, `border-strong` quote rule with `text-secondary` text, `text-muted` list markers.
+- Status line: `text-muted` for stopped, `danger` for failed.
+- Caret: the text colour (`CanvasText` under forced colours), pulsing with `--animate-chat-caret`.
+
+## Accessibility
+
+The message is plain content in the thread's log: no role of its own (the `role` input sets the look, and the host drops the attribute). The header's time is a `time` element whose `datetime` keeps the exact value. While `streaming`, the message is `aria-busy="true"` and the caret is a pseudo-element, which is never read. The status line is text in the log, so a screen reader announces it when the status changes. A `user` message is told apart by its `author` text, not only by its colour and side.
+
+## Inputs
+
+| Name            | Type                                                      | Default       | Description                                                                                                                    |
+| --------------- | --------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `role`          | `BfChatMessageRole` (`'user' \| 'assistant'`)             | `'assistant'` | Who wrote it: `user` (a bubble at the inline end) or `assistant` (full width, no bubble).                                      |
+| `author`        | `string`                                                  | `''`          | Whose message it is, shown in the header, such as "You" or the assistant's name; empty shows none.                             |
+| `time`          | `Date \| string \| null`                                  | `null`        | When it was written: a Date or an ISO 8601 string, shown as hours and minutes; empty or invalid shows no time.                 |
+| `timeText`      | `string`                                                  | `''`          | Shown in place of the formatted time, such as "just now"; the `time` element's `datetime` keeps the exact value.               |
+| `streaming`     | `boolean`                                                 | `false`       | The text is still arriving: a caret pulses at its end and the message is `aria-busy`.                                          |
+| `status`        | `BfChatMessageStatus` (`'done' \| 'stopped' \| 'failed'`) | `'done'`      | How it ended: `done` (no status line), `stopped` or `failed`.                                                                  |
+| `statusMessage` | `string`                                                  | `''`          | Shown in place of the built-in status line (`chatMessageStopped`, `chatMessageFailed`), such as the error the server returned. |
+
+## Slots
+
+- `default`: The message text: plain text or the app's rendered markdown, styled as prose.
+- `content`: Inline content below the text, such as cards, images or chips (not styled as prose).
+- `action`: Beside the status line, such as a Retry button.
+
+## Notes
+
+### Do
+
+- Set `author` on every message, so its speaker is never shown by colour and position alone.
+- Turn `streaming` off when the last piece of text has arrived, also when the request fails or stops.
+
+### Don't
+
+- Don't put buttons in the text: use the `action` slot for one beside the status line.