@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/components/session-state-dot.d.ts

@@ -0,0 +1,111 @@
+import type { ReactNode } from "react";
+import type { AgentState } from "../types.ts";
+/**
+ * The dot itself: a coloured circle, pulsing or still.
+ *
+ * Shared by {@link SessionStateDot} and `ConsoleShell`, which computes its
+ * colour from the theme rather than from a palette prop and decides for itself
+ * when to pulse. Not on the package barrel — the public component is the one
+ * that reads the session.
+ *
+ * The colour is written to `background` AND `color`, so a caller can extend
+ * the dot with a `currentColor` utility (`shadow-[0_0_6px_currentColor]` for a
+ * glow) without restating the palette.
+ *
+ * @internal
+ */
+export declare function StateDot({ color, pulseMs, className, title, }: {
+    /** The dot's colour. */
+    color: string;
+    /** Length of one pulse cycle, or `null` for a still dot. */
+    pulseMs: number | null;
+    /** Size and any extras; the shape classes are the dot's own. */
+    className?: string | undefined;
+    /** Tooltip text, typically the raw state. */
+    title?: string | undefined;
+}): ReactNode;
+/**
+ * Props of {@link SessionStateDot}.
+ *
+ * @public
+ */
+export type SessionStateDotProps = {
+    /**
+     * The dot's colour per {@link AgentState} — the chrome's own palette. A
+     * complete record, so a state added upstream is a compile error here rather
+     * than a silently unpainted dot; `satisfies Record<AgentState, string>` on the
+     * caller's literal is the shape to write it in.
+     */
+    colors: Readonly<Record<AgentState, string>>;
+    /**
+     * The words this chrome has a better term for. Anything not named falls back
+     * to {@link AGENT_STATE_LABELS}, so a page overrides one member (`speaking:
+     * "Narrating"`) without restating the union.
+     */
+    labels?: Partial<Readonly<Record<AgentState, string>>> | undefined;
+    /**
+     * Whether the dot pulses while `listening` (slowly) and `thinking` (faster).
+     * Defaults to `true`; a chrome whose dot glows rather than beats passes
+     * `false`.
+     */
+    pulse?: boolean | undefined;
+    /** Additional CSS class names for the wrapping `<span>`, appended to its own. */
+    className?: string | undefined;
+    /**
+     * REPLACES the dot's default size (`w-2 h-2`) rather than adding to it —
+     * there is no `tailwind-merge` in this package, so two conflicting width
+     * utilities would not have a reliable winner. The dot's shape classes stay.
+     */
+    dotClassName?: string | undefined;
+    /** Additional CSS class names for the label `<span>`. */
+    labelClassName?: string | undefined;
+};
+/**
+ * The live session state as a coloured dot and a word, on its own narrow
+ * subscription.
+ *
+ * Three custom chromes had each written this: a `satisfies Record<AgentState,
+ * string>` palette (kept — it is the prop), a `STATE_LABELS` spread over
+ * {@link AGENT_STATE_LABELS} (kept — it is `labels`), and then the same
+ * fourteen lines of markup around them, including the same two-arm ternary
+ * deciding which states pulse and how fast. `agent-state-labels.ts` argued
+ * against a dot component on the grounds that it would take the shared part
+ * (the words) hostage to the part that is not (the palette); this takes the
+ * palette as a prop precisely so it does not. What is shared is the structure
+ * — the exhaustive colour lookup, the label fallback, the pulse rule, the
+ * `useSessionStatus()` subscription that keeps the rest of the header from
+ * re-rendering at STT-partial rate.
+ *
+ * Must be rendered inside the providers `mountClient()` installs.
+ *
+ * @example A dispatch board's readout: its own colours, three of its own words
+ * ```tsx
+ * import type { AgentState } from "@alexkroman1/aai-ui";
+ * import { SessionStateDot } from "@alexkroman1/aai-ui";
+ *
+ * const STATE_COLORS = {
+ *   disconnected: "#6b7280",
+ *   connecting: "#6b7280",
+ *   ready: "#22c55e",
+ *   listening: "#22c55e",
+ *   thinking: "#eab308",
+ *   speaking: "#3b82f6",
+ *   error: "#6b7280",
+ * } satisfies Record<AgentState, string>;
+ *
+ * function StatusReadout() {
+ *   return (
+ *     <SessionStateDot
+ *       colors={STATE_COLORS}
+ *       labels={{ listening: "LISTENING", thinking: "PROCESSING", speaking: "TRANSMITTING" }}
+ *       labelClassName="text-[11px] uppercase"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link SessionStateDotProps}.
+ *
+ * @public
+ */
+export declare function SessionStateDot({ colors, labels, pulse, className, dotClassName, labelClassName, }: SessionStateDotProps): ReactNode;

