@assistant-ui/core 0.2.2 → 0.2.3

package/src/react/model-context/makeAssistantToolUI.ts

@@ -4,10 +4,25 @@ import {
   useAssistantToolUI,
 } from "./useAssistantToolUI";
 
+/**
+ * Component returned by {@link makeAssistantToolUI}.
+ *
+ * Rendering the component registers a renderer for matching tool-call message
+ * parts.
+ */
 export type AssistantToolUI = FC & {
+  /** Tool renderer registered by this component. */
   unstable_tool: AssistantToolUIProps<any, any>;
 };
 
+/**
+ * Creates a React component that registers a tool-call renderer when rendered.
+ *
+ * Use this to package reusable display components for tools whose definitions
+ * are registered elsewhere.
+ *
+ * @param tool - Tool renderer registration.
+ */
 export const makeAssistantToolUI = <TArgs, TResult>(
   tool: AssistantToolUIProps<TArgs, TResult>,
 ) => {

package/src/react/model-context/toolbox.ts

@@ -5,15 +5,46 @@ type WithRender<T, TArgs extends Record<string, unknown>, TResult> = T extends {
   type: "frontend" | "human";
 }
   ? T & { render: ToolCallMessagePartComponent<TArgs, TResult> }
-  : T & { render?: ToolCallMessagePartComponent<TArgs, TResult> | undefined };
+  : T & {
+      render?: ToolCallMessagePartComponent<TArgs, TResult> | undefined;
+    };
 
+/**
+ * Tool definition accepted by the React tool registry.
+ *
+ * Extends the core tool contract with a render component. Human tools rely on
+ * the renderer to collect input from the user. Frontend tools execute in the
+ * browser and require a UI surface for their progress and result. Backend
+ * tools execute server-side and may omit a renderer. The `render` component is
+ * required for frontend and human tools and optional for backend tools.
+ */
 export type ToolDefinition<
   TArgs extends Record<string, unknown>,
   TResult,
 > = WithRender<Tool<TArgs, TResult>, TArgs, TResult>;
 
+/**
+ * Named collection of tools exposed to the assistant model.
+ *
+ * Keys are the tool names the model receives and uses in tool calls.
+ *
+ * @example
+ * ```tsx
+ * const toolkit = {
+ *   get_weather: {
+ *     type: "frontend",
+ *     description: "Get the weather for a city.",
+ *     parameters: weatherSchema,
+ *     execute: async ({ city }: { city: string }) => fetchWeather(city),
+ *     render: WeatherToolUI,
+ *   },
+ * } satisfies Toolkit;
+ * ```
+ */
 export type Toolkit = Record<string, ToolDefinition<any, any>>;
 
+/** Configuration for the {@link Tools} resource. */
 export type ToolsConfig = {
+  /** Tools to register with model context and, when provided, message renderers. */
   toolkit: Toolkit;
 };

package/src/react/model-context/useAssistantDataUI.ts

@@ -2,11 +2,20 @@ import { useEffect } from "react";
 import { useAui } from "@assistant-ui/store";
 import type { DataMessagePartComponent } from "../types/MessagePartComponentTypes";
 
+/** Props used to register a renderer for `data` message parts. */
 export type AssistantDataUIProps<T = any> = {
+  /** Data part name this renderer handles. */
   name: string;
+  /** Component rendered for matching data message parts. */
   render: DataMessagePartComponent<T>;
 };
 
+/**
+ * Registers a renderer for named `data` message parts while the component is
+ * mounted.
+ *
+ * @param dataUI - Data renderer registration, or `null` to skip registration.
+ */
 export const useAssistantDataUI = (dataUI: AssistantDataUIProps | null) => {
   const aui = useAui();
   useEffect(() => {

package/src/react/model-context/useAssistantTool.ts

@@ -3,13 +3,47 @@ import { useAui } from "@assistant-ui/store";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 import type { AssistantToolProps as CoreAssistantToolProps } from "../..";
 
+/**
+ * Props used to register a tool from React.
+ */
 export type AssistantToolProps<
   TArgs extends Record<string, unknown>,
   TResult,
 > = CoreAssistantToolProps<TArgs, TResult> & {
+  /** Component used to render calls to this tool in assistant messages. */
   render?: ToolCallMessagePartComponent<TArgs, TResult> | undefined;
 };
 
+/**
+ * Registers a tool with the assistant model context while the component is
+ * mounted.
+ *
+ * If `render` is provided, it is also installed as the renderer for matching
+ * tool-call message parts. The registration is removed automatically when the
+ * component unmounts or the tool definition changes.
+ *
+ * Pass a referentially stable tool object, such as one declared at module
+ * scope or memoized with `useMemo`, to avoid re-registering on every render.
+ *
+ * @param tool - Tool definition and name to register.
+ *
+ * @example
+ * ```tsx
+ * const weatherTool = {
+ *   toolName: "get_weather",
+ *   type: "frontend",
+ *   description: "Get the weather for a city.",
+ *   parameters: weatherSchema,
+ *   execute: async ({ city }: { city: string }) => fetchWeather(city),
+ *   render: WeatherToolUI,
+ * } satisfies AssistantToolProps<{ city: string }, Weather>;
+ *
+ * function WeatherToolRegistration() {
+ *   useAssistantTool(weatherTool);
+ *   return null;
+ * }
+ * ```
+ */
 export const useAssistantTool = <
   TArgs extends Record<string, unknown>,
   TResult,

package/src/react/model-context/useAssistantToolUI.ts

@@ -2,11 +2,23 @@ import { useEffect } from "react";
 import { useAui } from "@assistant-ui/store";
 import type { ToolCallMessagePartComponent } from "../types/MessagePartComponentTypes";
 
+/** Props used to register a renderer for tool-call message parts. */
 export type AssistantToolUIProps<TArgs, TResult> = {
+  /** Name of the tool whose calls should use this renderer. */
   toolName: string;
+  /** Component rendered for matching tool-call message parts. */
   render: ToolCallMessagePartComponent<TArgs, TResult>;
 };
 
+/**
+ * Registers a tool-call renderer while the component is mounted.
+ *
+ * This only affects rendering. Pair it with {@link useAssistantTool},
+ * {@link Tools}, or a backend tool registry to expose the actual tool
+ * definition to the model.
+ *
+ * @param tool - Tool renderer registration, or `null` to skip registration.
+ */
 export const useAssistantToolUI = (
   tool: AssistantToolUIProps<any, any> | null,
 ) => {

package/src/react/model-context/useToolArgsStatus.ts

@@ -7,13 +7,42 @@ import {
 
 type PropFieldStatus = "streaming" | "complete";
 
+/**
+ * Streaming completion status for the arguments of the current tool call.
+ */
 export type ToolArgsStatus<
   TArgs extends Record<string, unknown> = Record<string, unknown>,
 > = {
+  /** Overall lifecycle state of the tool-call part. */
   status: "running" | "complete" | "incomplete" | "requires-action";
+  /** Per-argument status keyed by argument name. */
   propStatus: Partial<Record<keyof TArgs, PropFieldStatus>>;
 };
 
+/**
+ * Reads whether each argument field for the current tool-call message part is
+ * still streaming or complete.
+ *
+ * Use inside a tool-call renderer to avoid showing incomplete argument values
+ * as final.
+ *
+ * @throws If called outside a tool-call message part.
+ *
+ * @example
+ * ```tsx
+ * function WeatherToolUI({
+ *   args,
+ * }: ToolCallMessagePartProps<{ city: string }>) {
+ *   const { propStatus } = useToolArgsStatus<{ city: string }>();
+ *
+ *   return (
+ *     <span>
+ *       {propStatus.city === "streaming" ? "Reading city..." : args.city}
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
 export const useToolArgsStatus = <
   TArgs extends Record<string, unknown> = Record<string, unknown>,
 >(): ToolArgsStatus<TArgs> => {

package/src/react/primitive-hooks/useActionBarCopy.ts

@@ -27,11 +27,15 @@ export const useActionBarCopy = ({
     if (!valueToCopy) return;
 
     const write = copyToClipboard ?? (() => {});
-    const result = write(valueToCopy);
-    Promise.resolve(result).then(() => {
-      aui.message().setIsCopied(true);
-      setTimeout(() => aui.message().setIsCopied(false), copiedDuration);
-    });
+    // The rejection handler swallows clipboard write failures (permission denied,
+    // API unavailable) so they don't surface as unhandled promise rejections.
+    Promise.resolve(write(valueToCopy)).then(
+      () => {
+        aui.message().setIsCopied(true);
+        setTimeout(() => aui.message().setIsCopied(false), copiedDuration);
+      },
+      () => {},
+    );
   }, [aui, isEditing, composerValue, copiedDuration, copyToClipboard]);
 
   return { copy, disabled, isCopied };

package/src/react/primitives/messagePart/MessagePartInProgress.ts

@@ -0,0 +1,15 @@
+import type { FC, PropsWithChildren } from "react";
+import { useAuiState } from "@assistant-ui/store";
+
+export namespace MessagePartPrimitiveInProgress {
+  export type Props = PropsWithChildren;
+}
+
+export const MessagePartPrimitiveInProgress: FC<
+  MessagePartPrimitiveInProgress.Props
+> = ({ children }) => {
+  const isInProgress = useAuiState((s) => s.part.status.type === "running");
+  return isInProgress ? children : null;
+};
+
+MessagePartPrimitiveInProgress.displayName = "MessagePartPrimitive.InProgress";