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

package/src/primitives/composer/ComposerInput.text-change.test.tsx

@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+
+import { fireEvent, screen } from "@testing-library/dom";
+import { defineComponent, h, nextTick } from "vue";
+import { actAsync as act, cleanup, render } from "../../tests/vue";
+import { afterEach, expect, it } from "vitest";
+import { useAui } from "@ulearning/ai-store";
+import { useLocalRuntime } from "@ulearning/ai-core/vue";
+import type { ChatModelAdapter } from "@ulearning/ai-core";
+import { AssistantRuntimeProvider } from "@ulearning/ai-core/vue";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { ComposerPrimitiveInput } from "./ComposerInput";
+
+const adapter: ChatModelAdapter = {
+  async *run() {
+    yield { content: [{ type: "text", text: "done" }] };
+  },
+};
+
+afterEach(cleanup);
+
+it("emits composer.textChange with the user origin for typing and the send origin for the clear", async () => {
+  let aui!: ReturnType<typeof useAui>;
+  const Capture = defineComponent({
+    setup() {
+      aui = useAui();
+      return () => null;
+    },
+  });
+  const App = defineComponent({
+    setup() {
+      const runtime = useLocalRuntime(adapter);
+      return () =>
+        h(
+          AssistantRuntimeProvider,
+          { runtime },
+          {
+            default: () => [
+              h(Capture),
+              h(ThreadPrimitiveViewportProvider, null, {
+                default: () =>
+                  h(ComposerPrimitiveInput, { "aria-label": "Composer" }),
+              }),
+            ],
+          },
+        );
+    },
+  });
+  render(h(App));
+  await nextTick();
+  const changes: unknown[] = [];
+  aui.on({ scope: "*", event: "composer.textChange" }, (change) =>
+    changes.push(change),
+  );
+  const input = screen.getByRole("textbox", { name: "Composer" });
+
+  await act(async () => {
+    fireEvent.input(input, { target: { value: "hi" } });
+  });
+  await act(async () => {
+    fireEvent.input(input, { target: { value: "" } });
+  });
+  await act(async () => {
+    fireEvent.input(input, { target: { value: "hello" } });
+  });
+  await act(async () => {
+    aui.composer.send();
+  });
+
+  const threadId = aui.threads.getState().mainThreadId;
+  expect(changes).toEqual([
+    { threadId, text: "hi", origin: "user" },
+    { threadId, text: "", origin: "user" },
+    { threadId, text: "hello", origin: "user" },
+    { threadId, text: "", origin: "send" },
+  ]);
+});

package/src/primitives/composer/ComposerInput.thread-scope.test.tsx

@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+
+import { fireEvent, screen } from "@testing-library/dom";
+import { defineComponent, nextTick } from "vue";
+import { actAsync as act, cleanup, render } from "../../tests/vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { AuiConfig, AuiProvider, Derived, useAui } from "@ulearning/ai-store";
+import { ExternalThread, InMemoryThreadList } from "@ulearning/ai-core/store";
+import { resource, useResource } from "@ulearning/ai-tap";
+import { ThreadPrimitiveViewportProvider } from "../../context/providers/ThreadViewportProvider";
+import { ComposerPrimitiveInput } from "./ComposerInput";
+
+const StandaloneThread = resource(function useStandaloneThread() {
+  return useResource(ExternalThread({ messages: [] }));
+});
+const StandaloneApp = defineComponent({
+  setup() {
+    const config = AuiConfig({
+      thread: StandaloneThread(),
+      composer: Derived({
+        source: "thread",
+        query: {},
+        get: (aui) => aui.thread.composer(),
+      }),
+    });
+    return () => (
+      <AuiProvider config={config}>
+        <ThreadPrimitiveViewportProvider>
+          <ComposerPrimitiveInput aria-label="Composer" />
+        </ThreadPrimitiveViewportProvider>
+      </AuiProvider>
+    );
+  },
+});
+
+afterEach(cleanup);
+
+it("edits a draft without a thread-list scope", async () => {
+  render(<StandaloneApp />);
+  await nextTick();
+  const input = screen.getByRole("textbox", {
+    name: "Composer",
+  }) as HTMLTextAreaElement;
+  await act(async () => {
+    fireEvent.input(input, { target: { value: "New question" } });
+  });
+  expect(input.value).toBe("New question");
+});
+
+it("restores composer focus when the thread switches", async () => {
+  let captured!: ReturnType<typeof useAui>;
+  const App = defineComponent({
+    setup() {
+      const aui = useAui({
+        threads: InMemoryThreadList({
+          thread: () => ExternalThread({ messages: [] }),
+        }),
+      });
+      captured = aui;
+      return () => (
+        <AuiProvider value={aui}>
+          <ThreadPrimitiveViewportProvider>
+            <button>Outside</button>
+            <ComposerPrimitiveInput aria-label="Composer" autoFocus />
+          </ThreadPrimitiveViewportProvider>
+        </AuiProvider>
+      );
+    },
+  });
+  render(<App />);
+  await nextTick();
+  const input = screen.getByRole("textbox", { name: "Composer" });
+  expect(document.activeElement).toBe(input);
+  await act(() => screen.getByRole("button", { name: "Outside" }).focus());
+  const oldId = captured.threads.getState().mainThreadId;
+  await act(async () => {
+    captured.threads.switchToNewThread();
+  });
+  await vi.waitFor(() =>
+    expect(captured.threads.getState().mainThreadId).not.toBe(oldId),
+  );
+  expect(document.activeElement).toBe(input);
+});

