@ciridae/ui 0.16.1 → 1.0.1

package/dist/components/chart.js

@@ -0,0 +1,116 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CartesianGrid, Line, LineChart, ResponsiveContainer, Tooltip, XAxis, YAxis, } from "recharts";
+import { css, cx } from "#primitives/css";
+import { useCiridaeLocale } from "./locale.js";
+const seriesColorCount = 5;
+// Recharts axes default to 500; keep series above them and below the hover cursor at 1100.
+const seriesLineZIndex = 600;
+// Series colors are custom properties so recharts' SVG attributes can use theme tokens.
+const frame = css({
+    display: "grid",
+    gap: "layout.controlGap",
+    minWidth: "0",
+    "--series-0": "token(colors.accent.blue)",
+    "--series-1": "token(colors.accent.green)",
+    "--series-2": "token(colors.accent.yellow)",
+    "--series-3": "token(colors.accent.bronze)",
+    "--series-4": "token(colors.accent.red)",
+    "--chart-grid": "token(colors.border.subtle)",
+    "--chart-muted": "token(colors.fg.muted)",
+    "& .recharts-cartesian-axis-tick-value": {
+        fill: "fg.muted",
+        fontFamily: "numeric",
+        fontSize: "caption",
+    },
+    "& .recharts-surface": { overflow: "visible" },
+});
+const tooltip = css({
+    display: "grid",
+    gap: "control.trackInset",
+    padding: "panel.compact",
+    border: "1px solid token(colors.border.control)",
+    borderRadius: "action",
+    background: "bg.card",
+    boxShadow: "card",
+    fontSize: "caption",
+});
+const tooltipRow = css({
+    display: "flex",
+    alignItems: "center",
+    gap: "control.iconGap",
+    whiteSpace: "nowrap",
+    "& > [data-value]": {
+        marginInlineStart: "auto",
+        paddingInlineStart: "layout.contentGap",
+        fontFamily: "numeric",
+    },
+});
+const legend = css({
+    display: "flex",
+    flexWrap: "wrap",
+    gap: "layout.controlGap",
+    color: "fg.muted",
+    fontSize: "caption",
+});
+const legendItem = css({
+    display: "inline-flex",
+    alignItems: "center",
+    gap: "control.iconGap",
+    minWidth: "0",
+    maxWidth: "100%",
+    "& > span:last-child": {
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        whiteSpace: "nowrap",
+        lineHeight: "compact",
+    },
+});
+const swatch = css({
+    width: "indicator.swatch",
+    height: "indicator.swatch",
+    flexShrink: "0",
+    borderRadius: "round",
+});
+const seriesColor = (index) => `var(--series-${index % seriesColorCount})`;
+// Positional keys: a label such as a pod name may hold dots, which recharts reads as a path.
+const seriesKey = (index) => `series${index}`;
+/**
+ * Lines over a fixed time window. Samples from different series are joined on their timestamp, so
+ * a series missing a sample leaves a gap rather than a line drawn through it.
+ */
+export function TimeSeriesChart({ series, start, end, formatValue, formatTimestamp, height = 220, allowDecimals = true, className, ...props }) {
+    const rows = chartRows(series);
+    const { formatDateTime, formatTime } = useCiridaeLocale();
+    const spansDays = end - start > 24 * 60 * 60;
+    const formatTick = (unixSeconds) => spansDays
+        ? formatDateTime(unixSeconds * 1000, {
+            month: "short",
+            day: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+        })
+        : formatTime(unixSeconds * 1000, { hour: "2-digit", minute: "2-digit" });
+    return (_jsxs("div", { ...props, className: cx(frame, className), "data-ciridae-ui": "", children: [_jsx(ResponsiveContainer, { width: "100%", height: height, children: _jsxs(LineChart, { data: rows, margin: { top: 4, right: 4, bottom: 0, left: 0 }, children: [_jsx(CartesianGrid, { stroke: "var(--chart-grid)", vertical: false }), _jsx(XAxis, { dataKey: "time", type: "number", domain: [start, end], scale: "time", tickFormatter: formatTimestamp ?? formatTick, stroke: "var(--chart-grid)", tickLine: false, minTickGap: 48 }), _jsx(YAxis, { allowDecimals: allowDecimals, tickFormatter: formatValue, stroke: "var(--chart-grid)", tickLine: false, axisLine: false, width: "auto" }), _jsx(Tooltip, { cursor: { stroke: "var(--chart-muted)", strokeDasharray: "3 3" }, isAnimationActive: false, content: ({ active, label, payload }) => active && payload && payload.length > 0 ? (_jsxs("div", { className: tooltip, children: [_jsx("span", { children: formatTimestamp
+                                            ? formatTimestamp(Number(label))
+                                            : formatDateTime(Number(label) * 1000, {
+                                                month: "short",
+                                                day: "numeric",
+                                                hour: "2-digit",
+                                                minute: "2-digit",
+                                                second: "2-digit",
+                                            }) }), payload.map((item) => {
+                                        const index = Number(String(item.dataKey).replace("series", ""));
+                                        return (_jsxs("span", { className: tooltipRow, children: [_jsx("span", { className: swatch, style: { background: seriesColor(index) } }), _jsx("span", { children: series[index]?.label }), _jsx("span", { "data-value": "", children: formatValue(Number(item.value)) })] }, String(item.dataKey)));
+                                    })] })) : null }), series.map((item, index) => (_jsx(Line, { dataKey: seriesKey(index), name: item.label, stroke: seriesColor(index), strokeWidth: 1.5, zIndex: seriesLineZIndex, dot: false, isAnimationActive: false }, item.label)))] }) }), series.length > 1 && (_jsx("div", { className: legend, children: series.map((item, index) => (_jsxs("span", { className: legendItem, title: item.label, children: [_jsx("span", { className: swatch, style: { background: seriesColor(index) } }), _jsx("span", { children: item.label })] }, item.label))) }))] }));
+}
+function chartRows(series) {
+    const rowsByTime = new Map();
+    series.forEach((item, index) => {
+        for (const [time, value] of item.points) {
+            const row = rowsByTime.get(time) ?? { time };
+            row[seriesKey(index)] = value;
+            rowsByTime.set(time, row);
+        }
+    });
+    return [...rowsByTime.values()].sort((left, right) => left.time - right.time);
+}

