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

package/src/tests/vue.ts

@@ -0,0 +1,124 @@
+import { flushTapSync } from "@ulearning/ai-tap";
+import {
+  createApp,
+  defineComponent,
+  h,
+  isRef,
+  nextTick,
+  shallowRef,
+  type App,
+  type Ref,
+  type VNode,
+} from "vue";
+
+const apps = new Set<App>();
+const containers = new Set<HTMLElement>();
+export const fixtureRevision = shallowRef(0);
+export const act = <T>(action: () => T): T => flushTapSync(action);
+export async function actAsync<T>(action: () => T): Promise<Awaited<T>> {
+  const result = await flushTapSync(action);
+  await nextTick();
+  return result;
+}
+export function createTestRoot(container: HTMLElement) {
+  const source = shallowRef<VNode | null>(null);
+  let app: App | undefined;
+  return {
+    render(node: VNode) {
+      source.value = node;
+      if (!app) {
+        app = createApp(defineComponent({ setup: () => () => source.value }));
+        apps.add(app);
+        app.mount(container);
+      }
+    },
+    unmount() {
+      if (app) {
+        app.unmount();
+        apps.delete(app);
+        app = undefined;
+      }
+    },
+  };
+}
+export const cleanup = () => {
+  for (const app of apps) app.unmount();
+  apps.clear();
+  for (const container of containers) container.remove();
+  containers.clear();
+};
+export function render(node: VNode, options?: { container?: HTMLElement }) {
+  const source = shallowRef(node);
+  const container = options?.container ?? document.createElement("div");
+  if (!options?.container) document.body.append(container);
+  containers.add(container);
+  const app = createApp(defineComponent({ setup: () => () => source.value }));
+  apps.add(app);
+  app.mount(container);
+  return {
+    container,
+    queryByTestId(id: string) {
+      return container.querySelector<HTMLElement>(`[data-testid="${id}"]`);
+    },
+    getByTestId(id: string) {
+      const element = container.querySelector<HTMLElement>(
+        `[data-testid="${id}"]`,
+      );
+      if (!element) throw new Error(`Missing test element: ${id}`);
+      return element;
+    },
+    async rerender(value: VNode) {
+      flushTapSync(() => {
+        source.value = value;
+      });
+      await nextTick();
+    },
+    unmount() {
+      app.unmount();
+      apps.delete(app);
+      container.remove();
+      containers.delete(container);
+    },
+  };
+}
+export function renderHook<T, P = undefined>(
+  setup: (props: Ref<P>) => T,
+  options?: { initialProps: P },
+) {
+  const props = shallowRef(options?.initialProps as P);
+  let value!: T;
+  const fixture = render(
+    h(
+      defineComponent({
+        setup() {
+          value = setup(props);
+          return () => null;
+        },
+      }),
+    ),
+  );
+  return {
+    result: {
+      get current(): T extends Ref<infer U> ? U : T {
+        return (isRef(value) ? value.value : value) as T extends Ref<infer U>
+          ? U
+          : T;
+      },
+    },
+    rerender(next: P) {
+      props.value = next;
+      fixtureRevision.value++;
+    },
+    unmount: fixture.unmount,
+  };
+}
+
+/** Ignore Vue's invisible fragment anchors when asserting visible HTML. */
+export function visibleHTML(container: HTMLElement) {
+  const clone = container.cloneNode(true) as HTMLElement;
+  const walker = document.createTreeWalker(clone, NodeFilter.SHOW_COMMENT);
+  const comments: Node[] = [];
+  while (walker.nextNode()) comments.push(walker.currentNode);
+  for (const node of comments) node.parentNode!.removeChild(node);
+  return clone.innerHTML;
+}

package/src/unstable/useComposerInput.test.tsx

