@elabs-ai/components-ai 4.0.0

package/src/tool-result-card.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+/**
+ * ToolResultCard — an artifact the agent PRODUCED, presented as the headline
+ * (#192, research 10 §B.4).
+ *
+ * The elevation channel of the surface-separation system (research 08 §H):
+ * raised fill + shadow, NO border (elevation is the separation gesture — a
+ * border here would be the redundant-border anti-pattern). A separate
+ * component from `Tool` by design: `Tool` owns the rail/inspect idiom (a step
+ * that ran, JSON behind disclosure); `ToolResultCard` hosts the produced
+ * chart/table/file as `children` — so an agent picks the channel by NAME,
+ * not by a behavioural mode flag.
+ *
+ * Presentational and dependency-light: it does NOT import `@elabs-ai/components-charts` or
+ * `@elabs-ai/components-data` (one-way dep graph) — the consumer passes the artifact (an
+ * `<AutoChart>`, `<DataTable>`, file preview, …) as children, and maps an
+ * AI-SDK tool state to `status` via `statusFromToolState` (tool.tsx).
+ *
+ * **The card owns artifact-scoped chrome in its header row** — `title |
+ * actions | status`, matching `ArtifactActions`, `DialogSection.actions` and
+ * `SectionHeader.actions` elsewhere in the system. `actions` is scoped to the
+ * artifact AS A WHOLE (expand it, download it, open it somewhere else); the
+ * payload's own controls — a chart's flip-to-table, a table's sort — stay in
+ * the payload's own frame, in the body. A card that hoisted them would present
+ * one row of buttons that act on two different things.
+ */
+import { StatusBadge, type Status } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+export interface ToolResultCardProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Headline of the produced artifact (`text-subtitle`). */
+  title?: ReactNode;
+  /** The business summary line under the title (`text-meta`), not JSON. */
+  summary?: ReactNode;
+  /** Canonical execution status (closed enum); renders a `StatusBadge`. */
+  status?: Status;
+  /**
+   * Controls scoped to the whole artifact — expand, download, open. Rendered in
+   * the header row between the title and the status.
+   *
+   * A `ReactNode` slot, not a `role="toolbar"`: that role promises roving-tabindex
+   * traversal, which this row does not implement. Keep the payload's own controls
+   * out of here (see the note at the top of this file).
+   */
+  actions?: ReactNode;
+  /**
+   * The technical view, kept behind disclosure — pass a default-collapsed
+   * `<ToolDetails>` holding `ToolInput`/`ToolOutput` (research 10 §B.5).
+   */
+  details?: ReactNode;
+}
+
+/** The produced artifact IS the headline; pass it as `children`. */
+export const ToolResultCard = forwardRef<HTMLDivElement, ToolResultCardProps>(
+  function ToolResultCard(
+    { title, summary, status, actions, details, className, children, ...props },
+    ref,
+  ) {
+    const hasHeader = title != null || summary != null || status != null || actions != null;
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "not-prose w-full space-y-3 rounded-lg bg-surface-elevated p-4 shadow-sm",
+          className,
+        )}
+        {...props}
+      >
+        {hasHeader ? (
+          <div className="space-y-0.5">
+            <div className="flex items-center justify-between gap-3">
+              {title ? <h3 className="min-w-0 truncate text-subtitle">{title}</h3> : null}
+              {actions ? <div className="flex shrink-0 items-center gap-1">{actions}</div> : null}
+              {status ? <StatusBadge className="shrink-0" size="sm" status={status} /> : null}
+            </div>
+            {summary ? <p className="text-meta text-muted-foreground">{summary}</p> : null}
+          </div>
+        ) : null}
+        {children}
+        {details}
+      </div>
+    );
+  },
+);

package/src/tool.stories.tsx