package/dist/components/chat-page.d.ts

@@ -0,0 +1,34 @@
+import { type ComponentProps, type ReactNode } from "react";
+import type { ChatClient } from "../chat/chat-client.js";
+import type { ConversationId } from "../chat/contract.js";
+export { AgentTaskCard, AgentWork, AgentWorkButton, agentTaskAnchorId, jumpToAgentTask, type AgentTask, type AgentTaskAsk, type AgentTaskCardProps, type AgentTaskReply, type AgentWorkButtonProps, type AgentWorkProps, } from "./agent-work.js";
+export type ChatPageProps = ComponentProps<"div"> & {
+    /** The open thread, such as a wide `ChatConversation`. */
+    children: ReactNode;
+    /**
+     * The column on the right: the agent's work (`AgentWork`), or what a conversation draws on,
+     * such as what the agent read.
+     */
+    aside?: ReactNode;
+} & ({
+    variant?: "agent";
+    history?: never;
+    phoneView?: never;
+} | {
+    variant: "conversations";
+    /** The conversation list, such as `ChatHistory`. */
+    history: ReactNode;
+    /** Which one column shows under 700px. */
+    phoneView?: "history" | "conversation";
+});
+export declare function ChatPage({ variant, history, children, aside, phoneView, className, ...props }: ChatPageProps): import("@types/react").JSX.Element;
+export type ChatHistoryProps = {
+    /** Needs a `QueryClientProvider` above it. */
+    client: ChatClient;
+    selectedId: ConversationId | null;
+    onSelect: (conversationId: ConversationId) => void;
+    onNew: () => void;
+    className?: string;
+};
+/** The caller's conversations, newest first under day labels, with search and New chat. */
+export declare function ChatHistory({ client, selectedId, onSelect, onNew, className }: ChatHistoryProps): import("@types/react").JSX.Element;

package/dist/components/chat-page.js