package/src/primitives/composer/ComposerInput.tsx

@@ -0,0 +1,462 @@
+"use client";
+
+import {
+  computed,
+  defineComponent,
+  h,
+  mergeProps,
+  shallowRef,
+  watchEffect,
+  type ComponentPublicInstance,
+  type TextareaHTMLAttributes,
+  type VNode,
+  type VNodeChild,
+} from "vue";
+import { Slot, useForwardExpose } from "reka-ui";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useOnScrollToBottom } from "../../utils/hooks/useOnScrollToBottom";
+import { useMediaQuery } from "../../utils/hooks/useMediaQuery";
+import { renderSlot } from "../../utils/Primitive";
+import { isCompositionKey } from "../../utils/isCompositionKey";
+import { useAui } from "@ulearning/ai-store";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { useComposerInputPluginRegistryOptional } from "./ComposerInputPluginContext";
+import { useComposerCompactContextOptional } from "./ComposerCompactContext";
+import { useComposerCancelWithFocus } from "./useComposerCancelWithFocus";
+import { useThreadRootElementRef } from "../thread/ThreadRootElementContext";
+import {
+  useComposerInputDisabled,
+  useComposerInputValue,
+  useTriggerPopoverAriaProps,
+} from "./useComposerInputState";
+import {
+  useTextareaAutosize,
+  type TextareaAutosizeOptions,
+  type TextareaHeightChangeMeta,
+} from "./useTextareaAutosize";
+
+const TOUCH_PRIMARY_QUERY = "(pointer: coarse) and (not (any-pointer: fine))";
+
+export namespace ComposerPrimitiveInput {
+  export type Element = ComponentPublicInstance;
+
+  type BaseProps = {
+    /** Native key event; retained casing for composer history bindings. */
+    onKeyDown?: ((event: KeyboardEvent) => void) | undefined;
+    /**
+     * Whether to render as a child component using Slot.
+     * When true, the component will merge its props with its child.
+     */
+    asChild?: boolean | undefined;
+    /**
+     * A Vue element to use as the input container, with props merged in.
+     */
+    render?: VNode | undefined;
+    /**
+     * Whether to cancel message composition when Escape is pressed.
+     * After cancelling an edit, focus returns to the main thread composer when
+     * available, unless a handler has moved focus elsewhere.
+     * @default true
+     */
+    cancelOnEscape?: boolean | undefined;
+    /**
+     * Whether to focus the input when a new run starts if nothing is focused
+     * or focus is already inside the same thread or composer. Keeps the current
+     * selection when the input is already focused. Applies when `autoFocus` is
+     * enabled.
+     *
+     * @deprecated Experimental since 2024-10-12. Not scheduled for removal; the API may change in any release.
+     *
+     * @default true
+     */
+    unstable_focusOnRunStart?: boolean | undefined;
+    /**
+     * Whether to automatically focus the input when scrolling to bottom.
+     *
+     * @deprecated Experimental since 2024-10-12. Not scheduled for removal; the API may change in any release.
+     *
+     * @default true
+     */
+    unstable_focusOnScrollToBottom?: boolean | undefined;
+    /**
+     * Whether to automatically focus the input when switching threads.
+     *
+     * @deprecated Experimental since 2024-10-12. Not scheduled for removal; the API may change in any release.
+     *
+     * @default true
+     */
+    unstable_focusOnThreadSwitched?: boolean | undefined;
+    /**
+     * Whether plain Enter on a touch-primary device should insert a newline
+     * instead of submitting, detected via
+     * `(pointer: coarse) and (not (any-pointer: fine))`. Only takes effect
+     * when `submitMode` resolves to `"enter"`.
+     *
+     * @deprecated Experimental since 2026-05-24. Not scheduled for removal; the API may change in any release.
+     *
+     * @default false
+     */
+    unstable_insertNewlineOnTouchEnter?: boolean | undefined;
+    /**
+     * Whether to automatically add pasted files as attachments.
+     * @default true
+     */
+    addAttachmentOnPaste?: boolean | undefined;
+  };
+
+  type SubmitModeProps =
+    | {
+        /**
+         * Controls how the Enter key submits messages.
+         * - "enter": Plain Enter submits (Shift+Enter for newline)
+         * - "ctrlEnter": Ctrl/Cmd+Enter submits (plain Enter for newline)
+         * - "none": Keyboard submission disabled
+         * @default "enter"
+         */
+        submitMode?: "enter" | "ctrlEnter" | "none" | undefined;
+        /**
+         * @deprecated Use `submitMode` instead
+         * @ignore
+         */
+        submitOnEnter?: never;
+      }
+    | {
+        submitMode?: never;
+        /**
+         * Whether to submit the message when Enter is pressed (without Shift).
+         * @default true
+         * @deprecated Use `submitMode` instead. Will be removed in a future version.
+         */
+        submitOnEnter?: boolean | undefined;
+      };
+
+  export type Props = TextareaHTMLAttributes &
+    TextareaAutosizeOptions & {
+      children?: VNodeChild;
+      autoFocus?: boolean;
+    } & BaseProps &
+    SubmitModeProps;
+}
+
+/**
+ * A text input component for composing messages.
+ *
+ * This component provides a rich text input experience with automatic resizing,
+ * keyboard shortcuts, file paste support, and intelligent focus management.
+ * It integrates with the composer context to manage message state and submission.
+ *
+ * When rendered inside `TriggerPopoverRoot` and a popover is open, the
+ * underlying `<textarea>` automatically receives `aria-controls`,
+ * `aria-expanded`, `aria-haspopup`, and `aria-activedescendant` for the
+ * combobox relationship. These computed attributes override user-provided
+ * values for those four ARIA props while the popover is open.
+ *
+ * @example
+ * ```tsx
+ * // Ctrl/Cmd+Enter to submit (plain Enter inserts newline)
+ * <ComposerPrimitive.Input
+ *   placeholder="Type your message..."
+ *   submitMode="ctrlEnter"
+ * />
+ *
+ * // Insert a newline on Enter on touch-primary devices.
+ * <ComposerPrimitive.Input
+ *   placeholder="Type your message..."
+ *   unstable_insertNewlineOnTouchEnter
+ * />
+ *
+ * // Old API (deprecated, still supported)
+ * <ComposerPrimitive.Input
+ *   placeholder="Type your message..."
+ *   submitOnEnter={true}
+ * />
+ * ```
+ */
+export const ComposerPrimitiveInput =
+  defineComponent<ComposerPrimitiveInput.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef, currentElement } = useForwardExpose();
+      const aui = useAui();
+      const threadRootRef = useThreadRootElementRef();
+      const pluginRegistry = useComposerInputPluginRegistryOptional();
+      const compactContext = useComposerCompactContextOptional();
+      const declaredSubmitMode = computed(
+        () =>
+          props.submitMode ??
+          (props.submitOnEnter === false ? "none" : "enter"),
+      );
+      const isTouchPrimary = useMediaQuery(() =>
+        props.unstable_insertNewlineOnTouchEnter ? TOUCH_PRIMARY_QUERY : null,
+      );
+      const effectiveSubmitMode = computed(() =>
+        props.unstable_insertNewlineOnTouchEnter &&
+        isTouchPrimary.value &&
+        declaredSubmitMode.value === "enter"
+          ? "none"
+          : declaredSubmitMode.value,
+      );
+      const value = useComposerInputValue();
+      const isDisabled = useComposerInputDisabled(
+        () => props.disabled === true || props.disabled === "true",
+      );
+      const textarea = shallowRef<HTMLTextAreaElement | null>(null);
+      watchEffect(
+        () => {
+          const element = currentElement.value;
+          textarea.value =
+            element instanceof HTMLTextAreaElement ? element : null;
+        },
+        { flush: "post" },
+      );
+      const cancel = useComposerCancelWithFocus(() => aui.composer.cancel());
+      let composing = false;
+      const updateCursor = (input: HTMLTextAreaElement) => {
+        const position = input.selectionStart ?? input.value.length;
+        for (const plugin of pluginRegistry?.getPlugins() ?? [])
+          plugin.setCursorPosition(position);
+      };
+      const pluginKey = (event: KeyboardEvent) => {
+        for (const plugin of pluginRegistry?.getPlugins() ?? [])
+          if (plugin.handleKeyDown(event)) return true;
+        return false;
+      };
+      const keydown = (event: KeyboardEvent) => {
+        if (event.defaultPrevented) return;
+        props.onKeyDown?.(event);
+        if (
+          event.defaultPrevented ||
+          isDisabled.value ||
+          isCompositionKey(event)
+        )
+          return;
+        if (pluginKey(event)) return;
+        if (event.key === "Escape") {
+          if (
+            props.cancelOnEscape !== false &&
+            aui.composer.getState().canCancel
+          ) {
+            cancel(textarea.value);
+            event.preventDefault();
+          }
+          return;
+        }
+        if (event.key !== "Enter") return;
+        const thread = aui.thread.getState();
+        if (
+          event.shiftKey &&
+          (event.ctrlKey || event.metaKey) &&
+          thread.capabilities.queue &&
+          declaredSubmitMode.value !== "none" &&
+          aui.composer.getState().canSend
+        ) {
+          event.preventDefault();
+          aui.composer.send({ steer: true });
+          return;
+        }
+        if (
+          event.shiftKey ||
+          (thread.isRunning &&
+            !thread.capabilities.queue &&
+            thread.voice === undefined)
+        )
+          return;
+        if (
+          effectiveSubmitMode.value === "enter" ||
+          (effectiveSubmitMode.value === "ctrlEnter" &&
+            (event.ctrlKey || event.metaKey))
+        ) {
+          event.preventDefault();
+          textarea.value?.closest("form")?.requestSubmit();
+        }
+      };
+      const paste = async (event: ClipboardEvent) => {
+        if (event.defaultPrevented || props.addAttachmentOnPaste === false)
+          return;
+        const files = Array.from(event.clipboardData?.files ?? []);
+        if (
+          !aui.thread.getState().capabilities.attachments ||
+          files.length === 0
+        )
+          return;
+        event.preventDefault();
+        await Promise.all(
+          files.map(async (file) => {
+            try {
+              await aui.composer.addAttachment(file);
+            } catch {
+              /* The runtime emits composer.attachmentAddError. */
+            }
+          }),
+        );
+      };
+      const heightChange = (height: number, meta: TextareaHeightChangeMeta) => {
+        props.onHeightChange?.(height, meta);
+        const input = textarea.value;
+        if (!input || input.value === "" || !compactContext?.value) return;
+        const style = input.ownerDocument.defaultView!.getComputedStyle(input);
+        const number = (text: string) => parseFloat(text) || 0;
+        const contentHeight =
+          style.boxSizing === "border-box"
+            ? height -
+              number(style.paddingTop) -
+              number(style.paddingBottom) -
+              number(style.borderTopWidth) -
+              number(style.borderBottomWidth)
+            : height;
+        if (Math.round(contentHeight / meta.rowHeight) > 1)
+          compactContext.value.setMultiline(true);
+      };
+      useTextareaAutosize(
+        textarea,
+        value,
+        {
+          get minRows() {
+            return props.minRows;
+          },
+          get maxRows() {
+            return props.maxRows;
+          },
+          get cacheMeasurements() {
+            return props.cacheMeasurements;
+          },
+          onHeightChange: heightChange,
+        },
+        () => !props.render && !props.asChild,
+        () => [attrs.style, attrs.placeholder],
+      );
+      const focus = () => {
+        const input = textarea.value;
+        if (!input || !(props.autoFocus ?? attrs.autofocus) || isDisabled.value)
+          return;
+        input.focus({ preventScroll: true });
+        input.setSelectionRange(input.value.length, input.value.length);
+      };
+      const focusOnRunStart = () => {
+        const input = textarea.value;
+        if (!input) return;
+        const doc = input.ownerDocument;
+        const active = doc.activeElement;
+        if (active === input) return;
+        const root = threadRootRef?.value;
+        const composer = input.closest("[data-aui-composer-type]");
+        if (
+          active &&
+          active !== doc.body &&
+          !composer?.contains(active) &&
+          (!root?.contains(active) ||
+            active.closest("[data-aui-thread-root]") !== root)
+        )
+          return;
+        focus();
+      };
+      useIsomorphicLayoutEffect(focus);
+      useOnScrollToBottom(() => {
+        if (
+          aui.composer.getState().type === "thread" &&
+          props.unstable_focusOnScrollToBottom !== false
+        )
+          focus();
+      });
+      useIsomorphicLayoutEffect(() => {
+        if (
+          aui.composer.getState().type !== "thread" ||
+          props.unstable_focusOnRunStart === false
+        )
+          return undefined;
+        return aui.on("thread.runStart", focusOnRunStart);
+      });
+      useIsomorphicLayoutEffect(() => {
+        if (
+          aui.composer.getState().type !== "thread" ||
+          props.unstable_focusOnThreadSwitched === false ||
+          !aui.optional.threads
+        )
+          return undefined;
+        return aui.on("threads.selectionChanged", focus);
+      });
+      useIsomorphicLayoutEffect(() => {
+        if (value.value === "") compactContext?.value?.setMultiline(false);
+      });
+      const aria = useTriggerPopoverAriaProps();
+      const input = (event: Event) => {
+        if (event.defaultPrevented || !aui.composer.getState().isEditing)
+          return;
+        const target = event.target as HTMLTextAreaElement;
+        const nativeComposing = (event as InputEvent).isComposing === true;
+        if (composing && !nativeComposing) composing = false;
+        flushTapSync(() =>
+          aui.composer.setText(target.value, { origin: "user" }),
+        );
+        if (!nativeComposing && !composing) updateCursor(target);
+      };
+      const compositionEnd = (event: CompositionEvent) => {
+        if (event.defaultPrevented) return;
+        composing = false;
+        if (!aui.composer.getState().isEditing) return;
+        const target = event.target as HTMLTextAreaElement;
+        flushTapSync(() =>
+          aui.composer.setText(target.value, { origin: "user" }),
+        );
+        updateCursor(target);
+      };
+      return () => {
+        const inputProps = mergeProps(
+          { name: "input", value: value.value },
+          attrs,
+          aria.value,
+          {
+            ...(props.render || props.asChild
+              ? {
+                  minRows: props.minRows,
+                  maxRows: props.maxRows,
+                  cacheMeasurements: props.cacheMeasurements,
+                  onHeightChange: heightChange,
+                }
+              : {}),
+            ref: forwardRef,
+            disabled: isDisabled.value,
+            onInput: input,
+            onKeydown: keydown,
+            onPaste: paste,
+            onCompositionstart: (event: CompositionEvent) => {
+              if (!event.defaultPrevented) composing = true;
+            },
+            onCompositionend: compositionEnd,
+            onSelect: (event: Event) => {
+              if (!event.defaultPrevented && !composing)
+                updateCursor(event.target as HTMLTextAreaElement);
+            },
+          },
+        );
+        const children = slots.default?.() ?? props.children;
+        if (props.render) return renderSlot(props.render, children, inputProps);
+        return props.asChild
+          ? h(Slot, inputProps, { default: () => children })
+          : h("textarea", inputProps);
+      };
+    },
+    {
+      name: "ComposerPrimitive.Input",
+      inheritAttrs: false,
+      props: [
+        "render",
+        "asChild",
+        "children",
+        "autoFocus",
+        "disabled",
+        "onKeyDown",
+        "submitMode",
+        "submitOnEnter",
+        "cancelOnEscape",
+        "unstable_focusOnRunStart",
+        "unstable_focusOnScrollToBottom",
+        "unstable_focusOnThreadSwitched",
+        "unstable_insertNewlineOnTouchEnter",
+        "addAttachmentOnPaste",
+        "minRows",
+        "maxRows",
+        "cacheMeasurements",
+        "onHeightChange",
+      ],
+    },
+  );

