Skip to content

The Open Standard for Generative UI

10.0 KB
Raw Blame
import type { ToolActivity, ToolCallStatus } from "@openuidev/react-headless";
import clsx from "clsx";
import { createContext, createElement, useContext, useId, useState, type ReactNode } from "react";
import { toolIcon } from "./ToolGlyphs";
import { toolLabel, useToolLabels } from "./toolLabels";

/**
 * Compound, reusable building blocks for rendering one tool call + its result.
 *
 * `ToolCall.Root` holds the typed {@link ToolActivity} and expand state in
 * context; the thin parts read it and expose typed `data-*` / `aria` attributes
 * plus a `render` escape hatch (Base-UI / Radix style) so a consumer can swap
 * the element or markup per place. The batteries-included `DefaultToolCard` /
 * `TimelineToolCard` are just two compositions of these parts — drop them into a
 * sidebar, a compact chip, or a debug panel and reuse the typed state without
 * re-deriving anything.
 *
 * @category Components
 */

// ── Context ──

interface ToolCallContextValue {
  activity: ToolActivity;
  isLast: boolean;
  /**
   * Whether the owning thread is still running. The in-progress affordances
   * (glyph animation, name shimmer) require this so a tool call that closed its args
   * but never received a result does NOT animate forever after the run ends.
   * Defaults to `true` for standalone (thread-less) primitive use.
   */
  running: boolean;
  isOpen: boolean;
  setOpen: (value: boolean) => void;
  panelId: string;
  /** Stable id on the rendered Trigger button; names the Content region. */
  triggerId: string;
}

const ToolCallContext = createContext<ToolCallContextValue | null>(null);

/** Reads the nearest {@link ToolCall.Root} context. @category Hooks */
export function useToolCall(): ToolCallContextValue {
  const ctx = useContext(ToolCallContext);
  if (!ctx) throw new Error("ToolCall.* parts must be used inside <ToolCall.Root>");
  return ctx;
}

// ── render escape hatch ──

type RenderProp<State, Props> = (state: State, props: Props) => ReactNode;

/**
 * Renders the consumer's `render` prop if given, else the default element with
 * `defaultProps`, exposing the typed `state` to the render prop. Not a hook
 * (contains no hooks) despite slotting into component bodies.
 */
function renderPart<State, Props extends Record<string, unknown>>(
  render: RenderProp<State, Props> | undefined,
  tag: string,
  state: State,
  defaultProps: Props,
): ReactNode {
  if (render) return render(state, defaultProps);
  return createElement(tag, defaultProps);
}

/** Whether a tool call is still in flight (arguments streaming or executing). */
export const isToolRunning = (status: ToolCallStatus) =>
  status === "streaming" || status === "executing";

// ── Shared formatting helpers ──

/** Pretty-prints a JSON result string, falling back to the raw string. @category Functions */
export function prettyResult(value?: string): string {
  if (value == null) return "";
  try {
    return JSON.stringify(JSON.parse(value), null, 2);
  } catch {
    return value;
  }
}

const isObject = (v: unknown): v is Record<string, unknown> =>
  typeof v === "object" && v !== null && !Array.isArray(v);

/** Pretty-prints any value (objects stringified, strings shown verbatim). */
function prettyValue(value: unknown): string {
  if (typeof value === "string") return value;
  try {
    return JSON.stringify(value, null, 2);
  } catch {
    return String(value);
  }
}

/**
 * Resolves what to show in the request panel. Honors the deprecated `_request`
 * arg key (shows just that), and — when the parsed input is empty (unparseable
 * / earliest streaming frame) — falls back to the raw argument string so the
 * user sees the partial text instead of an empty `{}`.
 */
function resolveRequest(activity: ToolActivity): string {
  const input = activity.input;
  // `!= null` matches the legacy ToolCallComponent gating — a `_request: null`
  // is treated as absent, not as the request payload.
  if (isObject(input) && input["_request"] != null) return prettyValue(input["_request"]);
  if (isObject(input) && Object.keys(input).length === 0) {
    const raw = activity.toolCall.function.arguments;
    if (raw && raw.trim()) return raw;
  }
  return prettyValue(input);
}

/** The deprecated `_response` arg key, if non-null (else `undefined`). */
function resolveLegacyResponse(activity: ToolActivity): unknown {
  const input = activity.input;
  const value = isObject(input) ? input["_response"] : undefined;
  return value != null ? value : undefined;
}

// ── Parts ──

interface PartProps<State> {
  render?: RenderProp<State, Record<string, unknown>>;
  className?: string;
  children?: ReactNode;
}