@@ -0,0 +1,171 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * Chat as a full page. `variant="agent"`, the default, is the main agent's one long-running
+ * thread (a wide `ChatConversation`) with its work (`AgentWork`: what it is doing now and what
+ * waits on the user) in the `aside` on the right; under 700px the aside goes and the page's
+ * header carries `AgentWorkButton` instead. `variant="conversations"` lays out the
+ * conversation history, the open conversation and an optional context column; `ChatHistory`
+ * lists the caller's conversations from the chat client, searchable and grouped by day, with New
+ * chat. Under 700px one column shows at a time, the history or the conversation; the context
+ * column shows from 1000px up.
+ */
+import { PlusIcon } from "@phosphor-icons/react";
+import { differenceInCalendarDays, isToday, isYesterday } from "date-fns";
+import { useState } from "react";
+import { css, cx } from "#primitives/css";
+import { useConversationList } from "../chat/use-conversation-list.js";
+import { IconButton } from "./button.js";
+import { icon, Spinner } from "./icon.js";
+import { SearchField } from "./input.js";
+import { useCiridaeLocale } from "./locale.js";
+import { Skeleton } from "./skeleton.js";
+export { AgentTaskCard, AgentWork, AgentWorkButton, agentTaskAnchorId, jumpToAgentTask, } from "./agent-work.js";
+const page = css({
+    display: "grid",
+    gridTemplateColumns: "token(sizes.shell.sidebar) minmax(0, 1fr)",
+    flex: "1",
+    minHeight: "0",
+    "&[data-has-aside]": {
+        gridTemplateColumns: "token(sizes.shell.sidebar) minmax(0, 1fr) token(sizes.shell.sidebar)",
+    },
+    // The agent's thread, and its work on the right.
+    "&[data-variant=agent], &[data-variant=agent][data-has-aside]": {
+        gridTemplateColumns: "minmax(0, 1fr)",
+    },
+    "&[data-variant=agent][data-has-aside]": {
+        gridTemplateColumns: "minmax(0, 1fr) token(sizes.shell.sidebar)",
+    },
+    _rail: {
+        "&[data-variant=conversations][data-has-aside]": {
+            gridTemplateColumns: "token(sizes.shell.sidebar) minmax(0, 1fr)",
+        },
+    },
+    _phone: {
+        gridTemplateColumns: "minmax(0, 1fr)",
+        "&[data-has-aside], &[data-variant=agent][data-has-aside]": {
+            gridTemplateColumns: "minmax(0, 1fr)",
+        },
+        "&[data-phone-view=history] > [data-chat-page=conversation]": { display: "none" },
+        "&[data-phone-view=conversation] > [data-chat-page=history]": { display: "none" },
+    },
+});
+const column = css({ display: "flex", flexDirection: "column", minWidth: "0", minHeight: "0" });
+const historyColumn = css({
+    borderInlineEnd: "1px solid token(colors.border.panel)",
+    _phone: { borderInlineEnd: "0" },
+});
+const asideColumn = css({
+    overflowY: "auto",
+    borderInlineStart: "1px solid token(colors.border.panel)",
+    "[data-variant=conversations] > &": { _rail: { display: "none" } },
+    _phone: { display: "none" },
+});
+export function ChatPage({ variant = "agent", history, children, aside, phoneView = "conversation", className, ...props }) {
+    const conversations = variant === "conversations";
+    return (_jsxs("div", { ...props, className: cx(page, className), "data-ciridae-ui": "", "data-variant": variant, "data-has-aside": aside ? "" : undefined, "data-phone-view": conversations ? phoneView : undefined, children: [conversations && (_jsx("div", { className: cx(column, historyColumn), "data-chat-page": "history", children: history })), _jsx("div", { className: column, "data-chat-page": "conversation", children: children }), aside && _jsx("aside", { className: cx(column, asideColumn), children: aside })] }));
+}
+const historyHeader = css({
+    display: "flex",
+    alignItems: "center",
+    gap: "layout.controlGap",
+    flexShrink: "0",
+    paddingBlock: "layout.controlGap",
+    paddingInline: "panel.default",
+});
+const historyList = css({
+    flex: "1",
+    minHeight: "0",
+    overflowY: "auto",
+    paddingInline: "menu.inset",
+    paddingBlockEnd: "panel.default",
+});
+const groupLabel = css({
+    paddingBlockStart: "layout.controlGap",
+    paddingBlockEnd: "layout.tightGap",
+    paddingInline: "menu.itemInline",
+    color: "fg.muted",
+    fontSize: "code",
+    lineHeight: "compact",
+});
+const historyRow = css({
+    display: "flex",
+    alignItems: "center",
+    gap: "layout.controlGap",
+    width: "100%",
+    height: "menu.item",
+    paddingInline: "menu.itemInline",
+    border: "0",
+    borderRadius: "action",
+    background: "transparent",
+    color: "fg.primary",
+    font: "inherit",
+    fontSize: "caption",
+    lineHeight: "compact",
+    textAlign: "start",
+    cursor: "pointer",
+    _hover: { background: "bg.hover" },
+    _focusVisible: { focusRing: "inset" },
+    "&[aria-current=page]": { background: "bg.selected" },
+    "& > [data-title]": {
+        flex: "1",
+        minWidth: "0",
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        whiteSpace: "nowrap",
+    },
+    "& > time": { flexShrink: "0", color: "fg.muted", fontSize: "code" },
+});
+const emptyLine = css({
+    paddingBlock: "layout.controlGap",
+    paddingInline: "menu.itemInline",
+    color: "fg.muted",
+    fontSize: "caption",
+});
+const skeletonRow = css({ height: "menu.item", display: "flex", alignItems: "center" });
+/** The caller's conversations, newest first under day labels, with search and New chat. */
+export function ChatHistory({ client, selectedId, onSelect, onNew, className }) {
+    const [query, setQuery] = useState("");
+    const locale = useCiridaeLocale();
+    const { labels } = locale;
+    const list = useConversationList(client);
+    const conversations = list.data?.pages.flatMap((listPage) => listPage.data) ?? [];
+    const needle = query.trim().toLowerCase();
+    const matching = needle
+        ? conversations.filter((conversation) => [conversation.title, conversation.preview].some((text) => text?.toLowerCase().includes(needle)))
+        : conversations;
+    const groups = groupByDay(matching, locale);
+    return (_jsxs("nav", { className: cx(column, css({ flex: "1" }), className), "aria-label": labels.chat.conversations, children: [_jsxs("div", { className: historyHeader, children: [_jsx(SearchField, { size: "compact", placeholder: labels.common.search, "aria-label": labels.chat.searchConversations, value: query, onChange: (event) => setQuery(event.target.value), onClear: query ? () => setQuery("") : undefined, wrapperClassName: css({ flex: "1" }) }), _jsx(IconButton, { "aria-label": labels.chat.newChat, size: "small", onClick: onNew, children: _jsx(PlusIcon, { className: icon({ size: "small" }) }) })] }), _jsxs("div", { className: historyList, children: [list.isPending &&
+                        Array.from({ length: 6 }, (_, index) => (_jsx("div", { className: skeletonRow, children: _jsx(Skeleton, { shape: "text", style: { width: `${72 - (index % 3) * 12}%` } }) }, index))), !list.isPending && matching.length === 0 && (_jsx("div", { className: emptyLine, children: labels.common.noResults })), groups.map((group) => (_jsxs("section", { children: [_jsx("div", { className: groupLabel, children: group.label }), group.conversations.map((conversation) => {
+                                const status = conversation.latest_response?.status;
+                                return (_jsxs("button", { type: "button", className: historyRow, "aria-current": conversation.id === selectedId ? "page" : undefined, onClick: () => onSelect(conversation.id), children: [_jsx("span", { "data-title": "", children: conversation.title ?? conversation.preview ?? labels.chat.newChat }), status === "queued" || status === "in_progress" ? (_jsx(Spinner, { size: "compact", label: labels.chat.running })) : (_jsx("time", { dateTime: conversation.updated_at, children: formatUpdatedAt(Date.parse(conversation.updated_at), locale) }))] }, conversation.id));
+                            })] }, group.label)))] })] }));
+}
+/** Conversations under Today, Yesterday, Previous 7 days and Earlier, newest first. */
+function groupByDay(conversations, { labels }) {
+    const now = Date.now();
+    const labelOf = (at) => isToday(at)
+        ? labels.dates.today
+        : isYesterday(at)
+            ? labels.dates.yesterday
+            : differenceInCalendarDays(now, at) < 7
+                ? labels.chat.previousWeek
+                : labels.dates.earlier;
+    const groups = [];
+    for (const conversation of conversations) {
+        const label = labelOf(Date.parse(conversation.updated_at));
+        const group = groups.find((candidate) => candidate.label === label);
+        if (group)
+            group.conversations.push(conversation);
+        else
+            groups.push({ label, conversations: [conversation] });
+    }
+    return groups;
+}
+/** The time today, the weekday this week, the date before that. */
+function formatUpdatedAt(at, { formatDate, formatTime }) {
+    if (isToday(at))
+        return formatTime(at);
+    if (differenceInCalendarDays(Date.now(), at) < 7)
+        return formatDate(at, { weekday: "short" });
+    return formatDate(at, { month: "short", day: "numeric" });
+}

