@assistant-ui/react 0.15.24 → 0.15.26

package/src/model-context/makeAssistantVisible.test.tsx

@@ -8,6 +8,11 @@ import {
   type ChangeEvent,
 } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  mergeModelContexts,
+  type ModelContextProvider,
+} from "@assistant-ui/core";
+import type { Tool } from "assistant-stream";
 
 const { registerMock, auiMock } = vi.hoisted(() => {
   const register = vi.fn((_provider: unknown) => () => {});
@@ -30,10 +35,15 @@ type EditTool = {
   execute: (args: { editId: string; value: string }) => Promise<unknown>;
 };
 
-type ModelContextProvider = {
+type ClickTool = {
+  execute: (args: { clickId: string }) => Promise<unknown>;
+};
+
+type VisibleToolsProvider = {
   getModelContext: () => {
     tools: {
-      edit: EditTool;
+      edit?: EditTool;
+      click?: ClickTool;
     };
   };
 };
@@ -79,6 +89,36 @@ const ControlledTextarea = forwardRef<
   );
 });
 
+const Button = forwardRef<HTMLButtonElement, ComponentProps<"button">>(
+  (props, ref) => <button {...props} ref={ref} />,
+);
+
+const SplitRefButton = forwardRef<HTMLButtonElement, ComponentProps<"div">>(
+  ({ children, ...props }, ref) => (
+    <div {...props}>
+      <button ref={ref}>{children}</button>
+    </div>
+  ),
+);
+
+const getRegisteredTools = () => {
+  const provider = registerMock.mock.calls[0]![0] as VisibleToolsProvider;
+  return provider.getModelContext().tools;
+};
+
+const executeTool = (tool: Tool | undefined, args: Record<string, unknown>) => {
+  if (!tool?.execute) throw new Error("Missing executable tool");
+  return Promise.resolve(
+    tool.execute(args, {
+      toolCallId: "test-call",
+      abortSignal: new AbortController().signal,
+      human: async () => {
+        throw new Error("Unexpected human input request");
+      },
+    }),
+  );
+};
+
 const runEditTool = async (
   element: HTMLInputElement | HTMLTextAreaElement,
   value: string,
@@ -86,8 +126,9 @@ const runEditTool = async (
   const editId = element.dataset.editId;
   if (editId === undefined) throw new Error("Missing edit id");
 
-  const provider = registerMock.mock.calls[0]![0] as ModelContextProvider;
-  const task = provider.getModelContext().tools.edit.execute({
+  const edit = getRegisteredTools().edit;
+  if (!edit) throw new Error("Missing edit tool");
+  const task = edit.execute({
     editId,
     value,
   });
@@ -95,7 +136,7 @@ const runEditTool = async (
   await task;
 };
 
-describe("makeAssistantVisible editable components", () => {
+describe("makeAssistantVisible", () => {
   beforeEach(() => {
     registerMock.mockClear();
     vi.stubGlobal("CSS", { escape: (value: string) => value });
@@ -143,4 +184,273 @@ describe("makeAssistantVisible editable components", () => {
     expect(textarea.getAttribute("data-react-value")).toBe("updated");
     expect(onChange).toHaveBeenCalledOnce();
   });
+
+  it("preserves the default action settle delay", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+    });
+    const input = render(<EditableInput />).getByRole("textbox");
+    const editId = (input as HTMLInputElement).dataset.editId!;
+    const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+
+    expect(
+      (input as HTMLInputElement).dataset.actionSettleDelay,
+    ).toBeUndefined();
+
+    const task = getRegisteredTools().edit!.execute({
+      editId,
+      value: "updated",
+    });
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 2000);
+    await vi.runAllTimersAsync();
+    await task;
+    setTimeoutSpy.mockRestore();
+  });
+
+  it("uses the default when the rendered settle delay is invalid", async () => {
+    const ClickableButton = makeAssistantVisible(Button, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const button = render(<ClickableButton>Run</ClickableButton>).getByRole(
+      "button",
+    );
+    const clickId = (button as HTMLButtonElement).dataset.clickId!;
+    (button as HTMLButtonElement).dataset.actionSettleDelay = "invalid";
+    const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 2000);
+    await vi.runAllTimersAsync();
+    await task;
+    setTimeoutSpy.mockRestore();
+  });
+
+  it.each(["", "   "])(
+    "uses the default for a blank rendered settle delay of %j",
+    async (renderedDelay) => {
+      const VisibleInput = makeAssistantVisible(ControlledInput, {
+        clickable: true,
+        editable: true,
+        settleDelayMs: 25,
+      });
+      const input = render(<VisibleInput />).getByRole("textbox");
+      const clickId = (input as HTMLInputElement).dataset.clickId!;
+      const editId = (input as HTMLInputElement).dataset.editId!;
+      const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+      input.dataset.actionSettleDelay = renderedDelay;
+
+      const clickTask = getRegisteredTools().click!.execute({ clickId });
+      expect(setTimeoutSpy).toHaveBeenLastCalledWith(
+        expect.any(Function),
+        2000,
+      );
+      await vi.runAllTimersAsync();
+      await clickTask;
+
+      setTimeoutSpy.mockClear();
+      const editTask = getRegisteredTools().edit!.execute({
+        editId,
+        value: "updated",
+      });
+      expect(setTimeoutSpy).toHaveBeenLastCalledWith(
+        expect.any(Function),
+        2000,
+      );
+      await vi.runAllTimersAsync();
+      await editTask;
+      setTimeoutSpy.mockRestore();
+    },
+  );
+
+  it("uses the configured settle delay for click actions", async () => {
+    const ClickableButton = makeAssistantVisible(Button, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const onClick = vi.fn();
+    const button = render(
+      <ClickableButton onClick={onClick}>Run</ClickableButton>,
+    ).getByRole("button");
+    const clickId = (button as HTMLButtonElement).dataset.clickId!;
+    const settled = vi.fn();
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+    void task.then(settled);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(24);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await task;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("uses the action id when the forwarded ref targets a child", async () => {
+    const ClickableButton = makeAssistantVisible(SplitRefButton, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const onClick = vi.fn();
+    const view = render(
+      <ClickableButton data-testid="action" onClick={onClick}>
+        Run
+      </ClickableButton>,
+    );
+    const action = view.getByTestId("action");
+    const clickId = action.dataset.clickId!;
+    const settled = vi.fn();
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+    void task.then(settled);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(24);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await task;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("shares tools across wrappers while keeping per-element delays", async () => {
+    const SlowButton = makeAssistantVisible(Button, {
+      clickable: true,
+      editable: true,
+      settleDelayMs: 25,
+    });
+    const ImmediateButton = makeAssistantVisible(Button, {
+      clickable: true,
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const view = render(
+      <>
+        <SlowButton>Slow</SlowButton>
+        <ImmediateButton>Immediate</ImmediateButton>
+      </>,
+    );
+    const providers = registerMock.mock.calls.map(
+      ([provider]) => provider as ModelContextProvider,
+    );
+    const mergedContext = mergeModelContexts(new Set(providers));
+
+    expect(mergedContext.tools?.click).toBe(
+      providers[0]!.getModelContext().tools?.click,
+    );
+    expect(mergedContext.tools?.click).toBe(
+      providers[1]!.getModelContext().tools?.click,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[0]!.getModelContext().tools?.edit,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[1]!.getModelContext().tools?.edit,
+    );
+
+    const [slowButton, immediateButton] = view.getAllByRole("button");
+    const click = mergedContext.tools!.click!;
+    const slowTask = executeTool(click, {
+      clickId: (slowButton as HTMLButtonElement).dataset.clickId!,
+    });
+    const immediateTask = executeTool(click, {
+      clickId: (immediateButton as HTMLButtonElement).dataset.clickId!,
+    });
+
+    await immediateTask;
+    let slowSettled = false;
+    void slowTask.then(() => {
+      slowSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(24);
+    expect(slowSettled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    await slowTask;
+  });
+
+  it("shares the edit tool across wrappers while keeping per-element delays", async () => {
+    const SlowInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 25,
+    });
+    const ImmediateInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const view = render(
+      <>
+        <SlowInput aria-label="Slow" />
+        <ImmediateInput aria-label="Immediate" />
+      </>,
+    );
+    const providers = registerMock.mock.calls.map(
+      ([provider]) => provider as ModelContextProvider,
+    );
+    const mergedContext = mergeModelContexts(new Set(providers));
+
+    expect(mergedContext.tools?.edit).toBe(
+      providers[0]!.getModelContext().tools?.edit,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[1]!.getModelContext().tools?.edit,
+    );
+
+    const slowInput = view.getByRole("textbox", { name: "Slow" });
+    const immediateInput = view.getByRole("textbox", { name: "Immediate" });
+    const edit = mergedContext.tools!.edit!;
+    const slowTask = executeTool(edit, {
+      editId: (slowInput as HTMLInputElement).dataset.editId!,
+      value: "slow update",
+    });
+    const immediateTask = executeTool(edit, {
+      editId: (immediateInput as HTMLInputElement).dataset.editId!,
+      value: "immediate update",
+    });
+
+    await immediateTask;
+    expect(immediateInput).toHaveProperty("value", "immediate update");
+    let slowSettled = false;
+    void slowTask.then(() => {
+      slowSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(24);
+    expect(slowSettled).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await slowTask;
+    expect(slowInput).toHaveProperty("value", "slow update");
+  });
+
+  it("allows the action settle delay to be disabled", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const input = render(<EditableInput />).getByRole("textbox");
+    const editId = (input as HTMLInputElement).dataset.editId!;
+    const timersBefore = vi.getTimerCount();
+
+    const task = getRegisteredTools().edit!.execute({
+      editId,
+      value: "updated",
+    });
+
+    expect(vi.getTimerCount()).toBe(timersBefore);
+    await task;
+    expect(input).toHaveProperty("value", "updated");
+  });
+
+  it.each([-1, Number.NaN, Number.POSITIVE_INFINITY, 2_147_483_648])(
+    "rejects an invalid action settle delay of %s",
+    (settleDelayMs) => {
+      expect(() =>
+        makeAssistantVisible(Button, { clickable: true, settleDelayMs }),
+      ).toThrow(
+        new RangeError("settleDelayMs must be between 0 and 2147483647"),
+      );
+    },
+  );
 });

package/src/model-context/makeAssistantVisible.tsx

@@ -15,6 +15,27 @@ import { useAui } from "@assistant-ui/store";
 import { useComposedRefs } from "radix-ui/internal";
 import { tool } from "@assistant-ui/core";
 
+const DEFAULT_ACTION_SETTLE_DELAY_MS = 2000;
+const MAX_ACTION_SETTLE_DELAY_MS = 2_147_483_647;
+
+const waitForSettle = async (settleDelayMs: number) => {
+  const delay =
+    Number.isFinite(settleDelayMs) &&
+    settleDelayMs >= 0 &&
+    settleDelayMs <= MAX_ACTION_SETTLE_DELAY_MS
+      ? settleDelayMs
+      : DEFAULT_ACTION_SETTLE_DELAY_MS;
+  if (delay === 0) return;
+  await new Promise<void>((resolve) => setTimeout(resolve, delay));
+};
+
+const readActionSettleDelay = (element: HTMLElement) => {
+  const value = element.dataset.actionSettleDelay;
+  return value === undefined || value.trim() === ""
+    ? DEFAULT_ACTION_SETTLE_DELAY_MS
+    : Number(value);
+};
+
 const click = tool({
   parameters: {
     type: "object",
@@ -30,9 +51,7 @@ const click = tool({
     const el = document.querySelector(`[data-click-id='${escapedClickId}']`);
     if (el instanceof HTMLElement) {
       el.click();
-
-      // todo make adjustable
-      await new Promise((resolve) => setTimeout(resolve, 2000));
+      await waitForSettle(readActionSettleDelay(el));
       return {};
     } else {
       return "Element not found";
@@ -77,9 +96,7 @@ const edit = tool({
       setNativeValue(el, value);
       el.dispatchEvent(new Event("input", { bubbles: true }));
       el.dispatchEvent(new Event("change", { bubbles: true }));
-
-      // todo make adjustable
-      await new Promise((resolve) => setTimeout(resolve, 2000));
+      await waitForSettle(readActionSettleDelay(el));
       return {};
     } else {
       return "Element not found";
@@ -91,8 +108,23 @@ const ReadableContext = createContext<boolean>(false);
 
 export const makeAssistantVisible = <T extends ComponentType<any>>(
   Component: T,
-  config?: { clickable?: boolean | undefined; editable?: boolean | undefined },
+  config?: {
+    clickable?: boolean | undefined;
+    editable?: boolean | undefined;
+    settleDelayMs?: number | undefined;
+  },
 ) => {
+  const settleDelayMs = config?.settleDelayMs ?? DEFAULT_ACTION_SETTLE_DELAY_MS;
+  if (
+    !Number.isFinite(settleDelayMs) ||
+    settleDelayMs < 0 ||
+    settleDelayMs > MAX_ACTION_SETTLE_DELAY_MS
+  ) {
+    throw new RangeError(
+      `settleDelayMs must be between 0 and ${MAX_ACTION_SETTLE_DELAY_MS}`,
+    );
+  }
+
   const ReadableComponent = forwardRef(
     (props: PropsWithoutRef<T>, outerRef: ForwardedRef<any>) => {
       const isNestedReadable = useContext(ReadableContext);
@@ -127,6 +159,10 @@ export const makeAssistantVisible = <T extends ComponentType<any>>(
             {...(props as any)}
             {...(config?.clickable ? { "data-click-id": clickId } : {})}
             {...(config?.editable ? { "data-edit-id": clickId } : {})}
+            {...(config?.settleDelayMs !== undefined &&
+            (config.clickable || config.editable)
+              ? { "data-action-settle-delay": settleDelayMs }
+              : {})}
             ref={ref}
           />
         </ReadableContext.Provider>

package/src/primitives/assistantModal/AssistantModalRoot.tsx

@@ -7,6 +7,7 @@ import { useAuiEvent } from "@assistant-ui/store";
 
 export namespace AssistantModalPrimitiveRoot {
   export type Props = PopoverPrimitive.PopoverProps & {
+    /** @deprecated Experimental since 2024-10-12. Not scheduled for removal; the API may change in any release. */
     unstable_openOnRunStart?: boolean | undefined;
   };
 }

package/src/primitives/attachment.ts

@@ -1,4 +1,7 @@
 export { AttachmentPrimitiveRoot as Root } from "./attachment/AttachmentRoot";
-export { AttachmentPrimitiveThumb as unstable_Thumb } from "./attachment/AttachmentThumb";
+export {
+  /** @deprecated Experimental since 2024-10-10. Not scheduled for removal; the API may change in any release. */
+  AttachmentPrimitiveThumb as unstable_Thumb,
+} from "./attachment/AttachmentThumb";
 export { AttachmentPrimitiveName as Name } from "./attachment/AttachmentName";
 export { AttachmentPrimitiveRemove as Remove } from "./attachment/AttachmentRemove";