@ahrowe/ui 0.48.0 → 0.50.0

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

@@ -6,7 +6,7 @@ export type ActionIconSlots = 'root' | 'icon';
  * A Button with only an icon, sized by that icon, so every Button prop applies except the ones
  * that describe a label or a size.
  */
-export interface ActionIconProps extends Omit<ButtonProps, 'icon' | 'size' | 'children' | 'isLoading' | 'classNames' | 'styles'> {
+export interface ActionIconProps extends Omit<ButtonProps, 'icon' | 'size' | 'children' | 'isLoading' | 'shortcut' | 'classNames' | 'styles'> {
     icon: IconContent;
     classNames?: SlotClassNames<ActionIconSlots>;
     styles?: SlotStyles<ActionIconSlots>;

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

@@ -26,7 +26,7 @@ export declare enum ButtonType {
     Reset = "reset",
     Submit = "submit"
 }
-export type ButtonSlots = 'background' | 'content' | 'loadingContainer' | 'label';
+export type ButtonSlots = 'background' | 'content' | 'loadingContainer' | 'label' | 'shortcut';
 /**
  * `DataProps` supplies the `data-*` index signature, which `ButtonHTMLAttributes` doesn't cover.
  * `type`, `color` and `onClick` below deliberately narrow their inherited counterparts.
@@ -43,6 +43,11 @@ export interface ButtonProps extends DataProps, React.ButtonHTMLAttributes<HTMLB
     onClick?: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void> | void;
     children?: React.ReactNode;
     icon?: IconContent;
+    /**
+     * A shortcut drawn after the label, in `useHotkeys` spelling (`'mod+s'`): `⌘S` on Apple
+     * platforms, `Ctrl+S` elsewhere. Drawn only; bind it with `useHotkeys`.
+     */
+    shortcut?: string;
     isLoading?: boolean;
     disabled?: boolean;
     title?: string;

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/hooks/useHotkeys.d.ts

@@ -18,6 +18,11 @@ export interface UseHotkeysOptions {
      * Default `true`.
      */
     preventDefault?: boolean;
+    /**
+     * Fire again for each repeat while the combo is held. Default `false`, so holding `mod+s` saves
+     * once. Turn it on for keys that step through something, such as arrows or zoom.
+     */
+    repeat?: boolean;
 }
 /**
  * A combo written for the reader: `'mod+shift+k'` reads `⇧⌘K` on an Apple platform and
@@ -30,6 +35,12 @@ export interface UseHotkeysOptions {
  * Resolved from the platform at call time, so a server-rendered page renders the non-Apple form.
  */
 export declare function formatHotkey(combo: string): string;
+/**
+ * A combo as `aria-keyshortcuts` spells it: `'mod+shift+k'` is `Control+Shift+K`, or
+ * `Meta+Shift+K` on an Apple platform. Resolved from the platform like `formatHotkey`, so the two
+ * always name the same keys.
+ */
+export declare function ariaKeyshortcuts(combo: string | undefined): string | undefined;
 /**
  * Keyboard shortcuts, for a whole app or for one element.
  *

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/ActionIcon.md

@@ -38,8 +38,8 @@ import { faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 | `ref` | `Ref<HTMLButtonElement>` | Ref to the button |
 
 Every other Button prop and native `<button>` attribute passes through, except `size`,
-`children` and `isLoading`. The box is the icon plus `4px` on each side; set `width` and `height`
-for a different one.
+`children`, `isLoading` and `shortcut`. The box is the icon plus `4px` on each side; set `width`
+and `height` for a different one.
 
 **Slots:** `root` `icon`
 

package/docs/Button.md

@@ -11,7 +11,7 @@ works with any colour. The colours are the library-wide `ThemeColor`s or any CSS
 [ThemeColor.md](ThemeColor.md).
 
 ```tsx
-import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor } from '@ahrowe/ui';
+import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor, useHotkeys } from '@ahrowe/ui';
 import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 
 // The main action
@@ -52,6 +52,10 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
 // Small
 <Button size={ButtonSize.Small}>Cancel</Button>
 
+// A keyboard shortcut: the button draws it, useHotkeys binds it
+useHotkeys({ 'mod+s': handleSave });
+<Button styleType={ButtonStyleType.Filled} shortcut='mod+s' onClick={handleSave}>Save</Button>
+
 // Press-and-hold: act on press rather than release
 <Button
   icon={faPlus}
@@ -81,6 +85,7 @@ import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-ic
 | `size` | `ButtonSize` | Size variant. `Icon` strips all padding, inherits the surrounding text size, and centres a lone icon — set the width/height yourself |
 | `type` | `ButtonType` | HTML button type |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
+| `shortcut` | `string` | A combo in [useHotkeys](Hooks.md) spelling, e.g. `'mod+s'`. Shown after the label, written for the platform. Binding it is yours, see below |
 | `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks like `disabled` but keeps full colour |
 | `disabled` | `boolean` | Fades the button to half opacity |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
@@ -92,6 +97,17 @@ press-and-hold controls that act on press rather than release), `onContextMenu`,
 takes the `ButtonType` enum, and `onClick` may return a promise. `color` is Button's own prop, not
 the obsolete HTML attribute.
 
+**Shortcuts are drawn, not bound.** `shortcut` writes the combo in a pill after the label,
+`⌘S` on an Apple platform and `Ctrl+S` elsewhere. It also sets `aria-keyshortcuts`, so a screen
+reader announces it apart from the button's name. It is hidden on a touch screen
+(`pointer: coarse`), which usually has no keyboard to press it on.
+
+Listening for it is yours, with `useHotkeys` and the same string, because only your app knows
+when the action is available. A button cannot tell: it would still fire while hidden in an
+inactive tab, behind an open Modal, or twice when the same action has a button in the toolbar and
+another in the footer. Turn the binding off wherever the button is disabled:
+`useHotkeys({ 'mod+s': handleSave }, { enabled: !isSaving })`.
+
 **Theming:** each colour reads the theme variables listed in [ThemeColor.md](ThemeColor.md). The
 `Filled` `Primary` button also paints `--primary-gradient` when the theme sets one. See
 [ThemeProvider.md](ThemeProvider.md).
@@ -112,7 +128,7 @@ sits inside the edge, in `--focus-border-color`, or in the text colour on a `Fil
 ripple is in the text colour too. Every button reserves a `1px` border, so switching style never
 shifts layout or changes its height.
 
-**Slots:** `background` `content` `loadingContainer` `label`
+**Slots:** `background` `content` `loadingContainer` `label` `shortcut`
 
 **Sizing in a flex row:** a Button never shrinks below its own content (`min-width: min-content`),
 so an icon is never cut off by a flexible sibling. A multi-word label still wraps above that floor.

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