package/dist/components/chat-sheet-controller.d.ts

@@ -0,0 +1,50 @@
+import { type HotkeyChord } from "./hotkeys.js";
+import type { ChatSheetPlacement } from "./chat-sheet.js";
+import type { ConversationId } from "../chat/contract.js";
+export type UseChatSheetControllerOptions = {
+    /** The hotkey that opens, focuses and closes the sheet; Cmd/Ctrl+J by default. */
+    hotkey?: HotkeyChord;
+    /** Where the sheet sits until the reader moves it; "docked" by default. */
+    defaultPlacement?: ChatSheetPlacement;
+    /** Where docking fits; below it the sheet is a drawer. "(min-width: 1280px)" by default. */
+    dockedQuery?: string;
+    /** Keeps the reader's placement in `localStorage` under this key. */
+    persistKey?: string;
+    /** Shows the sheet's full-page button: the app opens its chat page on this conversation. */
+    onOpenFullPage?: (conversationId: ConversationId | null) => void;
+};
+export declare function useChatSheetController({ hotkey, defaultPlacement, dockedQuery, persistKey, onOpenFullPage, }?: UseChatSheetControllerOptions): {
+    open: boolean;
+    setOpen: import("@types/react").Dispatch<import("@types/react").SetStateAction<boolean>>;
+    toggle: () => void;
+    draft: string;
+    setDraft: import("@types/react").Dispatch<import("@types/react").SetStateAction<string>>;
+    conversationId: (string & import("zod/index.cjs").$brand<"ConversationId">) | null;
+    setConversationId: import("@types/react").Dispatch<import("@types/react").SetStateAction<(string & import("zod/index.cjs").$brand<"ConversationId">) | null>>;
+    composerRef: import("@types/react").RefObject<HTMLDivElement | null>;
+    focusComposer: (caret?: number) => void;
+    prefill: (text: string) => void;
+    placement: ChatSheetPlacement;
+    openFullPage: (() => void) | undefined;
+    openInSheet: () => void;
+    sheetProps: {
+        open: boolean;
+        onOpenChange: import("@types/react").Dispatch<import("@types/react").SetStateAction<boolean>>;
+        placement: ChatSheetPlacement;
+        onPlacementChange: ((next: ChatSheetPlacement) => void) | undefined;
+        onOpenFullPage: (() => void) | undefined;
+        draft: string;
+        onDraftChange: import("@types/react").Dispatch<import("@types/react").SetStateAction<string>>;
+        composerRef: import("@types/react").RefObject<HTMLDivElement | null>;
+        conversationId: (string & import("zod/index.cjs").$brand<"ConversationId">) | null;
+        onConversationCreated: (conversation: {
+            id: ConversationId;
+        }) => void;
+    };
+    pageProps: {
+        draft: string;
+        onDraftChange: import("@types/react").Dispatch<import("@types/react").SetStateAction<string>>;
+        composerRef: import("@types/react").RefObject<HTMLDivElement | null>;
+    };
+};
+export type ChatSheetController = ReturnType<typeof useChatSheetController>;

