@ahrowe/ui 0.49.0 → 0.50.0

package/dist/types/common/chatComposer/chatComposer.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { ChatComposerProps } from './chatComposer.types.js';
+declare function ChatComposer(props: ChatComposerProps): ReactElement;
+export default ChatComposer;

package/dist/types/common/chatComposer/chatComposer.types.d.ts

@@ -0,0 +1,40 @@
+import { CSSProperties, ReactNode, Ref, TextareaHTMLAttributes } from 'react';
+import { SlotClassNames, SlotStyles, DataProps } from '../types/slots.types.js';
+export type ChatComposerSlots = 'input' | 'button';
+/** Text ChatComposer renders of its own, for translating it. */
+export interface ChatComposerLabels {
+    /** Shown in the empty field, and its accessible name. */
+    placeholder?: string;
+    /** Send button, read out by screen readers. */
+    send?: string;
+    /** Stop button shown while `onStop` is set, read out by screen readers. */
+    stop?: string;
+}
+/** Native attributes go to the `<textarea>`; `className` and `style` to the root. */
+export interface ChatComposerProps extends DataProps, Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'onChange' | 'value' | 'defaultValue' | 'placeholder'> {
+    /** Called with the trimmed text. Not called while the field is empty or only whitespace. */
+    onSend: (text: string) => void;
+    /** Controlled value. Sending clears it through `onChange('')`. */
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Runs before the composer's own handling; `preventDefault()` on an Enter keeps it from sending. */
+    onKeyDown?: TextareaHTMLAttributes<HTMLTextAreaElement>['onKeyDown'];
+    /** Swaps the send button for a stop button while set, e.g. while an AI answer streams. Enter sends nothing meanwhile. */
+    onStop?: () => void;
+    disabled?: boolean;
+    /** The height of the empty field, in lines. It grows from there to seven. Default 1. */
+    rows?: number;
+    /** Before the field: an attach or emoji button. Moves to a row below it once the text wraps. */
+    startContent?: ReactNode;
+    /** Between the field and the send button. Moves to a row below it, with the send button, once the text wraps. */
+    endContent?: ReactNode;
+    /** Ref to the inner `<textarea>`. */
+    ref?: Ref<HTMLTextAreaElement>;
+    /** Overrides the text ChatComposer renders of its own. Merged per key. */
+    labels?: ChatComposerLabels;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<ChatComposerSlots>;
+    styles?: SlotStyles<ChatComposerSlots>;
+}

package/dist/types/common/chatComposer/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './chatComposer.js';
+export * from './chatComposer.types.js';

package/dist/types/common/chatMessage/chatMessage.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { ChatMessageProps } from './chatMessage.types.js';
+declare function ChatMessage(props: ChatMessageProps): ReactElement;
+export default ChatMessage;

package/dist/types/common/chatMessage/chatMessage.types.d.ts