package/dist/components/sidebar-layout.d.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+/**
+ * A two-column layout with a fixed-width sidebar and a flexible main area.
+ * Commonly used to pair a custom sidebar (cart, dashboard) with `<ChatView />`.
+ *
+ * @example
+ * ```tsx
+ * import { ChatView, SidebarLayout } from "@alexkroman1/aai-ui";
+ *
+ * function OrderPanel() {
+ *   return <div>Cart</div>;
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <SidebarLayout sidebar={<OrderPanel />}>
+ *       <ChatView />
+ *     </SidebarLayout>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Layout props.
+ *
+ * @public
+ */
+export declare function SidebarLayout({ sidebar, children, sidebarWidth, sidebarPosition, className, }: {
+    /** The sidebar pane — a cart, a dashboard, a run history. */
+    sidebar: ReactNode;
+    /** The main pane, normally a `<ChatView />`. */
+    children: ReactNode;
+    /**
+     * Width of the sidebar as a CSS length. Defaults to `"18rem"`, and applies
+     * from the `md` breakpoint up: below it the two panes stack, because a fixed
+     * width that never shrinks leaves a phone-width main pane unreadable.
+     */
+    sidebarWidth?: string | undefined;
+    /** Which side the sidebar sits on. Defaults to `"left"`. */
+    sidebarPosition?: "left" | "right" | undefined;
+    /** Additional CSS class names for the root element, appended to its own. */
+    className?: string;
+}): import("react").JSX.Element;

package/dist/components/sidebar-layout.js

@@ -0,0 +1,56 @@
+import { useTheme } from "../context.js";
+import clsx from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/sidebar-layout.tsx
+/** @jsxImportSource react */
+/**
+* A two-column layout with a fixed-width sidebar and a flexible main area.
+* Commonly used to pair a custom sidebar (cart, dashboard) with `<ChatView />`.
+*
+* @example
+* ```tsx
+* import { ChatView, SidebarLayout } from "@alexkroman1/aai-ui";
+*
+* function OrderPanel() {
+*   return <div>Cart</div>;
+* }
+*
+* function App() {
+*   return (
+*     <SidebarLayout sidebar={<OrderPanel />}>
+*       <ChatView />
+*     </SidebarLayout>
+*   );
+* }
+* ```
+*
+* @param props - Layout props.
+*
+* @public
+*/
+function SidebarLayout({ sidebar, children, sidebarWidth = "18rem", sidebarPosition = "left", className }) {
+	const theme = useTheme();
+	const sidebarEl = /* @__PURE__ */ jsx("div", {
+		className: clsx("shrink-0 flex flex-col overflow-y-auto", "w-full max-h-[40vh] md:w-(--aai-sidebar-w) md:max-h-none", sidebarPosition === "left" ? "border-b md:border-b-0 md:border-r" : "border-t md:border-t-0 md:border-l order-last md:order-none"),
+		style: { borderColor: theme.border },
+		children: sidebar
+	});
+	const vars = {
+		background: theme.bg,
+		"--aai-sidebar-w": sidebarWidth
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: clsx("flex flex-col md:flex-row min-h-screen md:h-screen", className),
+		style: vars,
+		children: [
+			sidebarPosition === "left" && sidebarEl,
+			/* @__PURE__ */ jsx("div", {
+				className: "flex-1 min-w-0 min-h-0",
+				children
+			}),
+			sidebarPosition === "right" && sidebarEl
+		]
+	});
+}
+//#endregion
+export { SidebarLayout };