package/dist/components/chat-sheet-controller.js

@@ -0,0 +1,133 @@
+/*
+ * Everything around a `ChatSheet` except the chat itself: whether it is open, the composer's
+ * text, the open conversation, where the sheet sits, its hotkey, and the hand-off between the
+ * sheet and a full chat page. `hotkey` (Cmd/Ctrl+J) opens the sheet on its composer, focuses the
+ * composer when it is open elsewhere, and closes it from the composer. The sheet docks only where
+ * `dockedQuery` matches and is a drawer below it. The app spreads `sheetProps` onto `ChatSheet`
+ * (with its client, title and suggestions) and `pageProps` onto a full page's `ChatConversation`.
+ */
+import { useCallback, useRef, useState, useSyncExternalStore } from "react";
+import { useHotkey } from "./hotkeys.js";
+import { useCiridaeLocale } from "./locale.js";
+const DEFAULT_DOCKED_QUERY = "(min-width: 1280px)";
+function readPlacement(persistKey) {
+    if (!persistKey)
+        return null;
+    try {
+        const stored = globalThis.localStorage?.getItem(persistKey);
+        return stored === "docked" || stored === "drawer" ? stored : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writePlacement(persistKey, placement) {
+    if (!persistKey)
+        return;
+    try {
+        globalThis.localStorage?.setItem(persistKey, placement);
+    }
+    catch {
+        // The reader loses the placement across reloads, not the move.
+    }
+}
+/** Focuses the composer, with the caret at `caret` in a text field or at the end of rich text. */
+function focusAt(composer, caret) {
+    composer.focus();
+    if (caret === undefined)
+        return;
+    if (composer instanceof HTMLTextAreaElement)
+        composer.setSelectionRange(caret, caret);
+    else {
+        const selection = globalThis.getSelection?.();
+        selection?.selectAllChildren(composer);
+        selection?.collapseToEnd();
+    }
+}
+function useMediaQuery(query) {
+    const subscribe = useCallback((onChange) => {
+        const list = globalThis.matchMedia?.(query);
+        list?.addEventListener("change", onChange);
+        return () => list?.removeEventListener("change", onChange);
+    }, [query]);
+    return useSyncExternalStore(subscribe, () => globalThis.matchMedia?.(query).matches ?? true, () => true);
+}
+export function useChatSheetController({ hotkey = "Mod+J", defaultPlacement = "docked", dockedQuery = DEFAULT_DOCKED_QUERY, persistKey, onOpenFullPage, } = {}) {
+    const [open, setOpen] = useState(false);
+    const [draft, setDraft] = useState("");
+    const [conversationId, setConversationId] = useState(null);
+    const [preferredPlacement, setPreferredPlacement] = useState(() => readPlacement(persistKey) ?? defaultPlacement);
+    const composerRef = useRef(null);
+    const dockable = useMediaQuery(dockedQuery);
+    const placement = dockable ? preferredPlacement : "drawer";
+    const focusComposer = useCallback((caret) => {
+        // After the sheet has drawn its composer.
+        requestAnimationFrame(() => {
+            const composer = composerRef.current;
+            if (composer)
+                focusAt(composer, caret);
+        });
+    }, []);
+    const { labels } = useCiridaeLocale();
+    useHotkey(hotkey, () => {
+        const composer = composerRef.current;
+        if (!open) {
+            setOpen(true);
+            focusComposer();
+        }
+        else if (composer && document.activeElement !== composer)
+            composer.focus();
+        else
+            setOpen(false);
+    }, { meta: { name: labels.keyboard.openChat } });
+    const toggle = useCallback(() => setOpen((current) => !current), []);
+    /** Opens the sheet with `text` in its composer, ready to send or edit. */
+    const prefill = useCallback((text) => {
+        setDraft(text);
+        setOpen(true);
+        focusComposer();
+    }, [focusComposer]);
+    const changePlacement = useCallback((next) => {
+        setPreferredPlacement(next);
+        writePlacement(persistKey, next);
+    }, [persistKey]);
+    const openFullPage = onOpenFullPage
+        ? () => {
+            setOpen(false);
+            onOpenFullPage(conversationId);
+        }
+        : undefined;
+    /** Back from the full page: the sheet opens on the same conversation and draft. */
+    const openInSheet = useCallback(() => {
+        setOpen(true);
+        focusComposer();
+    }, [focusComposer]);
+    return {
+        open,
+        setOpen,
+        toggle,
+        draft,
+        setDraft,
+        conversationId,
+        setConversationId,
+        composerRef,
+        focusComposer,
+        prefill,
+        placement,
+        openFullPage,
+        openInSheet,
+        sheetProps: {
+            open,
+            onOpenChange: setOpen,
+            placement,
+            onPlacementChange: dockable ? changePlacement : undefined,
+            onOpenFullPage: openFullPage,
+            draft,
+            onDraftChange: setDraft,
+            composerRef,
+            conversationId,
+            onConversationCreated: (conversation) => setConversationId(conversation.id),
+        },
+        pageProps: { draft, onDraftChange: setDraft, composerRef },
+    };
+}

package/dist/components/chat-sheet.d.ts

@@ -0,0 +1,80 @@
+import { type ReactNode, type Ref } from "react";
+import { type AgentTask, type AgentTaskReply } from "./agent-work.js";
+import { DrawerBody } from "./drawer.js";
+import type { MentionMark, MentionTrigger } from "./mention-input.js";
+import type { ChatClient } from "../chat/chat-client.js";
+import type { Conversation, ConversationId, Mention } from "../chat/contract.js";
+export type ChatSheetPlacement = "docked" | "drawer";
+/** A record the agent reads for this conversation, named in the row under the header. */
+export type ChatSheetContext = {
+    label: string;
+    icon?: ReactNode;
+};
+/** Something the page did during the conversation, shown as a centered line at its time. */
+export type ChatSheetEvent = {
+    id: string;
+    at: string;
+    text: string;
+};
+/** The thread and composer's own props, shared by the sheet and `ChatConversation`. */
+export type ChatConversationProps = {
+    /**
+     * `agent`, the default, is the main agent's one long-running thread, with its `tasks` as cards
+     * under day labels; `conversations` is one conversation of many, such as beside `ChatHistory`.
+     */
+    variant?: "agent" | "conversations";
+    /** What the main agent runs on its own, oldest first; `agent` only. */
+    tasks?: readonly AgentTask[];
+    /** The user's approval or answer on a waiting task's card. */
+    onTaskReply?: (task: AgentTask, reply: AgentTaskReply) => void;
+    /** Needs a `QueryClientProvider` above it. */
+    client: ChatClient;
+    /** Null before the first message; the conversation is created with it and reported. */
+    conversationId: ConversationId | null;
+    onConversationCreated: (conversation: Conversation) => void;
+    placeholder: string;
+    /** The composer's text, when the host owns it, such as to start a question for the user. */
+    draft?: string;
+    onDraftChange?: (draft: string) => void;
+    /** The composer's field, so the host can focus it, such as from its shortcut. */
+    composerRef?: Ref<HTMLDivElement>;
+    /** Characters such as `@` that pick a record into the message as a chip. */
+    mentions?: readonly MentionTrigger[];
+    /** What a mention's chip and picker row lead with, such as a record's icon. */
+    mentionMark?: MentionMark;
+    /** What a mention in a reply does on the page, such as showing the field it names. */
+    onMentionSelect?: (mention: Mention) => void;
+    /** Makes a mention a link, such as to its record's page; undefined leaves it to `onMentionSelect`. */
+    mentionHref?: (mention: Mention) => string | undefined;
+    /** Lines the page adds between the messages, such as that it is showing a field. */
+    events?: readonly ChatSheetEvent[];
+    /** Who answers, named on the assistant's avatar; the product's own name, or an agent persona's. */
+    assistantName?: string;
+    /** Prompts an empty conversation offers, such as questions about the page; picking one sends it. */
+    suggestions?: readonly string[];
+    /** A Copy control in the footer of each reply once its turn has finished, and not failed. */
+    copyReplies?: boolean;
+};
+export type ChatSheetProps = ChatConversationProps & {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title: ReactNode;
+    /** What the agent reads, under the header; omitted when the sheet is not about a page. */
+    context?: readonly ChatSheetContext[];
+    /** `docked` sits beside the page inside `AppShell`; `drawer` floats over it. */
+    placement?: ChatSheetPlacement;
+    /** Shows the dock and undock button in the header. */
+    onPlacementChange?: (placement: ChatSheetPlacement) => void;
+    /** Shows a header button that moves the conversation to a full page. */
+    onOpenFullPage?: () => void;
+};
+export declare function ChatSheet({ open, onOpenChange, title, context, placement, onPlacementChange, onOpenFullPage, ...conversationProps }: ChatSheetProps): import("@types/react").JSX.Element | null;
+/**
+ * The thread and the composer: everything that reads or writes the conversation. `layout="wide"`
+ * sets both in one readable column for a full page; the sheet uses `sheet`.
+ */
+export declare function ChatConversation({ client, conversationId, onConversationCreated, placeholder, draft, onDraftChange, composerRef, mentions, mentionMark, onMentionSelect, mentionHref, events, assistantName: ownAssistantName, suggestions, copyReplies, variant, tasks, onTaskReply, layout, scrollBody: ScrollBody, }: ChatConversationProps & {
+    layout?: "sheet" | "wide";
+    /** The drawer's body inside a `Drawer`, a plain element otherwise. */
+    scrollBody?: typeof DrawerBody | "div";
+}): import("@types/react").JSX.Element;