@corbits/react-ui 0.1.0

package/dist/ui/progress-checklist.d.ts

@@ -0,0 +1,25 @@
+export type ChecklistStepStatus = "pending" | "running" | "done" | "failed";
+export type ChecklistStep = {
+    readonly id: string;
+    readonly label: string;
+    readonly status: ChecklistStepStatus;
+    /** Why it failed, or what it found. Shown under the label. */
+    readonly detail?: string;
+};
+/**
+ * A list of steps and how far along they are — a long operation reporting
+ * itself while the user waits.
+ *
+ * Each row states its status in text, not only by icon or colour. A checklist
+ * where "done" is conveyed by a green tick alone is unreadable to anyone who
+ * cannot distinguish it from the grey one, and the status word costs a line of
+ * markup.
+ *
+ * The whole list is `aria-live="polite"`, so steps completing are announced as
+ * they happen without stealing focus from wherever the user actually is.
+ */
+export declare function ProgressChecklist({ steps, label, className, }: {
+    steps: readonly ChecklistStep[];
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/ui/progress-checklist.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Check, X } from "lucide-react";
+import { cn } from "../lib/utils.js";
+import { StatusDot } from "./status-dot.js";
+const STATUS_LABEL = {
+    pending: "Not started",
+    running: "In progress",
+    done: "Done",
+    failed: "Failed"
+};
+/**
+ * A list of steps and how far along they are — a long operation reporting
+ * itself while the user waits.
+ *
+ * Each row states its status in text, not only by icon or colour. A checklist
+ * where "done" is conveyed by a green tick alone is unreadable to anyone who
+ * cannot distinguish it from the grey one, and the status word costs a line of
+ * markup.
+ *
+ * The whole list is `aria-live="polite"`, so steps completing are announced as
+ * they happen without stealing focus from wherever the user actually is.
+ */ export function ProgressChecklist({ steps, label = "Progress", className }) {
+    if (steps.length === 0) return null;
+    return /*#__PURE__*/ _jsx("ol", {
+        "aria-label": label,
+        "aria-live": "polite",
+        className: cn("flex flex-col gap-2.5", className),
+        children: steps.map((step, index)=>/*#__PURE__*/ _jsxs("li", {
+                className: "flex items-start gap-3",
+                children: [
+                    /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": true,
+                        className: cn("mt-0.5 grid size-5 shrink-0 place-items-center rounded-full border text-[10px] font-semibold", step.status === "done" && "border-transparent bg-success text-success-foreground", step.status === "failed" && "border-transparent bg-destructive text-destructive-foreground", step.status === "running" && "border-primary-emphasis text-primary-emphasis", step.status === "pending" && "border-input text-muted-foreground"),
+                        children: step.status === "done" ? /*#__PURE__*/ _jsx(Check, {
+                            className: "size-3"
+                        }) : step.status === "failed" ? /*#__PURE__*/ _jsx(X, {
+                            className: "size-3"
+                        }) : step.status === "running" ? /*#__PURE__*/ _jsx(StatusDot, {
+                            label: "",
+                            live: true,
+                            tone: "emphasis"
+                        }) : index + 1
+                    }),
+                    /*#__PURE__*/ _jsxs("div", {
+                        className: "flex min-w-0 flex-col gap-0.5",
+                        children: [
+                            /*#__PURE__*/ _jsxs("p", {
+                                className: cn("text-sm leading-snug", step.status === "pending" ? "text-muted-foreground" : "text-foreground"),
+                                children: [
+                                    step.label,
+                                    " ",
+                                    /*#__PURE__*/ _jsxs("span", {
+                                        className: "text-xs text-muted-foreground",
+                                        children: [
+                                            "· ",
+                                            STATUS_LABEL[step.status]
+                                        ]
+                                    })
+                                ]
+                            }),
+                            step.detail === undefined ? null : /*#__PURE__*/ _jsx("p", {
+                                className: "text-xs leading-relaxed text-muted-foreground",
+                                children: step.detail
+                            })
+                        ]
+                    })
+                ]
+            }, step.id))
+    });
+}