package/dist/components/start-screen.d.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+/**
+ * A centered start screen: a white card on the cream page with the logo, an
+ * eyebrow label, a serif title, subtitle, and the start CTA. Renders
+ * `children` (the main app) once the session has started.
+ *
+ * @example
+ * ```tsx
+ * import { ChatView, StartScreen } from "@alexkroman1/aai-ui";
+ *
+ * function MyAgent() {
+ *   return (
+ *     <StartScreen icon="🍕" title="Pizza Palace" subtitle="Voice-powered ordering">
+ *       <ChatView />
+ *     </StartScreen>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Start-screen props.
+ *
+ * @public
+ */
+export declare function StartScreen({ children, icon, title, subtitle, buttonText, className, }: {
+    /** The app, rendered once the session has started. */
+    children: ReactNode;
+    /** Element rendered in place of the logo on the card. */
+    icon?: ReactNode | undefined;
+    /** The card's serif title. Defaults to the agent's declared name. */
+    title?: string | undefined;
+    /** A line under the title. */
+    subtitle?: string | undefined;
+    /** Label of the start CTA. Defaults to `"Start Conversation"`. */
+    buttonText?: string | undefined;
+    /** Additional CSS class names for the root element, appended to its own. */
+    className?: string | undefined;
+}): ReactNode;

package/dist/components/start-screen.js

@@ -0,0 +1,71 @@
+import { useSessionCore, useSessionSelector, useTheme } from "../context.js";
+import { a as inkTint } from "../_colors-CpZO-88A.js";
+import { Button } from "./button.js";
+import { t as AaiLogo } from "../aai-logo-D8pMVn9_.js";
+import { t as Eyebrow } from "../eyebrow-UfmSz9yy.js";
+import clsx from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/start-screen.tsx
+/** @jsxImportSource react */
+/**
+* A centered start screen: a white card on the cream page with the logo, an
+* eyebrow label, a serif title, subtitle, and the start CTA. Renders
+* `children` (the main app) once the session has started.
+*
+* @example
+* ```tsx
+* import { ChatView, StartScreen } from "@alexkroman1/aai-ui";
+*
+* function MyAgent() {
+*   return (
+*     <StartScreen icon="🍕" title="Pizza Palace" subtitle="Voice-powered ordering">
+*       <ChatView />
+*     </StartScreen>
+*   );
+* }
+* ```
+*
+* @param props - Start-screen props.
+*
+* @public
+*/
+function StartScreen({ children, icon, title, subtitle, buttonText = "Start Conversation", className }) {
+	const started = useSessionSelector((s) => s.started);
+	const { start } = useSessionCore();
+	const theme = useTheme();
+	if (started) return children;
+	return /* @__PURE__ */ jsx("div", {
+		className: clsx("flex items-center justify-center h-screen font-aai", className),
+		style: { background: theme.bg },
+		children: /* @__PURE__ */ jsxs("div", {
+			className: "flex flex-col items-center gap-5 border rounded-xl px-10 py-12 sm:px-16 sm:py-14 max-w-105 text-center",
+			style: {
+				background: theme.surface,
+				borderColor: theme.border,
+				boxShadow: "0 4px 12px -2px rgb(20 18 12 / 0.08)"
+			},
+			children: [
+				icon ?? /* @__PURE__ */ jsx(AaiLogo, { size: 24 }),
+				/* @__PURE__ */ jsx(Eyebrow, { children: "Voice Agent" }),
+				title && /* @__PURE__ */ jsx("h1", {
+					className: "font-aai-serif font-normal text-[32px] leading-[1.15] tracking-[-0.2px] m-0 text-balance",
+					style: { color: theme.text },
+					children: title
+				}),
+				subtitle && /* @__PURE__ */ jsx("p", {
+					className: "text-[15px] leading-[22px] m-0 max-w-75",
+					style: { color: inkTint(theme.text, theme.surface, 75) },
+					children: subtitle
+				}),
+				/* @__PURE__ */ jsx(Button, {
+					size: "lg",
+					className: "mt-2",
+					onClick: start,
+					children: buttonText
+				})
+			]
+		})
+	});
+}
+//#endregion
+export { StartScreen };