@@ -0,0 +1,201 @@
+/** @vitest-environment jsdom */
+import {
+  computed,
+  defineComponent,
+  h,
+  shallowReactive,
+  type ComputedRef,
+} from "vue";
+import { cleanup, render } from "../tests/vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+type ComposerState = { isEditing: boolean; text: string };
+
+const fixture = shallowReactive({
+  composer: { isEditing: true, text: "hello" } as ComposerState,
+  threadDisabled: false,
+  dictationInputDisabled: undefined as boolean | undefined,
+  sendDisabled: false,
+  activeAria: null as { popoverId: string; highlightedItemId?: string } | null,
+});
+afterEach(cleanup);
+
+const composerSetText = vi.fn();
+const composerSend = vi.fn();
+const flushTapSync = vi.fn((fn: () => void) => fn());
+
+vi.mock("@ulearning/ai-store", () => ({
+  useAui: () => ({
+    composer: {
+      getState: () => ({ isEditing: fixture.composer.isEditing }),
+      setText: composerSetText,
+      send: composerSend,
+    },
+  }),
+  useAuiState: (selector: (s: unknown) => unknown) =>
+    computed(() =>
+      selector({
+        composer: {
+          isEditing: fixture.composer.isEditing,
+          text: fixture.composer.text,
+          dictation: fixture.dictationInputDisabled
+            ? { inputDisabled: fixture.dictationInputDisabled }
+            : undefined,
+        },
+        thread: { isDisabled: fixture.threadDisabled },
+      }),
+    ),
+}));
+vi.mock("@ulearning/ai-tap", () => ({
+  flushTapSync: (fn: () => void) => flushTapSync(fn),
+}));
+vi.mock("@ulearning/ai-core/vue", () => ({
+  useComposerSend: () => ({
+    send: composerSend,
+    disabled: computed(() => fixture.sendDisabled),
+  }),
+}));
+vi.mock("../primitives/composer/trigger/TriggerPopoverRootContext", () => ({
+  useTriggerPopoverActiveAriaOptional: () => computed(() => fixture.activeAria),
+}));
+
+import {
+  unstable_useComposerInput,
+  unstable_useTriggerPopoverAriaProps,
+  type Unstable_ComposerInput,
+  type Unstable_TriggerPopoverAriaProps,
+} from "./useComposerInput";
+
+const renderInput = (options?: { disabled?: boolean }) => {
+  let result!: Unstable_ComposerInput;
+  const Harness = defineComponent({
+    setup() {
+      result = unstable_useComposerInput(options);
+      return () => null;
+    },
+  });
+  render(h(Harness));
+  return () => result;
+};
+
+const renderAria = () => {
+  let result!: ComputedRef<Unstable_TriggerPopoverAriaProps>;
+  const Harness = defineComponent({
+    setup() {
+      result = unstable_useTriggerPopoverAriaProps();
+      return () => null;
+    },
+  });
+  render(h(Harness));
+  return () => result.value;
+};
+
+beforeEach(() => {
+  fixture.composer = { isEditing: true, text: "hello" };
+  fixture.threadDisabled = false;
+  fixture.dictationInputDisabled = undefined;
+  fixture.sendDisabled = false;
+  fixture.activeAria = null;
+  composerSetText.mockClear();
+  composerSend.mockClear();
+  flushTapSync.mockClear();
+});
+
+describe("unstable_useComposerInput", () => {
+  it("exposes the composer text while editing", () => {
+    expect(renderInput()().value.value).toBe("hello");
+  });
+
+  it("reports an empty value when the composer is not editing", () => {
+    fixture.composer = { isEditing: false, text: "stale" };
+    expect(renderInput()().value.value).toBe("");
+  });
+
+  it("writes text via flushTapSync when editing", () => {
+    renderInput()().setText("world");
+    expect(flushTapSync).toHaveBeenCalledTimes(1);
+    expect(composerSetText).toHaveBeenCalledWith("world", { origin: "user" });
+  });
+
+  it("ignores setText when the composer is not editing (editing guard)", () => {
+    fixture.composer = { isEditing: false, text: "" };
+    renderInput()().setText("world");
+    expect(composerSetText).not.toHaveBeenCalled();
+  });
+
+  it("combines the disabled option with composer disabled sources", () => {
+    expect(renderInput()().isDisabled.value).toBe(false);
+    expect(renderInput({ disabled: true })().isDisabled.value).toBe(true);
+
+    fixture.threadDisabled = true;
+    expect(renderInput()().isDisabled.value).toBe(true);
+
+    fixture.threadDisabled = false;
+    fixture.dictationInputDisabled = true;
+    expect(renderInput()().isDisabled.value).toBe(true);
+  });
+
+  it("derives canSend from send gating and disabled state", () => {
+    expect(renderInput()().canSend.value).toBe(true);
+
+    fixture.sendDisabled = true;
+    expect(renderInput()().canSend.value).toBe(false);
+
+    fixture.sendDisabled = false;
+    expect(renderInput({ disabled: true })().canSend.value).toBe(false);
+
+    fixture.threadDisabled = true;
+    expect(renderInput()().canSend.value).toBe(false);
+
+    fixture.threadDisabled = false;
+    fixture.dictationInputDisabled = true;
+    expect(renderInput()().canSend.value).toBe(false);
+  });
+
+  it("forwards send options to the composer action", () => {
+    renderInput()().send({ steer: true });
+    expect(composerSend).toHaveBeenCalledWith({ steer: true });
+  });
+
+  it("does not send while send is unavailable or the input is disabled", () => {
+    fixture.sendDisabled = true;
+    renderInput()().send();
+    expect(composerSend).not.toHaveBeenCalled();
+
+    fixture.sendDisabled = false;
+    renderInput({ disabled: true })().send();
+    expect(composerSend).not.toHaveBeenCalled();
+
+    fixture.threadDisabled = true;
+    renderInput()().send();
+    expect(composerSend).not.toHaveBeenCalled();
+
+    fixture.threadDisabled = false;
+    fixture.dictationInputDisabled = true;
+    renderInput()().send();
+    expect(composerSend).not.toHaveBeenCalled();
+  });
+});
+
+describe("unstable_useTriggerPopoverAriaProps", () => {
+  it("is empty when no popover is active", () => {
+    expect(renderAria()()).toEqual({});
+  });
+
+  it("describes the active popover combobox relationship", () => {
+    fixture.activeAria = { popoverId: "pop-1", highlightedItemId: "item-2" };
+    expect(renderAria()()).toEqual({
+      "aria-controls": "pop-1",
+      "aria-expanded": true,
+      "aria-haspopup": "listbox",
+      "aria-activedescendant": "item-2",
+    });
+  });
+
+  it("emits an undefined aria-activedescendant when nothing is highlighted", () => {
+    fixture.activeAria = { popoverId: "pop-1" };
+    const props = renderAria()();
+    expect(props).toHaveProperty("aria-activedescendant", undefined);
+    expect(props["aria-controls"]).toBe("pop-1");
+  });
+});

