@alexkroman1/aai-ui 5.13.2 → 6.1.0

package/dist/{message-list-YdLocGoT.js → message-list-BwA3rdPi.js}

@@ -1,12 +1,82 @@
 import { useSessionSelector, useTheme } from "./context.js";
 import { i as primaryTint, r as inkTint } from "./_colors-CcAi2FOU.js";
-import { t as ToolCallBlock } from "./tool-call-block-CAscLGFy.js";
+import { t as ToolCallBlock } from "./tool-call-block-CrLN7xlI.js";
 import clsx from "clsx";
-import { memo, useMemo } from "react";
-import { jsx, jsxs } from "react/jsx-runtime";
 import { StickToBottom } from "use-stick-to-bottom";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useMemo } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
+//#region components/auto-scroll.tsx
+/** @jsxImportSource react */
+/**
+* A scroll container that stays pinned to the bottom as its content grows,
+* releases when the reader scrolls up, and re-engages once they return to the
+* bottom.
+*
+* For clients that render their own chat chrome instead of using
+* {@link MessageList} — a terminal, a dispatch board, a themed transcript.
+* `MessageList` already behaves this way; this is the same mechanism with no
+* opinion about what goes inside it.
+*
+* @remarks
+* The pattern this replaces is a `useEffect` that calls
+* `ref.current?.scrollIntoView()` on every message change. That version has
+* three faults, and they compound: it fights the reader, since scrolling up to
+* re-read is undone by the next transcript delta; it misses growth that is not
+* a new message, because a streamed reply, an expanding tool block or a
+* markdown reflow changes height without changing the dependency array; and it
+* needs a synthetic dependency (`messages.length + transcript.length`) to fire
+* at all, which is where the dead `if (version < 0) return;` line comes from.
+* A `ResizeObserver` on the content — what this uses — has none of those.
+*
+* @example
+* ```tsx
+* import { AutoScroll, useSession } from "@alexkroman1/aai-ui";
+*
+* function Transcript() {
+*   const session = useSession();
+*   return (
+*     <AutoScroll className="flex-1 min-h-0" contentClassName="flex flex-col gap-2 p-4">
+*       {session.messages.map((m) => (
+*         <div key={m.id}>{m.content}</div>
+*       ))}
+*     </AutoScroll>
+*   );
+* }
+* ```
+*
+* @param children - The scrollable content.
+* @param className - Classes for the outer container. It must be given a
+*   bounded height (`flex-1 min-h-0`, `h-full`, a fixed height) — an unbounded
+*   one grows with its content and never scrolls, so nothing pins.
+* @param contentClassName - Classes for the inner content element, where
+*   padding and the children's own layout belong.
+* @param scrollClassName - Classes for the scrolling element itself. Defaults
+*   to hiding the scrollbar; pass `"overflow-y-auto"` to show a native one.
+* @param style - Inline styles for the outer container.
+* @param initial - Scroll behavior on mount. Defaults to `"instant"` (start at
+*   the latest content without animating a scroll the reader did not ask for).
+* @param resize - Scroll behavior when pinned content grows. Defaults to
+*   `"smooth"`.
+*
+* @public
+*/
+function AutoScroll({ children, className, contentClassName, scrollClassName = "overflow-y-auto [scrollbar-width:none]", style, initial = "instant", resize = "smooth" }) {
+	return /* @__PURE__ */ jsx(StickToBottom, {
+		role: "log",
+		className: clsx("flex-1 min-h-0", className),
+		style,
+		initial,
+		resize,
+		children: /* @__PURE__ */ jsx(StickToBottom.Content, {
+			scrollClassName,
+			className: contentClassName,
+			children
+		})
+	});
+}
+//#endregion
 //#region components/markdown.tsx
 /** @jsxImportSource react */
 const BARE_ORDERED_MARKER = /^(\s*)(\d{1,9})([.)])\s*$/;
@@ -191,11 +261,25 @@ const DOT_STYLES = [
 	animation: "aai-bounce 1.4s infinite ease-in-out both",
 	animationDelay: `${delay}s`
 }));
