@alexkroman1/aai-ui 0.9.3 → 0.10.0

package/dist/_components/app.d.ts

@@ -1,5 +1,23 @@
 import type * as preact from "preact";
-/** @public */
+/**
+ * The default top-level UI component for an AAI voice agent.
+ * Renders a {@link StartScreen} (with the AAI logo or a custom title from
+ * {@link useMountConfig}) followed by a {@link ChatView} once the session starts.
+ *
+ * This is the component rendered by {@link mount} when no custom component is
+ * provided.
+ *
+ * @example
+ * ```tsx
+ * import { App, mount } from "@aai/ui";
+ *
+ * mount(App, { target: "#app", title: "My Agent" });
+ * ```
+ *
+ * @param className - Additional CSS class names applied to the root element.
+ *
+ * @public
+ */
 export declare function App({ className }: {
     className?: string;
 }): preact.JSX.Element;

package/dist/_components/app.js

@@ -9,7 +9,25 @@ function AnsiLogo() {
 		children: "▄▀█ ▄▀█ █\n█▀█ █▀█ █"
 	});
 }
-/** @public */
+/**
+* The default top-level UI component for an AAI voice agent.
+* Renders a {@link StartScreen} (with the AAI logo or a custom title from
+* {@link useMountConfig}) followed by a {@link ChatView} once the session starts.
+*
+* This is the component rendered by {@link mount} when no custom component is
+* provided.
+*
+* @example
+* ```tsx
+* import { App, mount } from "@aai/ui";
+*
+* mount(App, { target: "#app", title: "My Agent" });
+* ```
+*
+* @param className - Additional CSS class names applied to the root element.
+*
+* @public
+*/
 function App({ className }) {
 	const { title } = useMountConfig();
 	return /* @__PURE__ */ jsx(StartScreen, {

package/dist/_components/button.d.ts

@@ -1,11 +1,50 @@
 import type * as preact from "preact";
-type ButtonVariant = "default" | "secondary" | "ghost";
-type ButtonSize = "default" | "lg";
-/** @public */
+/**
+ * Visual style of a {@link Button}.
+ *
+ * - `"default"` — Primary filled button (accent background).
+ * - `"secondary"` — Muted surface background with border.
+ * - `"ghost"` — Transparent background with border.
+ *
+ * @public
+ */
+export type ButtonVariant = "default" | "secondary" | "ghost";
+/**
+ * Size preset for a {@link Button}.
+ *
+ * - `"default"` — Compact (height 2rem / 32 px).
+ * - `"lg"` — Large with generous padding, suitable for primary CTAs.
+ *
+ * @public
+ */
+export type ButtonSize = "default" | "lg";
+/**
+ * A styled button with variant and size presets.
+ *
+ * Accepts all standard `<button>` HTML attributes in addition to the props
+ * listed below.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="secondary" onClick={handleClick}>
+ *   Stop
+ * </Button>
+ *
+ * <Button size="lg" className="w-full">
+ *   Start Conversation
+ * </Button>
+ * ```
+ *
+ * @param variant - Visual style (`"default"` | `"secondary"` | `"ghost"`). Defaults to `"default"`.
+ * @param size - Size preset (`"default"` | `"lg"`). Defaults to `"default"`.
+ * @param className - Additional CSS class names.
+ * @param children - Button label / content.
+ *
+ * @public
+ */
 export declare function Button({ variant, size, className, children, ...rest }: {
     variant?: ButtonVariant;
     size?: ButtonSize;
     className?: string;
     children?: preact.ComponentChildren;
 } & Omit<preact.JSX.HTMLAttributes<HTMLButtonElement>, "className">): preact.JSX.Element;
-export {};

package/dist/_components/button.js

@@ -1,18 +1,42 @@
 import clsx from "clsx";
 import { jsx } from "preact/jsx-runtime";
 //#region _components/button.tsx
-/** @public */
+const LG_STYLE = {
+	display: "grid",
+	placeItems: "center",
+	appearance: "none",
+	margin: 0,
+	padding: "12px 32px",
+	lineHeight: 1
+};
+/**
+* A styled button with variant and size presets.
+*
+* Accepts all standard `<button>` HTML attributes in addition to the props
+* listed below.
+*
+* @example
+* ```tsx
+* <Button variant="secondary" onClick={handleClick}>
+*   Stop
+* </Button>
+*
+* <Button size="lg" className="w-full">
+*   Start Conversation
+* </Button>
+* ```
+*
+* @param variant - Visual style (`"default"` | `"secondary"` | `"ghost"`). Defaults to `"default"`.
+* @param size - Size preset (`"default"` | `"lg"`). Defaults to `"default"`.
+* @param className - Additional CSS class names.
+* @param children - Button label / content.
+*
+* @public
+*/
 function Button({ variant = "default", size = "default", className, children, ...rest }) {
 	return /* @__PURE__ */ jsx("button", {
 		type: "button",
-		style: size === "lg" ? {
-			display: "grid",
-			placeItems: "center",
-			appearance: "none",
-			margin: 0,
-			padding: "12px 32px",
-			lineHeight: 1
-		} : void 0,
+		style: size === "lg" ? LG_STYLE : void 0,
 		class: clsx(size !== "lg" && "flex items-center justify-center appearance-none m-0 h-8 px-3 py-1.5 w-fit leading-none", "rounded-aai text-sm font-medium cursor-pointer border outline-none", variant === "secondary" && "bg-aai-surface-hover text-aai-text-secondary border-aai-border", variant === "ghost" && "bg-transparent text-aai-text-secondary border-aai-border", variant === "default" && "bg-aai-primary text-white border-transparent", className),
 		...rest,
 		children

package/dist/_components/chat-view.d.ts

@@ -1,5 +1,29 @@
 import type * as preact from "preact";
-/** @public */
+/**
+ * The main chat interface for a voice agent session.
+ * Displays a header (with title and {@link StateIndicator}), an
+ * {@link ErrorBanner}, the {@link MessageList}, and session {@link Controls}.
+ *
+ * Must be rendered inside a {@link SessionProvider}.
+ *
+ * @example
+ * ```tsx
+ * <StartScreen icon="🍕" title="Pizza Palace">
+ *   <ChatView />
+ * </StartScreen>
+ * ```
+ *
+ * @example Pair with a sidebar
+ * ```tsx
+ * <SidebarLayout sidebar={<RecipeCard />}>
+ *   <ChatView className="border-l" />
+ * </SidebarLayout>
+ * ```
+ *
+ * @param className - Additional CSS class names applied to the root element.
+ *
+ * @public
+ */
 export declare function ChatView({ className }: {
     className?: string;
 }): preact.JSX.Element;

package/dist/_components/chat-view.js

@@ -7,7 +7,31 @@ import { StateIndicator } from "./state-indicator.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "preact/jsx-runtime";
 //#region _components/chat-view.tsx
-/** @public */
+/**
+* The main chat interface for a voice agent session.
+* Displays a header (with title and {@link StateIndicator}), an
+* {@link ErrorBanner}, the {@link MessageList}, and session {@link Controls}.
+*
+* Must be rendered inside a {@link SessionProvider}.
+*
+* @example
+* ```tsx
+* <StartScreen icon="🍕" title="Pizza Palace">
+*   <ChatView />
+* </StartScreen>
+* ```
+*
+* @example Pair with a sidebar
+* ```tsx
+* <SidebarLayout sidebar={<RecipeCard />}>
+*   <ChatView className="border-l" />
+* </SidebarLayout>
+* ```
+*
+* @param className - Additional CSS class names applied to the root element.
+*
+* @public
+*/
 function ChatView({ className }) {
 	const { session } = useSession();
 	const { title } = useMountConfig();

package/dist/_components/controls.d.ts

@@ -1,4 +1,18 @@
-/** @public */
+/**
+ * Session control buttons: **Stop / Resume** and **New Conversation**.
+ *
+ * Reads session state from {@link useSession}. Must be rendered inside a
+ * {@link SessionProvider}.
+ *
+ * @example
+ * ```tsx
+ * <Controls className="justify-end" />
+ * ```
+ *
+ * @param className - Additional CSS class names applied to the container.
+ *
+ * @public
+ */
 export declare function Controls({ className }: {
     className?: string;
 }): import("preact").JSX.Element;

package/dist/_components/controls.js

@@ -3,7 +3,21 @@ import { Button } from "./button.js";
 import clsx from "clsx";
 import { jsx, jsxs } from "preact/jsx-runtime";
 //#region _components/controls.tsx
-/** @public */
+/**
+* Session control buttons: **Stop / Resume** and **New Conversation**.
+*
+* Reads session state from {@link useSession}. Must be rendered inside a
+* {@link SessionProvider}.
+*
+* @example
+* ```tsx
+* <Controls className="justify-end" />
+* ```
+*
+* @param className - Additional CSS class names applied to the container.
+*
+* @public
+*/
 function Controls({ className }) {
 	const { running, toggle, reset } = useSession();
 	return /* @__PURE__ */ jsxs("div", {

package/dist/_components/error-banner.d.ts

@@ -1,6 +1,20 @@
 import type * as preact from "preact";
 import type { Reactive, SessionError } from "../types.ts";
-/** @public */
+/**
+ * Displays a session error as a styled inline banner.
+ * Returns `null` when there is no active error.
+ *
+ * @example
+ * ```tsx
+ * const { session } = useSession();
+ * <ErrorBanner error={session.error} />
+ * ```
+ *
+ * @param error - A reactive {@link SessionError} (or `null`).
+ * @param className - Additional CSS class names.
+ *
+ * @public
+ */
 export declare function ErrorBanner({ error, className, }: {
     error: Reactive<SessionError | null>;
     className?: string;

package/dist/_components/error-banner.js

@@ -1,7 +1,21 @@
 import clsx from "clsx";
 import { jsx } from "preact/jsx-runtime";
 //#region _components/error-banner.tsx
-/** @public */
+/**
+* Displays a session error as a styled inline banner.
+* Returns `null` when there is no active error.
+*
+* @example
+* ```tsx
+* const { session } = useSession();
+* <ErrorBanner error={session.error} />
+* ```
+*
+* @param error - A reactive {@link SessionError} (or `null`).
+* @param className - Additional CSS class names.
+*
+* @public
+*/
 function ErrorBanner({ error, className }) {
 	if (!error.value) return null;
 	return /* @__PURE__ */ jsx("div", {

package/dist/_components/message-bubble.d.ts

@@ -1,7 +1,23 @@
 import type * as preact from "preact";
-import type { Message } from "../types.ts";
-/** @public */
+import type { ChatMessage } from "../types.ts";
+/**
+ * Renders a single chat message as a styled bubble.
+ *
+ * - **User** messages appear right-aligned with a faint surface background.
+ * - **Assistant** messages appear left-aligned as plain text.
+ *
+ * @example
+ * ```tsx
+ * <MessageBubble message={{ role: "user", content: "Hello!" }} />
+ * <MessageBubble message={{ role: "assistant", content: "Hi there!" }} />
+ * ```
+ *
+ * @param message - The chat message to display (see {@link ChatMessage}).
+ * @param className - Additional CSS class names applied to the root element.
+ *
+ * @public
+ */
 export declare function MessageBubble({ message, className, }: {
-    message: Message;
+    message: ChatMessage;
     className?: string;
 }): preact.JSX.Element;

package/dist/_components/message-bubble.js

@@ -1,7 +1,23 @@
 import clsx from "clsx";
 import { jsx } from "preact/jsx-runtime";
 //#region _components/message-bubble.tsx
-/** @public */
+/**
+* Renders a single chat message as a styled bubble.
+*
+* - **User** messages appear right-aligned with a faint surface background.
+* - **Assistant** messages appear left-aligned as plain text.
+*
+* @example
+* ```tsx
+* <MessageBubble message={{ role: "user", content: "Hello!" }} />
+* <MessageBubble message={{ role: "assistant", content: "Hi there!" }} />
+* ```
+*
+* @param message - The chat message to display (see {@link ChatMessage}).
+* @param className - Additional CSS class names applied to the root element.
+*
+* @public
+*/
 function MessageBubble({ message, className }) {
 	if (message.role === "user") return /* @__PURE__ */ jsx("div", {
 		class: clsx("flex flex-col w-full items-end", className),

package/dist/_components/message-list.d.ts

@@ -1,4 +1,21 @@
-/** @public */
+/**
+ * Scrollable list of all chat messages, tool-call blocks, live transcript,
+ * streaming agent utterance, and a thinking indicator.
+ *
+ * Messages and tool calls are interleaved in the correct order. The list
+ * auto-scrolls to the latest content via {@link useAutoScroll}.
+ *
+ * Must be rendered inside a {@link SessionProvider}.
+ *
+ * @example
+ * ```tsx
+ * <MessageList className="flex-1" />
+ * ```
+ *
+ * @param className - Additional CSS class names applied to the scroll container.
+ *
+ * @public
+ */
 export declare function MessageList({ className }: {
     className?: string;
 }): import("preact").JSX.Element;

package/dist/_components/message-list.js

@@ -4,14 +4,31 @@ import { ThinkingIndicator } from "./thinking-indicator.js";
 import { ToolCallBlock } from "./tool-call-block.js";
 import { Transcript } from "./transcript.js";
 import clsx from "clsx";
-import { computed } from "@preact/signals";
+import { useComputed } from "@preact/signals";
 import { jsx, jsxs } from "preact/jsx-runtime";
 //#region _components/message-list.tsx
-/** @public */
+/**
+* Scrollable list of all chat messages, tool-call blocks, live transcript,
+* streaming agent utterance, and a thinking indicator.
+*
+* Messages and tool calls are interleaved in the correct order. The list
+* auto-scrolls to the latest content via {@link useAutoScroll}.
+*
+* Must be rendered inside a {@link SessionProvider}.
+*
+* @example
+* ```tsx
+* <MessageList className="flex-1" />
+* ```
+*
+* @param className - Additional CSS class names applied to the scroll container.
+*
+* @public
+*/
 function MessageList({ className }) {
 	const { session } = useSession();
 	const scrollRef = useAutoScroll();
-	const showThinking = computed(() => {
+	const showThinking = useComputed(() => {
 		if (session.state.value !== "thinking") return false;
 		const last = session.toolCalls.value.at(-1);
 		if (last?.status === "pending") return false;

package/dist/_components/state-indicator.d.ts

@@ -1,6 +1,28 @@
 import type * as preact from "preact";
 import type { AgentState, Reactive } from "../types.ts";
-/** @public */
+/**
+ * Colored dot + label showing the current {@link AgentState}.
+ *
+ * State-to-color mapping:
+ * - `disconnected` — gray
+ * - `connecting` — yellow
+ * - `ready` — green
+ * - `listening` — blue
+ * - `thinking` — purple
+ * - `speaking` — red
+ * - `error` — red
+ *
+ * @example
+ * ```tsx
+ * const { session } = useSession();
+ * <StateIndicator state={session.state} />
+ * ```
+ *
+ * @param state - A reactive {@link AgentState} value.
+ * @param className - Additional CSS class names.
+ *
+ * @public
+ */
 export declare function StateIndicator({ state, className, }: {
     state: Reactive<AgentState>;
     className?: string;

package/dist/_components/state-indicator.js

@@ -1,7 +1,29 @@
 import clsx from "clsx";
 import { jsx, jsxs } from "preact/jsx-runtime";
 //#region _components/state-indicator.tsx
-/** @public */
+/**
+* Colored dot + label showing the current {@link AgentState}.
+*
+* State-to-color mapping:
+* - `disconnected` — gray
+* - `connecting` — yellow
+* - `ready` — green
+* - `listening` — blue
+* - `thinking` — purple
+* - `speaking` — red
+* - `error` — red
+*
+* @example
+* ```tsx
+* const { session } = useSession();
+* <StateIndicator state={session.state} />
+* ```
+*
+* @param state - A reactive {@link AgentState} value.
+* @param className - Additional CSS class names.
+*
+* @public
+*/
 function StateIndicator({ state, className }) {
 	return /* @__PURE__ */ jsxs("div", {
 		class: clsx("inline-flex items-center justify-center gap-1.5 text-[13px] font-medium leading-[130%] text-aai-text-muted capitalize", className),

package/dist/_components/thinking-indicator.d.ts

@@ -1,5 +1,16 @@
 import type * as preact from "preact";
-/** @public */
+/**
+ * Animated three-dot "thinking" indicator shown while the agent is processing.
+ *
+ * @example
+ * ```tsx
+ * {isThinking && <ThinkingIndicator />}
+ * ```
+ *
+ * @param className - Additional CSS class names.
+ *
+ * @public
+ */
 export declare function ThinkingIndicator({ className }: {
     className?: string;
 }): preact.JSX.Element;

package/dist/_components/thinking-indicator.js

@@ -1,21 +1,33 @@
 import clsx from "clsx";
 import { jsx } from "preact/jsx-runtime";
 //#region _components/thinking-indicator.tsx
-/** @public */
+const DOT_STYLES = [
+	0,
+	.16,
+	.32
+].map((delay) => ({
+	animation: "aai-bounce 1.4s infinite ease-in-out both",
+	animationDelay: `${delay}s`
+}));
+/**
+* Animated three-dot "thinking" indicator shown while the agent is processing.
+*
+* @example
+* ```tsx
+* {isThinking && <ThinkingIndicator />}
+* ```
+*
+* @param className - Additional CSS class names.
+*
+* @public
+*/
 function ThinkingIndicator({ className }) {
 	return /* @__PURE__ */ jsx("div", {
 		class: clsx("flex items-center gap-2 text-aai-text-dim text-sm font-medium min-h-5", className),
-		children: [
-			0,
-			.16,
-			.32
-		].map((delay) => /* @__PURE__ */ jsx("div", {
+		children: DOT_STYLES.map((style, i) => /* @__PURE__ */ jsx("div", {
 			class: "w-1.5 h-1.5 rounded-full bg-aai-text-dim",
-			style: {
-				animation: "aai-bounce 1.4s infinite ease-in-out both",
-				animationDelay: `${delay}s`
-			}
-		}, delay))
+			style
+		}, i))
 	});
 }
 //#endregion

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

@@ -1,6 +1,26 @@
 import type * as preact from "preact";
 import type { ToolCallInfo } from "../types.ts";
-/** @public */
+/**
+ * Renders a tool invocation with an icon, title, subtitle, and a
+ * collapsible result viewer.
+ *
+ * Built-in tool types (`web_search`, `visit_webpage`, `run_code`,
+ * `fetch_json`, `user_input`) get custom icons and labels. Unknown tools
+ * fall back to a generic bolt icon.
+ *
+ * While the tool call is pending a shimmer animation is shown. Once
+ * complete, clicking the block expands the formatted JSON result.
+ *
+ * @example
+ * ```tsx
+ * <ToolCallBlock toolCall={toolCall} />
+ * ```
+ *
+ * @param toolCall - The tool call to render (see {@link ToolCallInfo}).
+ * @param className - Additional CSS class names.
+ *
+ * @public
+ */
 export declare function ToolCallBlock({ toolCall, className, }: {
     toolCall: ToolCallInfo;
     className?: string;

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

@@ -1,6 +1,6 @@
 import { BoltIcon, ChatBubbleIcon, DownloadIcon, ExternalLinkIcon, SearchIcon, TerminalIcon } from "./tool-icons.js";
-import { useMemo, useState } from "preact/hooks";
 import clsx from "clsx";
+import { useComputed, useSignal } from "@preact/signals";
 import { jsx, jsxs } from "preact/jsx-runtime";
 //#region _components/tool-call-block.tsx
 const argField = (key) => (args) => String(args[key] ?? "");
@@ -49,22 +49,44 @@ function formatResult(result) {
 		return result;
 	}
 }
-/** @public */
+/**
+* Renders a tool invocation with an icon, title, subtitle, and a
+* collapsible result viewer.
+*
+* Built-in tool types (`web_search`, `visit_webpage`, `run_code`,
+* `fetch_json`, `user_input`) get custom icons and labels. Unknown tools
+* fall back to a generic bolt icon.
+*
+* While the tool call is pending a shimmer animation is shown. Once
+* complete, clicking the block expands the formatted JSON result.
+*
+* @example
+* ```tsx
+* <ToolCallBlock toolCall={toolCall} />
+* ```
+*
+* @param toolCall - The tool call to render (see {@link ToolCallInfo}).
+* @param className - Additional CSS class names.
+*
+* @public
+*/
 function ToolCallBlock({ toolCall, className }) {
-	const [isOpen, setOpen] = useState(false);
+	const isOpen = useSignal(false);
 	const config = TOOL_CONFIG[toolCall.toolName] ?? DEFAULT_CONFIG;
 	const isPending = toolCall.status === "pending";
 	const title = config.title || toolCall.toolName;
-	const canExpand = !isPending && !!toolCall.result;
-	const formatted = useMemo(() => toolCall.result ? formatResult(toolCall.result) : "", [toolCall.result]);
+	const canExpand = !isPending && Boolean(toolCall.result);
+	const formatted = useComputed(() => toolCall.result ? formatResult(toolCall.result) : "");
 	return /* @__PURE__ */ jsxs("div", {
 		class: clsx("flex flex-col", className),
 		children: [/* @__PURE__ */ jsxs("button", {
 			type: "button",
-			"aria-expanded": canExpand ? isOpen : void 0,
+			"aria-expanded": canExpand ? isOpen.value : void 0,
 			disabled: isPending,
 			class: clsx("flex items-center gap-2 px-3 py-2 rounded-aai border border-aai-border bg-aai-surface-faint select-none text-left w-full", canExpand && "cursor-pointer"),
-			onClick: () => canExpand && setOpen(!isOpen),
+			onClick: () => {
+				if (canExpand) isOpen.value = !isOpen.value;
+			},
 			children: [
 				/* @__PURE__ */ jsx(config.Icon, { class: "w-4 h-4 text-aai-text-dim shrink-0" }),
 				/* @__PURE__ */ jsx("span", {
@@ -77,17 +99,17 @@ function ToolCallBlock({ toolCall, className }) {
 				}),
 				canExpand && /* @__PURE__ */ jsx("span", {
 					class: "text-xs text-aai-text-dim shrink-0",
-					children: isOpen ? "▾" : "▸"
+					children: isOpen.value ? "▾" : "▸"
 				})
 			]
-		}), isOpen && /* @__PURE__ */ jsxs("div", {
+		}), isOpen.value && /* @__PURE__ */ jsxs("div", {
 			class: "border-x border-b border-aai-border rounded-b-aai bg-aai-surface max-h-64 overflow-auto",
 			children: [toolCall.toolName === "run_code" && toolCall.args.code && /* @__PURE__ */ jsx("pre", {
 				class: "text-xs text-aai-text p-2 whitespace-pre-wrap border-b border-aai-border font-mono",
 				children: String(toolCall.args.code)
-			}), formatted && /* @__PURE__ */ jsx("pre", {
+			}), formatted.value && /* @__PURE__ */ jsx("pre", {
 				class: "text-xs text-aai-text-dim p-2 whitespace-pre-wrap",
-				children: formatted
+				children: formatted.value
 			})]
 		})]
 	});