@ulearning/ai-sdk 0.0.0-stage → 1.0.0-next.0

package/src/unstable/useLiveCompletionAdapter.ts

@@ -0,0 +1,217 @@
+"use client";
+
+import {
+  computed,
+  shallowRef,
+  toValue,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useIsomorphicLayoutEffect } from "../utils/useIsomorphicLayoutEffect";
+import type {
+  Unstable_TriggerAdapter,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+
+/** @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release. */
+export type Unstable_UseLiveCompletionAdapterOptions = {
+  /**
+   * Fetches the items for a query from an async source. Called debounced; the
+   * resolved items are cached and returned synchronously to the popover on the
+   * next render.
+   */
+  readonly fetcher: (query: string) => Promise<readonly Unstable_TriggerItem[]>;
+  /**
+   * Identifies the fetcher's data source. Change this when switching accounts,
+   * workspaces, or another boundary that should invalidate cached results.
+   */
+  readonly cacheKey?: string | number | undefined;
+  /** Debounce applied before a fetch fires, in milliseconds. @default 60 */
+  readonly debounceMs?: number | undefined;
+  /** When `false`, no fetch is scheduled and the adapter stays empty. @default true */
+  readonly enabled?: boolean | undefined;
+};
+
+/** Sentinel that no real query (including the empty string) equals, so the first query always fetches. */
+const NO_QUERY = "\u0000";
+
+/**
+ * Bridges an async completion source (a server search, a gateway RPC) into the
+ * synchronous `Unstable_TriggerAdapter` that `ComposerTriggerPopover` consumes.
+ * `search(query)` returns the last fetched items synchronously and schedules a
+ * debounced fetch when the query changes; when results arrive the returned
+ * `adapter` identity changes, which re-runs the popover's lookup so the fresh
+ * items render. This is a search-only adapter (`categories` are empty).
+ *
+ * `isLoading` is `true` while a fetch is in flight. Pass it to the popover's
+ * `isLoading` prop to render a loading state.
+ *
+ * @deprecated Experimental since 2026-06-15. Not scheduled for removal; the API may change in any release.
+ *
+ * @example
+ * ```tsx
+ * const mentions = unstable_useLiveCompletionAdapter({
+ *   fetcher: (query) => searchUsers(query),
+ * });
+ *
+ * <ComposerTriggerPopover
+ *   char="@"
+ *   adapter={mentions.adapter}
+ *   isLoading={mentions.isLoading}
+ *   directive={{ onInserted }}
+ * />
+ * ```
+ */
+export function unstable_useLiveCompletionAdapter(
+  options: MaybeRefOrGetter<Unstable_UseLiveCompletionAdapterOptions>,
+): ComputedRef<{ adapter: Unstable_TriggerAdapter; isLoading: boolean }> {
+  const initial = toValue(options);
+  const state = shallowRef<{
+    query: string;
+    items: readonly Unstable_TriggerItem[];
+    failed: boolean;
+  }>({ query: NO_QUERY, items: [], failed: false });
+  const isLoading = shallowRef(false);
+  const enabled = computed(() => toValue(options).enabled ?? true);
+  let fetcher = initial.fetcher;
+  let committedEnabled = initial.enabled ?? true;
+  let debounceMs = initial.debounceMs ?? 60;
+  let cacheKey = initial.cacheKey;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let token = 0;
+  let pendingQuery: string | null = null;
+  let retryableQuery: string | null = null;
+  let pendingRetryQuery: string | null = null;
+  let inactive = true;
+  let deferredQuery: string | null = null;
+
+  const cancelTimer = () => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  const rearmPendingRetry = () => {
+    if (pendingRetryQuery === null) return;
+    retryableQuery = pendingRetryQuery;
+    pendingRetryQuery = null;
+  };
+  const invalidatePending = () => {
+    rearmPendingRetry();
+    cancelTimer();
+    pendingQuery = null;
+    token++;
+    isLoading.value = false;
+  };
+  const scheduleFetch = (query: string) => {
+    if (!committedEnabled) return;
+    if (inactive) {
+      deferredQuery = query;
+      return;
+    }
+    if (pendingQuery === query) return;
+    rearmPendingRetry();
+    if (retryableQuery === query) {
+      retryableQuery = null;
+      pendingRetryQuery = query;
+    }
+    pendingQuery = query;
+    cancelTimer();
+    const requestToken = ++token;
+    isLoading.value = true;
+    timer = setTimeout(() => {
+      timer = null;
+      Promise.resolve()
+        .then(() => fetcher(query))
+        .then(
+          (items) => {
+            if (requestToken !== token) return;
+            pendingRetryQuery = null;
+            state.value = { query, items, failed: false };
+            isLoading.value = false;
+          },
+          () => {
+            if (requestToken !== token) return;
+            pendingQuery = null;
+            pendingRetryQuery = null;
+            state.value = { query, items: [], failed: true };
+            isLoading.value = false;
+          },
+        );
+    }, debounceMs);
+  };
+  const commitConfiguration = () => {
+    const current = toValue(options);
+    fetcher = current.fetcher;
+    committedEnabled = current.enabled ?? true;
+    debounceMs = current.debounceMs ?? 60;
+    if (cacheKey !== current.cacheKey) {
+      cacheKey = current.cacheKey;
+      invalidatePending();
+      retryableQuery = null;
+      pendingRetryQuery = null;
+      state.value = { query: NO_QUERY, items: [], failed: false };
+    }
+    if (!committedEnabled) {
+      invalidatePending();
+      if (state.value.query !== NO_QUERY)
+        state.value = { query: NO_QUERY, items: [], failed: false };
+    }
+  };
+  useIsomorphicLayoutEffect(commitConfiguration, () => {
+    const current = toValue(options);
+    return [
+      current.fetcher,
+      current.cacheKey,
+      current.enabled,
+      current.debounceMs,
+    ];
+  });
+  useIsomorphicLayoutEffect(() => {
+    // Reconnection order can differ for descendant KeepAlive hooks. Commit
+    // this owner's configuration before replaying work retained while hidden.
+    commitConfiguration();
+    inactive = false;
+    const query = deferredQuery;
+    deferredQuery = null;
+    if (query !== null) scheduleFetch(query);
+    return () => {
+      inactive = true;
+      invalidatePending();
+    };
+  }, []);
+  // Arm retries only after the failure render commits, preventing render-time
+  // search from creating an automatic retry loop.
+  useIsomorphicLayoutEffect(
+    () => {
+      retryableQuery = state.value.failed ? state.value.query : null;
+    },
+    () => [state.value],
+  );
+  const adapter = computed<Unstable_TriggerAdapter>(() => {
+    const active = enabled.value;
+    const snapshot = state.value;
+    return {
+      categories: () => [],
+      categoryItems: () => [],
+      search: (query: string) => {
+        if (!active) return [];
+        if (query !== snapshot.query || retryableQuery === query) {
+          queueMicrotask(() => scheduleFetch(query));
+        } else {
+          queueMicrotask(() => {
+            if (deferredQuery !== null && deferredQuery !== query)
+              deferredQuery = null;
+            if (pendingQuery !== null && pendingQuery !== query)
+              invalidatePending();
+          });
+        }
+        return snapshot.items;
+      },
+    };
+  });
+  return computed(() => ({
+    adapter: adapter.value,
+    isLoading: isLoading.value,
+  }));
+}

package/src/unstable/useMentionAdapter.test.tsx

@@ -0,0 +1,380 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, renderHook } from "../tests/vue";
+import {
+  createTapRoot,
+  flushTapSync,
+  resource,
+  useResource,
+  useState,
+} from "@ulearning/ai-tap";
+import type { Unstable_TriggerAdapter } from "@ulearning/ai-core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TriggerNavigationResource } from "../primitives/composer/trigger/triggerNavigationResource";
+import {
+  unstable_useMentionAdapter,
+  type Unstable_UseMentionAdapterOptions,
+} from "./useMentionAdapter";
+
+const runtime = vi.hoisted(() => {
+  const state = {
+    tools: {} as Record<string, { description?: string }>,
+  };
+  const listeners = new Map<string, Set<() => void>>();
+  const events: string[] = [];
+  return {
+    state,
+    listeners,
+    events,
+    client: {
+      thread: {
+        getModelContext: () => ({ tools: state.tools }),
+      },
+      on: (
+        selector: string | { scope: string; event: string },
+        listener: () => void,
+      ) => {
+        const event = typeof selector === "string" ? selector : selector.event;
+        events.push(event);
+        const eventListeners = listeners.get(event) ?? new Set();
+        eventListeners.add(listener);
+        listeners.set(event, eventListeners);
+        return () => eventListeners.delete(listener);
+      },
+    },
+    emit: (event: string) =>
+      listeners.get(event)?.forEach((listener) => listener()),
+  };
+});
+
+vi.mock("@ulearning/ai-store", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@ulearning/ai-store")>()),
+  useAui: () => runtime.client,
+}));
+
+const TestNavigationResource = resource(function useTestNavigationResource(
+  initialAdapter: Unstable_TriggerAdapter,
+) {
+  const [adapter, setAdapter] = useState(initialAdapter);
+  const navigation = useResource(
+    TriggerNavigationResource({ adapter, query: "", open: true }),
+  );
+  return { navigation, setAdapter };
+});
+
+afterEach(cleanup);
+
+describe("unstable_useMentionAdapter", () => {
+  beforeEach(() => {
+    runtime.state.tools = {};
+    runtime.listeners.clear();
+    runtime.events.length = 0;
+  });
+
+  it("ignores flat items when categories is explicitly empty", () => {
+    const { result } = renderHook(() =>
+      unstable_useMentionAdapter({
+        items: [{ id: "alice", type: "person", label: "Alice" }],
+        categories: [],
+      }),
+    );
+
+    expect(result.current.adapter.search?.("")).toEqual([]);
+  });
+
+  it("does not expose flat items when the last category is removed", () => {
+    const items = [{ id: "alice", type: "person", label: "Alice" }];
+    const initialOptions: Unstable_UseMentionAdapterOptions = {
+      items,
+      categories: [
+        {
+          id: "people",
+          label: "People",
+          items: [{ id: "bob", type: "person", label: "Bob" }],
+        },
+      ],
+    };
+    const { result, rerender } = renderHook(
+      (options) => unstable_useMentionAdapter(options),
+      {
+        initialProps: initialOptions,
+      },
+    );
+
+    expect(result.current.adapter.search?.("")).toEqual([
+      { id: "bob", type: "person", label: "Bob" },
+    ]);
+
+    rerender({ items, categories: [] });
+    expect(result.current.adapter.search?.("")).toEqual([]);
+
+    rerender({ items });
+    expect(result.current.adapter.search?.("")).toEqual([
+      { id: "alice", type: "person", label: "Alice" },
+    ]);
+  });
+
+  it("keeps categorized model-context tools current", () => {
+    runtime.state.tools = {
+      searchDocs: { description: "Search documentation" },
+    };
+
+    const { result } = renderHook(() =>
+      unstable_useMentionAdapter({
+        categories: [{ id: "people", label: "People", items: [] }],
+        includeModelContextTools: true,
+      }),
+    );
+    const initialAdapter = result.current.adapter;
+    const navigationRoot = createTapRoot(function NavigationRoot() {
+      return useResource(TestNavigationResource(initialAdapter));
+    });
+
+    expect(navigationRoot.getValue().navigation.categories).toEqual([
+      { id: "people", label: "People" },
+      { id: "tools", label: "Tools" },
+    ]);
+    expect(runtime.events).toContain("thread.modelContextUpdate");
+
+    act(() =>
+      flushTapSync(() =>
+        navigationRoot.getValue().navigation.selectCategory("tools"),
+      ),
+    );
+
+    expect(navigationRoot.getValue().navigation.items).toEqual([
+      {
+        id: "searchDocs",
+        type: "tool",
+        label: "searchDocs",
+        description: "Search documentation",
+      },
+    ]);
+
+    act(() => {
+      runtime.state.tools = {
+        createIssue: { description: "Create an issue" },
+      };
+      runtime.emit("thread.modelContextUpdate");
+    });
+
+    expect(result.current.adapter).not.toBe(initialAdapter);
+    act(() =>
+      flushTapSync(() =>
+        navigationRoot.getValue().setAdapter(result.current.adapter),
+      ),
+    );
+    expect(navigationRoot.getValue().navigation.items).toEqual([
+      {
+        id: "createIssue",
+        type: "tool",
+        label: "createIssue",
+        description: "Create an issue",
+      },
+    ]);
+    act(() => {
+      runtime.state.tools = {};
+      runtime.emit("thread.modelContextUpdate");
+    });
+    act(() =>
+      flushTapSync(() =>
+        navigationRoot.getValue().setAdapter(result.current.adapter),
+      ),
+    );
+
+    expect(navigationRoot.getValue().navigation.categories).toEqual([
+      { id: "people", label: "People" },
+    ]);
+    expect(navigationRoot.getValue().navigation.items).toEqual([]);
+    navigationRoot.unmount();
+  });
+
+  it("keeps flat model-context tools current while navigation is open", () => {
+    runtime.state.tools = {
+      searchDocs: { description: "Search documentation" },
+    };
+
+    const { result } = renderHook(() => unstable_useMentionAdapter());
+    const initialAdapter = result.current.adapter;
+    const navigationRoot = createTapRoot(function NavigationRoot() {
+      return useResource(TestNavigationResource(initialAdapter));
+    });
+
+    expect(runtime.events).toContain("thread.modelContextUpdate");
+
+    expect(navigationRoot.getValue().navigation.items).toEqual([
+      {
+        id: "searchDocs",
+        type: "tool",
+        label: "searchDocs",
+        description: "Search documentation",
+      },
+    ]);
+
+    act(() => {
+      runtime.state.tools = {
+        createIssue: { description: "Create an issue" },
+      };
+      runtime.emit("thread.modelContextUpdate");
+    });
+
+    expect(result.current.adapter).not.toBe(initialAdapter);
+    act(() =>
+      flushTapSync(() =>
+        navigationRoot.getValue().setAdapter(result.current.adapter),
+      ),
+    );
+    expect(navigationRoot.getValue().navigation.items).toEqual([
+      {
+        id: "createIssue",
+        type: "tool",
+        label: "createIssue",
+        description: "Create an issue",
+      },
+    ]);
+    navigationRoot.unmount();
+  });
+
+  it("refreshes tool mentions when the selected thread changes", () => {
+    runtime.state.tools = {
+      searchDocs: { description: "Search documentation" },
+    };
+
+    const { result } = renderHook(() => unstable_useMentionAdapter());
+    const initialAdapter = result.current.adapter;
+
+    expect(runtime.events).toContain("threads.selectionChanged");
+
+    act(() => {
+      runtime.state.tools = {
+        createIssue: { description: "Create an issue" },
+      };
+      runtime.emit("threads.selectionChanged");
+    });
+
+    expect(result.current.adapter).not.toBe(initialAdapter);
+    expect(result.current.adapter.search?.("")).toEqual([
+      {
+        id: "createIssue",
+        type: "tool",
+        label: "createIssue",
+        description: "Create an issue",
+      },
+    ]);
+  });
+
+  it("keeps adapter identity when tool mentions are unchanged", () => {
+    runtime.state.tools = {
+      searchDocs: { description: "Search documentation" },
+    };
+
+    const { result } = renderHook(() => unstable_useMentionAdapter());
+    const initialAdapter = result.current.adapter;
+
+    act(() => {
+      runtime.state.tools = {
+        searchDocs: { description: "Search documentation" },
+      };
+      runtime.emit("thread.modelContextUpdate");
+    });
+
+    expect(result.current.adapter).toBe(initialAdapter);
+  });
+
+  it("observes a description mutated in place on a stable tool object", () => {
+    const tool = { description: "Search documentation" };
+    runtime.state.tools = { searchDocs: tool };
+
+    const { result } = renderHook(() => unstable_useMentionAdapter());
+    const initialAdapter = result.current.adapter;
+
+    act(() => {
+      tool.description = "Search the docs site";
+      runtime.emit("thread.modelContextUpdate");
+    });
+
+    expect(result.current.adapter).not.toBe(initialAdapter);
+    expect(result.current.adapter.search?.("")).toEqual([
+      {
+        id: "searchDocs",
+        type: "tool",
+        label: "searchDocs",
+        description: "Search the docs site",
+      },
+    ]);
+  });
+
+  it("uses an explicit tool category without custom categories", () => {
+    runtime.state.tools = {
+      searchDocs: { description: "Search documentation" },
+    };
+
+    const { result } = renderHook(() =>
+      unstable_useMentionAdapter({
+        includeModelContextTools: {
+          category: { id: "actions", label: "Actions" },
+        },
+      }),
+    );
+
+    expect(result.current.adapter.categories()).toEqual([
+      { id: "actions", label: "Actions" },
+    ]);
+    expect(result.current.adapter.categoryItems("actions")).toEqual([
+      {
+        id: "searchDocs",
+        type: "tool",
+        label: "searchDocs",
+        description: "Search documentation",
+      },
+    ]);
+  });
+
+  it("keeps an async explicit item list flat when a tool category is configured", () => {
+    runtime.state.tools = {
+      searchDocs: { description: "Search documentation" },
+      createIssue: { description: "Create an issue" },
+    };
+
+    const initialOptions: Unstable_UseMentionAdapterOptions = { items: [] };
+    const { result, rerender } = renderHook(
+      (options) =>
+        unstable_useMentionAdapter(() => ({
+          ...(options.value.items === undefined
+            ? {}
+            : { items: options.value.items }),
+          includeModelContextTools: {
+            category: { id: "actions", label: "Actions" },
+          },
+        })),
+      { initialProps: initialOptions },
+    );
+
+    expect(result.current.adapter.categories()).toEqual([]);
+
+    rerender({
+      items: [
+        {
+          id: "searchDocs",
+          type: "person",
+          label: "Documentation owner",
+        },
+      ],
+    });
+
+    expect(result.current.adapter.categories()).toEqual([]);
+    expect(result.current.adapter.search?.("")).toEqual([
+      {
+        id: "searchDocs",
+        type: "person",
+        label: "Documentation owner",
+      },
+      {
+        id: "createIssue",
+        type: "tool",
+        label: "createIssue",
+        description: "Create an issue",
+      },
+    ]);
+  });
+});