@openwarelabs/ui 0.4.0 → 0.6.0

package/README.md

@@ -50,11 +50,11 @@ import { Button, Field, Input, Toaster, toast } from "@openwarelabs/ui";
 
 ## Components
 
-83 components, each with a page in the docs.
+93 components, each with a page in the docs.
 
 | Group | Components |
 | --- | --- |
-| Typography | `Text` (each style on the Typography page as a variant: hero to caption, code and kbd; tones, `truncate`, `as`), `Link`, `Kbd`, `Code`, `CodeBlock`, `Snippet` |
+| Typography | `Text` (each style on the Typography page as a variant: hero to caption, code and kbd; tones, `truncate`, `as`), `Link`, `Kbd`, `Code`, `CodeBlock`, `Snippet`, `Prose` (styles rendered Markdown or HTML, at chat or article size) |
 | Actions | `Button` (primary, secondary, ghost, danger; sm, md, lg; `loading`; `shape="pill"`), `buttonClassName()` for links, `ButtonGroup`, `CloseButton`, `CopyButton`, `ToggleButton`, `SegmentedControl`, `ToggleButtonGroup` (one or several on), `Toolbar` + `ToolbarSeparator` (arrow keys across its controls) |
 | Inputs | `Form` (the browser's checks, your own and the server's errors, under each field; `useFormStatus`), `Field`, `Fieldset`, `Input` (start and end content), `Textarea` (`autoGrow`), `NumberField`, `SearchField`, `InputOTP`, `ColorField`, `DateField` and `TimeField` (typed in segments, in the locale's order) |
 | Choices | `Checkbox`, `CheckboxGroup`, `RadioGroup` (plain or cards), `Switch`, `Select`, `Combobox`, `Slider` (one value or a range), `ChoiceCard`, `ListBox` (one or many, on the page) |
@@ -63,11 +63,25 @@ import { Button, Field, Input, Toaster, toast } from "@openwarelabs/ui";
 | Overlays | `Dialog`, `ConfirmDialog`, `Drawer`, `Popover`, `Menu` + `MenuItem`, `CommandPalette` |
 | Navigation | `Tabs`, `Accordion`, `Disclosure`, `Breadcrumbs`, `Pagination`, `Steps`, `NavList` + `NavItem` |
 | Data display | `Table` (sorting, selection), `Stat`, `FileTree`, `EmptyState`, `Tag`, `ColorSwatch`, `Avatar`, `AvatarGroup`, `User` |
+| AI | `PromptInput` (attachments, stop while streaming) + `PromptSuggestion`, `ChatConversation` (follows the newest message, jump to latest), `ChatMessage` + `ChatMessageActions`, `ChatLoader`, `ChatTool` (a tool call with its status, input, output and approval), `ChainOfThought`, `ChatSource` + `ChatSources`, `TextShimmer` |
 | Layout | `Card`, `SettingsRow`, `Stack`, `Separator`, `ScrollShadow`, `VisuallyHidden` |
 | Marketing | `SiteHeader`, `SectionHeading`, `Chip`, `DotGrid` |
 
 Hooks for your own components: `useControllableState`, `useFloating` (top-layer positioning that flips), `usePresence` (keeps a layer mounted while it animates out), `useDismiss`, `useModalDialog`, `useMenuKeyboard`. Every prop is typed and described, so your editor explains it on hover.
 
+## Use with AI
+
+The MCP server, `@openwarelabs/ui-mcp`, gives Claude Code, Codex, Cursor and other AI tools the setup, every component's examples and props, every block's code and the tokens, so they build with the real components:
+
+```sh
+claude mcp add openware-ui -- npx -y @openwarelabs/ui-mcp   # Claude Code
+codex mcp add openware-ui -- npx -y @openwarelabs/ui-mcp    # Codex
+```
+
+Cursor and most other clients take `{ "mcpServers": { "openware-ui": { "command": "npx", "args": ["-y", "@openwarelabs/ui-mcp"] } } }`. [mcp/README.md](mcp/README.md) has every tool and client.
+
+In the docs, every component and block has a **Copy for AI** button: a prompt with its whole reference (examples and props, or a block's two files) to paste into any AI tool. The built docs also have `llms.txt`, `llms-full.txt` and a Markdown copy of every page under `ai/`. `npm run mcp:build` rebuilds the server from the docs.
+
 ## Tokens
 
 Every colour, space, radius, shadow and weight is a CSS variable named `--ow-…` (`var(--ow-surface)`, `var(--ow-radius-container)`), and every text style is a class (`ow-type-section-title`, `ow-type-lead`). `tokens/tokens.json` is the single source; `npm run tokens` regenerates the CSS and `npm run contrast` checks every text and focus pair in both themes.
@@ -90,6 +104,18 @@ The docs' header has a colour picker that does this live, and the Theming page s
 
 **No bundler?** `dist/openware-ui.iife.js` sets `window.OpenwareUI`, reading React from `window.React`. A CDN serves it straight from npm: `https://cdn.jsdelivr.net/npm/@openwarelabs/ui/dist/openware-ui.iife.js`, with `dist/styles.css` beside it.
 
+## Releasing
+
+```sh
+npm run release              # works out the version, checks, tags and pushes
+npm run release -- --dry-run # shows the version and the notes, changes nothing
+npm run release -- minor     # forces patch, minor, major or an exact version
+```
+
+The version comes from the commit subjects since the last release, written as [Conventional Commits](https://www.conventionalcommits.org): `feat:` makes a minor release, `fix:` and `perf:` a patch, and `feat!:` or a `BREAKING CHANGE:` line a major one (a minor one before 1.0). `chore:`, `docs:`, `refactor:`, `test:`, `ci:`, `build:` and `style:` don't release on their own. The command checks that `main` is clean and up to date, runs every check and build, bumps both packages, writes `CHANGELOG.md`, commits, tags `vX.Y.Z` and pushes.
+
+The tag starts `.github/workflows/release.yml`, which runs the checks again, publishes `@openwarelabs/ui` and `@openwarelabs/ui-mcp` to npm with trusted publishing (no token, with provenance), and makes the GitHub release from the changelog. CI checks every pull request's commit subjects against the convention; `npm run commits:check` does the same locally.
+
 ## Rules worth keeping
 
 - One primary button per view. Everything else is secondary or ghost.

package/dist/components/ChainOfThought/ChainOfThought.d.cts

@@ -0,0 +1,44 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+/** Where the reasoning, or one step of it, has got to. */
+export type ChainOfThoughtStatus = "pending" | "running" | "success" | "error";
+export interface ChainOfThoughtStep {
+    /** A stable key for the step, so it keeps its place as steps are added. */
+    id: string;
+    /** The step in words: "Find where invoice dates are formatted". */
+    title: ReactNode;
+    /** Where the step has got to: a hollow ring, a spinner, a check or a cross. */
+    status: ChainOfThoughtStatus;
+    /** More about the step under its title: what it found, a file path, a short list. */
+    detail?: ReactNode;
+    /** A 12px icon in place of the check or the hollow ring, e.g. a search icon. Running and failed steps keep their own mark. */
+    icon?: ReactNode;
+}
+export interface ChainOfThoughtProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The plan, in order, each with its status. */
+    steps?: ChainOfThoughtStep[];
+    /** "running" shows "Thinking…" with a shimmer and keeps it open; anything else is finished.
+     * @default "success" */
+    status?: ChainOfThoughtStatus;
+    /** How long it thought, in milliseconds: "Thought for 12 s". */
+    duration?: number;
+    /** The header's words. Defaults to "Thinking…" while running and "Thought for 12 s" once done. */
+    label?: ReactNode;
+    /** The reasoning itself, as text, shown above the steps. It can grow while it streams in. */
+    children?: ReactNode;
+    /** Whether the reasoning shows. Leave out to let it follow `status`. */
+    expanded?: boolean;
+    /** Whether it starts open. Defaults to open while running and closed once done. */
+    defaultExpanded?: boolean;
+    /** Called with the new state when it opens or closes, by the person or by a change of status. */
+    onExpandedChange?(expanded: boolean): void;
+    /** Folds the reasoning away when `status` turns from "running" to done, unless the person has opened or closed it.
+     * @default true */
+    collapseWhenDone?: boolean;
+    /** The locale for the duration's digits, e.g. "de-CH". Defaults to the browser's. */
+    locale?: string;
+}
+/**
+ * An agent's reasoning and plan: a "Thinking…" header that opens to the reasoning and a list of steps on a thin line,
+ * each with its status. It stays open while the agent works and folds to "Thought for 12 s" when it's done.
+ */
+export declare const ChainOfThought: import("react").ForwardRefExoticComponent<ChainOfThoughtProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ChainOfThought/ChainOfThought.d.ts

@@ -0,0 +1,44 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+/** Where the reasoning, or one step of it, has got to. */
+export type ChainOfThoughtStatus = "pending" | "running" | "success" | "error";
+export interface ChainOfThoughtStep {
+    /** A stable key for the step, so it keeps its place as steps are added. */
+    id: string;
+    /** The step in words: "Find where invoice dates are formatted". */
+    title: ReactNode;
+    /** Where the step has got to: a hollow ring, a spinner, a check or a cross. */
+    status: ChainOfThoughtStatus;
+    /** More about the step under its title: what it found, a file path, a short list. */
+    detail?: ReactNode;
+    /** A 12px icon in place of the check or the hollow ring, e.g. a search icon. Running and failed steps keep their own mark. */
+    icon?: ReactNode;
+}
+export interface ChainOfThoughtProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The plan, in order, each with its status. */
+    steps?: ChainOfThoughtStep[];
+    /** "running" shows "Thinking…" with a shimmer and keeps it open; anything else is finished.
+     * @default "success" */
+    status?: ChainOfThoughtStatus;
+    /** How long it thought, in milliseconds: "Thought for 12 s". */
+    duration?: number;
+    /** The header's words. Defaults to "Thinking…" while running and "Thought for 12 s" once done. */
+    label?: ReactNode;
+    /** The reasoning itself, as text, shown above the steps. It can grow while it streams in. */
+    children?: ReactNode;
+    /** Whether the reasoning shows. Leave out to let it follow `status`. */
+    expanded?: boolean;
+    /** Whether it starts open. Defaults to open while running and closed once done. */
+    defaultExpanded?: boolean;
+    /** Called with the new state when it opens or closes, by the person or by a change of status. */
+    onExpandedChange?(expanded: boolean): void;
+    /** Folds the reasoning away when `status` turns from "running" to done, unless the person has opened or closed it.
+     * @default true */
+    collapseWhenDone?: boolean;
+    /** The locale for the duration's digits, e.g. "de-CH". Defaults to the browser's. */
+    locale?: string;
+}
+/**
+ * An agent's reasoning and plan: a "Thinking…" header that opens to the reasoning and a list of steps on a thin line,
+ * each with its status. It stays open while the agent works and folds to "Thought for 12 s" when it's done.
+ */
+export declare const ChainOfThought: import("react").ForwardRefExoticComponent<ChainOfThoughtProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Chat/ChatConversation.d.cts

@@ -0,0 +1,48 @@
+import { type HTMLAttributes, type MutableRefObject, type ReactNode } from "react";
+export interface ChatConversationProps extends HTMLAttributes<HTMLDivElement> {
+    /** The messages: ChatMessages, a ChatLoader, anything else in the column. */
+    children?: ReactNode;
+    /** Shown in place of the messages while there are none: a greeting, suggestions, an EmptyState. */
+    empty?: ReactNode;
+    /** Docked under the messages and lined up with them, outside the log: usually a PromptInput. It stays in view while
+     * the messages scroll, and Jump to latest floats above it. */
+    footer?: ReactNode;
+    /** Names the conversation for screen readers.
+     * @default "Conversation" */
+    "aria-label"?: string;
+    /** The id of a visible heading that names the conversation, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** `comfortable` keeps the messages in a 720px column in the middle, for reading; `full` lets them use the whole
+     * width, for a narrow side panel.
+     * @default "comfortable" */
+    width?: "comfortable" | "full";
+    /** The words on the button that appears once the reader scrolls up.
+     * @default "Jump to latest" */
+    jumpLabel?: string;
+    /** How that button counts the messages that arrived while the reader was scrolled up.
+     * @default (count) => `${count} new` */
+    formatNewCount?(count: number): string;
+}
+export interface ChatConversationHandle {
+    /** Scrolls to the newest message and follows new content again: smoothly, or at once under reduced motion. Call it
+     * when the person sends a message, so they see their own words and the answer. */
+    scrollToBottom(options?: {
+        behavior?: ScrollBehavior;
+    }): void;
+}
+/** What messages inside a conversation need from it. */
+interface ChatConversationContextValue {
+    /** True once the first messages have painted: messages that mount after that animate in. */
+    ready: MutableRefObject<boolean>;
+    /** A message mounted; it counts as new while the reader is scrolled up. Returns the cleanup for when it goes. */
+    register(id: string): () => void;
+}
+/** @internal */
+export declare const ChatConversationContext: import("react").Context<ChatConversationContextValue | null>;
+/**
+ * The scrolling column of a chat. It follows the newest content while the reader is at the bottom (new messages, an
+ * answer that's still streaming), stops as soon as they scroll up to read, and offers a "Jump to latest" button to
+ * come back. It's a polite live region (role="log"), so screen readers hear messages as they're added.
+ */
+export declare const ChatConversation: import("react").ForwardRefExoticComponent<ChatConversationProps & import("react").RefAttributes<ChatConversationHandle>>;
+export {};

package/dist/components/Chat/ChatConversation.d.ts

@@ -0,0 +1,48 @@
+import { type HTMLAttributes, type MutableRefObject, type ReactNode } from "react";
+export interface ChatConversationProps extends HTMLAttributes<HTMLDivElement> {
+    /** The messages: ChatMessages, a ChatLoader, anything else in the column. */
+    children?: ReactNode;
+    /** Shown in place of the messages while there are none: a greeting, suggestions, an EmptyState. */
+    empty?: ReactNode;
+    /** Docked under the messages and lined up with them, outside the log: usually a PromptInput. It stays in view while
+     * the messages scroll, and Jump to latest floats above it. */
+    footer?: ReactNode;
+    /** Names the conversation for screen readers.
+     * @default "Conversation" */
+    "aria-label"?: string;
+    /** The id of a visible heading that names the conversation, in place of aria-label. */
+    "aria-labelledby"?: string;
+    /** `comfortable` keeps the messages in a 720px column in the middle, for reading; `full` lets them use the whole
+     * width, for a narrow side panel.
+     * @default "comfortable" */
+    width?: "comfortable" | "full";
+    /** The words on the button that appears once the reader scrolls up.
+     * @default "Jump to latest" */
+    jumpLabel?: string;
+    /** How that button counts the messages that arrived while the reader was scrolled up.
+     * @default (count) => `${count} new` */
+    formatNewCount?(count: number): string;
+}
+export interface ChatConversationHandle {
+    /** Scrolls to the newest message and follows new content again: smoothly, or at once under reduced motion. Call it
+     * when the person sends a message, so they see their own words and the answer. */
+    scrollToBottom(options?: {
+        behavior?: ScrollBehavior;
+    }): void;
+}
+/** What messages inside a conversation need from it. */
+interface ChatConversationContextValue {
+    /** True once the first messages have painted: messages that mount after that animate in. */
+    ready: MutableRefObject<boolean>;
+    /** A message mounted; it counts as new while the reader is scrolled up. Returns the cleanup for when it goes. */
+    register(id: string): () => void;
+}
+/** @internal */
+export declare const ChatConversationContext: import("react").Context<ChatConversationContextValue | null>;
+/**
+ * The scrolling column of a chat. It follows the newest content while the reader is at the bottom (new messages, an
+ * answer that's still streaming), stops as soon as they scroll up to read, and offers a "Jump to latest" button to
+ * come back. It's a polite live region (role="log"), so screen readers hear messages as they're added.
+ */
+export declare const ChatConversation: import("react").ForwardRefExoticComponent<ChatConversationProps & import("react").RefAttributes<ChatConversationHandle>>;
+export {};

package/dist/components/Chat/ChatLoader.d.cts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+export interface ChatLoaderProps {
+    /** Words in place of the dots, with a shimmer across them: "Thinking…", "Reading the codebase…". */
+    label?: ReactNode;
+    /** Just the dots or the label, without a message's avatar and spacing: for inside a message, a step or a status bar.
+     * @default false */
+    inline?: boolean;
+    /** The agent's name above, as on its messages: "Acme agent". */
+    name?: ReactNode;
+    /** The agent's bot tile by default; any node in its place, or null for none. */
+    avatar?: ReactNode;
+    /** What screen readers hear while the dots show. With a `label`, they hear the label.
+     * @default "Working…" */
+    srLabel?: string;
+    className?: string;
+}
+/**
+ * The agent is working and nothing has arrived yet: three dots that pulse in turn, or a shimmering label such as
+ * "Thinking…". It sits in the conversation like the agent's next message, so the answer takes its place without a jump.
+ */
+export declare function ChatLoader({ label, inline, name, avatar, srLabel, className }: ChatLoaderProps): import("react").JSX.Element;

package/dist/components/Chat/ChatLoader.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+export interface ChatLoaderProps {
+    /** Words in place of the dots, with a shimmer across them: "Thinking…", "Reading the codebase…". */
+    label?: ReactNode;
+    /** Just the dots or the label, without a message's avatar and spacing: for inside a message, a step or a status bar.
+     * @default false */
+    inline?: boolean;
+    /** The agent's name above, as on its messages: "Acme agent". */
+    name?: ReactNode;
+    /** The agent's bot tile by default; any node in its place, or null for none. */
+    avatar?: ReactNode;
+    /** What screen readers hear while the dots show. With a `label`, they hear the label.
+     * @default "Working…" */
+    srLabel?: string;
+    className?: string;
+}
+/**
+ * The agent is working and nothing has arrived yet: three dots that pulse in turn, or a shimmering label such as
+ * "Thinking…". It sits in the conversation like the agent's next message, so the answer takes its place without a jump.
+ */
+export declare function ChatLoader({ label, inline, name, avatar, srLabel, className }: ChatLoaderProps): import("react").JSX.Element;

package/dist/components/Chat/ChatMessage.d.cts

@@ -0,0 +1,93 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface ChatAgentAvatarProps {
+    /** sm 24px, md 28px beside a message, lg 36px in a page or panel header: the sizes of Avatar.
+     * @default "md" */
+    size?: "sm" | "md" | "lg";
+    /** Give it when the avatar stands alone; beside the agent's name, leave it out and it's hidden from screen readers. */
+    label?: string;
+    className?: string;
+}
+/**
+ * The agent's avatar: a bot icon on a tinted circle, in the sizes of Avatar. Messages and the loader show it by
+ * default; use it wherever else the agent appears, such as a chat's header.
+ */
+export declare function ChatAgentAvatar({ size, label, className }: ChatAgentAvatarProps): import("react").JSX.Element;
+/**
+ * Whether this message or loader should animate in: only when it arrives in a conversation that's already showing,
+ * not for the history it opens with.
+ * @internal
+ */
+export declare function useChatEntrance(): boolean;
+export type ChatMessageFrom = "user" | "assistant" | "system";
+export type ChatMessageStatus = "streaming" | "done" | "error";
+export interface ChatMessageProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** Who it's from. `user`: the person, in a bubble on the right. `assistant`: the agent, full width beside its
+     * avatar. `system`: a muted line in the middle, between hairlines, for things that happened ("Maya changed the
+     * model to Claude Sonnet"). */
+    from: ChatMessageFrom;
+    /** The message. A person's plain text keeps its line breaks; give an agent's formatted answer as Prose, and put
+     * paragraphs in Text so blocks sit 12px apart. */
+    children?: ReactNode;
+    /** Shown above the message: "Acme agent", "Maya Chen". Left out, screen readers hear "You" or "Agent" instead. */
+    name?: ReactNode;
+    /** The agent's bot tile by default; any node (an Avatar) in its place, or null for none. A person's message shows one
+     * only when you give it. */
+    avatar?: ReactNode;
+    /** When it was sent, as a Date or an ISO string. It shows as a short local time, with the full date on hover. */
+    time?: Date | string;
+    /** The locale for the time, such as "en-GB". Defaults to the browser's. */
+    locale?: string;
+    /** `streaming` while the text is still arriving: a soft caret blinks after it and the message is aria-busy.
+     * `error` shows a line saying what went wrong, with Retry when you pass `onRetry`.
+     * @default "done" */
+    status?: ChatMessageStatus;
+    /** What went wrong, for `status="error"`.
+     * @default "The answer didn't finish." for the agent, "Couldn't send this message." for a person */
+    error?: ReactNode;
+    /** Shows a Retry button on the error line. */
+    onRetry?(): void;
+    /** The Retry button's words, for another language.
+     * @default "Retry" */
+    retryLabel?: string;
+    /** Actions under the message, usually a ChatMessageActions. They wait until the message has finished streaming. */
+    actions?: ReactNode;
+    /** `hover` shows the actions while the message is hovered or has focus, and always on touch screens. `always` keeps
+     * them in view, for the latest answer.
+     * @default "hover" */
+    showActions?: "hover" | "always";
+}
+/**
+ * One message in a conversation: the person's in a bubble on the right, the agent's across the full width with its
+ * avatar, name and time, or a system line in the middle. It shows a caret while the answer streams, an error with
+ * Retry when it fails, and its actions on hover.
+ */
+export declare const ChatMessage: import("react").ForwardRefExoticComponent<ChatMessageProps & import("react").RefAttributes<HTMLElement>>;
+export type ChatRating = "up" | "down";
+export interface ChatMessageActionsProps {
+    /** The message as plain text. Shows Copy, which copies it and says "Copied" for two seconds. */
+    copyText?: string;
+    /** Shows Edit, for the person's own messages. */
+    onEdit?(): void;
+    /** Shows Retry, to ask for the answer again. */
+    onRetry?(): void;
+    /** Shows Good response and Bad response. Called with the one pressed, or null when the pressed one is pressed again. */
+    onRate?(rating: ChatRating | null): void;
+    /** Which rating is pressed, when you keep it yourself. */
+    rating?: ChatRating | null;
+    /** The starting rating when uncontrolled.
+     * @default null */
+    defaultRating?: ChatRating | null;
+    /** More actions after these: ghost, sm, icon-only Buttons, each in a Tooltip with its aria-label. */
+    children?: ReactNode;
+    /** The buttons' words, for another language. */
+    labels?: Partial<Record<"copy" | "copied" | "edit" | "retry" | "good" | "bad", string>>;
+    /** Names the toolbar for screen readers.
+     * @default "Message actions" */
+    "aria-label"?: string;
+    className?: string;
+}
+/**
+ * The row of small actions under a message: Copy, Edit, Retry, and Good or Bad response. Only the ones you give a
+ * callback (or `copyText`) appear. It's a toolbar: one tab stop, with the arrow keys moving between the buttons.
+ */
+export declare function ChatMessageActions({ copyText: text, onEdit, onRetry, onRate, rating, defaultRating, children, labels, "aria-label": ariaLabel, className, }: ChatMessageActionsProps): import("react").JSX.Element;

package/dist/components/Chat/ChatMessage.d.ts

@@ -0,0 +1,93 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface ChatAgentAvatarProps {
+    /** sm 24px, md 28px beside a message, lg 36px in a page or panel header: the sizes of Avatar.
+     * @default "md" */
+    size?: "sm" | "md" | "lg";
+    /** Give it when the avatar stands alone; beside the agent's name, leave it out and it's hidden from screen readers. */
+    label?: string;
+    className?: string;
+}
+/**
+ * The agent's avatar: a bot icon on a tinted circle, in the sizes of Avatar. Messages and the loader show it by
+ * default; use it wherever else the agent appears, such as a chat's header.
+ */
+export declare function ChatAgentAvatar({ size, label, className }: ChatAgentAvatarProps): import("react").JSX.Element;
+/**
+ * Whether this message or loader should animate in: only when it arrives in a conversation that's already showing,
+ * not for the history it opens with.
+ * @internal
+ */
+export declare function useChatEntrance(): boolean;
+export type ChatMessageFrom = "user" | "assistant" | "system";
+export type ChatMessageStatus = "streaming" | "done" | "error";
+export interface ChatMessageProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** Who it's from. `user`: the person, in a bubble on the right. `assistant`: the agent, full width beside its
+     * avatar. `system`: a muted line in the middle, between hairlines, for things that happened ("Maya changed the
+     * model to Claude Sonnet"). */
+    from: ChatMessageFrom;
+    /** The message. A person's plain text keeps its line breaks; give an agent's formatted answer as Prose, and put
+     * paragraphs in Text so blocks sit 12px apart. */
+    children?: ReactNode;
+    /** Shown above the message: "Acme agent", "Maya Chen". Left out, screen readers hear "You" or "Agent" instead. */
+    name?: ReactNode;
+    /** The agent's bot tile by default; any node (an Avatar) in its place, or null for none. A person's message shows one
+     * only when you give it. */
+    avatar?: ReactNode;
+    /** When it was sent, as a Date or an ISO string. It shows as a short local time, with the full date on hover. */
+    time?: Date | string;
+    /** The locale for the time, such as "en-GB". Defaults to the browser's. */
+    locale?: string;
+    /** `streaming` while the text is still arriving: a soft caret blinks after it and the message is aria-busy.
+     * `error` shows a line saying what went wrong, with Retry when you pass `onRetry`.
+     * @default "done" */
+    status?: ChatMessageStatus;
+    /** What went wrong, for `status="error"`.
+     * @default "The answer didn't finish." for the agent, "Couldn't send this message." for a person */
+    error?: ReactNode;
+    /** Shows a Retry button on the error line. */
+    onRetry?(): void;
+    /** The Retry button's words, for another language.
+     * @default "Retry" */
+    retryLabel?: string;
+    /** Actions under the message, usually a ChatMessageActions. They wait until the message has finished streaming. */
+    actions?: ReactNode;
+    /** `hover` shows the actions while the message is hovered or has focus, and always on touch screens. `always` keeps
+     * them in view, for the latest answer.
+     * @default "hover" */
+    showActions?: "hover" | "always";
+}
+/**
+ * One message in a conversation: the person's in a bubble on the right, the agent's across the full width with its
+ * avatar, name and time, or a system line in the middle. It shows a caret while the answer streams, an error with
+ * Retry when it fails, and its actions on hover.
+ */
+export declare const ChatMessage: import("react").ForwardRefExoticComponent<ChatMessageProps & import("react").RefAttributes<HTMLElement>>;
+export type ChatRating = "up" | "down";
+export interface ChatMessageActionsProps {
+    /** The message as plain text. Shows Copy, which copies it and says "Copied" for two seconds. */
+    copyText?: string;
+    /** Shows Edit, for the person's own messages. */
+    onEdit?(): void;
+    /** Shows Retry, to ask for the answer again. */
+    onRetry?(): void;
+    /** Shows Good response and Bad response. Called with the one pressed, or null when the pressed one is pressed again. */
+    onRate?(rating: ChatRating | null): void;
+    /** Which rating is pressed, when you keep it yourself. */
+    rating?: ChatRating | null;
+    /** The starting rating when uncontrolled.
+     * @default null */
+    defaultRating?: ChatRating | null;
+    /** More actions after these: ghost, sm, icon-only Buttons, each in a Tooltip with its aria-label. */
+    children?: ReactNode;
+    /** The buttons' words, for another language. */
+    labels?: Partial<Record<"copy" | "copied" | "edit" | "retry" | "good" | "bad", string>>;
+    /** Names the toolbar for screen readers.
+     * @default "Message actions" */
+    "aria-label"?: string;
+    className?: string;
+}
+/**
+ * The row of small actions under a message: Copy, Edit, Retry, and Good or Bad response. Only the ones you give a
+ * callback (or `copyText`) appear. It's a toolbar: one tab stop, with the arrow keys moving between the buttons.
+ */
+export declare function ChatMessageActions({ copyText: text, onEdit, onRetry, onRate, rating, defaultRating, children, labels, "aria-label": ariaLabel, className, }: ChatMessageActionsProps): import("react").JSX.Element;

package/dist/components/ChatSource/ChatSource.d.cts

@@ -0,0 +1,58 @@
+import { type HTMLAttributes, type MouseEvent, type ReactNode } from "react";
+/** One source an answer drew on: a file, a pull request, a web page. ChatSource and ChatSources both take it. */
+export interface ChatSourceItem {
+    /** What it is: a function, a pull request's title, a page's title. */
+    title: ReactNode;
+    /** Where it is, in one line: "src/billing/invoice.ts · lines 40–72", "Pull request #482", "docs.stripe.com". */
+    source?: ReactNode;
+    /** A few lines from it, in the preview. ChatSources leaves it out. */
+    snippet?: ReactNode;
+    /** Where it opens. With it the citation is a link; without, a button. */
+    href?: string;
+    /** Opens `href` in a new tab, for sources outside your app.
+     * @default false */
+    external?: boolean;
+    /** A 15px icon for the kind of source, beside its title. */
+    icon?: ReactNode;
+    /** Its number, shown in the citation chip and on its card: [1], [2]. */
+    index?: number;
+}
+export interface ChatSourceProps extends ChatSourceItem {
+    /** A short name for the chip when there's no `index`: "invoice.ts", "#482". */
+    label?: string;
+    /** How a string `snippet` shows: `text` as a quote, `code` in the mono face with its line breaks kept.
+     * @default "text" */
+    snippetFormat?: "text" | "code";
+    /** The words of the preview's link to `href`.
+     * @default "Open" */
+    openLabel?: string;
+    /** Called when the chip is pressed, e.g. to show the source in a side panel. On touch, the first press opens the preview instead. */
+    onClick?(event: MouseEvent<HTMLElement>): void;
+    /** Names the chip for screen readers. Defaults to "Source 1", or the label. */
+    "aria-label"?: string;
+    /** Classes for the chip's wrapper, which also holds the preview. */
+    className?: string;
+}
+/**
+ * An inline citation in an answer: a small numbered chip that previews its source on hover, keyboard focus, or a tap,
+ * in a card above the page. The chip is a link to the source when it has an `href`; the preview describes it to screen
+ * readers without taking focus.
+ */
+export declare const ChatSource: import("react").ForwardRefExoticComponent<ChatSourceProps & import("react").RefAttributes<HTMLElement>>;
+export interface ChatSourcesProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The sources, in the order the answer cites them. An `id` keeps each one's place as the list changes. */
+    sources: Array<ChatSourceItem & {
+        id?: string;
+    }>;
+    /** The toggle's words. Defaults to "3 sources". */
+    label?: ReactNode;
+    /** Whether the list shows. */
+    expanded?: boolean;
+    /** Whether the list starts open.
+     * @default false */
+    defaultExpanded?: boolean;
+    /** Called with the new state when the person opens or closes the list. */
+    onExpandedChange?(expanded: boolean): void;
+}
+/** The sources under an answer: a "3 sources" toggle that opens to a card for each, linking to it when it has an `href`. */
+export declare const ChatSources: import("react").ForwardRefExoticComponent<ChatSourcesProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/ChatSource/ChatSource.d.ts