package/dist/components/tool-call-block.d.ts

@@ -0,0 +1,28 @@
+/** @jsxImportSource react */
+import { type ReactNode } from "react";
+import type { ToolCallInfo } from "../types.ts";
+/**
+ * Renders a tool invocation as the design system's console row (see
+ * `ToolCallRow`): a small outlined "TOOL" chip (or the tool's configured
+ * icon), the tool name in mono, a truncated args preview, and a rotating
+ * chevron that expands the formatted result.
+ *
+ * Tool display is configured via `ToolConfigContext`. If no config is found
+ * for a tool name, the raw tool name is shown as the title.
+ *
+ * While the tool call is pending a shimmer animation is shown. Once
+ * complete, clicking the row expands the formatted JSON result.
+ *
+ * Memoized: tool-call objects are referentially stable across session
+ * snapshots and rows are keyed on the stable `callId`, so a list update only
+ * re-renders the rows whose tool call actually changed.
+ *
+ * @param toolCall - The tool call to render (see {@link ToolCallInfo}).
+ * @param className - Additional CSS class names.
+ *
+ * @internal Not exported from the package — rendered by `MessageList`.
+ */
+export declare const ToolCallBlock: import("react").MemoExoticComponent<({ toolCall, className, }: {
+    toolCall: ToolCallInfo;
+    className?: string;
+}) => ReactNode>;

package/dist/components/tool-call-block.js

@@ -0,0 +1,3 @@
+import "../context.js";
+import { t as ToolCallBlock } from "../tool-call-block-uXtMOUWN.js";
+export { ToolCallBlock };

package/dist/components/tool-call-row.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from "react";
+/**
+ * Size preset for {@link ToolCallRow}: `"default"` is the deployed agent
+ * UI's scale, `"compact"` the studio transcript's denser one.
+ *
+ * @public
+ */
+export type ToolCallRowVariant = "default" | "compact";
+/**
+ * Props for {@link ToolCallRow}.
+ *
+ * @public
+ */
+export interface ToolCallRowProps {
+    /** Tool title, rendered in mono (shimmers while `pending`). */
+    title: ReactNode;
+    /** One-line detail (typically an args preview), truncated to the row. */
+    detail?: ReactNode | undefined;
+    /** True while the call is in flight — animates the title with a shimmer. */
+    pending?: boolean | undefined;
+    /** Optional icon rendered in place of the outlined "TOOL" chip. */
+    icon?: ReactNode | undefined;
+    /** Size preset; defaults to `"default"`. */
+    variant?: ToolCallRowVariant | undefined;
+    /** Additional CSS class names for the outer container. */
+    className?: string | undefined;
+    /**
+     * Expanded panel content. When present the row is expandable: a chevron is
+     * shown and clicking toggles the panel. When absent the row is inert (the
+     * button is disabled). Content provides its own padding and typography;
+     * the panel supplies the top border, surface background, and a max height.
+     */
+    children?: ReactNode;
+}
+/**
+ * The design system's console row for one tool invocation: a small outlined
+ * "TOOL" chip (or a custom `icon`), the tool title in mono, a truncated
+ * detail preview, and a rotating chevron that expands to the panel content.
+ *
+ * Purely presentational — callers own the mapping from their tool-call data
+ * to `title`/`detail`/`pending` and the expanded panel. The deployed agent
+ * UI's message list renders it via its tool-call block, and the studio's
+ * chat transcript renders it with `variant="compact"`, so the two surfaces
+ * read as one component.
+ *
+ * Colors come from the nearest theme context (see {@link useTheme}); without
+ * a provider the default AssemblyAI theme applies.
+ *
+ * @example
+ * ```tsx
+ * import { ToolCallRow, useSession } from "@alexkroman1/aai-ui";
+ *
+ * // A custom chrome's tool log, from the snapshot's own `toolCalls`.
+ * function ToolLog() {
+ *   const { toolCalls } = useSession();
+ *   return (
+ *     <div>
+ *       {toolCalls.map((call) => (
+ *         <ToolCallRow
+ *           key={call.callId}
+ *           title={call.name}
+ *           detail={call.result}
+ *           pending={call.status === "pending"}
+ *         />
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - See {@link ToolCallRowProps}.
+ *
+ * @public
+ */
+export declare function ToolCallRow({ title, detail, pending, icon, variant, className, children, }: ToolCallRowProps): ReactNode;

