@assistant-ui/react 0.12.25 → 0.12.27

package/src/tests/DataRenderers.test.ts

@@ -1,52 +1,65 @@
 import { describe, it, expect } from "vitest";
-import type { DataMessagePartComponent, DataRenderersState } from "../types";
-
-/**
- * Tests for the DataRenderers state management logic.
- *
- * Since the DataRenderers resource relies on @assistant-ui/tap's resource system
- * (which requires fiber infrastructure), we test the core state logic directly.
- */
-describe("DataRenderers state logic", () => {
-  // Replicate the state management logic from DataRenderers.ts
-  const createState = (): {
-    state: DataRenderersState;
-    setDataUI: (name: string, render: DataMessagePartComponent) => () => void;
-  } => {
-    let state: DataRenderersState = { renderers: {} };
-
-    const setDataUI = (name: string, render: DataMessagePartComponent) => {
+import type {
+  DataMessagePartComponent,
+  DataRenderersState,
+} from "@assistant-ui/core/react";
+
+// The resource in DataRenderers.ts requires fiber infrastructure, so these
+// tests replicate the reducer directly and exercise it in isolation.
+
+type StateHarness = {
+  state: DataRenderersState;
+  setDataUI: (name: string, render: DataMessagePartComponent) => () => void;
+  setFallbackDataUI: (render: DataMessagePartComponent) => () => void;
+};
+
+const createState = (): StateHarness => {
+  let state: DataRenderersState = { renderers: {}, fallbacks: [] };
+
+  const setDataUI = (name: string, render: DataMessagePartComponent) => {
+    state = {
+      ...state,
+      renderers: {
+        ...state.renderers,
+        [name]: [...(state.renderers[name] ?? []), render],
+      },
+    };
+    return () => {
       state = {
         ...state,
         renderers: {
           ...state.renderers,
-          [name]: [...(state.renderers[name] ?? []), render],
+          [name]: state.renderers[name]?.filter((r) => r !== render) ?? [],
         },
       };
+    };
+  };
 
-      return () => {
-        state = {
-          ...state,
-          renderers: {
-            ...state.renderers,
-            [name]: state.renderers[name]?.filter((r) => r !== render) ?? [],
-          },
-        };
+  const setFallbackDataUI = (render: DataMessagePartComponent) => {
+    state = { ...state, fallbacks: [...state.fallbacks, render] };
+    return () => {
+      state = {
+        ...state,
+        fallbacks: state.fallbacks.filter((r) => r !== render),
       };
     };
+  };
 
-    return {
-      get state() {
-        return state;
-      },
-      setDataUI,
-    };
+  return {
+    get state() {
+      return state;
+    },
+    setDataUI,
+    setFallbackDataUI,
   };
+};
 
+describe("DataRenderers state logic", () => {
   describe("initial state", () => {
-    it("should start with empty renderers", () => {
+    it("should start with empty renderers and fallbacks", () => {
       const { state } = createState();
       expect(state.renderers).toEqual({});
+      expect(state.fallbacks).toEqual([]);
     });
   });
 
@@ -129,8 +142,78 @@ describe("DataRenderers state logic", () => {
   });
 });
 
+describe("DataRenderers fallback state logic", () => {
+  it("should register a fallback renderer", () => {
+    const s = createState();
+    const Fallback = (() => null) as unknown as DataMessagePartComponent;
+
+    s.setFallbackDataUI(Fallback);
+
+    expect(s.state.fallbacks).toHaveLength(1);
+    expect(s.state.fallbacks[0]).toBe(Fallback);
+  });
+
+  it("should unregister the fallback renderer on cleanup", () => {
+    const s = createState();
+    const Fallback = (() => null) as unknown as DataMessagePartComponent;
+
+    const unsub = s.setFallbackDataUI(Fallback);
+    expect(s.state.fallbacks).toHaveLength(1);
+
+    unsub();
+    expect(s.state.fallbacks).toHaveLength(0);
+  });
+
+  it("should stack fallbacks; the first registered takes priority", () => {
+    const s = createState();
+    const Fallback1 = (() => null) as unknown as DataMessagePartComponent;
+    const Fallback2 = (() => null) as unknown as DataMessagePartComponent;
+
+    s.setFallbackDataUI(Fallback1);
+    s.setFallbackDataUI(Fallback2);
+
+    expect(s.state.fallbacks).toEqual([Fallback1, Fallback2]);
+  });
+
+  it("should only unregister the specific fallback on cleanup", () => {
+    const s = createState();
+    const Fallback1 = (() => null) as unknown as DataMessagePartComponent;
+    const Fallback2 = (() => null) as unknown as DataMessagePartComponent;
+
+    const unsub1 = s.setFallbackDataUI(Fallback1);
+    s.setFallbackDataUI(Fallback2);
+
+    unsub1();
+    expect(s.state.fallbacks).toEqual([Fallback2]);
+  });
+
+  it("should restore the previous fallback when the active one unmounts", () => {
+    const s = createState();
+    const Fallback1 = (() => null) as unknown as DataMessagePartComponent;
+    const Fallback2 = (() => null) as unknown as DataMessagePartComponent;
+
+    s.setFallbackDataUI(Fallback1);
+    const unsub2 = s.setFallbackDataUI(Fallback2);
+
+    unsub2();
+    expect(s.state.fallbacks).toEqual([Fallback1]);
+  });
+
+  it("should not affect named renderers when setting fallback", () => {
+    const s = createState();
+    const Named = (() => null) as unknown as DataMessagePartComponent;
+    const Fallback = (() => null) as unknown as DataMessagePartComponent;
+
+    s.setDataUI("chart", Named);
+    s.setFallbackDataUI(Fallback);
+
+    expect(s.state.renderers["chart"]).toHaveLength(1);
+    expect(s.state.renderers["chart"]![0]).toBe(Named);
+    expect(s.state.fallbacks[0]).toBe(Fallback);
+  });
+});
+
 describe("Data part component resolution", () => {
-  // Replicate the component lookup logic from MessageParts.tsx
   const resolveDataComponent = (
     partName: string,
     inlineConfig?: {
@@ -138,16 +221,13 @@ describe("Data part component resolution", () => {
       Fallback?: DataMessagePartComponent;
     },
     globalRenderers?: Record<string, DataMessagePartComponent[]>,
+    globalFallbacks?: DataMessagePartComponent[],
   ): DataMessagePartComponent | undefined => {
+    const named = globalRenderers?.[partName]?.[0];
+    if (named) return named;
     const inlineFallback =
       inlineConfig?.by_name?.[partName] ?? inlineConfig?.Fallback;
-    const globalRenderer = globalRenderers?.[partName];
-
-    // Global takes priority (first element), then inline fallback
-    if (globalRenderer && globalRenderer.length > 0) {
-      return globalRenderer[0] ?? inlineFallback;
-    }
-    return inlineFallback;
+    return globalFallbacks?.[0] ?? inlineFallback;
   };
 
   it("should return undefined when no config provided", () => {
@@ -219,4 +299,57 @@ describe("Data part component resolution", () => {
     );
     expect(result).toBe(Fallback);
   });
+
+  // --- Global fallback stack resolution ---
+
+  it("should use global fallback when no name-specific renderer exists", () => {
+    const GlobalFallback = (() => null) as unknown as DataMessagePartComponent;
+
+    const result = resolveDataComponent("unknown-widget", undefined, {}, [
+      GlobalFallback,
+    ]);
+    expect(result).toBe(GlobalFallback);
+  });
+
+  it("should prefer global name-match over global fallback", () => {
+    const NamedComponent = (() => null) as unknown as DataMessagePartComponent;
+    const GlobalFallback = (() => null) as unknown as DataMessagePartComponent;
+
+    const result = resolveDataComponent(
+      "chart",
+      undefined,
+      { chart: [NamedComponent] },
+      [GlobalFallback],
+    );
+    expect(result).toBe(NamedComponent);
+  });
+
+  it("should prefer the first global fallback over inline Fallback", () => {
+    const InlineFallback = (() => null) as unknown as DataMessagePartComponent;
+    const GlobalFallback = (() => null) as unknown as DataMessagePartComponent;
+
+    const result = resolveDataComponent(
+      "unknown",
+      { Fallback: InlineFallback },
+      {},
+      [GlobalFallback],
+    );
+    expect(result).toBe(GlobalFallback);
+  });
+
+  it("should pick the first registered when multiple fallbacks are stacked", () => {
+    const First = (() => null) as unknown as DataMessagePartComponent;
+    const Second = (() => null) as unknown as DataMessagePartComponent;
+
+    const result = resolveDataComponent("anything", undefined, {}, [
+      First,
+      Second,
+    ]);
+    expect(result).toBe(First);
+  });
+
+  it("should return undefined when no fallbacks of any kind exist", () => {
+    const result = resolveDataComponent("unknown", undefined, {}, []);
+    expect(result).toBeUndefined();
+  });
 });

package/src/tests/MessageParts.loading.test.tsx

@@ -0,0 +1,104 @@
+// @vitest-environment jsdom
+
+import { render, screen, waitFor } from "@testing-library/react";
+import type { FC, PropsWithChildren } from "react";
+import { describe, expect, it } from "vitest";
+import { AssistantRuntimeProvider } from "../context";
+import * as MessagePartPrimitive from "../primitives/messagePart";
+import * as MessagePrimitive from "../primitives/message";
+import * as ThreadPrimitive from "../primitives/thread";
+import { useLocalRuntime } from "../legacy-runtime/runtime-cores/local/useLocalRuntime";
+import type { ChatModelAdapter, ThreadMessageLike } from "../index";
+
+const noOpAdapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const initialMessages: ThreadMessageLike[] = [
+  {
+    role: "assistant",
+    content: [],
+    status: { type: "running" },
+  },
+];
+
+const completeInitialMessages: ThreadMessageLike[] = [
+  {
+    role: "assistant",
+    content: [],
+    status: { type: "complete", reason: "stop" },
+  },
+];
+
+const RunningText: FC = () => {
+  return (
+    <p>
+      <MessagePartPrimitive.Text />
+      <MessagePartPrimitive.InProgress>
+        <span data-testid="loading-dot">dot</span>
+      </MessagePartPrimitive.InProgress>
+    </p>
+  );
+};
+
+const ComponentsMessage: FC = () => {
+  return <MessagePrimitive.Parts components={{ Text: RunningText }} />;
+};
+
+const ChildrenMessage: FC = () => {
+  return (
+    <MessagePrimitive.Parts>
+      {({ part }) => {
+        if (part.type === "text") return <RunningText />;
+        return null;
+      }}
+    </MessagePrimitive.Parts>
+  );
+};
+
+const RuntimeProvider: FC<
+  PropsWithChildren<{ messages?: ThreadMessageLike[] }>
+> = ({ children, messages = initialMessages }) => {
+  const runtime = useLocalRuntime(noOpAdapter, {
+    initialMessages: messages,
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+};
+
+const renderThread = (MessageComponent: FC, messages?: ThreadMessageLike[]) => {
+  render(
+    <RuntimeProvider messages={messages}>
+      <ThreadPrimitive.Messages components={{ Message: MessageComponent }} />
+    </RuntimeProvider>,
+  );
+};
+
+describe("MessagePrimitive.Parts loading state", () => {
+  it("renders the loading indicator for the components API when assistant parts are empty", async () => {
+    renderThread(ComponentsMessage);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("loading-dot")).toBeTruthy();
+    });
+  });
+
+  it("renders the loading indicator for the children API when assistant parts are empty", async () => {
+    renderThread(ChildrenMessage);
+
+    await waitFor(() => {
+      expect(screen.getByTestId("loading-dot")).toBeTruthy();
+    });
+  });
+
+  it("does not render the loading indicator when assistant parts are empty but the message is complete", async () => {
+    renderThread(ChildrenMessage, completeInitialMessages);
+
+    await waitFor(() => {
+      expect(screen.queryByTestId("loading-dot")).toBeNull();
+    });
+  });
+});

package/src/tests/RemoteThreadListRuntime.deferredProvider.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+
+import { render } from "@testing-library/react";
+import { type FC, type PropsWithChildren, useState } from "react";
+import { describe, expect, it } from "vitest";
+import { useRemoteThreadListRuntime } from "@assistant-ui/core/react";
+import { makeAdapter } from "@assistant-ui/core/tests/remote-thread-list-test-helpers";
+import type { AssistantRuntime } from "@assistant-ui/core";
+import { AssistantRuntimeProvider } from "../context";
+import { useLocalRuntime } from "../legacy-runtime/runtime-cores/local/useLocalRuntime";
+import { useAssistantRuntime } from "../legacy-runtime/hooks/AssistantContext";
+import type { ChatModelAdapter, RemoteThreadListAdapter } from "../index";
+
+const noOpAdapter: ChatModelAdapter = {
+  async *run() {},
+};
+
+const useTestRuntimeHook = () => useLocalRuntime(noOpAdapter);
+
+const RuntimeProvider: FC<
+  PropsWithChildren<{ adapter: RemoteThreadListAdapter }>
+> = ({ children, adapter }) => {
+  const runtime = useRemoteThreadListRuntime({
+    runtimeHook: useTestRuntimeHook,
+    adapter,
+  });
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+};
+
+const RuntimeCapture: FC<{
+  runtimeRef: { current: AssistantRuntime | null };
+}> = ({ runtimeRef }) => {
+  const runtime = useAssistantRuntime();
+  runtimeRef.current = runtime;
+  return null;
+};
+
+// regression for #3678: deferred unstable_Provider must not strand the runtime binder.
+describe("useRemoteThreadListRuntime with a deferred unstable_Provider", () => {
+  it("composer.setText does not throw EMPTY_THREAD_ERROR when unstable_Provider defers children", () => {
+    const Provider: FC<PropsWithChildren> = ({ children }) => {
+      const [ready] = useState(false);
+      if (!ready) return null;
+      return <>{children}</>;
+    };
+    const adapter = makeAdapter({ unstable_Provider: Provider });
+
+    const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+    render(
+      <RuntimeProvider adapter={adapter}>
+        <RuntimeCapture runtimeRef={runtimeRef} />
+      </RuntimeProvider>,
+    );
+
+    const runtime = runtimeRef.current;
+    expect(runtime).toBeTruthy();
+    expect(() => runtime!.thread.composer.setText("hello")).not.toThrow();
+  });
+
+  it("composer.setText still works when unstable_Provider renders children unconditionally", () => {
+    const Provider: FC<PropsWithChildren> = ({ children }) => <>{children}</>;
+    const adapter = makeAdapter({ unstable_Provider: Provider });
+
+    const runtimeRef: { current: AssistantRuntime | null } = { current: null };
+    render(
+      <RuntimeProvider adapter={adapter}>
+        <RuntimeCapture runtimeRef={runtimeRef} />
+      </RuntimeProvider>,
+    );
+
+    const runtime = runtimeRef.current;
+    expect(runtime).toBeTruthy();
+    expect(() => runtime!.thread.composer.setText("hello")).not.toThrow();
+  });
+});

package/src/unstable/useMentionAdapter.ts

@@ -0,0 +1,220 @@
+"use client";
+
+import { useMemo, type FC } from "react";
+import { useAui } from "@assistant-ui/store";
+import type {
+  Unstable_DirectiveFormatter,
+  Unstable_TriggerAdapter,
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@assistant-ui/core";
+import { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+import type { ReadonlyJSONObject } from "assistant-stream/utils";
+
+/** Icon component shape consumed by `ComposerTriggerPopover`'s `iconMap`. */
+export type Unstable_IconComponent = FC<{ className?: string }>;
+
+export type Unstable_Mention = {
+  readonly id: string;
+  readonly type: string;
+  readonly label: string;
+  readonly description?: string | undefined;
+  /** Shortcut for `metadata.icon`; merged with `metadata` if both are given. */
+  readonly icon?: string | undefined;
+  readonly metadata?: ReadonlyJSONObject | undefined;
+};
+
+export type Unstable_MentionCategory = {
+  readonly id: string;
+  readonly label: string;
+  readonly items: readonly Unstable_Mention[];
+};
+
+export type Unstable_ModelContextToolsOptions = {
+  /** Wrap tools in a dedicated category (drill-down mode). */
+  readonly category?: { readonly id: string; readonly label: string };
+  /** Format tool name for display. */
+  readonly formatLabel?: (toolName: string) => string;
+  /** Default icon key for each tool. */
+  readonly icon?: string;
+};
+
+export type Unstable_UseMentionAdapterOptions = {
+  /** Flat mention list. Ignored when `categories` is set. */
+  readonly items?: readonly Unstable_Mention[];
+  /** Categorized mentions for drill-down navigation. */
+  readonly categories?: readonly Unstable_MentionCategory[];
+  /**
+   * How tools registered via `useAssistantTool` integrate.
+   * - `false`: exclude.
+   * - `true`: include (default when no `items`/`categories`; as a category
+   *   if `categories` is set, flat otherwise).
+   * - object: explicit config.
+   *
+   * Omitted → defaults to `true` iff neither `items` nor `categories`.
+   */
+  readonly includeModelContextTools?:
+    | boolean
+    | Unstable_ModelContextToolsOptions;
+  /** Directive formatter. @default unstable_defaultDirectiveFormatter */
+  readonly formatter?: Unstable_DirectiveFormatter;
+  /** Fires after an item is inserted into the composer. */
+  readonly onInserted?: (item: Unstable_TriggerItem) => void;
+  /** Maps `metadata.icon` / `category.id` string keys to React components. */
+  readonly iconMap?: Record<string, Unstable_IconComponent>;
+  /** Fallback icon when no entry in `iconMap` matches. */
+  readonly fallbackIcon?: Unstable_IconComponent;
+};
+
+export type Unstable_MentionDirective = {
+  readonly formatter: Unstable_DirectiveFormatter;
+  readonly onInserted?: ((item: Unstable_TriggerItem) => void) | undefined;
+};
+
+/**
+ * @deprecated Under active development and might change without notice.
+ *
+ * Creates a spreadable `{ adapter, directive }` bundle for `@` mentions.
+ * Supports tools registered via `useAssistantTool`, explicit items, or both —
+ * flat or categorized.
+ *
+ * @example
+ * ```tsx
+ * const mention = unstable_useMentionAdapter();
+ * <ComposerTriggerPopover char="@" {...mention} />
+ * ```
+ */
+export function unstable_useMentionAdapter(
+  options?: Unstable_UseMentionAdapterOptions,
+): {
+  adapter: Unstable_TriggerAdapter;
+  directive: Unstable_MentionDirective;
+  iconMap?: Record<string, Unstable_IconComponent>;
+  fallbackIcon?: Unstable_IconComponent;
+} {
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
+  const aui = useAui();
+
+  const items = options?.items;
+  const categories = options?.categories;
+  const includeTools =
+    options?.includeModelContextTools ?? (!items && !categories);
+  const toolsConfig =
+    typeof includeTools === "object" ? includeTools : undefined;
+  const wantsTools = includeTools !== false;
+  const formatter = options?.formatter;
+  const onInserted = options?.onInserted;
+
+  // biome-ignore lint/correctness/useHookAtTopLevel: intentional conditional/nested hook usage
+  const adapter = useMemo<Unstable_TriggerAdapter>(() => {
+    const getModelContextTools = (): Unstable_TriggerItem[] => {
+      if (!wantsTools) return [];
+      const ctx = aui.thread().getModelContext();
+      const tools = ctx.tools;
+      if (!tools) return [];
+      const formatLabel = toolsConfig?.formatLabel;
+      const defaultIcon = toolsConfig?.icon;
+      return Object.entries(tools).map(([name, tool]) =>
+        toTriggerItem({
+          id: name,
+          type: "tool",
+          label: formatLabel ? formatLabel(name) : name,
+          description: tool.description ?? undefined,
+          icon: defaultIcon,
+        }),
+      );
+    };
+
+    // Categorized: drill-down mode
+    if (categories && categories.length > 0) {
+      const groups = categories.map((cat) => ({
+        id: cat.id,
+        label: cat.label,
+        items: cat.items.map(toTriggerItem),
+      }));
+
+      let toolCategory: {
+        id: string;
+        label: string;
+        items: Unstable_TriggerItem[];
+      } | null = null;
+      if (wantsTools) {
+        const toolItems = getModelContextTools();
+        if (toolItems.length > 0) {
+          toolCategory = {
+            id: toolsConfig?.category?.id ?? "tools",
+            label: toolsConfig?.category?.label ?? "Tools",
+            items: toolItems,
+          };
+        }
+      }
+      const allGroups = toolCategory ? [...groups, toolCategory] : groups;
+
+      return {
+        categories: () => allGroups.map(({ id, label }) => ({ id, label })),
+        categoryItems: (id) => allGroups.find((g) => g.id === id)?.items ?? [],
+        search: (query) => {
+          const lower = query.toLowerCase();
+          return allGroups
+            .flatMap((g) => g.items)
+            .filter((item) => matchesQuery(item, lower));
+        },
+      };
+    }
+
+    // Flat: items + (optionally) tools, all in one search pool
+    const flatItems = (items ?? []).map(toTriggerItem);
+    const getFlatPool = (): Unstable_TriggerItem[] => {
+      if (!wantsTools) return flatItems;
+      const toolItems = getModelContextTools();
+      // Dedupe by id — explicit items win.
+      const seen = new Set(flatItems.map((i) => i.id));
+      return [...flatItems, ...toolItems.filter((t) => !seen.has(t.id))];
+    };
+
+    return {
+      categories: (): readonly Unstable_TriggerCategory[] => [],
+      categoryItems: () => [],
+      search: (query) => {
+        const lower = query.toLowerCase();
+        return getFlatPool().filter((item) => matchesQuery(item, lower));
+      },
+    };
+  }, [aui, items, categories, wantsTools, toolsConfig]);
+
+  // biome-ignore lint/correctness/useHookAtTopLevel: `unstable_` prefix not recognized as hook
+  const directive = useMemo<Unstable_MentionDirective>(
+    () => ({
+      formatter: formatter ?? unstable_defaultDirectiveFormatter,
+      ...(onInserted ? { onInserted } : {}),
+    }),
+    [formatter, onInserted],
+  );
+
+  return {
+    adapter,
+    directive,
+    ...(options?.iconMap ? { iconMap: options.iconMap } : {}),
+    ...(options?.fallbackIcon ? { fallbackIcon: options.fallbackIcon } : {}),
+  };
+}
+
+function toTriggerItem(m: Unstable_Mention): Unstable_TriggerItem {
+  const metadata =
+    m.icon !== undefined ? { ...(m.metadata ?? {}), icon: m.icon } : m.metadata;
+  return {
+    id: m.id,
+    type: m.type,
+    label: m.label,
+    ...(m.description !== undefined ? { description: m.description } : {}),
+    ...(metadata !== undefined ? { metadata } : {}),
+  };
+}
+
+function matchesQuery(item: Unstable_TriggerItem, lower: string): boolean {
+  if (!lower) return true;
+  if (item.id.toLowerCase().includes(lower)) return true;
+  if (item.label.toLowerCase().includes(lower)) return true;
+  if (item.description?.toLowerCase().includes(lower)) return true;
+  return false;
+}