@@ -0,0 +1,60 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+  Tool,
+  ToolContent,
+  ToolDetails,
+  ToolHeader,
+  ToolInput,
+  ToolOutput,
+  statusFromToolState,
+} from "./tool";
+const meta = { title: "AI/Tool", component: Tool, parameters: { layout: "padded" } } satisfies Meta<
+  typeof Tool
+>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+// JSON-behind-disclosure is the package default (#192, research 10 §B.5): the
+// header carries the business summary; the raw payload sits inside the
+// default-COLLAPSED ToolDetails, one expand away.
+export const Default: Story = {
+  render: () => (
+    <Tool defaultOpen className="max-w-prose">
+      <ToolHeader type="tool-search_web" state="output-available" summary="3 results found" />
+      <ToolContent>
+        <ToolDetails>
+          <ToolInput input={{ query: "platform status page" }} />
+          <ToolOutput
+            output={{ hits: 3, sources: ["status.example.com", "community", "docs"] }}
+            errorText={undefined}
+          />
+        </ToolDetails>
+      </ToolContent>
+    </Tool>
+  ),
+};
+// STREAMING — the call is still running (`input-streaming`). `ToolOutput`
+// derives `isStreaming` from the SAME `statusFromToolState` mapping the header
+// badge uses (no second source of truth), and renders a layout-shaped
+// skeleton in the Result slot instead of `null` — and never the error branch,
+// even though this demo call will eventually resolve to `errorText`.
+export const Streaming: Story = {
+  name: "ToolOutput isStreaming",
+  render: () => {
+    const state = "input-streaming" as const;
+    return (
+      <Tool defaultOpen className="max-w-prose">
+        <ToolHeader type="tool-search_web" state={state} summary="Searching…" />
+        <ToolContent>
+          <ToolDetails defaultOpen>
+            <ToolInput input={{ query: "platform status page" }} />
+            <ToolOutput
+              output={undefined}
+              errorText={undefined}
+              isStreaming={statusFromToolState(state) === "pending"}
+            />
+          </ToolDetails>
+        </ToolContent>
+      </Tool>
+    );
+  },
+};