package/dist/components/tool-config-context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Display configuration for a tool call in the UI.
+ *
+ * @public
+ */
+export type ToolDisplayConfig = Record<string, {
+    icon?: string;
+    label?: string;
+}>;
+/**
+ * Context for tool display configuration. Installed by `mountClient()` from
+ * `ClientConfig.tools`; the built-in components read it via `useToolConfig`.
+ *
+ * @internal
+ */
+export declare const ToolConfigContext: import("react").Context<ToolDisplayConfig>;
+/**
+ * Read tool display configuration from the nearest `ToolConfigContext.Provider`.
+ *
+ * @internal
+ */
+export declare function useToolConfig(): ToolDisplayConfig;

package/dist/components/upload-progress.d.ts

@@ -0,0 +1,76 @@
+import { type ReactNode } from "react";
+import type { UploadStatus } from "../use-workflow-form.ts";
+/**
+ * How far a form's files have got, rendered as a bar.
+ *
+ * The wait this covers is the one a run cannot describe: a workflow run does not
+ * EXIST until its input is stored, so from the moment a form is submitted until
+ * the last byte lands there is no run id, no status, and nothing for
+ * `<WorkflowProgress>` to read — which for a 200 MB recording is minutes of a
+ * page that looks stuck. `useWorkflowSubmit` reports the bytes as they go and
+ * this is what draws them.
+ *
+ * Three things it decides, so a page does not:
+ *
+ * - **It renders nothing when there is nothing to describe.** `upload` is
+ *   undefined before the first byte and again from the moment the last one
+ *   lands, so `<UploadProgressBar upload={upload} />` is correct unguarded and a
+ *   form with no files never shows a bar at all.
+ * - **An unknown total is INDETERMINATE, not zero.** A body whose length the
+ *   transport cannot state up front (see `UploadProgress.total`) has no honest
+ *   width, and a bar pinned at 0% reads as an upload that is not moving.
+ * - **The file is NAMED, and counted when there is more than one.** Files are
+ *   sent one after another, so a single bar otherwise appears to restart from
+ *   zero partway through with nothing to say why.
+ * - **A paused upload SAYS SO, rather than being a bar that stopped.** Those look
+ *   identical, which is the whole reason `UploadStatus.paused` exists, and the
+ *   fill stops animating so the difference is visible without reading.
+ *
+ * The pause control appears only when a handler for it is passed. That is not
+ * politeness about props: a button whose press does nothing is worse than no
+ * button, and a page holding an `upload` it did not produce (a saved status, a
+ * parent's state) has nothing to pause.
+ *
+ * @example
+ * ```tsx no-check
+ * import { Form, SubmitButton, UploadProgressBar, useWorkflowSubmit, WorkflowFields } from "@alexkroman1/aai-ui";
+ * import type { transcribe } from "./agent.ts";
+ *
+ * function TranscribeForm() {
+ *   const { submitForm, upload, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
+ *   return (
+ *     <Form onSubmit={submitForm} error={error}>
+ *       <WorkflowFields workflow="transcribe" />
+ *       <UploadProgressBar upload={upload} />
+ *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Progress-bar props.
+ *
+ * @public
+ */
+export declare function UploadProgressBar({ upload, onPause, onResume, className, }: {
+    /**
+     * What `useWorkflowSubmit` / `useWorkflowStream` report as `upload`.
+     * `undefined` renders nothing, so a page may pass its state straight through
+     * and never guard the element.
+     */
+    upload?: UploadStatus | undefined;
+    /**
+     * The hook's `pauseUpload`. **Pass it together with `onResume`** to get the
+     * pause control; pass neither for a bar that only reports. One without the
+     * other is a one-way door drawn as a toggle, so the control is hidden unless
+     * both are present.
+     */
+    onPause?: (() => void) | undefined;
+    /** The hook's `resumeUpload`. See `onPause` — the two travel together. */
+    onResume?: (() => void) | undefined;
+    /**
+     * **Replaces** the default classes rather than extending them, so a custom
+     * chrome is not fighting a default it did not ask for.
+     */
+    className?: string | undefined;
+}): ReactNode;