@@ -0,0 +1,60 @@
+import { CSSProperties, ReactNode } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+import { ColorValue } from '../themeProvider/color.types.js';
+/** How much the message stands out. Independent of its colour. */
+export declare enum ChatMessageStyleType {
+    /** Solid bubble, text in a contrasting colour. The default for `isOwn`. */
+    Filled = "filled",
+    /** A light tint of the colour. The default for everyone else. */
+    Light = "light",
+    /** No bubble, full width: an AI assistant's answer. */
+    Plain = "plain"
+}
+/** Delivery state of an own message: an icon next to `time`, and `Failed` a notice under the bubble. */
+export declare enum ChatMessageStatus {
+    Sending = "sending",
+    Sent = "sent",
+    Delivered = "delivered",
+    Read = "read",
+    Failed = "failed"
+}
+export type ChatMessageSlots = 'avatar' | 'body' | 'author' | 'bubble' | 'meta' | 'actions';
+/** Text ChatMessage renders of its own, for translating it. */
+export interface ChatMessageLabels {
+    /** Read out for the status icon. */
+    sending?: string;
+    sent?: string;
+    delivered?: string;
+    read?: string;
+    /** Shown under the bubble. */
+    failed?: string;
+    /** Names an own message without `author` for screen readers. */
+    you?: string;
+}
+export interface ChatMessageProps extends HtmlProps<HTMLDivElement> {
+    /** The message. A string keeps its line breaks; anything else (rendered Markdown, an image) renders as given. */
+    children?: ReactNode;
+    /** Sent by the current user: aligned to the end, `Filled` in `Primary` by default. */
+    isOwn?: boolean;
+    /** Follows a message from the same author: hides `author` from view, keeps the space of `avatar` and tightens the gap above. */
+    isContinued?: boolean;
+    /** Shown beside the bubble, typically an `Avatar`. */
+    avatar?: ReactNode;
+    /** Name above the bubble. Screen readers get it on every message of a run, not only the first. */
+    author?: ReactNode;
+    /** Shown in the bubble's corner. Format it yourself, e.g. with `Intl.DateTimeFormat`. */
+    time?: ReactNode;
+    status?: ChatMessageStatus;
+    /** Shown below the bubble, after the `Failed` notice: copy, retry, rate. */
+    actions?: ReactNode;
+    /** Default `Filled` when `isOwn`, otherwise `Light`. */
+    styleType?: ChatMessageStyleType;
+    /** A `ThemeColor` or any CSS colour. Default `Primary` when `isOwn`, otherwise `Neutral`. */
+    color?: ColorValue;
+    /** Overrides the text ChatMessage renders of its own. Merged per key. */
+    labels?: ChatMessageLabels;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<ChatMessageSlots>;
+    styles?: SlotStyles<ChatMessageSlots>;
+}

package/dist/types/common/chatMessage/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './chatMessage.js';
+export * from './chatMessage.types.js';

package/dist/types/common/chatMessageList/chatMessageList.d.ts

@@ -0,0 +1,4 @@
+import { ReactElement } from 'react';
+import { ChatMessageListProps } from './chatMessageList.types.js';
+declare function ChatMessageList(props: ChatMessageListProps): ReactElement;
+export default ChatMessageList;

package/dist/types/common/chatMessageList/chatMessageList.types.d.ts

@@ -0,0 +1,27 @@
+import { CSSProperties, ReactNode, Ref } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
+export type ChatMessageListSlots = 'viewport' | 'content' | 'scrollButton';
+/** Text ChatMessageList renders of its own, for translating it. */
+export interface ChatMessageListLabels {
+    /** Accessible name of the message log. */
+    messages?: string;
+    /** Button that jumps back to the newest message, read out by screen readers. */
+    scrollToBottom?: string;
+}
+export interface ChatMessageListHandle {
+    /** Scrolls to the newest message and follows new ones again. Call it after the user sends one. */
+    scrollToBottom: () => void;
+}
+export interface ChatMessageListProps extends HtmlProps<HTMLDivElement> {
+    /** `ChatMessage`s, and anything between them: a `Divider` with a date, a typing indicator. Oldest first. */
+    children?: ReactNode;
+    /** Loads older messages when the user scrolls to the top. Prepend them; the view stays where it was. Leave it out once there are no more. */
+    onLoadMore?: () => Promise<void>;
+    ref?: Ref<ChatMessageListHandle>;
+    /** Overrides the text ChatMessageList renders of its own. Merged per key. */
+    labels?: ChatMessageListLabels;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<ChatMessageListSlots>;
+    styles?: SlotStyles<ChatMessageListSlots>;
+}

package/dist/types/common/chatMessageList/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './chatMessageList.js';
+export * from './chatMessageList.types.js';

package/dist/types/common/configProvider/configProvider.types.d.ts

@@ -49,6 +49,9 @@ import { RoomViewerProps } from '../roomViewer/roomViewer.types.js';
 import { PopoverProps } from '../popover/popover.types.js';
 import { ModalProps } from '../modal/modal.types.js';
 import { StepperProps } from '../stepper/stepper.types.js';
