@bitforgehq/ui 0.4.0 → 0.5.0-next.3

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.