package/dist/components/url-chips.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The session's shareable UI URL — the page this UI is served from, what
+ * you'd send someone to talk to the agent.
+ *
+ * @internal
+ */
+export declare function UiUrlChip({ className }: {
+    className?: string | undefined;
+}): import("react").JSX.Element;
+/**
+ * The session's programmatic WebSocket endpoint — the URL a script or backend
+ * can connect to directly instead of using this UI.
+ *
+ * @internal
+ */
+export declare function ApiUrlChip({ className }: {
+    className?: string | undefined;
+}): import("react").JSX.Element;
+/**
+ * The UI and API URLs side by side. They answer the same question — "how do I
+ * reach this agent?" — so they belong together and each needs its label to be
+ * told apart. Rendered by the default shell in every session mode (S2S,
+ * pipeline).
+ *
+ * @internal
+ */
+export declare function SessionUrlChips({ className }: {
+    className?: string | undefined;
+}): import("react").JSX.Element;

package/dist/components/workflow-fields.d.ts

@@ -0,0 +1,46 @@
+import type { WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+/**
+ * Render one field per scalar property of a workflow's input schema.
+ *
+ * Pass the workflow's NAME and the schema is fetched here; pass a
+ * {@link WorkflowSummary} you already hold and nothing is fetched. The name form
+ * is the one a page usually wants — it is the same string the submit hook takes,
+ * and the alternative is three lines (`useWorkflows()`, a `.find()` by name, and
+ * folding that lookup's error into the form's) whose only product is this
+ * component's argument.
+ *
+ * Renders nothing when the workflow declared no schema — a workflow with no
+ * declared input takes anything, and a form for "anything" is not a form — and
+ * nothing while a named lookup is still in flight, so the hand-written fields
+ * beside it are not reordered when the schema lands.
+ *
+ * @example
+ * ```tsx no-check
+ * import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
+ *   from "@alexkroman1/aai-ui";
+ * import type { transcribe } from "./agent.ts";
+ *
+ * function StartRun() {
+ *   const { submitForm, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
+ *   return (
+ *     <Form onSubmit={submitForm} error={error}>
+ *       <WorkflowFields workflow="transcribe" />
+ *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Field-set props.
+ *
+ * @public
+ */
+export declare function WorkflowFields({ workflow, }: {
+    /**
+     * The workflow whose input schema to render. A NAME is looked up here (one
+     * `GET workflows`); a {@link WorkflowSummary} the page already holds fetches
+     * nothing. `undefined` renders nothing, so a page may pass a selection
+     * straight through before one is made.
+     */
+    workflow?: WorkflowSummary | string | undefined;
+}): import("react").JSX.Element | null;