@@ -0,0 +1,58 @@
+import { type HTMLAttributes, type MouseEvent, type ReactNode } from "react";
+/** One source an answer drew on: a file, a pull request, a web page. ChatSource and ChatSources both take it. */
+export interface ChatSourceItem {
+    /** What it is: a function, a pull request's title, a page's title. */
+    title: ReactNode;
+    /** Where it is, in one line: "src/billing/invoice.ts · lines 40–72", "Pull request #482", "docs.stripe.com". */
+    source?: ReactNode;
+    /** A few lines from it, in the preview. ChatSources leaves it out. */
+    snippet?: ReactNode;
+    /** Where it opens. With it the citation is a link; without, a button. */
+    href?: string;
+    /** Opens `href` in a new tab, for sources outside your app.
+     * @default false */
+    external?: boolean;
+    /** A 15px icon for the kind of source, beside its title. */
+    icon?: ReactNode;
+    /** Its number, shown in the citation chip and on its card: [1], [2]. */
+    index?: number;
+}
+export interface ChatSourceProps extends ChatSourceItem {
+    /** A short name for the chip when there's no `index`: "invoice.ts", "#482". */
+    label?: string;
+    /** How a string `snippet` shows: `text` as a quote, `code` in the mono face with its line breaks kept.
+     * @default "text" */
+    snippetFormat?: "text" | "code";
+    /** The words of the preview's link to `href`.
+     * @default "Open" */
+    openLabel?: string;
+    /** Called when the chip is pressed, e.g. to show the source in a side panel. On touch, the first press opens the preview instead. */
+    onClick?(event: MouseEvent<HTMLElement>): void;
+    /** Names the chip for screen readers. Defaults to "Source 1", or the label. */
+    "aria-label"?: string;
+    /** Classes for the chip's wrapper, which also holds the preview. */
+    className?: string;
+}
+/**
+ * An inline citation in an answer: a small numbered chip that previews its source on hover, keyboard focus, or a tap,
+ * in a card above the page. The chip is a link to the source when it has an `href`; the preview describes it to screen
+ * readers without taking focus.
+ */
+export declare const ChatSource: import("react").ForwardRefExoticComponent<ChatSourceProps & import("react").RefAttributes<HTMLElement>>;
+export interface ChatSourcesProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** The sources, in the order the answer cites them. An `id` keeps each one's place as the list changes. */
+    sources: Array<ChatSourceItem & {
+        id?: string;
+    }>;
+    /** The toggle's words. Defaults to "3 sources". */
+    label?: ReactNode;
+    /** Whether the list shows. */
+    expanded?: boolean;
+    /** Whether the list starts open.
+     * @default false */
+    defaultExpanded?: boolean;
+    /** Called with the new state when the person opens or closes the list. */
+    onExpandedChange?(expanded: boolean): void;
+}
+/** The sources under an answer: a "3 sources" toggle that opens to a card for each, linking to it when it has an `href`. */
+export declare const ChatSources: import("react").ForwardRefExoticComponent<ChatSourcesProps & import("react").RefAttributes<HTMLDivElement>>;