package/src/primitives/composer/ComposerInputPluginContext.tsx

@@ -0,0 +1,80 @@
+"use client";
+
+import {
+  defineComponent,
+  inject,
+  provide,
+  type InjectionKey,
+  type VNodeChild,
+} from "vue";
+
+/**
+ * A plugin that intercepts keyboard events and cursor changes in the composer
+ * input. Used by trigger popover declarations to handle popover navigation
+ * without ComposerInput knowing about specific triggers.
+ */
+export type ComposerInputPlugin = {
+  /** Handle a key event. Return true if consumed (stops propagation to other plugins and default behavior). */
+  handleKeyDown(e: {
+    readonly key: string;
+    readonly shiftKey: boolean;
+    readonly ctrlKey?: boolean;
+    readonly metaKey?: boolean;
+    readonly nativeEvent?: { isComposing?: boolean };
+    preventDefault(): void;
+  }): boolean;
+
+  /** Called on every cursor position change (selection change / text change). */
+  setCursorPosition(pos: number): void;
+};
+
+/** Options for registering a plugin. */
+export type ComposerInputPluginRegisterOptions = {
+  /**
+   * Relative priority. Plugins with higher priority receive events first.
+   * @default 0
+   */
+  priority?: number;
+};
+
+// Ref-based registry: plugins are read imperatively at event time, so register/unregister does not trigger re-renders.
+export type ComposerInputPluginRegistry = {
+  register(
+    plugin: ComposerInputPlugin,
+    opts?: ComposerInputPluginRegisterOptions,
+  ): () => void;
+  getPlugins(): readonly ComposerInputPlugin[];
+};
+
+const ComposerInputPluginRegistryContext: InjectionKey<ComposerInputPluginRegistry> =
+  Symbol("ComposerInputPluginRegistry");
+export const useComposerInputPluginRegistryOptional = () =>
+  inject(ComposerInputPluginRegistryContext, null);
+
+export const ComposerInputPluginProvider = defineComponent<{
+  children?: VNodeChild;
+}>(
+  (props, { slots }) => {
+    const plugins = new Map<ComposerInputPlugin, number>();
+    let snapshot: readonly ComposerInputPlugin[] = [];
+    const refresh = () => {
+      snapshot = [...plugins]
+        .sort((a, b) => b[1] - a[1])
+        .map(([plugin]) => plugin);
+    };
+    const registry: ComposerInputPluginRegistry = {
+      register(plugin, opts) {
+        plugins.set(plugin, opts?.priority ?? 0);
+        refresh();
+        return () => {
+          plugins.delete(plugin);
+          refresh();
+        };
+      },
+      getPlugins: () => snapshot,
+    };
+    provide(ComposerInputPluginRegistryContext, registry);
+    return () => slots.default?.() ?? props.children;
+  },
+  { name: "ComposerInputPluginProvider", props: ["children"] },
+);