package/src/unstable/useComposerInput.ts

@@ -0,0 +1,125 @@
+"use client";
+
+import {
+  computed,
+  toValue,
+  type ComputedRef,
+  type ShallowRef,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useAui } from "@ulearning/ai-store";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { useComposerSend } from "@ulearning/ai-core/vue";
+import type { ComposerSendOptions } from "@ulearning/ai-core/store";
+import {
+  type TriggerPopoverAriaProps,
+  useComposerInputDisabled,
+  useComposerInputValue,
+  useTriggerPopoverAriaProps,
+} from "../primitives/composer/useComposerInputState";
+
+/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */
+export type Unstable_UseComposerInputOptions = {
+  /**
+   * Disables the input in addition to the composer's own disabled sources
+   * (thread disabled, active dictation). When disabled, `isDisabled` is `true`
+   * and `canSend` is `false`.
+   */
+  disabled?: boolean | undefined;
+};
+
+/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */
+export type Unstable_ComposerInput = {
+  /** Current composer text, or `""` when the composer is not editing. */
+  value: Readonly<ShallowRef<string>>;
+  /**
+   * Writes `text` into the composer, mirroring `ComposerPrimitive.Input`:
+   * a no-op unless the composer is editing; the controlled value stays in
+   * sync within the same tick.
+   */
+  setText(text: string): void;
+  /**
+   * Sends the current message when `canSend` is `true`; otherwise a no-op.
+   * Accepts the same options as the composer send action.
+   */
+  send(options?: ComposerSendOptions): void;
+  /**
+   * Whether the input is disabled, combining the `disabled` option with the
+   * composer's own disabled sources (thread disabled, active dictation).
+   */
+  isDisabled: ComputedRef<boolean>;
+  /**
+   * Whether a send is currently available. Matches `ComposerPrimitive.Send`
+   * gating (non-empty editing composer, not running without queue support) and
+   * is additionally `false` while `isDisabled`.
+   */
+  canSend: ComputedRef<boolean>;
+};
+
+/**
+ * Headless bridge to the composer's text value and send action, for building a
+ * custom composer input without `ComposerPrimitive.Input`. It is a thin bridge,
+ * not a second input: it does not own keyboard behavior, autosize, IME or
+ * contentEditable sync, paste/drop attachments, focus management, or rich-text
+ * state. Spread `unstable_useTriggerPopoverAriaProps()` onto your element for
+ * trigger-popover combobox semantics.
+ *
+ * @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release.
+ *
+ * @example
+ * ```tsx
+ * const { value, setText, send, isDisabled, canSend } = unstable_useComposerInput();
+ * <textarea
+ *   value={value}
+ *   disabled={isDisabled}
+ *   onChange={(e) => setText(e.target.value)}
+ *   onKeyDown={(e) => {
+ *     if (e.nativeEvent.isComposing || e.keyCode === 229) return;
+ *
+ *     if (e.key === "Enter" && !e.shiftKey && canSend) {
+ *       e.preventDefault();
+ *       send();
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export function unstable_useComposerInput(
+  options?: MaybeRefOrGetter<Unstable_UseComposerInputOptions>,
+): Unstable_ComposerInput {
+  const aui = useAui();
+  const value = useComposerInputValue();
+  const isDisabled = useComposerInputDisabled(() => toValue(options)?.disabled);
+  const setText = (text: string) => {
+    if (!aui.composer.getState().isEditing) return;
+    flushTapSync(() => aui.composer.setText(text, { origin: "user" }));
+  };
+  const { send: rawSend, disabled: sendDisabled } = useComposerSend();
+  const canSend = computed(() => !sendDisabled.value && !isDisabled.value);
+  const send = (sendOptions?: ComposerSendOptions) => {
+    if (canSend.value) rawSend(sendOptions);
+  };
+  return { value, setText, send, isDisabled, canSend };
+}
+
+/** @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release. */
+export type Unstable_TriggerPopoverAriaProps = TriggerPopoverAriaProps;
+
+/**
+ * ARIA combobox attributes for the focused element (typically the composer
+ * input) describing the open trigger popover, per the WAI-ARIA editable
+ * combobox pattern. Returns an empty object outside a `TriggerPopoverRoot` or
+ * when no popover is open. Spread these last so they take precedence over any
+ * matching ARIA props you set yourself, mirroring `ComposerPrimitive.Input`.
+ *
+ * @deprecated Experimental since 2026-06-23. Not scheduled for removal; the API may change in any release.
+ *
+ * @example
+ * ```tsx
+ * const aria = unstable_useTriggerPopoverAriaProps();
+ * <textarea {...aria} />
+ * ```
+ */
+export function unstable_useTriggerPopoverAriaProps(): ComputedRef<Unstable_TriggerPopoverAriaProps> {
+  return useTriggerPopoverAriaProps();
+}