package/dist/ui/provider-mark.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import type { ToolPart } from "../lib/chat-message.js";
+export type ProviderMarkProps = {
+    /** Provider key: `slack`, `linear`, `github`. Shown as a monogram if no logo. */
+    readonly provider: string;
+    /**
+     * The provider's brand mark, supplied by the host.
+     *
+     * This registry ships no third-party logos. Trademarks are not ours to
+     * redistribute, and an app that wants real marks has its own source for them
+     * — a brand API, a licensed icon set, its own SVGs. So the slot is here and
+     * the artwork is not, and the monogram means the fallback is never a blank
+     * square.
+     */
+    readonly logo?: ReactNode;
+    readonly size?: "sm" | "md";
+    readonly className?: string;
+};
+/** Which service an action goes through. */
+export declare function ProviderMark({ provider, logo, size, className }: ProviderMarkProps): import("react").JSX.Element;
+/**
+ * The provider marker for a tool call in a transcript.
+ *
+ * The provider is read off the tool id's `provider__operation` prefix — the
+ * same convention `toolLabel` uses — so a tool with no prefix is local and gets
+ * no marker rather than a guessed one.
+ */
+export declare function ToolProviderMark({ part, logo, className, }: {
+    part: ToolPart;
+    logo?: ReactNode;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/ui/provider-mark.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+const SIZE_CLASS = {
+    sm: "size-4 text-[8px]",
+    md: "size-6 text-[10px]"
+};
+/** Which service an action goes through. */ export function ProviderMark({ provider, logo, size = "sm", className }) {
+    const label = provider.charAt(0).toUpperCase() + provider.slice(1);
+    return /*#__PURE__*/ _jsx("span", {
+        role: "img",
+        "aria-label": label,
+        title: label,
+        className: cn("inline-grid shrink-0 place-items-center overflow-hidden rounded-sm bg-muted font-semibold text-muted-foreground", SIZE_CLASS[size], className),
+        children: logo ?? provider.slice(0, 2).toUpperCase()
+    });
+}
+/**
+ * The provider marker for a tool call in a transcript.
+ *
+ * The provider is read off the tool id's `provider__operation` prefix — the
+ * same convention `toolLabel` uses — so a tool with no prefix is local and gets
+ * no marker rather than a guessed one.
+ */ export function ToolProviderMark({ part, logo, className }) {
+    const [provider, ...rest] = part.toolName.split("__");
+    if (rest.length === 0 || provider === undefined || provider === "") return null;
+    return /*#__PURE__*/ _jsx(ProviderMark, {
+        provider: provider,
+        logo: logo,
+        className: className
+    });
+}

package/dist/ui/quick-reply-chips.d.ts

@@ -0,0 +1,14 @@
+import type { QuickReply } from "../lib/chat-message.js";
+/**
+ * Suggested replies. A list, not a row of loose buttons, so a screen reader
+ * announces how many suggestions there are before reading them — otherwise the
+ * user has to arrow through to find out.
+ *
+ * Sending is the host's job: this reports which chip was chosen and lets the
+ * host decide whether that fills the composer or sends immediately.
+ */
+export declare function QuickReplyChips({ replies, onSelect, className, }: {
+    replies: readonly QuickReply[];
+    onSelect: (reply: QuickReply) => void;
+    className?: string;
+}): import("react").JSX.Element | null;

package/dist/ui/quick-reply-chips.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+/**
+ * Suggested replies. A list, not a row of loose buttons, so a screen reader
+ * announces how many suggestions there are before reading them — otherwise the
+ * user has to arrow through to find out.
+ *
+ * Sending is the host's job: this reports which chip was chosen and lets the
+ * host decide whether that fills the composer or sends immediately.
+ */ export function QuickReplyChips({ replies, onSelect, className }) {
+    if (replies.length === 0) return null;
+    return /*#__PURE__*/ _jsx("ul", {
+        "aria-label": "Suggested replies",
+        className: cn("flex flex-wrap gap-2", className),
+        children: replies.map((reply)=>/*#__PURE__*/ _jsx("li", {
+                children: /*#__PURE__*/ _jsx("button", {
+                    type: "button",
+                    onClick: ()=>onSelect(reply),
+                    className: "rounded-full border border-border bg-muted px-3 py-1.5 text-xs text-muted-foreground transition-colors hover:bg-background hover:text-foreground",
+                    children: reply.label
+                })
+            }, reply.id))
+    });
+}

package/dist/ui/quote-card.d.ts

@@ -0,0 +1,39 @@
+export type Quote = {
+    readonly text: string;
+    readonly author?: string;
+};
+export type QuoteCardProps = {
+    /** Yours. This registry ships no copy — a component with opinions about what
+     *  your product says is a component you have to edit before you can use it. */
+    readonly quotes: readonly Quote[];
+    /**
+     * A key in `localStorage` for the last-shown index, so the card advances once
+     * per visit instead of showing the same line forever. Omit it and the card
+     * picks the first quote every time, which is the right behaviour when there
+     * is only one.
+     */
+    readonly storageKey?: string;
+    readonly className?: string;
+};
+/**
+ * A quote, rotated once per page load.
+ *
+ * Once per *load*, not on a timer. Text that swaps itself while someone is
+ * reading it is the pattern WCAG 2.2.2 exists to prohibit, and a marquee of
+ * clever lines on a sign-in page is exactly the case it had in mind. Advancing
+ * on load gives the same variety with none of that.
+ *
+ * The index is chosen during the initial `useState` and persisted in a mount
+ * effect, so the first paint already has its quote — deriving it in an effect
+ * would render quote zero and then swap it, which is the flicker this avoids.
+ *
+ * Every `localStorage` touch is wrapped: it throws outright in some private
+ * browsing modes, and a decorative card must not be able to take down the page
+ * it decorates. Losing the rotation is the correct failure — the card still
+ * renders, just from the top.
+ *
+ * `<blockquote>` and `<cite>`, because that is what this is. The quotation and
+ * its attribution are related in the markup rather than being two adjacent
+ * strings that happen to sit near each other.
+ */
+export declare function QuoteCard({ quotes, storageKey, className }: QuoteCardProps): import("react").JSX.Element | null;

package/dist/ui/quote-card.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { cn } from "../lib/utils.js";
+/**
+ * A quote, rotated once per page load.
+ *
+ * Once per *load*, not on a timer. Text that swaps itself while someone is
+ * reading it is the pattern WCAG 2.2.2 exists to prohibit, and a marquee of
+ * clever lines on a sign-in page is exactly the case it had in mind. Advancing
+ * on load gives the same variety with none of that.
+ *
+ * The index is chosen during the initial `useState` and persisted in a mount
+ * effect, so the first paint already has its quote — deriving it in an effect
+ * would render quote zero and then swap it, which is the flicker this avoids.
+ *
+ * Every `localStorage` touch is wrapped: it throws outright in some private
+ * browsing modes, and a decorative card must not be able to take down the page
+ * it decorates. Losing the rotation is the correct failure — the card still
+ * renders, just from the top.
+ *
+ * `<blockquote>` and `<cite>`, because that is what this is. The quotation and
+ * its attribution are related in the markup rather than being two adjacent
+ * strings that happen to sit near each other.
+ */ export function QuoteCard({ quotes, storageKey, className }) {
+    const [index] = useState(()=>{
+        if (storageKey === undefined || quotes.length === 0) return 0;
+        try {
+            const raw = window.localStorage.getItem(storageKey);
+            const parsed = raw === null ? -1 : Number.parseInt(raw, 10);
+            const last = Number.isInteger(parsed) && parsed >= 0 ? parsed : -1;
+            const next = (last + 1) % quotes.length;
+            window.localStorage.setItem(storageKey, String(next));
+            return next;
+        } catch  {
+            return 0;
+        }
+    });
+    const quote = quotes[index % Math.max(quotes.length, 1)];
+    if (quote === undefined) return null;
+    return /*#__PURE__*/ _jsxs("figure", {
+        className: cn("w-full max-w-xs rounded-xl border border-border bg-card/90 p-6 backdrop-blur-sm", className),
+        children: [
+            /*#__PURE__*/ _jsxs("blockquote", {
+                className: "text-base leading-relaxed whitespace-pre-line text-card-foreground",
+                children: [
+                    "“",
+                    quote.text,
+                    "”"
+                ]
+            }),
+            quote.author === undefined ? null : /*#__PURE__*/ _jsxs("figcaption", {
+                className: "mt-4 flex items-center gap-3",
+                children: [
+                    /*#__PURE__*/ _jsx("span", {
+                        "aria-hidden": true,
+                        className: "h-px flex-1 bg-border"
+                    }),
+                    /*#__PURE__*/ _jsx("cite", {
+                        className: "text-xs text-muted-foreground not-italic",
+                        children: quote.author
+                    })
+                ]
+            })
+        ]
+    });
+}

package/dist/ui/reasoning-block.d.ts

@@ -0,0 +1,35 @@
+export type ReasoningBlockProps = {
+    /** The agent's thinking. Rendered as text — it is not markup. */
+    readonly text: string;
+    /** Still streaming. Changes the summary wording and marks the body busy. */
+    readonly streaming?: boolean;
+    /** Summary while streaming. Defaults to "Thinking…". */
+    readonly streamingLabel?: string;
+    /** Summary once idle when no `durationLabel` is supplied. Defaults to "Thinking". */
+    readonly idleLabel?: string;
+    /** e.g. "Thought for 4s". Becomes the summary once reasoning has stopped streaming. */
+    readonly durationLabel?: string;
+    readonly defaultOpen?: boolean;
+    /**
+     * Controlled open state. Pair with `onOpenChange` to lift it to a parent —
+     * and honor it: a controlled `<details>` that ignores `onOpenChange` leaves
+     * the DOM attribute and React state diverged (the browser mutates `open`
+     * without React's knowledge), so the block can sit visibly open while the
+     * prop says closed.
+     */
+    readonly open?: boolean;
+    readonly onOpenChange?: (open: boolean) => void;
+    readonly className?: string;
+};
+/**
+ * The agent's thinking, folded away.
+ *
+ * Collapsed by default, including while streaming: reasoning is context for a
+ * reader who wants it and noise for one who does not, and a block that
+ * expands itself mid-stream makes the transcript jump under the reader.
+ *
+ * A native `<details>`, not a div with state: it gets the disclosure
+ * semantics, keyboard behaviour and find-in-page expansion from the browser,
+ * and those are three things a hand-rolled version gets wrong.
+ */
+export declare function ReasoningBlock({ text, streaming, streamingLabel, idleLabel, durationLabel, defaultOpen, open: openProp, onOpenChange, className, }: ReasoningBlockProps): import("react").JSX.Element | null;

package/dist/ui/reasoning-block.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronRight } from "lucide-react";
+import { useControllableState } from "../hooks/use-controllable-state.js";
+import { cn } from "../lib/utils.js";
+/**
+ * The agent's thinking, folded away.
+ *
+ * Collapsed by default, including while streaming: reasoning is context for a
+ * reader who wants it and noise for one who does not, and a block that
+ * expands itself mid-stream makes the transcript jump under the reader.
+ *
+ * A native `<details>`, not a div with state: it gets the disclosure
+ * semantics, keyboard behaviour and find-in-page expansion from the browser,
+ * and those are three things a hand-rolled version gets wrong.
+ */ export function ReasoningBlock({ text, streaming = false, streamingLabel = "Thinking…", idleLabel = "Thinking", durationLabel, defaultOpen = false, open: openProp, onOpenChange, className }) {
+    const [open, setOpen] = useControllableState({
+        value: openProp,
+        defaultValue: defaultOpen,
+        onChange: onOpenChange,
+        name: "ReasoningBlock"
+    });
+    if (text.trim().length === 0) return null;
+    const summary = streaming ? streamingLabel : durationLabel ?? idleLabel;
+    return /*#__PURE__*/ _jsxs("details", {
+        "data-slot": "reasoning-block",
+        open: open,
+        // The browser fires `toggle` for any `open` attribute change — prop-driven
+        // ones included — so a bare setOpen would echo the parent's own commands
+        // back through onOpenChange. Reporting only divergence means exactly one
+        // callback per user activation, and none when a parent drives `open`.
+        onToggle: (event)=>{
+            const domOpen = event.currentTarget.open;
+            if (domOpen !== open) setOpen(domOpen);
+        },
+        className: cn("text-xs", className),
+        children: [
+            /*#__PURE__*/ _jsxs("summary", {
+                className: cn(// `relative` plus the `::after` pseudo-element extends the
+                // effective hit area to 40px tall without changing the row's own
+                // padding/density — see design-engineering.md's hit-area pattern.
+                "relative flex cursor-pointer list-none items-center gap-1.5 rounded-md px-2 py-1.5 text-muted-foreground transition-colors after:absolute after:inset-x-0 after:top-1/2 after:h-10 after:-translate-y-1/2 hover:bg-muted hover:text-foreground", "[&::-webkit-details-marker]:hidden"),
+                children: [
+                    /*#__PURE__*/ _jsx(ChevronRight, {
+                        className: cn("size-3.5 shrink-0 transition-transform duration-200 ease-out", open && "rotate-90"),
+                        "aria-hidden": true
+                    }),
+                    /*#__PURE__*/ _jsx("span", {
+                        "aria-live": "polite",
+                        children: summary
+                    })
+                ]
+            }),
+            /*#__PURE__*/ _jsx("p", {
+                "aria-busy": streaming,
+                className: "mt-1 ml-4 border-l border-border pl-3 leading-relaxed whitespace-pre-wrap text-muted-foreground [animation:corbits-rail-block-in_200ms_var(--ease-out)_both]",
+                children: text
+            }, open ? "open" : "closed")
+        ]
+    });
+}

package/dist/ui/research-body.d.ts

@@ -0,0 +1,70 @@
+export type ResearchSource = {
+    readonly url: string;
+    readonly title?: string;
+    /** Where it came from — a publication, a forum, a feed name. */
+    readonly source: string;
+};
+export type ResearchCluster = {
+    readonly id: string;
+    readonly title: string;
+    readonly summary?: string;
+    /** Source names this cluster drew on. */
+    readonly sources?: readonly string[];
+    readonly items?: readonly ResearchSource[];
+};
+export type ResearchQuote = {
+    readonly quote: string;
+    readonly author?: string;
+    readonly source: string;
+    readonly url?: string;
+};
+export type ResearchBrief = {
+    readonly topic: string;
+    readonly sourceCount: number;
+    readonly itemCount: number;
+    /** Human-readable coverage window, e.g. "Jan 1 – Mar 31". Pre-formatted. */
+    readonly range?: string;
+    /** The one sentence someone reads if they read nothing else. */
+    readonly leadInsight?: string;
+    readonly clusters?: readonly ResearchCluster[];
+    readonly quotes?: readonly ResearchQuote[];
+    readonly citations?: readonly ResearchSource[];
+};
+/**
+ * Reads a brief (and its optional prose report) out of an artifact payload.
+ *
+ * Checks only `topic` and the two counts — the fields the header renders
+ * unconditionally and the ones whose absence would print "undefined sources".
+ * Everything below the header is already guarded by a presence check at its own
+ * render site, so validating it here would only reject briefs this component
+ * draws correctly.
+ */
+export declare function parseResearchArtifact(json: string): {
+    brief: ResearchBrief;
+    body?: string;
+} | null;
+/**
+ * A structured research brief: what was found, grouped, quoted and cited.
+ *
+ * The layout is an argument in order — headline stat line, the lead insight,
+ * then clusters, then evidence, then citations. A reader who stops after the
+ * first screen should still have the finding; a reader who wants to audit it
+ * can walk down to the sources without leaving the page.
+ *
+ * `body` is the prose report when the producer wrote one. Given both, the prose
+ * is the deliverable and the structured data becomes supporting evidence behind
+ * a `<details>` — collapsed rather than removed, because "show me your working"
+ * is the second question every reader of a generated report asks. `<details>` is
+ * a native disclosure: keyboard-operable and announced as expandable with no JS
+ * and no ARIA of our own.
+ *
+ * Prose is rendered as pre-wrapped text, not parsed as Markdown. The registry
+ * ships no Markdown dependency, and adding ~40kB of parser that a consumer then
+ * owns is not something a component should decide on their behalf. Wrap the
+ * `body` slot in your own renderer if you have one.
+ */
+export declare function ResearchBody({ brief, body, className, }: {
+    readonly brief: ResearchBrief;
+    readonly body?: string;
+    readonly className?: string;
+}): import("react").JSX.Element;