+import { ChatMessageProps } from '../chatMessage/chatMessage.types.js';
+import { ChatMessageListProps } from '../chatMessageList/chatMessageList.types.js';
+import { ChatComposerProps } from '../chatComposer/chatComposer.types.js';
 import { Presentation } from '../configProvider/presentation.types.js';
 /**
  * Global default props keyed by component name.
@@ -133,6 +136,9 @@ export interface ComponentDefaults {
     CommandPalette?: Partial<CommandPaletteProps>;
     WeatherIcon?: Partial<WeatherIconProps>;
     Stepper?: Partial<StepperProps>;
+    ChatMessage?: Partial<ChatMessageProps>;
+    ChatMessageList?: Partial<ChatMessageListProps>;
+    ChatComposer?: Partial<ChatComposerProps>;
 }
 export interface ConfigProviderProps {
     children: React.ReactNode;

package/dist/types/common/hooks/useAutoGrow.d.ts

@@ -0,0 +1,12 @@
+import { RefObject } from 'react';
+interface AutoGrowOptions {
+    enabled?: boolean;
+    /** Whether the text needs more than the field's `rows`, after each change of `value` or width. */
+    onGrow?: (isGrown: boolean) => void;
+}
+/**
+ * Keeps a textarea as tall as its text, up to the `max-height` its stylesheet sets. It measures
+ * again when `value` changes, so the field must be controlled, and when its width changes.
+ */
+export declare function useAutoGrow(ref: RefObject<HTMLElement | null>, value: unknown, { enabled, onGrow }?: AutoGrowOptions): void;
+export {};

package/dist/types/common/tabHeader/tabHeader.types.d.ts

@@ -1,12 +1,14 @@
 import { default as React } from 'react';
 import { IconContent } from '../types/icon.types.js';
 import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types.js';