function Root({
  activity,
  isLast = false,
  running = true,
  defaultOpen = false,
  open,
  onOpenChange,
  className,
  children,
}: {
  activity: ToolActivity;
  isLast?: boolean;
  /** Whether the owning thread is still running (gates the in-progress animations). */
  running?: boolean;
  /** Initial expand state when uncontrolled. */
  defaultOpen?: boolean;
  /** Controlled expand state, e.g. so a list can keep one call open at a time. */
  open?: boolean;
  /** Called with the requested expand state; pair with `open`. */
  onOpenChange?: (open: boolean) => void;
  className?: string;
  children: ReactNode;
}) {
  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
  const isOpen = open ?? uncontrolledOpen;
  const setOpen = (value: boolean) => {
    if (open === undefined) setUncontrolledOpen(value);
    onOpenChange?.(value);
  };
  const panelId = useId();
  const triggerId = useId();
  return (
    <ToolCallContext.Provider
      value={{ activity, isLast, running, isOpen, setOpen, panelId, triggerId }}
    >
      <div
        className={clsx("openui-tool-call", `openui-tool-call--${activity.status}`, className)}
        data-status={activity.status}
      >
        {children}
      </div>
    </ToolCallContext.Provider>
  );
}

const StatusIcon = ({
  render,
  className,
  size = 14,
}: PartProps<{ status: ToolCallStatus }> & { size?: number }) => {
  const { activity, isLast, running } = useToolCall();
  const spin = isToolRunning(activity.status) && isLast && running;
  const Icon = toolIcon(activity.toolName, activity.status);
  return renderPart(
    render,
    "span",
    { status: activity.status },
    {
      className: clsx("openui-tool-call__icon-wrapper", className),
      "data-status": activity.status,
      "data-spin": spin,
      children: <Icon size={size} animate={spin} className="openui-tool-call__icon" />,
    },
  );
};

const ToolName = ({ render, className }: PartProps<{ toolName: string }>) => {
  const { activity } = useToolCall();
  return renderPart(
    render,
    "span",
    { toolName: activity.toolName },
    {
      className,
      children: activity.toolName,
    },
  );
};

const StatusText = ({
  render,
  className,
}: PartProps<{ status: ToolCallStatus; label: string }>) => {
  const { activity, isLast, running } = useToolCall();
  const labels = useToolLabels();
  const label = activity.statusMessage ?? toolLabel(activity.status, activity.toolName, labels);
  const shimmer = isToolRunning(activity.status) && isLast && running;
  return renderPart(
    render,
    "span",
    { status: activity.status, label },
    {
      // Live region so status transitions (Calling → Running → Called/failed)
      // are announced; only changes are spoken, so settled cards stay quiet.
      role: "status",
      "aria-live": "polite",
      className: clsx(
        "openui-tool-call__name",
        { "openui-tool-call__name--shimmer": shimmer },
        className,
      ),
      children: label,
    },
  );
};

const Parameters = ({ render, className }: PartProps<{ input: unknown; inputString: string }>) => {
  const { activity } = useToolCall();
  // Honors the legacy `_request` key + falls back to raw args when unparseable.
  const inputString = resolveRequest(activity);
  return renderPart(
    render,
    "pre",
    { input: activity.input, inputString },
    {
      className,
      children: inputString,
    },
  );
};

const Result = ({
  render,
  className,
}: PartProps<{ result?: string; isError: boolean; errorText?: string }>) => {
  const { activity } = useToolCall();
  // Legacy tools packed the result into a `_response` arg key (no tool message).
  const legacyResponse = resolveLegacyResponse(activity);
  // Enabled when there's a paired result, an error, or a legacy `_response`.
  if (activity.result == null && !activity.isError && legacyResponse === undefined) return null;
  const text = activity.isError
    ? (activity.errorText ?? activity.result ?? "")
    : legacyResponse !== undefined
      ? prettyValue(legacyResponse)
      : prettyResult(activity.result);
  return renderPart(
    render,
    "div",
    { result: activity.result, isError: activity.isError, errorText: activity.errorText },
    {
      className: clsx({ "openui-tool-call__result--error": activity.isError }, className),
      children: text,
    },
  );
};

const Trigger = ({ render, className, children }: PartProps<{ state: "open" | "closed" }>) => {
  const { isOpen, setOpen, panelId, triggerId } = useToolCall();
  return renderPart(
    render,
    "button",
    { state: isOpen ? "open" : "closed" },
    {
      type: "button",
      id: triggerId,
      className,
      "aria-expanded": isOpen,
      "aria-controls": panelId,
      onClick: () => setOpen(!isOpen),
      children,
    },
  );
};

const Content = ({ render, className, children }: PartProps<{ isOpen: boolean }>) => {
  const { isOpen, panelId, triggerId } = useToolCall();
  if (!isOpen) return null;
  return renderPart(
    render,
    "div",
    { isOpen },
    {
      id: panelId,
      role: "region",
      "aria-labelledby": triggerId,
      "data-state": "open",
      className,
      children,
    },
  );
};

/**
 * The compound tool-call primitive set. Compose `Root` + parts to render a tool
 * call however a given surface needs.
 *
 * @category Components
 */
export const ToolCall = {
  Root,
  Trigger,
  Content,
  StatusIcon,
  StatusText,
  ToolName,
  Parameters,
  Result,
};