@bitforgehq/ui 0.4.0 → 0.5.0-next.3

package/ai/components/chat-thread.md

@@ -0,0 +1,521 @@
+# bf-chat-thread
+
+Scrolling chat message log that follows new text and offers a jump to latest
+
+`BfChatThreadComponent` from `@bitforgehq/ui` · Data display · since 0.5.0
+
+## Example
+
+```ts
+import { Component, DestroyRef, computed, inject, signal } from '@angular/core';
+import {
+  BfChatMessageComponent,
+  BfChatThreadComponent,
+  type BfChatMessageRole,
+  type BfChatMessageStatus,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfChatComposerComponent } from '@bitforgehq/ui/overlay';
+import { ArrowDown, ArrowUp, Square } from 'lucide';
+
+interface ChatTurn {
+  readonly id: number;
+  readonly role: BfChatMessageRole;
+  readonly text: string;
+  readonly streaming: boolean;
+  readonly status: BfChatMessageStatus;
+}
+
+/* Canned replies for the fake stream; a real app streams its model's answer instead. */
+const REPLIES = [
+  'Here are three directions. Ember and Oat: warm, rustic, a wood-fired oven in the window. ' +
+    'Second Cup: a playful name for a neighbourhood spot with refills on the house. ' +
+    'Field Notes: quiet, bookish, with long tables for people who work while they sip.',
+  'For the opening week, try a pay-what-you-like morning, a latte art evening with the ' +
+    'baristas, and a punch card that fills twice as fast. Small, friendly, easy to repeat.',
+];
+/* One word every 60 ms. */
+const WORD_DELAY = 60;
+
+/**
+ * Chat with a streaming reply.
+ *
+ * A `bf-chat-thread` above a `bf-chat-composer`: send a message and a fake assistant reply
+ * streams in word by word, the thread following it to the bottom. Scroll up while it writes and
+ * the "Jump to latest" button appears; Stop ends the reply and marks it stopped.
+ */
+@Component({
+  selector: 'app-example-chat-thread-overview',
+  imports: [
+    BfChatThreadComponent,
+    BfChatMessageComponent,
+    BfChatComposerComponent,
+    BfIconComponent,
+  ],
+  template: `
+    <div class="flex h-[26rem] flex-col gap-3">
+      <bf-chat-thread label="Cafe ideas" class="flex-1">
+        @for (turn of turns(); track turn.id) {
+          <bf-chat-message
+            [role]="turn.role"
+            [author]="turn.role === 'user' ? 'You' : 'Assistant'"
+            [streaming]="turn.streaming"
+            [status]="turn.status"
+          >
+            <p>{{ turn.text }}</p>
+          </bf-chat-message>
+        }
+        <bf-icon bfSlot="jump-icon" [icon]="arrowDown" />
+      </bf-chat-thread>
+      <bf-chat-composer
+        placeholder="Ask for ideas"
+        [(value)]="draft"
+        [running]="running()"
+        (sent)="ask($event)"
+        (stopped)="stop()"
+      >
+        <bf-icon bfSlot="send-icon" [icon]="arrowUp" />
+        <bf-icon bfSlot="stop-icon" [icon]="square" />
+      </bf-chat-composer>
+    </div>
+  `,
+})
+export class ChatThreadOverviewExampleComponent {
+  protected readonly arrowUp = ArrowUp;
+  protected readonly arrowDown = ArrowDown;
+  protected readonly square = Square;
+
+  readonly draft = signal('');
+  readonly turns = signal<ChatTurn[]>([
+    {
+      id: 1,
+      role: 'user',
+      text: 'I am opening a small cafe. Can you help me name it?',
+      streaming: false,
+      status: 'done',
+    },
+    {
+      id: 2,
+      role: 'assistant',
+      text: 'Gladly. Tell me about the place: the street, the mood, who you hope will come in.',
+      streaming: false,
+      status: 'done',
+    },
+  ]);
+  readonly running = computed(() => this.turns().some((turn) => turn.streaming));
+
+  private nextId = 3;
+  private replyIndex = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => this.clearTimer());
+  }
+
+  ask(text: string): void {
+    const replyId = this.nextId + 1;
+    this.turns.update((turns) => [
+      ...turns,
+      { id: this.nextId, role: 'user', text, streaming: false, status: 'done' },
+      { id: replyId, role: 'assistant', text: '', streaming: true, status: 'done' },
+    ]);
+    this.nextId += 2;
+    const words = (REPLIES[this.replyIndex++ % REPLIES.length] ?? '').split(' ');
+    let shown = 0;
+    this.timer = setInterval(() => {
+      shown += 1;
+      const done = shown >= words.length;
+      this.updateTurn(replyId, { text: words.slice(0, shown).join(' '), streaming: !done });
+      if (done) {
+        this.clearTimer();
+      }
+    }, WORD_DELAY);
+  }
+
+  stop(): void {
+    this.clearTimer();
+    const streaming = this.turns().find((turn) => turn.streaming);
+    if (streaming) {
+      this.updateTurn(streaming.id, { streaming: false, status: 'stopped' });
+    }
+  }
+
+  private updateTurn(id: number, change: Partial<ChatTurn>): void {
+    this.turns.update((turns) =>
+      turns.map((turn) => (turn.id === id ? { ...turn, ...change } : turn)),
+    );
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}
+```
+
+## Overview
+
+The scrolling message list of a chat: a `role="log"` around `bf-chat-message` elements 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, which scrolls back down (smoothly, at once under
+reduced motion) and follows again. While a message streams the log is `aria-busy`, so a screen
+reader announces the reply once it is complete, not piece by piece. Messages added after the
+first render rise and fade in; the ones it opens with do not. Give it a height (or `flex-1` in a
+column): it scrolls inside.
+
+The message list of a chat with an assistant: a scrolling `role="log"` of `bf-chat-message` elements that stays pinned to the newest message while a reply streams in, with a "Jump to latest" button once the user scrolls away.
+
+## When to use
+
+Use `bf-chat-thread` for a conversation between the user and an assistant (an ideation chat, a help bot), with a [bf-chat-composer](https://bitforge-ui.web.app/components/chat-composer) below it. Use [bf-timeline](https://bitforge-ui.web.app/components/timeline) instead for a history of events with actors and times, and [bf-list](https://bitforge-ui.web.app/components/list) for rows the user picks from.
+
+## Basic usage
+
+Put one [bf-chat-message](https://bitforge-ui.web.app/components/chat-message) per message inside, oldest first, usually from an `@for`. Give the thread a height (a fixed one, `max-h-*`, or `flex-1` in a column with a fixed height): it scrolls inside, and its own `p-1` keeps the focus ring and the bubbles off the edge. The example streams a pretend reply word by word: send a message, then scroll up while it writes.
+
+```ts
+import { Component, DestroyRef, computed, inject, signal } from '@angular/core';
+import {
+  BfChatMessageComponent,
+  BfChatThreadComponent,
+  type BfChatMessageRole,
+  type BfChatMessageStatus,
+} from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfChatComposerComponent } from '@bitforgehq/ui/overlay';
+import { ArrowDown, ArrowUp, Square } from 'lucide';
+
+interface ChatTurn {
+  readonly id: number;
+  readonly role: BfChatMessageRole;
+  readonly text: string;
+  readonly streaming: boolean;
+  readonly status: BfChatMessageStatus;
+}
+
+/* Canned replies for the fake stream; a real app streams its model's answer instead. */
+const REPLIES = [
+  'Here are three directions. Ember and Oat: warm, rustic, a wood-fired oven in the window. ' +
+    'Second Cup: a playful name for a neighbourhood spot with refills on the house. ' +
+    'Field Notes: quiet, bookish, with long tables for people who work while they sip.',
+  'For the opening week, try a pay-what-you-like morning, a latte art evening with the ' +
+    'baristas, and a punch card that fills twice as fast. Small, friendly, easy to repeat.',
+];
+/* One word every 60 ms. */
+const WORD_DELAY = 60;
+
+/**
+ * Chat with a streaming reply.
+ *
+ * A `bf-chat-thread` above a `bf-chat-composer`: send a message and a fake assistant reply
+ * streams in word by word, the thread following it to the bottom. Scroll up while it writes and
+ * the "Jump to latest" button appears; Stop ends the reply and marks it stopped.
+ */
+@Component({
+  selector: 'app-example-chat-thread-overview',
+  imports: [
+    BfChatThreadComponent,
+    BfChatMessageComponent,
+    BfChatComposerComponent,
+    BfIconComponent,
+  ],
+  template: `
+    <div class="flex h-[26rem] flex-col gap-3">
+      <bf-chat-thread label="Cafe ideas" class="flex-1">
+        @for (turn of turns(); track turn.id) {
+          <bf-chat-message
+            [role]="turn.role"
+            [author]="turn.role === 'user' ? 'You' : 'Assistant'"
+            [streaming]="turn.streaming"
+            [status]="turn.status"
+          >
+            <p>{{ turn.text }}</p>
+          </bf-chat-message>
+        }
+        <bf-icon bfSlot="jump-icon" [icon]="arrowDown" />
+      </bf-chat-thread>
+      <bf-chat-composer
+        placeholder="Ask for ideas"
+        [(value)]="draft"
+        [running]="running()"
+        (sent)="ask($event)"
+        (stopped)="stop()"
+      >
+        <bf-icon bfSlot="send-icon" [icon]="arrowUp" />
+        <bf-icon bfSlot="stop-icon" [icon]="square" />
+      </bf-chat-composer>
+    </div>
+  `,
+})
+export class ChatThreadOverviewExampleComponent {
+  protected readonly arrowUp = ArrowUp;
+  protected readonly arrowDown = ArrowDown;
+  protected readonly square = Square;
+
+  readonly draft = signal('');
+  readonly turns = signal<ChatTurn[]>([
+    {
+      id: 1,
+      role: 'user',
+      text: 'I am opening a small cafe. Can you help me name it?',
+      streaming: false,
+      status: 'done',
+    },
+    {
+      id: 2,
+      role: 'assistant',
+      text: 'Gladly. Tell me about the place: the street, the mood, who you hope will come in.',
+      streaming: false,
+      status: 'done',
+    },
+  ]);
+  readonly running = computed(() => this.turns().some((turn) => turn.streaming));
+
+  private nextId = 3;
+  private replyIndex = 0;
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => this.clearTimer());
+  }
+
+  ask(text: string): void {
+    const replyId = this.nextId + 1;
+    this.turns.update((turns) => [
+      ...turns,
+      { id: this.nextId, role: 'user', text, streaming: false, status: 'done' },
+      { id: replyId, role: 'assistant', text: '', streaming: true, status: 'done' },
+    ]);
+    this.nextId += 2;
+    const words = (REPLIES[this.replyIndex++ % REPLIES.length] ?? '').split(' ');
+    let shown = 0;
+    this.timer = setInterval(() => {
+      shown += 1;
+      const done = shown >= words.length;
+      this.updateTurn(replyId, { text: words.slice(0, shown).join(' '), streaming: !done });
+      if (done) {
+        this.clearTimer();
+      }
+    }, WORD_DELAY);
+  }
+
+  stop(): void {
+    this.clearTimer();
+    const streaming = this.turns().find((turn) => turn.streaming);
+    if (streaming) {
+      this.updateTurn(streaming.id, { streaming: false, status: 'stopped' });
+    }
+  }
+
+  private updateTurn(id: number, change: Partial<ChatTurn>): void {
+    this.turns.update((turns) =>
+      turns.map((turn) => (turn.id === id ? { ...turn, ...change } : turn)),
+    );
+  }
+
+  private clearTimer(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}
+```
+
+## Following new text
+
+The thread follows the newest message: when its content grows (new text in a streaming message, a new message, a taller composer that shrinks the log) it scrolls to the bottom in the next frame. The measuring runs in a `ResizeObserver` on the content and on the log, and the scroll is written in the next render, never inside the observer, so a resize can never end in the "ResizeObserver loop" error. When the user scrolls up (the wheel, a drag, a swipe, or <kbd>Arrow Up</kbd>, <kbd>Page Up</kbd> or <kbd>Home</kbd> in the log) it stops following and shows the "Jump to latest" button; new text then grows below without moving what the user reads. The button scrolls back down (smoothly; at once under reduced motion) and follows again. Scrolling back to the bottom by hand follows again too. A conversation too short to scroll keeps following. The `jump-icon` slot puts an icon before the button's text.
+
+## States
+
+A message can end `stopped` (the user pressed Stop) or `failed`, with a short status line under it and an `action` slot beside it for a Retry button. See [bf-chat-message](https://bitforge-ui.web.app/components/chat-message) for its inputs.
+
+```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');
+  }
+}
+```
+
+## Rendered markdown and rich content
+
+The message body is styled as prose (`bfProse`): headings, lists, links, inline code, code blocks and quotes, for the markdown the app renders to HTML itself (and sanitises). The `content` slot under the text holds cards, images or chips, outside the prose styles. `bfProse` works on any element of the app too, such as a help article.
+
+```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('');
+}
+```
+
+## Motion
+
+A message added after the first render rises 4 px and fades in (`--animate-chat-message-in`: 200 ms on `--ease-settle`); the messages the thread opens with appear at once. A streaming reply shows a pulsing caret at the end of its text (`--animate-chat-caret`). Under `prefers-reduced-motion: reduce` messages appear without motion, the caret stays still and the jump is instant.
+
+## Desktop
+
+The log scrolls with the wheel and the trackpad, and takes keyboard focus (its focus ring shows on <kbd>Tab</kbd>), so the arrow and page keys scroll it. The "Jump to latest" button is the outline button at `sm` with a raised shadow, centred over the bottom of the log; it has the button's hover and pressed steps, and after a press focus moves to the log, so it never falls to the page. Under a coarse pointer its hit area grows to 44 px.
+
+## Theming
+
+- The log has no surface of its own: it shows the page (`bg`) or the card it sits on; its focus ring is `ring`.
+- Messages: see [bf-chat-message](https://bitforge-ui.web.app/components/chat-message) (`primary-soft` user bubbles, `text` prose, `text-muted` headers).
+- Jump button: bf-button's outline look (`surface`, `border-strong`, `text`, `primary-soft-pressed` while pressed) with `shadow-raised`.
+- Motion: `--animate-chat-message-in` and `--animate-chat-caret`, timed by `--bf-duration-layout` and `--ease-settle`.
+
+## Accessibility
+
+The scrolling element is a `role="log"` with `aria-live="polite"`, named by `label` or the `chatThread` label ("Conversation"), so a screen reader announces new messages as they are added without interrupting. While any message streams, the log is `aria-busy="true"` (and so is the message): a screen reader holds the changes and reads the reply once, when it is complete, instead of every piece of text. Set each message's `author` so the announcement says who speaks. The log is focusable (`tabindex="0"`) so keyboard users can scroll it. "Jump to latest" is a real `button` with the `chatJumpToLatest` label as its text; it is only in the tab order while it shows, and pressing it moves focus to the log.
+
+### Keyboard
+
+| Key                                                           | Where          | Action                                                                                                   |
+| ------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------- |
+| <kbd>Tab</kbd>                                                | Page           | Moves focus to the log, then to the messages' links and buttons, then to "Jump to latest" while it shows |
+| <kbd>Arrow Up</kbd> / <kbd>Page Up</kbd> / <kbd>Home</kbd>    | Log            | Scrolls up and stops following new text                                                                  |
+| <kbd>Arrow Down</kbd> / <kbd>Page Down</kbd> / <kbd>End</kbd> | Log            | Scrolls down; at the bottom it follows again                                                             |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                           | Jump to latest | Scrolls to the newest message, follows again and focuses the log                                         |
+
+## Inputs
+
+| Name    | Type     | Default | Description                                                                    |
+| ------- | -------- | ------- | ------------------------------------------------------------------------------ |
+| `label` | `string` | `''`    | The log's accessible name; empty uses the `chatThread` label ("Conversation"). |
+
+## Slots
+
+- `default`: The messages, each a `bf-chat-message` (in order, oldest first).
+- `jump-icon`: An icon before the "Jump to latest" text, such as an arrow down.
+
+## Methods
+
+### `jumpToLatest(): void`
+
+Scrolls to the newest message (smoothly, at once under reduced motion) and follows it again.
+
+## Notes
+
+### Do
+
+- Give the thread a bounded height so it scrolls inside, with the composer below it.
+- Set `author` on every message so the log announces who wrote it.
+- Render and sanitise markdown in the app, and let the body style it.
+
+### Don't
+
+- Don't animate or scroll the thread yourself; it follows and animates new messages on its own.
+- Don't put a message's cards or chips in its text: use the `content` slot, which the prose styles leave alone.
+
+## Migration notes
+
+### 0.5.0
+
+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.

package/ai/components/checkbox.md

@@ -289,6 +289,7 @@ Hovering the row (box and label) darkens the box border, or the checked fill, wi
 - Hover over the row (pointer cursor): unchecked border `text-muted` (`danger` on error); checked box `primary-hover`.
 - Pressed (the row held down): the box border turns `text`; not while disabled or read-only.
 - Disabled: border `surface-sunken`, background `surface-muted`; label text `text-disabled`.
+- Motion: the mark grows in and shrinks out over 150 ms on `ease-md` (a fade only under reduced motion); an error message fades in (`animate-message-in`).
 - Read-only: `surface-muted` background, no hover, default cursor; unchecked keeps the `border-strong` border, checked (or indeterminate) a `primary` border and mark (≥ 4.8:1 on `surface-muted` in both themes).
 - Focus ring (on the visually hidden native input): `ring`.
 
@@ -359,6 +360,12 @@ Focuses the native checkbox; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.5.0
+
+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.
+
 ### 0.3.0
 
 New `ariaLabelledby` input: the id(s) of the element(s) that name the box when no visible `label`

package/ai/components/combobox.md

@@ -317,6 +317,9 @@ so touch apps use `fieldSize: 'lg'`.
 - `bf-field` renders the `<label for>`, the help and the error text; `aria-describedby`,
   `aria-invalid` and `aria-errormessage` follow the same rules as on `bf-select`.
 - `focus()` focuses the input; Signal Forms calls it from `focusBoundControl()`.
+- Motion: the list grows out of the field as it opens (a fade, a slight scale and a 4 px slide,
+  180 ms) and fades back as it closes (130 ms), keeping the options it showed. `aria-expanded`
+  changes at once and the closing list is inert. Under `prefers-reduced-motion` it only fades.
 
 ### Keyboard
 
@@ -393,6 +396,15 @@ Focuses the input; Signal Forms calls it from `focusBoundControl()`.
 
 ## Migration notes
 
+### 0.5.0
+
+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.
+
 ### 0.3.1
 
 New `bf-combobox` (`BfComboboxComponent<T>`) in `@bitforgehq/ui/overlay`: a text field with a

package/ai/components/date-input.md

@@ -291,6 +291,8 @@ The field box shows the `primary` border and focus ring while any part has focus
 
 The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`) and described by the help and error text. Each part is a `role="spinbutton"` named from the `dateInputDay`, `dateInputMonth` and `dateInputYear` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` (absent while empty) and `aria-valuetext` (the month's name); `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled` reflect the field. The separators are `aria-hidden`. The calendar button is named by `dateInputOpenCalendar` and carries `aria-haspopup="dialog"`, `aria-expanded` and, while open, `aria-controls`; the popover is a non-modal `dialog` named by the button, holding a `bf-calendar` with its own grid semantics. Focus moves into the calendar on open and back to the button on a pick or <kbd>Escape</kbd>. In native mode the platform input carries the label, `aria-invalid` and `aria-describedby`.
 
+Motion: the calendar grows out of the field as it opens (a fade, a slight scale and a 4 px slide, 180 ms) and fades back as it closes (130 ms). Focus returns at once and the closing popover is inert. Under `prefers-reduced-motion` it only fades.
+
 ### Keyboard
 
 | Key                                              | Where    | Action                                                            |
@@ -377,6 +379,13 @@ Closes the calendar popover, focus back on its button; does nothing while it is
 
 ## Migration notes
 
+### 0.5.0
+
+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.
+
 ### 0.3.1
 
 New `bf-date-input` in `@bitforgehq/ui/overlay`: a date field typed part by part, the day, month

package/ai/components/datetime-input.md

@@ -115,6 +115,8 @@ As the date and the time inputs: the focus ring on the field while a part has fo
 
 The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`), each a named `role="spinbutton"` with its range, value and value text, and the field's invalid, required, read-only and disabled state. The button is named by `dateInputOpenCalendar`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; the popover is a non-modal `dialog` named by the button, holding a `bf-calendar` grid and a `role="listbox"` of times named by `timeInputOpenList` (`aria-activedescendant`, `aria-selected`, `aria-disabled`). Focus moves into the calendar on open, to the list after a day is picked, and back to the button after a time is picked or on <kbd>Escape</kbd>.
 
+Motion: the popover grows out of the field as it opens (a fade, a slight scale and a 4 px slide, 180 ms) and fades back as it closes (130 ms). Focus returns at once and the closing popover is inert. Under `prefers-reduced-motion` it only fades.
+
 ### Keyboard
 
 | Key                                              | Where   | Action                                                   |

package/ai/components/field.md

@@ -232,6 +232,7 @@ export class FieldHelpAndErrorExampleComponent {
 
 - Label: `text-muted`, switching to `primary-text` (primary as text, ≥ 4.5:1 on `bg` and `surface`) while the control inside is focused (`group-focus-within/bf-field`) and to `text-disabled` when `disabled`.
 - Required marker: `danger`. Error text: `danger`. Help text: `text-muted`.
+- Motion: the error text fades in over 150 ms when it appears (`animate-message-in`, opacity only, so it stays under reduced motion).
 
 Label, control, help text and error text sit 6 px apart, the same label-to-message spacing as `bf-checkbox`, `bf-radio-group` and `bf-toggle`.
 
@@ -268,6 +269,15 @@ The field renders the label as a native `<label for>` pointing at `controlId`, a
 
 ## Migration notes
 
+### 0.5.0
+
+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.
+
 ### 0.3.0
 
 **Behaviour:** the label of a focused field is `primary-text` (was `primary`).