@paul-portfolio/react 0.5.0 → 0.6.0

package/README.md

@@ -146,6 +146,126 @@ Renders content that's available to screen readers but hidden visually.
 <VisuallyHidden>Loading</VisuallyHidden>
 ```
 
+## AI / LLM app components
+
+A set of interaction-heavy components for building assistant and chat surfaces.
+All are keyboard-operable and carry an axe test like the rest of the package.
+
+### RichTextEditor
+
+A small rich-text editor on a `contentEditable` region. The toolbar is
+configurable (`bold`, `italic`, `underline`, `h2`, `bulletList`, `orderedList`,
+`code`, `link`), Ctrl/Cmd+B/I/U work from the keyboard, and it emits HTML on
+every edit.
+
+```tsx
+<RichTextEditor
+  label="Prompt"
+  toolbar={["bold", "italic", "code"]}
+  onChange={(html) => setDraft(html)}
+/>
+```
+
+### ChatMessage
+
+A chat bubble aligned and coloured by `role` (`user` | `assistant` | `system`),
+with optional `avatar`, `name`, and `timestamp`. Pass `pending` while a reply is
+streaming to show the typing indicator.
+
+```tsx
+<ChatMessage role="assistant" name="Assistant" timestamp="10:30">
+  Here's the summary you asked for.
+</ChatMessage>
+<ChatMessage role="assistant" pending />
+```
+
+### ChatComposer
+
+An auto-growing prompt field. Enter sends, Shift+Enter inserts a newline, empty
+messages don't send, and the control locks while `busy`.
+
+```tsx
+<ChatComposer label="Message" onSubmit={send} busy={waiting} maxLength={2000} />
+```
+
+### StreamingText
+
+Reveals text a few characters at a time, the way a streamed model reply arrives,
+with a caret and a polite live region. Honours `prefers-reduced-motion` by
+showing the whole string at once.
+
+```tsx
+<StreamingText text={reply} speed={2} interval={30} onDone={scrollToEnd} />
+```
+
+### TypingDots
+
+The three-dot "assistant is typing" indicator. The animation is decorative and
+hidden from assistive tech; the `label` carries the meaning.
+
+```tsx
+<TypingDots label="Assistant is typing" />
+```
+
+### CodeBlock
+
+A read-only code panel with a language label and a copy button that reports
+success to assistive tech. Optional decorative line numbers.
+
+```tsx
+<CodeBlock code={snippet} language="ts" filename="stream.ts" showLineNumbers />
+```
+
+### CommandPalette
+
+A ⌘K command menu. Type to filter (label + `keywords`), arrow keys to move, Enter
+to run, Escape to close, with optional group headings. Follows the
+combobox/listbox pattern with `aria-activedescendant`.
+
+```tsx
+<CommandPalette
+  open={open}
+  onClose={() => setOpen(false)}
+  commands={[{ id: "new", label: "New chat", onSelect: startChat }]}
+/>
+```
+
+### Combobox
+
+An accessible autocomplete — a filtering text input with a listbox popup and
+full keyboard support. Handy for model/tool pickers.
+
+```tsx
+<Combobox label="Model" options={models} value={model} onChange={setModel} />
+```
+
+### Toast
+
+Wrap the app in `ToastProvider` and raise notifications with `useToast()`. Toasts
+stack in a live region (errors announce assertively) and auto-dismiss unless
+`duration` is `0`.
+
+```tsx
+const { toast } = useToast();
+toast({ title: "Saved", description: "Your changes are safe.", variant: "success" });
+```
+
+### TokenUsageMeter
+
+A budget bar for LLM token usage: prompt and completion tokens as two segments of
+a track sized against `maxTokens`, with the used total, percent, and an optional
+cost estimate. Shifts to a warning tone near the budget and an over tone past it.
+
+```tsx
+<TokenUsageMeter
+  label="Context window"
+  promptTokens={3200}
+  completionTokens={1400}
+  maxTokens={8000}
+  costPerMTok={3}
+/>
+```
+
 ### cx
 
 A tiny classname joiner used internally, exported for convenience.

package/dist/ChatComposer.d.ts

@@ -0,0 +1,23 @@
+type ChatComposerProps = {
+    /** Accessible name for the message field. */
+    label: string;
+    /** Visually hide the label; keep it for screen readers. */
+    hideLabel?: boolean;
+    /** Fires with the trimmed message when the user sends. */
+    onSubmit: (message: string) => void;
+    placeholder?: string;
+    /** Disable the field and button, e.g. while a reply is in flight. */
+    busy?: boolean;
+    disabled?: boolean;
+    /** Label for the send button. */
+    submitLabel?: string;
+    maxLength?: number;
+    className?: string;
+};
+/**
+ * A prompt composer for chat/AI surfaces: an auto-growing textarea that sends
+ * on Enter and inserts a newline on Shift+Enter. Empty messages don't send, and
+ * the whole control locks while `busy`.
+ */
+export declare function ChatComposer({ label, hideLabel, onSubmit, placeholder, busy, disabled, submitLabel, maxLength, className, }: ChatComposerProps): import("react").JSX.Element;
+export {};

package/dist/ChatComposer.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useRef, useState, } from 'react';
+import { cx } from './cx';
+const MAX_ROWS_HEIGHT = 200;
+/**
+ * A prompt composer for chat/AI surfaces: an auto-growing textarea that sends
+ * on Enter and inserts a newline on Shift+Enter. Empty messages don't send, and
+ * the whole control locks while `busy`.
+ */
+export function ChatComposer({ label, hideLabel = true, onSubmit, placeholder = 'Send a message…', busy = false, disabled = false, submitLabel = 'Send', maxLength, className, }) {
+    const id = useId();
+    const [value, setValue] = useState('');
+    const textareaRef = useRef(null);
+    const locked = busy || disabled;
+    function grow() {
+        const el = textareaRef.current;
+        if (!el)
+            return;
+        el.style.height = 'auto';
+        el.style.height = `${Math.min(el.scrollHeight, MAX_ROWS_HEIGHT)}px`;
+    }
+    function send() {
+        const message = value.trim();
+        if (!message || locked)
+            return;
+        onSubmit(message);
+        setValue('');
+        const el = textareaRef.current;
+        if (el)
+            el.style.height = 'auto';
+    }
+    function handleSubmit(e) {
+        e.preventDefault();
+        send();
+    }
+    function handleKeyDown(e) {
+        if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            send();
+        }
+    }
+    return (_jsxs("form", { className: cx('chat-composer', className), onSubmit: handleSubmit, children: [_jsx("label", { className: hideLabel ? 'sr-only' : 'chat-composer__label', htmlFor: id, children: label }), _jsxs("div", { className: "chat-composer__row", children: [_jsx("textarea", { ref: textareaRef, id: id, className: "chat-composer__field", rows: 1, value: value, placeholder: placeholder, disabled: locked, maxLength: maxLength, onChange: (e) => {
+                            setValue(e.target.value);
+                            grow();
+                        }, onKeyDown: handleKeyDown }), _jsx("button", { type: "submit", className: "chat-composer__send", disabled: locked || value.trim().length === 0, children: submitLabel })] }), maxLength != null && (_jsxs("span", { className: "chat-composer__count", "aria-live": "polite", children: [value.length, " / ", maxLength] }))] }));
+}

package/dist/ChatMessage.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+export type ChatRole = 'user' | 'assistant' | 'system';
+type ChatMessageProps = {
+    role: ChatRole;
+    /** Display name for the sender. */
+    name?: string;
+    /** Rendered timestamp string (already formatted by the caller). */
+    timestamp?: string;
+    /** Optional avatar node (e.g. an <Avatar />). */
+    avatar?: ReactNode;
+    /** Show a typing indicator instead of content. */
+    pending?: boolean;
+    className?: string;
+    children?: ReactNode;
+};
+/**
+ * A single chat bubble, aligned and coloured by role. Renders as an article so
+ * each turn is a navigable landmark, with the role in its accessible name.
+ * Pass `pending` while an assistant reply is streaming to show TypingDots.
+ */
+export declare function ChatMessage({ role, name, timestamp, avatar, pending, className, children, }: ChatMessageProps): import("react").JSX.Element;
+export {};

package/dist/ChatMessage.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from './cx';
+import { TypingDots } from './TypingDots';
+const ROLE_LABEL = {
+    user: 'You',
+    assistant: 'Assistant',
+    system: 'System',
+};
+/**
+ * A single chat bubble, aligned and coloured by role. Renders as an article so
+ * each turn is a navigable landmark, with the role in its accessible name.
+ * Pass `pending` while an assistant reply is streaming to show TypingDots.
+ */
+export function ChatMessage({ role, name, timestamp, avatar, pending = false, className, children, }) {
+    const roleLabel = ROLE_LABEL[role];
+    return (_jsxs("article", { className: cx('chat-message', `chat-message--${role}`, className), "aria-label": `${roleLabel} message`, children: [avatar && _jsx("div", { className: "chat-message__avatar", children: avatar }), _jsxs("div", { className: "chat-message__main", children: [(name || timestamp) && (_jsxs("div", { className: "chat-message__meta", children: [name && _jsx("span", { className: "chat-message__name", children: name }), timestamp && _jsx("span", { className: "chat-message__time", children: timestamp })] })), _jsx("div", { className: "chat-message__bubble", children: pending ? _jsx(TypingDots, { label: `${roleLabel} is typing` }) : children })] })] }));
+}

package/dist/CodeBlock.d.ts

@@ -0,0 +1,17 @@
+type CodeBlockProps = {
+    code: string;
+    /** Language label shown in the header (display only). */
+    language?: string;
+    /** Optional filename shown alongside the language. */
+    filename?: string;
+    /** Prefix each line with a line number. */
+    showLineNumbers?: boolean;
+    className?: string;
+};
+/**
+ * A read-only code panel with a language label and a copy button that reports
+ * success back to assistive tech. Line numbers are decorative and hidden from
+ * the a11y tree so a screen reader reads the code, not the gutter.
+ */
+export declare function CodeBlock({ code, language, filename, showLineNumbers, className, }: CodeBlockProps): import("react").JSX.Element;
+export {};

package/dist/CodeBlock.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { cx } from './cx';
+/**
+ * A read-only code panel with a language label and a copy button that reports
+ * success back to assistive tech. Line numbers are decorative and hidden from
+ * the a11y tree so a screen reader reads the code, not the gutter.
+ */
+export function CodeBlock({ code, language, filename, showLineNumbers = false, className, }) {
+    const [copied, setCopied] = useState(false);
+    const timer = useRef(null);
+    async function copy() {
+        try {
+            await navigator.clipboard.writeText(code);
+            setCopied(true);
+            if (timer.current)
+                clearTimeout(timer.current);
+            timer.current = setTimeout(() => setCopied(false), 2000);
+        }
+        catch {
+            // Clipboard blocked (permissions/insecure context) — leave state as is.
+        }
+    }
+    const lines = code.split('\n');
+    return (_jsxs("div", { className: cx('code-block', className), children: [_jsxs("div", { className: "code-block__head", children: [_jsxs("span", { className: "code-block__lang", children: [filename && _jsx("span", { className: "code-block__file", children: filename }), language] }), _jsx("button", { type: "button", className: "code-block__copy", "aria-label": copied ? 'Copied' : 'Copy code', onClick: copy, children: copied ? 'Copied' : 'Copy' })] }), _jsx("pre", { className: "code-block__pre", children: _jsx("code", { children: showLineNumbers
+                        ? lines.map((line, i) => (_jsxs("span", { className: "code-block__line", children: [_jsx("span", { className: "code-block__ln", "aria-hidden": "true", children: i + 1 }), _jsx("span", { className: "code-block__code", children: line })] }, i)))
+                        : code }) })] }));
+}

package/dist/Combobox.d.ts

@@ -0,0 +1,22 @@
+export type ComboboxOption = {
+    value: string;
+    label: string;
+};
+type ComboboxProps = {
+    label: string;
+    hideLabel?: boolean;
+    options: ComboboxOption[];
+    /** Controlled selected value. */
+    value?: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    className?: string;
+};
+/**
+ * An accessible autocomplete — a text input that filters a list of options and
+ * commits one on Enter or click. Great for model/tool pickers. Implements the
+ * ARIA combobox pattern with aria-expanded and aria-activedescendant so the
+ * active option is announced while focus stays in the input.
+ */
+export declare function Combobox({ label, hideLabel, options, value, onChange, placeholder, className, }: ComboboxProps): import("react").JSX.Element;
+export {};

package/dist/Combobox.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useState, } from 'react';
+import { cx } from './cx';
+/**
+ * An accessible autocomplete — a text input that filters a list of options and
+ * commits one on Enter or click. Great for model/tool pickers. Implements the
+ * ARIA combobox pattern with aria-expanded and aria-activedescendant so the
+ * active option is announced while focus stays in the input.
+ */
+export function Combobox({ label, hideLabel = false, options, value, onChange, placeholder, className, }) {
+    const baseId = useId();
+    const listId = `${baseId}-list`;
+    const selectedLabel = options.find((o) => o.value === value)?.label ?? '';
+    const [query, setQuery] = useState(selectedLabel);
+    const [open, setOpen] = useState(false);
+    const [active, setActive] = useState(-1);
+    // Reflect an externally-changed value back into the field.
+    useEffect(() => {
+        setQuery(selectedLabel);
+    }, [selectedLabel]);
+    // While closed the field shows the selected label, so don't filter by it.
+    const filtered = useMemo(() => {
+        if (!open)
+            return options;
+        const q = query.trim().toLowerCase();
+        if (!q)
+            return options;
+        return options.filter((o) => o.label.toLowerCase().includes(q));
+    }, [options, query, open]);
+    const optionId = (index) => `${baseId}-opt-${index}`;
+    function commit(option) {
+        if (!option)
+            return;
+        onChange(option.value);
+        setQuery(option.label);
+        setOpen(false);
+        setActive(-1);
+    }
+    function handleKeyDown(e) {
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                if (!open) {
+                    setOpen(true);
+                    return;
+                }
+                setActive((i) => Math.min(i + 1, filtered.length - 1));
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setActive((i) => Math.max(i - 1, 0));
+                break;
+            case 'Enter':
+                if (open && active >= 0) {
+                    e.preventDefault();
+                    commit(filtered[active]);
+                }
+                break;
+            case 'Escape':
+                e.preventDefault();
+                setOpen(false);
+                setActive(-1);
+                break;
+        }
+    }
+    // Close when focus leaves the whole control.
+    function handleBlur(e) {
+        if (!e.currentTarget.contains(e.relatedTarget)) {
+            setOpen(false);
+            setActive(-1);
+        }
+    }
+    return (_jsxs("div", { className: cx('combobox', className), onBlur: handleBlur, children: [_jsx("label", { className: hideLabel ? 'sr-only' : 'combobox__label', htmlFor: baseId, children: label }), _jsx("input", { id: baseId, type: "text", role: "combobox", "aria-expanded": open, "aria-controls": open && filtered.length > 0 ? listId : undefined, "aria-autocomplete": "list", "aria-activedescendant": open && active >= 0 ? optionId(active) : undefined, className: "combobox__input", placeholder: placeholder, value: query, onChange: (e) => {
+                    setQuery(e.target.value);
+                    setOpen(true);
+                    setActive(-1);
+                }, onClick: () => setOpen(true), onFocus: () => setOpen(true), onKeyDown: handleKeyDown }), open && filtered.length > 0 && (_jsx("ul", { id: listId, role: "listbox", "aria-label": label, className: "combobox__list", children: filtered.map((option, index) => (_jsx("li", { id: optionId(index), role: "option", "aria-selected": option.value === value, className: cx('combobox__option', index === active && 'combobox__option--active'), onMouseEnter: () => setActive(index), onMouseDown: (e) => e.preventDefault(), onClick: () => commit(option), children: option.label }, option.value))) }))] }));
+}

package/dist/CommandPalette.d.ts

@@ -0,0 +1,32 @@
+import { type ReactNode } from 'react';
+export type Command = {
+    id: string;
+    label: string;
+    /** Runs when the command is chosen. */
+    onSelect: () => void;
+    /** Extra terms to match against, beyond the label. */
+    keywords?: string[];
+    /** Optional group heading to bucket the command under. */
+    group?: string;
+    /** Decorative leading glyph/icon. */
+    icon?: ReactNode;
+    /** Trailing hint, e.g. a shortcut. */
+    hint?: string;
+};
+type CommandPaletteProps = {
+    open: boolean;
+    onClose: () => void;
+    commands: Command[];
+    placeholder?: string;
+    emptyMessage?: string;
+    /** Accessible name for the dialog. */
+    label?: string;
+    className?: string;
+};
+/**
+ * A ⌘K-style command menu. Type to filter, arrow keys to move, Enter to run,
+ * Escape to close. Follows the combobox/listbox pattern: the input owns
+ * aria-activedescendant so the active option is announced without moving focus.
+ */
+export declare function CommandPalette({ open, onClose, commands, placeholder, emptyMessage, label, className, }: CommandPaletteProps): import("react").ReactPortal | null;
+export {};

package/dist/CommandPalette.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { cx } from './cx';
+function matches(command, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return true;
+    const haystack = [command.label, ...(command.keywords ?? [])].join(' ').toLowerCase();
+    return haystack.includes(q);
+}
+/**
+ * A ⌘K-style command menu. Type to filter, arrow keys to move, Enter to run,
+ * Escape to close. Follows the combobox/listbox pattern: the input owns
+ * aria-activedescendant so the active option is announced without moving focus.
+ */
+export function CommandPalette({ open, onClose, commands, placeholder = 'Type a command…', emptyMessage = 'No commands found', label = 'Command palette', className, }) {
+    const baseId = useId();
+    const listId = `${baseId}-list`;
+    const inputRef = useRef(null);
+    const [query, setQuery] = useState('');
+    const [active, setActive] = useState(0);
+    const filtered = useMemo(() => commands.filter((c) => matches(c, query)), [commands, query]);
+    // Reset and focus each time the palette opens.
+    useEffect(() => {
+        if (!open)
+            return;
+        setQuery('');
+        setActive(0);
+        inputRef.current?.focus();
+    }, [open]);
+    // Keep the active index in range as the filtered set shrinks.
+    useEffect(() => {
+        setActive((i) => Math.min(i, Math.max(0, filtered.length - 1)));
+    }, [filtered.length]);
+    if (!open)
+        return null;
+    const optionId = (index) => `${baseId}-opt-${index}`;
+    function choose(index) {
+        const command = filtered[index];
+        if (!command)
+            return;
+        command.onSelect();
+        onClose();
+    }
+    function handleKeyDown(e) {
+        switch (e.key) {
+            case 'ArrowDown':
+                e.preventDefault();
+                setActive((i) => Math.min(i + 1, filtered.length - 1));
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                setActive((i) => Math.max(i - 1, 0));
+                break;
+            case 'Enter':
+                e.preventDefault();
+                choose(active);
+                break;
+            case 'Escape':
+                e.preventDefault();
+                onClose();
+                break;
+        }
+    }
+    // Preserve command order while grouping under optional headings.
+    const groups = [];
+    filtered.forEach((command, index) => {
+        const last = groups[groups.length - 1];
+        if (last && last.name === command.group) {
+            last.items.push({ command, index });
+        }
+        else {
+            groups.push({ name: command.group, items: [{ command, index }] });
+        }
+    });
+    return createPortal(_jsx("div", { className: "command-palette__backdrop", onMouseDown: onClose, children: _jsxs("div", { role: "dialog", "aria-modal": "true", "aria-label": label, className: cx('command-palette', className), onMouseDown: (e) => e.stopPropagation(), children: [_jsx("input", { ref: inputRef, type: "text", role: "combobox", "aria-expanded": filtered.length > 0, "aria-controls": filtered.length ? listId : undefined, "aria-activedescendant": filtered.length ? optionId(active) : undefined, "aria-autocomplete": "list", "aria-label": label, className: "command-palette__input", placeholder: placeholder, value: query, onChange: (e) => setQuery(e.target.value), onKeyDown: handleKeyDown }), filtered.length === 0 ? (_jsx("p", { className: "command-palette__empty", children: emptyMessage })) : (_jsx("ul", { id: listId, role: "listbox", "aria-label": label, className: "command-palette__list", children: groups.map((group, gi) => (_jsxs("li", { role: "presentation", children: [group.name && (_jsx("p", { className: "command-palette__group", role: "presentation", children: group.name })), _jsx("ul", { role: "presentation", className: "command-palette__group-items", children: group.items.map(({ command, index }) => (_jsxs("li", { id: optionId(index), role: "option", "aria-selected": index === active, className: cx('command-palette__option', index === active && 'command-palette__option--active'), onMouseEnter: () => setActive(index), onMouseDown: (e) => e.preventDefault(), onClick: () => choose(index), children: [command.icon && (_jsx("span", { className: "command-palette__icon", "aria-hidden": "true", children: command.icon })), _jsx("span", { className: "command-palette__label", children: command.label }), command.hint && (_jsx("span", { className: "command-palette__hint", children: command.hint }))] }, command.id))) })] }, group.name ?? gi))) }))] }) }), document.body);
+}

package/dist/RichTextEditor.d.ts

@@ -0,0 +1,27 @@
+/** The formatting controls the toolbar can offer, in render order. */
+export type RichTextControl = 'bold' | 'italic' | 'underline' | 'h2' | 'bulletList' | 'orderedList' | 'code' | 'link';
+type RichTextEditorProps = {
+    /** Accessible name for the editable region. */
+    label: string;
+    /** Visually hide the label while keeping it for screen readers. */
+    hideLabel?: boolean;
+    /** Initial HTML for an uncontrolled editor. */
+    defaultValue?: string;
+    /** Controlled HTML value. Pair with onChange. */
+    value?: string;
+    /** Fires with the editor's HTML whenever the content changes. */
+    onChange?: (html: string) => void;
+    placeholder?: string;
+    /** Which controls to show, and in what order. */
+    toolbar?: RichTextControl[];
+    disabled?: boolean;
+    className?: string;
+};
+/**
+ * A small rich-text editor built on a contentEditable region and the browser's
+ * execCommand formatting. The toolbar is configurable, every button carries an
+ * accessible label, and Ctrl/Cmd+B/I/U work from the keyboard. Emits HTML on
+ * every edit so it drops straight into an AI compose surface.
+ */
+export declare function RichTextEditor({ label, hideLabel, defaultValue, value, onChange, placeholder, toolbar, disabled, className, }: RichTextEditorProps): import("react").JSX.Element;
+export {};

package/dist/RichTextEditor.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, } from 'react';
+import { cx } from './cx';
+const CONTROLS = {
+    bold: { label: 'Bold', command: 'bold', shortcut: 'b', glyph: 'B' },
+    italic: { label: 'Italic', command: 'italic', shortcut: 'i', glyph: 'I' },
+    underline: { label: 'Underline', command: 'underline', shortcut: 'u', glyph: 'U' },
+    h2: { label: 'Heading', command: 'formatBlock', value: 'H2', glyph: 'H2' },
+    bulletList: { label: 'Bullet list', command: 'insertUnorderedList', glyph: '•' },
+    orderedList: { label: 'Numbered list', command: 'insertOrderedList', glyph: '1.' },
+    code: { label: 'Code block', command: 'formatBlock', value: 'PRE', glyph: '</>' },
+    link: { label: 'Link', command: 'createLink', prompt: true, glyph: '🔗' },
+};
+const DEFAULT_TOOLBAR = [
+    'bold',
+    'italic',
+    'underline',
+    'h2',
+    'bulletList',
+    'code',
+    'link',
+];
+const SHORTCUTS = {
+    b: 'bold',
+    i: 'italic',
+    u: 'underline',
+};
+/**
+ * A small rich-text editor built on a contentEditable region and the browser's
+ * execCommand formatting. The toolbar is configurable, every button carries an
+ * accessible label, and Ctrl/Cmd+B/I/U work from the keyboard. Emits HTML on
+ * every edit so it drops straight into an AI compose surface.
+ */
+export function RichTextEditor({ label, hideLabel = false, defaultValue, value, onChange, placeholder, toolbar = DEFAULT_TOOLBAR, disabled = false, className, }) {
+    const id = useId();
+    const editorRef = useRef(null);
+    const controlled = value !== undefined;
+    // Seed the initial HTML once. React never re-renders contentEditable content,
+    // so mutating innerHTML by hand is the supported path here.
+    useEffect(() => {
+        const el = editorRef.current;
+        if (!el)
+            return;
+        const next = controlled ? value : defaultValue;
+        if (next != null && el.innerHTML !== next) {
+            el.innerHTML = next;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [controlled ? value : undefined]);
+    function exec(spec) {
+        const el = editorRef.current;
+        if (!el || disabled)
+            return;
+        el.focus();
+        let commandValue = spec.value;
+        if (spec.prompt) {
+            const url = window.prompt('Link URL');
+            if (!url)
+                return;
+            commandValue = url;
+        }
+        document.execCommand(spec.command, false, commandValue);
+        onChange?.(el.innerHTML);
+    }
+    function handleKeyDown(e) {
+        if (!(e.ctrlKey || e.metaKey))
+            return;
+        const control = SHORTCUTS[e.key.toLowerCase()];
+        if (!control || !toolbar.includes(control))
+            return;
+        e.preventDefault();
+        exec(CONTROLS[control]);
+    }
+    return (_jsxs("div", { className: cx('rich-text', disabled && 'rich-text--disabled', className), children: [_jsx("label", { className: hideLabel ? 'sr-only' : 'rich-text__label', htmlFor: id, children: label }), _jsx("div", { className: "rich-text__toolbar", role: "toolbar", "aria-label": `${label} formatting`, children: toolbar.map((key) => {
+                    const spec = CONTROLS[key];
+                    return (_jsx("button", { type: "button", className: "rich-text__tool", "aria-label": spec.label, title: spec.label, disabled: disabled, 
+                        // Keep the selection while the button takes the click.
+                        onMouseDown: (e) => e.preventDefault(), onClick: () => exec(spec), children: _jsx("span", { "aria-hidden": "true", children: spec.glyph }) }, key));
+                }) }), _jsx("div", { ref: editorRef, id: id, role: "textbox", "aria-multiline": "true", "aria-label": label, "aria-disabled": disabled || undefined, contentEditable: !disabled, suppressContentEditableWarning: true, "data-placeholder": placeholder, className: "rich-text__editable", onInput: (e) => onChange?.(e.currentTarget.innerHTML), onKeyDown: handleKeyDown })] }));
+}

package/dist/StreamingText.d.ts

@@ -0,0 +1,20 @@
+type StreamingTextProps = {
+    /** The full text to reveal. */
+    text: string;
+    /** Characters revealed per tick. */
+    speed?: number;
+    /** Milliseconds between ticks. */
+    interval?: number;
+    /** Show a blinking caret while streaming. */
+    cursor?: boolean;
+    /** Called once when the whole string has been revealed. */
+    onDone?: () => void;
+    className?: string;
+};
+/**
+ * Reveals text a few characters at a time, the way a streamed model response
+ * arrives, with an optional caret. Honours prefers-reduced-motion by showing
+ * the whole string at once, and announces itself through a polite live region.
+ */
+export declare function StreamingText({ text, speed, interval, cursor, onDone, className, }: StreamingTextProps): import("react").JSX.Element;
+export {};

package/dist/StreamingText.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { cx } from './cx';
+function detectReducedMotion() {
+    return (typeof window !== 'undefined' &&
+        typeof window.matchMedia === 'function' &&
+        window.matchMedia('(prefers-reduced-motion: reduce)').matches);
+}
+/**
+ * Reveals text a few characters at a time, the way a streamed model response
+ * arrives, with an optional caret. Honours prefers-reduced-motion by showing
+ * the whole string at once, and announces itself through a polite live region.
+ */
+export function StreamingText({ text, speed = 2, interval = 30, cursor = true, onDone, className, }) {
+    // Read the preference synchronously so a reduced-motion user never sees the
+    // animation start, then keep it live for the rare mid-session change.
+    const [reduced, setReduced] = useState(detectReducedMotion);
+    const [count, setCount] = useState(() => (detectReducedMotion() ? text.length : 0));
+    const onDoneRef = useRef(onDone);
+    onDoneRef.current = onDone;
+    useEffect(() => {
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            return;
+        }
+        const query = window.matchMedia('(prefers-reduced-motion: reduce)');
+        const onChange = (e) => setReduced(e.matches);
+        query.addEventListener('change', onChange);
+        return () => query.removeEventListener('change', onChange);
+    }, []);
+    useEffect(() => {
+        if (reduced) {
+            setCount(text.length);
+            onDoneRef.current?.();
+            return;
+        }
+        setCount(0);
+        let current = 0;
+        const id = setInterval(() => {
+            current = Math.min(current + speed, text.length);
+            setCount(current);
+            if (current >= text.length) {
+                clearInterval(id);
+                onDoneRef.current?.();
+            }
+        }, interval);
+        return () => clearInterval(id);
+    }, [text, speed, interval, reduced]);
+    const streaming = count < text.length;
+    return (_jsxs("span", { role: "status", "aria-live": "polite", className: cx('streaming-text', className), children: [text.slice(0, count), cursor && !reduced && streaming && (_jsx("span", { className: "streaming-text__cursor", "aria-hidden": "true" }))] }));
+}

package/dist/Ticker.d.ts

@@ -1,4 +1,4 @@
-import { type ReactNode } from 'react';
+import { type ReactNode } from "react";
 type TickerProps = {
     /** Accessible name for the strip. Scroll mode renders a labelled region. */
     label: string;
@@ -7,11 +7,11 @@ type TickerProps = {
      * auto-scroll — every item stays reachable. `marquee` is a decorative,
      * aria-hidden CSS loop for pure flavour.
      */
-    mode?: 'scroll' | 'marquee';
+    mode?: "scroll" | "marquee";
     /** Which edge the strip sits on; picks the border side. */
-    edge?: 'top' | 'bottom';
+    edge?: "top" | "bottom";
     /** Which way the ambient motion travels. */
-    direction?: 'left' | 'right';
+    direction?: "left" | "right";
     /** Ambient auto-scroll speed for scroll mode, in px/sec. */
     speed?: number;
     className?: string;

package/dist/Ticker.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
-import { cx } from './cx';
-import { usePrefersReducedMotion } from './usePrefersReducedMotion';
+import { useEffect, useLayoutEffect, useRef, useState, } from "react";
+import { cx } from "./cx";
+import { usePrefersReducedMotion } from "./usePrefersReducedMotion";
 /** How long a touch keeps the strip frozen before the ambient scroll resumes. */
 const TOUCH_RESUME_MS = 4000;
 /**
@@ -11,17 +11,17 @@ const TOUCH_RESUME_MS = 4000;
  * children, so the strip stays content-agnostic.
  */
 export function Ticker(props) {
-    return props.mode === 'marquee' ? (_jsx(MarqueeTicker, { ...props })) : (_jsx(ScrollTicker, { ...props }));
+    return props.mode === "marquee" ? (_jsx(MarqueeTicker, { ...props })) : (_jsx(ScrollTicker, { ...props }));
 }
 function edgeClassFor(edge) {
-    return edge === 'top' ? 'ticker--top' : 'ticker--bottom';
+    return edge === "top" ? "ticker--top" : "ticker--bottom";
 }
 /** Decorative marquee: aria-hidden, CSS-driven, content duplicated for the loop. */
-function MarqueeTicker({ edge = 'top', direction = 'left', className, children, }) {
-    return (_jsx("div", { "aria-hidden": "true", "data-direction": direction, className: cx('ticker', 'ticker--marquee', edgeClassFor(edge), className), children: _jsxs("div", { className: "ticker__track", children: [_jsx("div", { className: "ticker__group", children: children }), _jsx("div", { className: "ticker__group", children: children })] }) }));
+function MarqueeTicker({ edge = "top", direction = "left", className, children, }) {
+    return (_jsx("div", { "aria-hidden": "true", "data-direction": direction, className: cx("ticker", "ticker--marquee", edgeClassFor(edge), className), children: _jsxs("div", { className: "ticker__track", children: [_jsx("div", { className: "ticker__group", children: children }), _jsx("div", { className: "ticker__group", children: children })] }) }));
 }
 /** Accessible scroll container with an ambient JS auto-scroll loop. */
-function ScrollTicker({ label, edge = 'top', direction = 'left', speed = 40, className, children, }) {
+function ScrollTicker({ label, edge = "top", direction = "left", speed = 40, className, children, }) {
     const reduced = usePrefersReducedMotion();
     const scrollerRef = useRef(null);
     const cloneRef = useRef(null);
@@ -32,19 +32,25 @@ function ScrollTicker({ label, edge = 'top', direction = 'left', speed = 40, cla
     useEffect(() => {
         pausedRef.current = paused;
     }, [paused]);
-    // Fallback for browsers without `inert`.
+    // Take the clone out of the tab order, but leave it clickable.
     //
-    // The clone carries `inert` in the markup, which drops its descendants from
-    // the tab order and the accessibility tree together, before first paint. This
-    // effect used to be the only mechanism, and it left a gap: an effect runs
-    // after the DOM exists, so between render and this call the duplicate held
-    // tabbable controls inside an aria-hidden container. Hiding something from
-    // assistive tech while leaving it reachable by keyboard is worse than not
-    // hiding it — the user lands on a control a screen reader insists is absent.
-    useEffect(() => {
-        if ('inert' in HTMLElement.prototype)
-            return;
-        const focusables = cloneRef.current?.querySelectorAll('a[href], button, input, select, textarea, [tabindex]');
+    // The clone used to carry `inert`, which was the right instinct aimed one
+    // notch too broadly: `inert` removes a subtree from the accessibility tree
+    // AND from the pointer. Since the loop wraps at half the scroll width,
+    // roughly half of what is on screen at any moment is the clone, so half the
+    // strip silently ignored clicks.
+    //
+    // What is actually wanted is narrower: hidden from assistive tech
+    // (`aria-hidden` on the element), not tabbable (`tabIndex = -1` here), and
+    // still interactive with a pointer. Both copies render the same children, so
+    // clicking either runs the same handler and the reader cannot tell which one
+    // they hit — which is the point.
+    //
+    // A layout effect rather than a passive one: it runs before the browser
+    // paints, so there is no frame in which the duplicate holds tabbable controls
+    // inside an aria-hidden container, which axe rates serious.
+    useLayoutEffect(() => {
+        const focusables = cloneRef.current?.querySelectorAll("a[href], button, input, select, textarea, [tabindex]");
         focusables?.forEach((el) => {
             el.tabIndex = -1;
         });
@@ -57,7 +63,7 @@ function ScrollTicker({ label, edge = 'top', direction = 'left', speed = 40, cla
         const el = scrollerRef.current;
         if (!el)
             return;
-        const dir = direction === 'left' ? 1 : -1;
+        const dir = direction === "left" ? 1 : -1;
         // Start the rightward strip one copy in, so it has somewhere to scroll back.
         if (dir < 0)
             el.scrollLeft = el.scrollWidth / 2;
@@ -87,10 +93,10 @@ function ScrollTicker({ label, edge = 'top', direction = 'left', speed = 40, cla
             clearTimeout(resumeTimer.current);
         resumeTimer.current = setTimeout(() => setPaused(false), TOUCH_RESUME_MS);
     };
-    const classes = cx('ticker', edgeClassFor(edge), className);
+    const classes = cx("ticker", edgeClassFor(edge), className);
     // Reduced motion: a plain, single-copy scrollable row. No clone, no loop.
     if (reduced) {
         return (_jsx("section", { "aria-label": label, className: classes, children: _jsx("div", { className: "ticker__group", children: children }) }));
     }
-    return (_jsx("section", { ref: scrollerRef, "aria-label": label, "data-direction": direction, className: classes, onMouseEnter: () => setPaused(true), onMouseLeave: () => setPaused(false), onTouchStart: freezeForTouch, children: _jsxs("div", { className: "ticker__track", "data-paused": paused || undefined, children: [_jsx("div", { className: "ticker__group", children: children }), _jsx("div", { ref: cloneRef, "aria-hidden": "true", inert: true, className: "ticker__group", children: children })] }) }));
+    return (_jsx("section", { ref: scrollerRef, "aria-label": label, "data-direction": direction, className: classes, onMouseEnter: () => setPaused(true), onMouseLeave: () => setPaused(false), onTouchStart: freezeForTouch, children: _jsxs("div", { className: "ticker__track", "data-paused": paused || undefined, children: [_jsx("div", { className: "ticker__group", children: children }), _jsx("div", { ref: cloneRef, "aria-hidden": "true", className: "ticker__group", children: children })] }) }));
 }

package/dist/Toast.d.ts

@@ -0,0 +1,25 @@
+import { type ReactNode } from 'react';
+export type ToastVariant = 'default' | 'success' | 'error' | 'warning';
+export type ToastOptions = {
+    title: string;
+    description?: string;
+    variant?: ToastVariant;
+    /** Auto-dismiss delay in ms. Use 0 to keep it until dismissed. */
+    duration?: number;
+};
+type ToastContextValue = {
+    toast: (options: ToastOptions) => number;
+    dismiss: (id: number) => void;
+};
+/**
+ * Wrap an app in ToastProvider and call `useToast().toast(...)` to raise a
+ * notification. Toasts stack in a live region so screen readers announce them —
+ * errors assertively, everything else politely — and auto-dismiss unless
+ * `duration` is 0.
+ */
+export declare function ToastProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Access the toast API. Must be called inside a ToastProvider. */
+export declare function useToast(): ToastContextValue;
+export {};

package/dist/Toast.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
+import { cx } from './cx';
+const ToastContext = createContext(null);
+const DEFAULT_DURATION = 5000;
+/**
+ * Wrap an app in ToastProvider and call `useToast().toast(...)` to raise a
+ * notification. Toasts stack in a live region so screen readers announce them —
+ * errors assertively, everything else politely — and auto-dismiss unless
+ * `duration` is 0.
+ */
+export function ToastProvider({ children }) {
+    const [toasts, setToasts] = useState([]);
+    const nextId = useRef(0);
+    const timers = useRef(new Map());
+    const dismiss = useCallback((id) => {
+        setToasts((list) => list.filter((t) => t.id !== id));
+        const timer = timers.current.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            timers.current.delete(id);
+        }
+    }, []);
+    const toast = useCallback((options) => {
+        const id = nextId.current++;
+        setToasts((list) => [...list, { ...options, id }]);
+        const duration = options.duration ?? DEFAULT_DURATION;
+        if (duration > 0) {
+            timers.current.set(id, setTimeout(() => dismiss(id), duration));
+        }
+        return id;
+    }, [dismiss]);
+    // Clear any pending timers on unmount.
+    useEffect(() => {
+        const map = timers.current;
+        return () => {
+            map.forEach((t) => clearTimeout(t));
+            map.clear();
+        };
+    }, []);
+    return (_jsxs(ToastContext.Provider, { value: { toast, dismiss }, children: [children, typeof document !== 'undefined' &&
+                createPortal(_jsx("div", { className: "toast-region", role: "region", "aria-label": "Notifications", children: toasts.map((t) => (_jsxs("div", { role: t.variant === 'error' ? 'alert' : 'status', "aria-live": t.variant === 'error' ? 'assertive' : 'polite', className: cx('toast', `toast--${t.variant ?? 'default'}`), children: [_jsxs("div", { className: "toast__body", children: [_jsx("p", { className: "toast__title", children: t.title }), t.description && _jsx("p", { className: "toast__description", children: t.description })] }), _jsx("button", { type: "button", className: "toast__dismiss", "aria-label": "Dismiss notification", onClick: () => dismiss(t.id), children: _jsx("span", { "aria-hidden": "true", children: "\u2715" }) })] }, t.id))) }), document.body)] }));
+}
+/** Access the toast API. Must be called inside a ToastProvider. */
+export function useToast() {
+    const context = useContext(ToastContext);
+    if (!context) {
+        throw new Error('useToast must be used within a ToastProvider');
+    }
+    return context;
+}

package/dist/TokenUsageMeter.d.ts

@@ -0,0 +1,21 @@
+type TokenUsageMeterProps = {
+    /** Accessible name for the meter, e.g. "Context window". */
+    label: string;
+    promptTokens: number;
+    completionTokens: number;
+    /** The budget the usage is measured against (e.g. the context window). */
+    maxTokens: number;
+    /** Price per million tokens, in dollars. Shows an estimated cost when set. */
+    costPerMTok?: number;
+    /** Fraction (0–1) of the budget at which the "near limit" tone kicks in. */
+    warnAt?: number;
+    className?: string;
+};
+/**
+ * A budget bar for LLM token usage: prompt and completion tokens as two
+ * segments of a track sized against `maxTokens`, with the used total, percent,
+ * and an optional cost estimate. Exposes progressbar semantics and switches to
+ * a warning/over tone as usage approaches or passes the budget.
+ */
+export declare function TokenUsageMeter({ label, promptTokens, completionTokens, maxTokens, costPerMTok, warnAt, className, }: TokenUsageMeterProps): import("react").JSX.Element;
+export {};

package/dist/TokenUsageMeter.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from './cx';
+const fmt = (n) => n.toLocaleString('en-US');
+/**
+ * A budget bar for LLM token usage: prompt and completion tokens as two
+ * segments of a track sized against `maxTokens`, with the used total, percent,
+ * and an optional cost estimate. Exposes progressbar semantics and switches to
+ * a warning/over tone as usage approaches or passes the budget.
+ */
+export function TokenUsageMeter({ label, promptTokens, completionTokens, maxTokens, costPerMTok, warnAt = 0.9, className, }) {
+    const used = promptTokens + completionTokens;
+    const safeMax = maxTokens > 0 ? maxTokens : 1;
+    const fraction = used / safeMax;
+    const percent = Math.round(fraction * 100);
+    const clamped = Math.min(used, maxTokens);
+    const over = used > maxTokens;
+    const warn = !over && fraction >= warnAt;
+    const promptPct = Math.min((promptTokens / safeMax) * 100, 100);
+    const completionPct = Math.min((completionTokens / safeMax) * 100, 100 - promptPct);
+    const cost = costPerMTok != null ? (used / 1_000_000) * costPerMTok : null;
+    return (_jsxs("div", { className: cx('token-meter', warn && 'token-meter--warn', over && 'token-meter--over', className), children: [_jsxs("div", { className: "token-meter__head", children: [_jsx("span", { className: "token-meter__label", children: label }), _jsxs("span", { className: "token-meter__stat", children: [fmt(used), " / ", fmt(maxTokens), " (", percent, "%)"] })] }), _jsxs("div", { role: "progressbar", "aria-label": label, "aria-valuemin": 0, "aria-valuemax": maxTokens, "aria-valuenow": clamped, "aria-valuetext": `${fmt(used)} of ${fmt(maxTokens)} tokens (${percent}%)`, className: "token-meter__track", children: [_jsx("div", { className: "token-meter__seg token-meter__seg--prompt", style: { width: `${promptPct}%` } }), _jsx("div", { className: "token-meter__seg token-meter__seg--completion", style: { width: `${completionPct}%` } })] }), _jsxs("div", { className: "token-meter__footer", children: [_jsxs("span", { className: "token-meter__legend", children: [_jsx("span", { className: "token-meter__key token-meter__key--prompt", "aria-hidden": "true" }), fmt(promptTokens), " prompt", _jsx("span", { className: "token-meter__key token-meter__key--completion", "aria-hidden": "true" }), fmt(completionTokens), " completion"] }), cost != null && _jsxs("span", { className: "token-meter__cost", children: ["$", cost.toFixed(2)] })] })] }));
+}

package/dist/TypingDots.d.ts

@@ -0,0 +1,12 @@
+type TypingDotsProps = {
+    /** Announced to screen readers; the dots themselves are decorative. */
+    label?: string;
+    className?: string;
+};
+/**
+ * A three-dot "typing" indicator for chat surfaces. The animation is purely
+ * visual and hidden from assistive tech; the `label` carries the meaning and is
+ * exposed through a polite live region.
+ */
+export declare function TypingDots({ label, className }: TypingDotsProps): import("react").JSX.Element;
+export {};

package/dist/TypingDots.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from './cx';
+/**
+ * A three-dot "typing" indicator for chat surfaces. The animation is purely
+ * visual and hidden from assistive tech; the `label` carries the meaning and is
+ * exposed through a polite live region.
+ */
+export function TypingDots({ label = 'Typing…', className }) {
+    return (_jsx("span", { role: "status", "aria-label": label, className: cx('typing-dots', className), children: _jsxs("span", { className: "typing-dots__dots", "aria-hidden": "true", children: [_jsx("span", { className: "typing-dots__dot" }), _jsx("span", { className: "typing-dots__dot" }), _jsx("span", { className: "typing-dots__dot" })] }) }));
+}

package/dist/index.d.ts

@@ -31,6 +31,16 @@ export { GaugeChart, type GaugeTone } from './GaugeChart';
 export { StackedLineChart, type LineSeries } from './StackedLineChart';
 export { WordCloud, type WordCloudDatum } from './WordCloud';
 export * as chartGeometry from './chartGeometry';
+export { RichTextEditor, type RichTextControl } from './RichTextEditor';
+export { ChatMessage, type ChatRole } from './ChatMessage';
+export { ChatComposer } from './ChatComposer';
+export { StreamingText } from './StreamingText';
+export { TypingDots } from './TypingDots';
+export { CodeBlock } from './CodeBlock';
+export { CommandPalette, type Command } from './CommandPalette';
+export { Combobox, type ComboboxOption } from './Combobox';
+export { ToastProvider, useToast, type ToastOptions, type ToastVariant, } from './Toast';
+export { TokenUsageMeter } from './TokenUsageMeter';
 export { VisuallyHidden } from './VisuallyHidden';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 export { cx } from './cx';

package/dist/index.js

@@ -31,6 +31,16 @@ export { GaugeChart } from './GaugeChart';
 export { StackedLineChart } from './StackedLineChart';
 export { WordCloud } from './WordCloud';
 export * as chartGeometry from './chartGeometry';
+export { RichTextEditor } from './RichTextEditor';
+export { ChatMessage } from './ChatMessage';
+export { ChatComposer } from './ChatComposer';
+export { StreamingText } from './StreamingText';
+export { TypingDots } from './TypingDots';
+export { CodeBlock } from './CodeBlock';
+export { CommandPalette } from './CommandPalette';
+export { Combobox } from './Combobox';
+export { ToastProvider, useToast, } from './Toast';
+export { TokenUsageMeter } from './TokenUsageMeter';
 export { VisuallyHidden } from './VisuallyHidden';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 export { cx } from './cx';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paul-portfolio/react",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "React components for the Paul Design System",
   "license": "MIT",
   "repository": {