-export type TabHeaderSlots = 'root' | 'tab' | 'icon' | 'labels' | 'title' | 'subtitle';
+export type TabHeaderSlots = 'root' | 'tab' | 'icon' | 'labels' | 'title' | 'subtitle' | 'endContent';
 export interface TabHeaderTab {
     id: string;
     icon: IconContent;
-    title?: string;
-    subtitle?: string;
+    title?: React.ReactNode;
+    subtitle?: React.ReactNode;
+    /** After the labels. Stays visible when a narrow screen collapses the tab, so keep it small: a `Badge`, a dot. */
+    endContent?: React.ReactNode;
     disabled?: boolean;
 }
 export interface TabHeaderProps extends Omit<HtmlProps, 'onChange'> {

package/dist/types/index.d.ts

@@ -29,6 +29,12 @@ export { default as Card } from './common/card/index.js';
 export * from './common/card/index.js';
 export { default as Carousel } from './common/carousel/index.js';
 export * from './common/carousel/index.js';
+export { default as ChatComposer } from './common/chatComposer/index.js';
+export * from './common/chatComposer/index.js';
+export { default as ChatMessage } from './common/chatMessage/index.js';
+export * from './common/chatMessage/index.js';
+export { default as ChatMessageList } from './common/chatMessageList/index.js';
+export * from './common/chatMessageList/index.js';
 export { default as Checkbox } from './common/checkbox/index.js';
 export * from './common/checkbox/index.js';
 export { default as Chip } from './common/chip/index.js';

package/docs/CLAUDE.md

@@ -41,9 +41,9 @@ enums and slot names. Do not infer props from a component's name.
   `Light` for status and selection, `Outlined` for secondary actions, `Plain` for tertiary ones.
 - **`icon` props** take a FontAwesome `IconDefinition` or any React element.
 - **`ref`** is a plain prop, there is no `forwardRef`. It lands on the element you would reach for:
-  Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`. Timer, Flip, Tilt,
-  Ripple, VirtualList, RoomDrawer and RoomViewer expose an imperative handle instead; its type is
-  exported next to the props.
+  Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`, ChatComposer its
+  `<textarea>`. Timer, Flip, Tilt, Ripple, VirtualList, ChatMessageList, RoomDrawer and RoomViewer
+  expose an imperative handle instead; its type is exported next to the props.
 - Every module is `'use client'`; nothing renders on the server. The exception is
   `@ahrowe/ui/floor-plan`, the plan model (FloorPlan.md) without React, for server code that reads
   or validates a plan. No right-to-left support.
@@ -76,6 +76,9 @@ enums and slot names. Do not infer props from a component's name.
 | Calendar.md | Calendar, CalendarView | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments |
 | Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions, ThemeColor | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
 | Carousel.md | Carousel | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
+| ChatComposer.md | ChatComposer | The field a chat message is written in, with its send button: under a ChatMessageList, which shows a whole chat put together |
+| ChatMessage.md | ChatMessage, ChatMessageStyleType, ChatMessageStatus | One message in a conversation: a messenger bubble, a support agent's reply, an AI assistant's answer |
+| ChatMessageList.md | ChatMessageList | The scrolling conversation of a chat: a messenger, a support widget, an AI assistant |
 | Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
 | Chip.md | Chip, ChipContainer, ChipStyleType, ThemeColor | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
 | ColorPicker.md | ColorPicker | Hex colour selection — theme editors, annotation tools, customisation panels |

package/docs/ChatComposer.md

@@ -0,0 +1,100 @@
+# ChatComposer
+
+**When to use:** The field a chat message is written in, with its send button: under a [ChatMessageList](ChatMessageList.md), which shows a whole chat put together. For multiline text in a form, with a label and validation, use [Textarea](Textarea.md).
+
+**Keywords:** message input, chat input, prompt, compose, reply box, enter to send, submit, attachment
+
+**Import:** `import { ChatComposer } from '@ahrowe/ui'`  
+**Types:** `import type { ChatComposerProps, ChatComposerLabels } from '@ahrowe/ui'`
+
+```tsx
+import { ActionIcon, ChatComposer } from '@ahrowe/ui';
+import { faFaceSmile, faPaperclip } from '@fortawesome/free-solid-svg-icons';
+
+// Uncontrolled: it clears itself after sending
+<ChatComposer onSend={(text) => send(text)} />
+
+// AI chat: a stop button replaces send while the answer streams
+<ChatComposer
+  onSend={ask}
+  onStop={isStreaming ? stop : undefined}
+  labels={{ placeholder: 'Ask anything' }}
+/>
+
+// Buttons of your own around the field
+<ChatComposer
+  onSend={send}
+  startContent={<ActionIcon icon={faPaperclip} aria-label='Attach a file' onClick={openFilePicker} />}
+  endContent={<ActionIcon icon={faFaceSmile} aria-label='Emoji' onClick={openEmojiPicker} />}
+/>
+
+// Controlled, e.g. to keep a draft per conversation: sending clears it through onChange('')
+<ChatComposer value={draft} onChange={setDraft} onSend={send} />
+
+// Native attributes go to the textarea; an Enter your onKeyDown prevents is not sent
+<ChatComposer
+  onSend={send}
+  maxLength={2000}
+  autoFocus
+  onKeyDown={(event) => {
+    if (event.key === 'Enter' && isMentionListOpen) {
+      event.preventDefault();
+      pickMention();
+    }
+  }}
+/>
+```
+
+**Keys:**
+
+| Key | Does |
+|-----|------|
+| `Enter` | Sends. On a touch screen it starts a new line instead, since that keyboard has no other way to, and only the button sends |
+| `Shift+Enter` | A new line |
+| `Ctrl+Enter` / `⌘+Enter` | Sends, on a touch screen too |
+
+The `Enter` that confirms a word in a Japanese, Chinese or Korean input method never sends,
+including in Safari, which reports it as an ordinary `Enter`.
+
+`onSend` gets the text trimmed, and is not called while the field is empty or only whitespace;
+the send button is disabled then too. The focus stays in the field after sending, so a phone
+keyboard stays open. The field grows with the text up to seven lines, then scrolls, and measures
+again when its width changes.
+
+**Buttons of your own.** `startContent` and `endContent` sit beside the field while the text fits
+in it. Once it needs more lines than `rows` (a second one, by default), the field takes the whole
+width and the buttons move to a row below it: `startContent` at the start, `endContent` and the
+send button at the end, the usual toolbar of an AI chat. So several of them never leave the field
+too narrow to write in. They move back once the field is empty, usually after sending, rather
+than as soon as the wider field fits the text on one line, which would wrap it again. With only
+the send button there is nothing to move, and it stays beside the field.
+
+While `onStop` is set the send button is a stop button that calls it, and `Enter` sends nothing,
+so the user can type the next message while an answer streams in.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `onSend` | `(text: string) => void` | Called with the trimmed text (required) |
+| `value` | `string` | Controlled value. Sending clears it through `onChange('')` |
+| `defaultValue` | `string` | Initial value, uncontrolled |
+| `onChange` | `(value: string) => void` | Every change |
+| `onStop` | `() => void` | Swaps send for a stop button while set |
+| `onKeyDown` | `KeyboardEventHandler` | Runs before the composer's own keys; `preventDefault()` on an Enter keeps it from sending |
+| `disabled` | `boolean` | Disables the field and both buttons |
+| `rows` | `number` | The empty field's height in lines, default 1. It grows from there to seven |
+| `startContent` | `ReactNode` | Before the field: attach, emoji. Below it once the text wraps, see above |
+| `endContent` | `ReactNode` | Between the field and the send button. Below it once the text wraps |
+| `ref` | `Ref<HTMLTextAreaElement>` | Ref to the inner `<textarea>`, e.g. to focus it when a conversation opens |
+
+Every other native attribute (`maxLength`, `autoFocus`, `name`, `spellCheck`, `onPaste`, `aria-*`,
+`data-*`) goes to the `<textarea>`, as on [Input](Input.md); `className` and `style` go to the
+root. An `aria-label` replaces the placeholder as the field's name, and `readOnly` also keeps it
+from sending.
+
+**Global defaults:** adopts `ConfigProvider`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `input` (the `<textarea>`) `button` (send or stop)
+
+**Labels:** `placeholder` (also the field's accessible name) `send` `stop`: the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ChatComposerLabels`.

package/docs/ChatMessage.md

@@ -0,0 +1,88 @@
+# ChatMessage
+
+**When to use:** One message in a conversation: a messenger bubble, a support agent's reply, an AI assistant's answer. Put them in a [ChatMessageList](ChatMessageList.md), which also shows a whole chat put together. For a note between messages ("Lisa joined", a date), use a [Divider](Divider.md) with `text`.
+
+**Keywords:** speech bubble, messenger, whatsapp, chatbot, assistant, LLM, reply, read receipt, seen, ticks, typing indicator
+
+**Import:** `import { ChatMessage, ChatMessageStyleType, ChatMessageStatus } from '@ahrowe/ui'`  
+**Types:** `import type { ChatMessageProps, ChatMessageLabels } from '@ahrowe/ui'`
+
+```tsx
+import { Avatar, ChatMessage, ChatMessageStatus, ChatMessageStyleType, CopyButton, Loader, LoaderType, ThemeColor } from '@ahrowe/ui';
+
+// Messenger: two from Ava in a run, then your own with its delivery state
+<ChatMessage author='Ava' avatar={<Avatar name='Ava' />} time='10:41'>Are we still on for tonight?</ChatMessage>
+<ChatMessage author='Ava' avatar={<Avatar name='Ava' />} time='10:41' isContinued>8 o'clock?</ChatMessage>
+<ChatMessage isOwn time='10:42' status={ChatMessageStatus.Read}>Yes, see you there</ChatMessage>
+
+// AI assistant: no bubble, full width, actions underneath
+<ChatMessage styleType={ChatMessageStyleType.Plain} actions={<CopyButton value={answer} />}>
+  <Markdown>{answer}</Markdown>
+</ChatMessage>
+
+// Someone typing, or an answer on its way: a Loader is the content
+<ChatMessage avatar={<Avatar name='Ava' />}>
+  <Loader type={LoaderType.Dots} size='1em' color={ThemeColor.Neutral} labels={{ loading: 'Ava is typing' }} />
+</ChatMessage>
+```
+
+**Enums:**
+
+- `ChatMessageStyleType`: `Filled` (default when `isOwn`) | `Light` (default otherwise) | `Plain`, see [ThemeColor.md](ThemeColor.md). A `Light` bubble keeps the page's text colour, as a `Light` Card does. `Plain` has no bubble and takes the full width, for an assistant's answer
+- `ChatMessageStatus`: `Sending` (a clock) | `Sent` (a check) | `Delivered` (two checks) | `Read` (two checks at full strength, in `--info-color` except on a `Filled` bubble, where the rest are dimmed) | `Failed` (no icon in the bubble: "Not sent" under it, ahead of `actions`, where a retry button belongs, with the icon in `--error-color` and the text in the page's own)
+
+**A run of messages.** Set `isContinued` on every message after the first from the same author:
+it hides `author` from view, tightens the gap above, rounds off the corner that points at the
+author, and keeps the space of `avatar` so the run stays aligned. Pass the same `author` and
+`avatar` to all of them: screen readers still read `author` on each one. Start a new run after a
+date `Divider`, or the first message under it shows no name.
+
+**Who sent it, for screen readers.** Alignment and colour are not read out, so each message names
+its sender: `author`, or "You" (`labels.you`, never shown) on an own message without one. In a
+one-to-one chat that is enough to leave `author` out; in a group, pass it to everyone else's.
+
+```tsx
+{messages.map((message, index) => (
+  <ChatMessage
+    key={message.id}
+    isOwn={message.authorId === me.id}
+    isContinued={messages[index - 1]?.authorId === message.authorId}
+    author={message.authorId === me.id ? undefined : message.authorName}
+    avatar={message.authorId === me.id ? undefined : <Avatar name={message.authorName} src={message.avatarUrl} />}
+    time={timeFormat.format(message.sentAt)}
+    status={message.status}
+  >
+    {message.text}
+  </ChatMessage>
+))}
+```
+
+**Content.** A string keeps its line breaks, so text typed with Shift+Enter shows as typed. Any
+other content renders as given: the library renders no Markdown, so pass your renderer's output
+(`react-markdown`, `marked`). A long word or URL wraps rather than widening the bubble. `time` and
+`status` sit at the bubble's end: on the same line as a short message, on a line of their own
+under a long one.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The message |
+| `isOwn` | `boolean` | Sent by the current user: aligned to the end, `Filled` in `Primary` by default |
+| `isContinued` | `boolean` | Follows a message from the same author, see above |
+| `avatar` | `ReactNode` | Beside the bubble, typically an [Avatar](Avatar.md) |
+| `author` | `ReactNode` | Name above the bubble, on the first message of a run. Screen readers get it on every one |
+| `time` | `ReactNode` | In the bubble's corner. Format it yourself, e.g. with `Intl.DateTimeFormat` |
+| `status` | `ChatMessageStatus` | Delivery state, an icon after `time` that screen readers read out. `Failed` is a notice under the bubble instead |
+| `actions` | `ReactNode` | Under the bubble, after the `Failed` notice: a [CopyButton](CopyButton.md), retry, thumbs up and down |
+| `styleType` | `ChatMessageStyleType` | See above |
+| `color` | `ColorValue` | A `ThemeColor` or any CSS colour. Default `Primary` when `isOwn`, otherwise `Neutral` |
+
+The bubble is at most 80% of the list's width (40em at most); `styles={{ body: { maxWidth } }}`
+changes that.
+
+**Global defaults:** adopts `ConfigProvider`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `avatar` `body` (the column holding author, bubble and actions) `author` `bubble` `meta` (time and status) `actions` (the row under the bubble, with the `Failed` notice)
+
+**Labels:** `sending` `sent` `delivered` `read` (the names screen readers give the status icon), `failed` (the notice under a failed message) and `you` (an own message's sender, for screen readers only). Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ChatMessageLabels`.

package/docs/ChatMessageList.md

@@ -0,0 +1,113 @@
+# ChatMessageList
+
+**When to use:** The scrolling conversation of a chat: a messenger, a support widget, an AI assistant. It opens at the newest message, follows new ones while the user is at the bottom, and loads older ones at the top without moving the view. Fill it with [ChatMessage](ChatMessage.md)s and put a [ChatComposer](ChatComposer.md) under it. For a long list that is not a conversation, use [VirtualList](VirtualList.md).
+
+**Keywords:** messenger, whatsapp, support chat, chatbot, assistant, LLM, history, thread, stick to bottom, autoscroll, infinite scroll, load older, jump to latest, unread
+
+**Import:** `import { ChatMessageList } from '@ahrowe/ui'`  
+**Types:** `import type { ChatMessageListProps, ChatMessageListHandle, ChatMessageListLabels } from '@ahrowe/ui'`
+
+## A whole chat
+
+```tsx
+import { useRef, useState } from 'react';
+import { Avatar, ChatComposer, ChatMessage, ChatMessageList, ChatMessageStatus, Divider } from '@ahrowe/ui';
+import type { ChatMessageListHandle } from '@ahrowe/ui';
+
+function Chat({ me, initial }: ChatProps) {
+  const [messages, setMessages] = useState<Message[]>(initial);
+  const [hasOlder, setHasOlder] = useState(true);
+  const listRef = useRef<ChatMessageListHandle>(null);
+
+  const loadOlder = async () => {
+    const page = await api.messagesBefore(messages[0].id);
+    setMessages((current) => [...page.messages, ...current]);
+    setHasOlder(page.hasMore);
+  };
+
+  const send = (text: string) => {
+    setMessages((current) => [...current, { id: crypto.randomUUID(), authorId: me.id, text, status: ChatMessageStatus.Sending }]);
+    // Sending from further up the history takes the user down to their message.
+    listRef.current?.scrollToBottom();
+  };
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100dvh' }}>
+      <ChatMessageList ref={listRef} style={{ flex: 1 }} onLoadMore={hasOlder ? loadOlder : undefined}>
+        <Divider text='Today' />
+        {messages.map((message, index) => (
+          <ChatMessage
+            key={message.id}
+            isOwn={message.authorId === me.id}
+            isContinued={messages[index - 1]?.authorId === message.authorId}
+            avatar={message.authorId === me.id ? undefined : <Avatar name={message.authorName} />}
+            author={message.authorId === me.id ? undefined : message.authorName}
+            status={message.status}
+          >
+            {message.text}
+          </ChatMessage>
+        ))}
+      </ChatMessageList>
+      <ChatComposer onSend={send} />
+    </div>
+  );
+}
+```
+
+An AI chat is the same with a `Plain` answer that grows as it streams, and the composer's stop
+button while it does:
+
+```tsx
+<ChatMessageList ref={listRef} style={{ flex: 1 }}>
+  {turns.map((turn) =>
+    turn.role === 'user' ? (
+      <ChatMessage key={turn.id} isOwn>{turn.text}</ChatMessage>
+    ) : (
+      <ChatMessage key={turn.id} styleType={ChatMessageStyleType.Plain} actions={<CopyButton value={turn.text} />}>
+        <Markdown>{turn.text}</Markdown>
+      </ChatMessage>
+    ),
+  )}
+</ChatMessageList>
+<ChatComposer onSend={ask} onStop={isStreaming ? stop : undefined} />
+```
+
+## Scrolling
+
+- **Following.** While the user is within 32px of the bottom, anything that makes the content
+  taller keeps the newest message in view: a new message, an answer streaming in, an image
+  loading, the list getting shorter because the composer grew or a phone keyboard opened.
+- **Reading back.** As soon as the user scrolls up, however little, nothing moves under them: new
+  messages arrive below, and a round button appears in the corner that jumps back down and starts
+  following again. It turns `Primary` once a new message has arrived below. Scrolling back to the
+  bottom by hand does the same.
+- **After sending**, call `scrollToBottom()` on the handle, or a user who sent from further up
+  never sees their own message arrive.
+- **Older messages.** With `onLoadMore`, reaching the top calls it and shows a loader there.
+  Prepend what it loads; the message that was at the top stays exactly where it was, at the very
+  top too, where the browser's own scroll anchoring does nothing and Safari has none at all. It is
+  called again while the loaded page still leaves the top in view. If it rejects, it is called
+  again after three seconds if the top is still in view, or whenever the user next scrolls there.
+  Pass `undefined` once there is nothing older.
+
+**Sizing.** The list scrolls itself and fills the height it is given: `flex: 1` in a column, as
+above, or a `height`. A conversation shorter than the list sits at the bottom, by the composer. To
+start at the top instead, as an AI chat often does: `styles={{ content: { marginTop: 0 } }}`.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Messages, oldest first, and anything between them: a `Divider` with a date, a typing indicator |
+| `onLoadMore` | `() => Promise<void>` | Loads older messages when the top comes into view, see above |
+| `ref` | `Ref<ChatMessageListHandle>` | `scrollToBottom()`: back to the newest message, smoothly unless the user prefers reduced motion, and following again |
+
+**Accessibility:** the scrolling element is a `role="log"`, which screen readers announce
+politely as messages are added, named "Messages" (`labels.messages`). It is a tab stop of its own,
+so the history can be scrolled from the keyboard, and `aria-busy` while older messages load.
+
+**Global defaults:** adopts `ConfigProvider`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `viewport` (the scrolling log) `content` (the column of messages inside it) `scrollButton`
+
+**Labels:** `messages` `scrollToBottom`: the text this component renders of its own. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `ChatMessageListLabels`.

package/docs/ConfigProvider.md

@@ -97,6 +97,7 @@ Each entry is a `Partial<...Props>`, so any of that component's props can be def
 - **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `RadioGroup` · `DatePicker` · `OptionPicker` · `OtpInput`
 - **Display:** `Button` · `CopyButton` · `ActionButtons` · `Badge` · `Chip` · `Card` · `SectionHeader` · `Skeleton` · `Loader` · `LoadingOverlay` · `Accordion` · `Divider` · `Timer` · `WeatherIcon` · `Stepper`
 - **Overlays:** `ConfirmModal` · `Modal` · `CommandPalette` · `Popover`
+- **Chat:** `ChatMessage` · `ChatMessageList` · `ChatComposer`
 - **Editors:** `RoomDrawer`, `RoomViewer`
 - **Scheduling:** `Calendar`, for `labels`, `locale`, `weekStartsOn`, `slotMinutes`, `views`, `hiddenDays`, `scrollToHour`, `workingHours` and `showWeekNumbers` only (see below)
 

package/docs/TabHeader.md

@@ -1,18 +1,18 @@
 # TabHeader
 
-**When to use:** A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages. Each tab carries an icon plus an optional title and subtitle.
+**When to use:** A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages. Each tab carries an icon plus an optional title, subtitle and end content such as a badge.
 
-**Keywords:** tabs navigation, tab bar
+**Keywords:** tabs navigation, tab bar, pill, counter
 
 **Import:** `import { TabHeader } from '@ahrowe/ui'`
 
-**Mobile behaviour:** On narrow screens (≤ 640px) only the active tab keeps its title and subtitle; every other tab collapses to just its icon.
+**Mobile behaviour:** On narrow screens (≤ 640px) only the active tab keeps its title and subtitle; every other tab collapses to its icon and `endContent`.
 
 ```tsx
 import { useState } from 'react';
-import { TabHeader } from '@ahrowe/ui';
+import { TabHeader, Badge, ThemeColor } from '@ahrowe/ui';
 import type { TabHeaderTab } from '@ahrowe/ui';
-import { faUser, faBell, faGear } from '@fortawesome/free-solid-svg-icons';
+import { faUser, faBell, faGear, faInbox, faAt } from '@fortawesome/free-solid-svg-icons';
 
 const TABS: TabHeaderTab[] = [
   { id: 'profile', icon: faUser, title: 'Profile', subtitle: 'Your details' },
@@ -32,6 +32,16 @@ function Example() {
   onChange={setTab}
 />
 
+// A count next to the title, still shown when a narrow screen collapses the tab
+<TabHeader
+  tabs={[
+    { id: 'inbox', icon: faInbox, title: 'Inbox', endContent: <Badge count={12} /> },
+    { id: 'mentions', icon: faAt, title: 'Mentions', endContent: <Badge count={3} color={ThemeColor.Error} /> },
+  ]}
+  currentTab={tab}
+  onChange={setTab}
+/>
+
 // Disabled tab — dimmed and not selectable
 <TabHeader
   tabs={[
@@ -57,8 +67,9 @@ function Example() {
 |-------|------|-------------|
 | `id` | `string` | Unique identifier, matched against `currentTab` |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element (always visible, incl. mobile) |
-| `title` | `string` | Optional title next to the icon |
-| `subtitle` | `string` | Optional subtitle beneath the title |
+| `title` | `ReactNode` | Optional title next to the icon |
+| `subtitle` | `ReactNode` | Optional subtitle beneath the title |
+| `endContent` | `ReactNode` | After the labels. Stays visible when a narrow screen collapses the tab, so keep it small: a `Badge`, a dot |
 | `disabled` | `boolean` | Dim the tab and prevent selection |
 
-**Slots:** `root` `tab` `icon` `labels` `title` `subtitle`
+**Slots:** `root` `tab` `icon` `labels` `title` `subtitle` `endContent`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",