package/src/tool.test.tsx

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Tool, ToolContent, ToolDetails, ToolHeader, ToolInput, ToolOutput } from "./tool";
+
+const renderTool = () =>
+  render(
+    <Tool defaultOpen>
+      <ToolHeader type="tool-search_web" state="output-available" summary="3 results found" />
+      <ToolContent>
+        <ToolDetails>
+          <ToolInput input={{ query: "platform status page" }} />
+        </ToolDetails>
+      </ToolContent>
+    </Tool>,
+  );
+
+describe("Tool JSON-behind-disclosure (#192, research 10 §B.5)", () => {
+  it("shows the business summary in the header and keeps ToolDetails COLLAPSED by default", () => {
+    renderTool();
+    expect(screen.getByText("3 results found")).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /show technical details/i })).toBeInTheDocument();
+    // The JSON payload is NOT the headline — hidden until opted in.
+    expect(screen.queryByText("Parameters")).not.toBeInTheDocument();
+  });
+
+  it("reveals the technical view on demand", async () => {
+    const user = userEvent.setup();
+    renderTool();
+    await user.click(screen.getByRole("button", { name: /show technical details/i }));
+    expect(screen.getByText("Parameters")).toBeInTheDocument();
+  });
+});
+
+describe("ToolOutput isStreaming (#269, loading-states.md)", () => {
+  it("renders a skeleton (not null) while streaming with no output yet", () => {
+    const { container } = render(
+      <ToolOutput output={undefined} errorText={undefined} isStreaming />,
+    );
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    const statuses = container.querySelectorAll('[role="status"]');
+    expect(statuses).toHaveLength(1);
+    expect(statuses[0]).toHaveAttribute("aria-live", "polite");
+  });
+
+  it("never shows the error branch while streaming, even with a stale errorText", () => {
+    render(<ToolOutput output={undefined} errorText="boom" isStreaming />);
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    expect(screen.queryByText("Error")).not.toBeInTheDocument();
+    expect(screen.queryByText("boom")).not.toBeInTheDocument();
+  });
+
+  it("shows the terminal error branch once settled (not streaming)", () => {
+    render(<ToolOutput output={undefined} errorText="boom" />);
+    expect(screen.getByText("Error")).toBeInTheDocument();
+    expect(screen.getByText("boom")).toBeInTheDocument();
+  });
+
+  it("still renders nothing when idle (no output, no error, not streaming)", () => {
+    const { container } = render(<ToolOutput output={undefined} errorText={undefined} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+});

package/src/tool.tsx

@@ -0,0 +1,235 @@
+"use client";
+
+import { Skeleton, StatusBadge, useLocale, type Status } from "@elabs-ai/components-ui";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { DynamicToolUIPart, ToolUIPart } from "ai";
+import { ChevronDownIcon, WrenchIcon } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+import { isValidElement } from "react";
+
+import { CodeBlock } from "./code-block";
+
+export type ToolProps = ComponentProps<typeof Collapsible>;
+
+export const Tool = ({ className, ...props }: ToolProps) => (
+  <Collapsible
+    className={cn("group not-prose mb-4 w-full rounded-md border", className)}
+    {...props}
+  />
+);
+
+export type ToolPart = ToolUIPart | DynamicToolUIPart;
+
+export type ToolHeaderProps = {
+  title?: string;
+  /**
+   * The business summary line ("3 documents found", "8 rows reconciled"),
+   * shown beside the name + StatusBadge (#192, research 10 §B.5). Falls back
+   * to nothing — the derived tool name still labels the row.
+   */
+  summary?: ReactNode;
+  className?: string;
+} & (
+  | { type: ToolUIPart["type"]; state: ToolUIPart["state"]; toolName?: never }
+  | {
+      type: DynamicToolUIPart["type"];
+      state: DynamicToolUIPart["state"];
+      toolName: string;
+    }
+);
+
+/**
+ * Map the AI-SDK `ToolUIPart` 7-state machine onto the canonical `Status`
+ * enum (#189, research 10 §B.1 mapping a). Lives here — not in `@elabs-ai/components-ui` —
+ * because it is typed against the SDK union; the `ai` import stays TYPES-ONLY
+ * (D6, gate-enforced by `pnpm ai:types-only`).
+ */
+export const statusFromToolState = (state: ToolPart["state"]): Status => {
+  switch (state) {
+    case "input-streaming":
+      return "pending";
+    case "input-available":
+      return "running";
+    case "approval-requested":
+      return "awaiting-approval";
+    case "approval-responded":
+      return "running";
+    case "output-available":
+      return "complete";
+    case "output-denied":
+      return "denied";
+    case "output-error":
+      return "failed";
+  }
+};
+
+/** Same signature as before #189; renders the canonical StatusBadge. */
+export const getStatusBadge = (status: ToolPart["state"]) => (
+  <StatusBadge status={statusFromToolState(status)} />
+);
+
+export const ToolHeader = ({
+  className,
+  title,
+  summary,
+  type,
+  state,
+  toolName,
+  ...props
+}: ToolHeaderProps) => {
+  const derivedName = type === "dynamic-tool" ? toolName : type.split("-").slice(1).join("-");
+
+  return (
+    <CollapsibleTrigger
+      className={cn("flex w-full items-center justify-between gap-4 p-3", className)}
+      {...props}
+    >
+      <div className="flex min-w-0 items-center gap-2">
+        <WrenchIcon className="size-4 shrink-0 text-muted-foreground" />
+        <span className="shrink-0 text-body font-medium">{title ?? derivedName}</span>
+        {getStatusBadge(state)}
+        {summary ? (
+          <span className="truncate text-meta text-muted-foreground">{summary}</span>
+        ) : null}
+      </div>
+      <ChevronDownIcon className="size-4 shrink-0 text-muted-foreground transition-transform group-data-[state=open]:rotate-180" />
+    </CollapsibleTrigger>
+  );
+};
+
+export type ToolContentProps = ComponentProps<typeof CollapsibleContent>;
+
+export const ToolContent = ({ className, ...props }: ToolContentProps) => (
+  <CollapsibleContent
+    className={cn(
+      "data-[state=closed]:fade-out-0 data-[state=closed]:slide-out-to-top-2 data-[state=open]:slide-in-from-top-2 space-y-4 p-4 text-popover-foreground outline-none data-[state=closed]:animate-out data-[state=open]:animate-in data-[state=open]:[--tw-ease:var(--ease-entrance)] data-[state=closed]:[--tw-ease:var(--ease-exit)]",
+      className,
+    )}
+    {...props}
+  />
+);
+
+export type ToolDetailsProps = ComponentProps<typeof Collapsible> & {
+  /** The disclosure label. */
+  label?: ReactNode;
+};
+
+/**
+ * The technical view, behind disclosure — the PACKAGE DEFAULT for tool JSON
+ * (#192, research 10 §B.5): a nested collapsible, COLLAPSED by default,
+ * holding `ToolInput`/`ToolOutput`. The header carries the business `summary`;
+ * the raw payload is one expand away, never the headline.
+ */
+export const ToolDetails = ({
+  className,
+  label = "Show technical details",
+  defaultOpen = false,
+  children,
+  ...props
+}: ToolDetailsProps) => (
+  <Collapsible
+    className={cn("group/tool-details not-prose", className)}
+    defaultOpen={defaultOpen}
+    {...props}
+  >
+    <CollapsibleTrigger className="flex items-center gap-1 rounded-sm text-meta text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">
+      <ChevronDownIcon className="size-3.5 transition-transform group-data-[state=open]/tool-details:rotate-180" />
+      {label}
+    </CollapsibleTrigger>
+    <CollapsibleContent className="mt-3 space-y-4">{children}</CollapsibleContent>
+  </Collapsible>
+);
+
+export type ToolInputProps = ComponentProps<"div"> & {
+  input: ToolPart["input"];
+};
+
+export const ToolInput = ({ className, input, ...props }: ToolInputProps) => (
+  <div className={cn("space-y-2 overflow-hidden", className)} {...props}>
+    <h4 className="text-meta uppercase text-muted-foreground">Parameters</h4>
+    <div className="rounded-md bg-muted/50">
+      <CodeBlock code={JSON.stringify(input, null, 2)} language="json" />
+    </div>
+  </div>
+);
+
+export type ToolOutputProps = ComponentProps<"div"> & {
+  /**
+   * The tool result. Objects/strings render as JSON inside the technical view.
+   *
+   * @deprecated Passing a pre-rendered **React element** here (the "rich
+   * output under a muted Result heading" path) is deprecated since #192
+   * (research 10 §B.5): a produced artifact is the HEADLINE, not a technical
+   * detail — host it in a `<ToolResultCard>` and keep `ToolOutput` for the
+   * JSON payload behind `<ToolDetails>`. The element path still renders for
+   * existing consumers (e.g. the copy-owned `ai-chart` registry block) but
+   * will be removed in a future release.
+   */
+  output: ToolPart["output"];
+  errorText: ToolPart["errorText"];
+  /**
+   * The call has not produced output yet (loading-states.md `isStreaming`) —
+   * derive it from the existing `statusFromToolState(state)` mapping
+   * (`"input-streaming"`/`"input-available"` → not yet `"complete"`/`"failed"`)
+   * rather than a second source of truth. While true and no `output`/
+   * `errorText` has arrived, renders a layout-shaped skeleton in the Result
+   * slot instead of `null`, so the technical view reserves its space. A
+   * still-running call is never a terminal failure — the error branch is
+   * suppressed while `isStreaming` per the loading-states.md error rule, even
+   * if a stale `errorText` is still set from a previous render.
+   * @default false
+   */
+  isStreaming?: boolean;
+};
+
+export const ToolOutput = ({
+  className,
+  output,
+  errorText,
+  isStreaming = false,
+  ...props
+}: ToolOutputProps) => {
+  const { t } = useLocale();
+
+  if (!(output || errorText || isStreaming)) {
+    return null;
+  }
+
+  const showError = !isStreaming && Boolean(errorText);
+  const pending = isStreaming && !output && !errorText;
+
+  let Output = <div>{output as ReactNode}</div>;
+
+  if (typeof output === "object" && !isValidElement(output)) {
+    Output = <CodeBlock code={JSON.stringify(output, null, 2)} language="json" />;
+  } else if (typeof output === "string") {
+    Output = <CodeBlock code={output} language="json" />;
+  }
+
+  return (
+    <div className={cn("space-y-2", className)} {...props}>
+      <h4 className="text-meta uppercase text-muted-foreground">
+        {showError ? "Error" : "Result"}
+      </h4>
+      {pending ? (
+        <div className="space-y-2 rounded-md bg-muted/50 p-3" role="status" aria-live="polite">
+          <span className="sr-only">{t("loading")}</span>
+          <Skeleton className="h-4 w-3/4" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-1/2" />
+        </div>
+      ) : (
+        <div
+          className={cn(
+            "overflow-x-auto rounded-md text-caption [&_table]:w-full",
+            showError ? "bg-destructive/10 text-destructive" : "bg-muted/50 text-foreground",
+          )}
+        >
+          {showError && <div>{errorText}</div>}
+          {Output}
+        </div>
+      )}
+    </div>
+  );
+};

package/src/toolbar.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import type { NodeToolbar as FlowNodeToolbar } from "@xyflow/react";
+import type { ComponentProps } from "react";
+import { Suspense } from "react";
+
+import { lazyFlowPart } from "./_flow-lazy";
+
+export type NodeToolbarProps = ComponentProps<typeof FlowNodeToolbar>;
+
+/** React Flow lives behind a dynamic import — see `_flow-lazy.ts` and ADR 0019. */
+const NodeToolbarImpl = lazyFlowPart<NodeToolbarProps>((m) => m.Toolbar);
+
+/**
+ * The floating control strip attached to a selected canvas NODE — it portals out
+ * of the node and follows it, and it is meaningless outside a `<Canvas>`.
+ *
+ * Named `NodeToolbar` (after the React Flow primitive it wraps) because
+ * `Toolbar` now means the general-purpose WAI-ARIA toolbar in
+ * `@elabs-ai/components-ui`: a keyboard row with a roving tabindex.
+ * The two solve unrelated problems, and the collision made "use the Toolbar"
+ * ambiguous at every call site.
+ */
+export const NodeToolbar = (props: NodeToolbarProps) => (
+  // `NodeToolbar` only ever renders inside a `<Canvas>` (it portals out of the
+  // node), so the engine chunk is already in cache; it is wrapped anyway because
+  // it is independently barrel-exported.
+  <Suspense fallback={null}>
+    {/* The strip portals out of the node it belongs to, so it is nowhere near
+        that node in the DOM — a stable selector is the only way a consumer or a
+        test can find it. Overridable, like every other `data-slot`. */}
+    <NodeToolbarImpl data-slot="node-toolbar" {...props} />
+  </Suspense>
+);
+
+/**
+ * @deprecated Renamed to {@link NodeToolbar}. `Toolbar` is now the WAI-ARIA
+ * toolbar in `@elabs-ai/components-ui`. This alias will be removed in
+ * the next major.
+ */
+export const Toolbar = NodeToolbar;
+
+/** @deprecated Renamed to {@link NodeToolbarProps}. */
+export type ToolbarProps = NodeToolbarProps;

package/src/transcription.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { useControllableState } from "@radix-ui/react-use-controllable-state";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { Experimental_TranscriptionResult as TranscriptionResult } from "ai";
+import type { ComponentProps, ReactNode } from "react";
+import { createContext, useCallback, useContext, useMemo } from "react";
+
+type TranscriptionSegment = TranscriptionResult["segments"][number];
+
+interface TranscriptionContextValue {
+  segments: TranscriptionSegment[];
+  currentTime: number;
+  onTimeUpdate: (time: number) => void;
+  onSeek?: (time: number) => void;
+}
+
+const TranscriptionContext = createContext<TranscriptionContextValue | null>(null);
+
+const useTranscription = () => {
+  const context = useContext(TranscriptionContext);
+  if (!context) {
+    throw new Error("Transcription components must be used within Transcription");
+  }
+  return context;
+};
+
+export type TranscriptionProps = Omit<ComponentProps<"div">, "children"> & {
+  segments: TranscriptionSegment[];
+  currentTime?: number;
+  onSeek?: (time: number) => void;
+  children: (segment: TranscriptionSegment, index: number) => ReactNode;
+};
+
+export const Transcription = ({
+  segments,
+  currentTime: externalCurrentTime,
+  onSeek,
+  className,
+  children,
+  ...props
+}: TranscriptionProps) => {
+  const [currentTime, setCurrentTime] = useControllableState({
+    defaultProp: 0,
+    onChange: onSeek,
+    prop: externalCurrentTime,
+  });
+
+  const contextValue = useMemo(
+    () => ({ currentTime, onSeek, onTimeUpdate: setCurrentTime, segments }),
+    [currentTime, onSeek, setCurrentTime, segments],
+  );
+
+  return (
+    <TranscriptionContext.Provider value={contextValue}>
+      <div
+        className={cn("flex flex-wrap gap-1 text-sm leading-relaxed", className)}
+        data-slot="transcription"
+        {...props}
+      >
+        {segments
+          .filter((segment) => segment.text.trim())
+          .map((segment, index) => children(segment, index))}
+      </div>
+    </TranscriptionContext.Provider>
+  );
+};
+
+export type TranscriptionSegmentProps = ComponentProps<"button"> & {
+  segment: TranscriptionSegment;
+  index: number;
+};
+
+export const TranscriptionSegment = ({
+  segment,
+  index,
+  className,
+  onClick,
+  ...props
+}: TranscriptionSegmentProps) => {
+  const { currentTime, onSeek } = useTranscription();
+
+  const isActive = currentTime >= segment.startSecond && currentTime < segment.endSecond;
+  const isPast = currentTime >= segment.endSecond;
+
+  const handleClick = useCallback(
+    (event: React.MouseEvent<HTMLButtonElement>) => {
+      if (onSeek) {
+        onSeek(segment.startSecond);
+      }
+      onClick?.(event);
+    },
+    [onSeek, segment.startSecond, onClick],
+  );
+
+  return (
+    <button
+      className={cn(
+        "inline text-start",
+        // #399 — the active word is transcript TEXT: `-text` rung, not the fill.
+        isActive && "text-primary-text",
+        isPast && "text-muted-foreground",
+        !(isActive || isPast) && "text-muted-foreground/60",
+        onSeek && "cursor-pointer hover:text-foreground",
+        !onSeek && "cursor-default",
+        className,
+      )}
+      data-active={isActive}
+      data-index={index}
+      data-slot="transcription-segment"
+      onClick={handleClick}
+      type="button"
+      {...props}
+    >
+      {segment.text}
+    </button>
+  );
+};