-/** Animated three-dot "thinking" indicator. @internal */
+/**
+* Animated three-dot "thinking" indicator.
+*
+* `role="status"` with a label, for the same reason `ConsoleShell` announces
+* its error banner: three animated dots are the only signal that the agent is
+* working on a reply, and to a screen reader they are three empty `<div>`s.
+* It is also the indicator's semantic handle — a spec asserting its presence by
+* counting `.rounded-full` elements breaks when the three dots become a spinner
+* (correct behaviour, red test) and again when any sibling row gains a round
+* badge (wrong behaviour, green test).
+*
+* @internal
+*/
 function ThinkingDots() {
 	const theme = useTheme();
 	const muted = inkTint(theme.text, theme.surface, 75);
 	return /* @__PURE__ */ jsx("div", {
+		role: "status",
+		"aria-label": "Thinking",
 		className: "flex items-center gap-2 text-sm font-medium min-h-5",
 		style: { color: muted },
 		children: DOT_STYLES.map((style, i) => /* @__PURE__ */ jsx("div", {
@@ -332,30 +416,24 @@ const MessageList = memo(function MessageList({ className }) {
 		toolCalls,
 		theme
 	]);
-	return /* @__PURE__ */ jsx(StickToBottom, {
-		role: "log",
-		className: clsx("flex-1 min-h-0", className),
+	return /* @__PURE__ */ jsxs(AutoScroll, {
+		className,
 		style: { background: theme.surface },
-		initial: "instant",
-		resize: "smooth",
-		children: /* @__PURE__ */ jsxs(StickToBottom.Content, {
-			scrollClassName: "overflow-y-auto [scrollbar-width:none]",
-			className: "flex flex-col gap-4 p-7",
-			children: [
-				items,
-				streamingMessage && /* @__PURE__ */ jsx(MessageBubble, {
-					message: streamingMessage,
-					theme
-				}),
-				userTranscript !== null && /* @__PURE__ */ jsx(UserBubble, {
-					theme,
-					color: inkTint(theme.text, theme.surface, 65),
-					children: userTranscript ? userTranscript : /* @__PURE__ */ jsx(ThinkingDots, {})
-				}),
-				showThinking && /* @__PURE__ */ jsx(ThinkingDots, {})
-			]
-		})
+		contentClassName: "flex flex-col gap-4 p-7",
+		children: [
+			items,
+			streamingMessage && /* @__PURE__ */ jsx(MessageBubble, {
+				message: streamingMessage,
+				theme
+			}),
+			userTranscript !== null && /* @__PURE__ */ jsx(UserBubble, {
+				theme,
+				color: inkTint(theme.text, theme.surface, 65),
+				children: userTranscript ? userTranscript : /* @__PURE__ */ jsx(ThinkingDots, {})
+			}),
+			showThinking && /* @__PURE__ */ jsx(ThinkingDots, {})
+		]
 	});
 });
 //#endregion
-export { Markdown as n, MessageList as t };
+export { Markdown as n, AutoScroll as r, MessageList as t };

package/dist/page.d.ts

@@ -0,0 +1,88 @@
+/** @jsxImportSource react */
+/**
+ * `page()` — mount a WORKFLOW APP's UI: React, theme, no session.
+ *
+ * The twin of `client()` for an agent whose front door is a form rather than a
+ * microphone (`workflowApp()`). It is a separate entry rather than
+ * an option on `client()` because of what `client()` unavoidably does: it
+ * constructs a `SessionCore`, which owns a WebSocket URL provider, an audio
+ * graph, and a microphone request. A flag would have to make all of that
+ * conditional, and every session hook would then have to answer "what does this
+ * mean with no session?" — so the honest split is two mounts. A page that wants
+ * voice uses `client()`; a page that wants neither audio nor a socket uses this.
+ *
+ * Authoring is otherwise identical — the file is still `client.tsx`, still
+ * React, still Tailwind, still the same theme tokens — so a workflow app reads
+ * like every other agent. What it reaches for instead of `useSession()` is
+ * `createWorkflowApi()` / `useWorkflowRun()`.
+ */
+import { type ComponentType } from "react";
+import type { ClientTheme } from "./types.ts";
+/**
+ * Configuration for {@link page}.
+ *
+ * @public
+ */
+export type PageConfig = {
+    /**
+     * The root component. Required — a workflow app has no default shell to fall
+     * back to, because there is no session for one to render.
+     */
+    component: ComponentType;
+    /** CSS selector or DOM element to render into. Defaults to `"#app"`. */
+    target?: string | HTMLElement;
+    /**
+     * Page title. Set only when given, so a title the HTML shell declared is never
+     * clobbered — the same rule `client()`'s custom-component tier follows.
+     */
+    name?: string;
+    /** Theme color overrides, read by the same tokens the voice components use. */
+    theme?: ClientTheme;
+};
+/**
+ * Handle returned by {@link page}. `Disposable`, so `using` works.
+ *
+ * @public
+ */
+export type PageHandle = {
+    /** Unmount the React tree. */
+    dispose(): void;
+    /** Alias for `dispose` for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * Mount a page for an agent whose work happens in workflows.
+ *
+ * There is deliberately no session, no microphone, and no socket: the component
+ * talks to the agent over the workflow HTTP API
+ * (`createWorkflowApi`/`useWorkflowRun`), which is durable and outlives the tab.
+ *
+ * @example
+ * ```tsx
+ * import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+ * import { useState } from "react";
+ *
+ * // Hoisted: a client built in render is a new object every render.
+ * const api = createWorkflowApi();
+ *
+ * function App() {
+ *   const [runId, setRunId] = useState<string>();
+ *   const { run } = useWorkflowRun(runId, { api });
+ *   return (
+ *     <button
+ *       type="button"
+ *       onClick={() => void api.start("digest", { topic: "ai" }).then(setRunId)}
+ *     >
+ *       {run ? run.status : "Start"}
+ *     </button>
+ *   );
+ * }
+ *
+ * page({ name: "Digest", component: App });
+ * ```
+ *
+ * @throws If the target element is not found in the DOM.
+ *
+ * @public
+ */
+export declare function page(config: PageConfig): PageHandle;