package/src/unstable/useComposerInputHistory.test.tsx

@@ -0,0 +1,207 @@
+/** @vitest-environment jsdom */
+import { createEvent, fireEvent, screen } from "@testing-library/dom";
+import { defineComponent, h, nextTick } from "vue";
+import { cleanup, render } from "../tests/vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const fixture = {
+  messages: [] as { role: string; content: { type: string; text: string }[] }[],
+  composerType: "thread",
+  activeAria: null as object | null,
+  selectionChangedHandlers: [] as (() => void)[],
+};
+const setText = vi.fn();
+
+vi.mock("@ulearning/ai-store", () => ({
+  useAui: () => ({
+    optional: { threads: {} },
+    composer: {
+      getState: () => ({ type: fixture.composerType }),
+      setText,
+    },
+    thread: { getState: () => ({ messages: fixture.messages }) },
+    on: (_event: string, cb: () => void) => {
+      fixture.selectionChangedHandlers.push(cb);
+      return () => {};
+    },
+  }),
+}));
+vi.mock("@ulearning/ai-tap", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@ulearning/ai-tap")>()),
+  flushTapSync: (fn: () => void) => fn(),
+}));
+vi.mock("../primitives/composer/trigger/TriggerPopoverRootContext", () => ({
+  useTriggerPopoverRootContextOptional: () => ({
+    getActiveAria: () => fixture.activeAria,
+  }),
+}));
+
+import { unstable_useComposerInputHistory } from "./useComposerInputHistory";
+
+const user = (text: string) => ({
+  role: "user",
+  content: [{ type: "text", text }],
+});
+const assistant = (text: string) => ({
+  role: "assistant",
+  content: [{ type: "text", text }],
+});
+
+const Harness = defineComponent({
+  setup() {
+    const history = unstable_useComposerInputHistory();
+    return () =>
+      h("textarea", { "data-testid": "input", onKeydown: history.onKeyDown });
+  },
+});
+const setup = async (value = "") => {
+  const utils = render(h(Harness));
+  await nextTick();
+  const textarea = screen.getByTestId("input") as HTMLTextAreaElement;
+  textarea.value = value;
+  textarea.setSelectionRange(value.length, value.length);
+  return { ...utils, textarea };
+};
+
+const arrow = (
+  textarea: HTMLTextAreaElement,
+  key: "ArrowUp" | "ArrowDown",
+  init: Record<string, unknown> = {},
+) => fireEvent.keyDown(textarea, { key, ...init });
+
+beforeEach(() => {
+  fixture.messages = [user("first"), assistant("reply"), user("second")];
+  fixture.composerType = "thread";
+  fixture.activeAria = null;
+  fixture.selectionChangedHandlers = [];
+  setText.mockClear();
+});
+
+afterEach(cleanup);
+
+describe("unstable_useComposerInputHistory", () => {
+  it("recalls the newest user message on ArrowUp in an empty composer", async () => {
+    const { textarea } = await setup("");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(false);
+    expect(setText).toHaveBeenCalledWith("second", { origin: "recall" });
+  });
+
+  it("steps to older entries and consumes the key at the oldest", async () => {
+    const { textarea } = await setup("");
+    arrow(textarea, "ArrowUp");
+    textarea.value = "second";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("first", { origin: "recall" });
+
+    textarea.value = "first";
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(false);
+    expect(setText).toHaveBeenCalledTimes(2);
+  });
+
+  it("restores the draft snapshot on ArrowDown past the newest", async () => {
+    const { textarea } = await setup("  ");
+    arrow(textarea, "ArrowUp");
+    textarea.value = "second";
+    arrow(textarea, "ArrowDown");
+    expect(setText).toHaveBeenLastCalledWith("  ", { origin: "recall" });
+
+    textarea.value = "  ";
+    const notPrevented = arrow(textarea, "ArrowDown");
+    expect(notPrevented).toBe(true);
+    expect(setText).toHaveBeenCalledTimes(2);
+  });
+
+  it("ignores ArrowUp when the composer holds a typed draft", async () => {
+    const { textarea } = await setup("draft in progress");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("keeps native arrows when the caret is not on the first line", async () => {
+    fixture.messages = [user("other"), user("line1\nline2")];
+    const { textarea } = await setup("");
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("line1\nline2", {
+      origin: "recall",
+    });
+    textarea.value = "line1\nline2";
+    textarea.setSelectionRange(8, 8);
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).toHaveBeenCalledTimes(1);
+  });
+
+  it("yields to an open trigger popover", async () => {
+    fixture.activeAria = {};
+    const { textarea } = await setup("");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("ignores IME composition, modifiers, selections, and prevented events", async () => {
+    const { textarea } = await setup("");
+    fireEvent.keyDown(textarea, { key: "ArrowUp", isComposing: true });
+    arrow(textarea, "ArrowUp", { shiftKey: true });
+    arrow(textarea, "ArrowUp", { metaKey: true });
+    textarea.value = "ab";
+    textarea.setSelectionRange(0, 2);
+    arrow(textarea, "ArrowUp");
+
+    textarea.value = "";
+    textarea.setSelectionRange(0, 0);
+    const prevented = createEvent.keyDown(textarea, { key: "ArrowUp" });
+    prevented.preventDefault();
+    fireEvent(textarea, prevented);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("derives the ring from trimmed user texts, newest first, deduped", async () => {
+    fixture.messages = [
+      user("first"),
+      user("first"),
+      assistant("noise"),
+      user("   "),
+      user("second"),
+    ];
+    const { textarea } = await setup("");
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("second", { origin: "recall" });
+    textarea.value = "second";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("first", { origin: "recall" });
+    textarea.value = "first";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenCalledTimes(2);
+  });
+
+  it("starts a fresh browse after the composer was cleared externally", async () => {
+    const { textarea } = await setup("");
+    arrow(textarea, "ArrowUp");
+    fixture.messages = [...fixture.messages, user("third")];
+    textarea.value = "";
+    arrow(textarea, "ArrowUp");
+    expect(setText).toHaveBeenLastCalledWith("third", { origin: "recall" });
+  });
+
+  it("is inert on edit composers", async () => {
+    fixture.composerType = "edit";
+    const { textarea } = await setup("");
+    const notPrevented = arrow(textarea, "ArrowUp");
+    expect(notPrevented).toBe(true);
+    expect(setText).not.toHaveBeenCalled();
+  });
+
+  it("resets browsing when the thread switches", async () => {
+    const { textarea } = await setup("");
+    arrow(textarea, "ArrowUp");
+    fixture.selectionChangedHandlers.forEach((cb) => cb());
+    textarea.value = "second";
+    const notPrevented = arrow(textarea, "ArrowDown");
+    expect(notPrevented).toBe(true);
+    expect(setText).toHaveBeenCalledTimes(1);
+  });
+});