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

package/src/primitives/composer/trigger/triggerSelectionResource.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it, vi } from "vitest";
+import { createTapRoot, flushTapSync, useResource } from "@ulearning/ai-tap";
+import type {
+  Unstable_DirectiveFormatter,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+import type { AssistantClient } from "@ulearning/ai-store";
+import { TriggerDetectionResource } from "./triggerDetectionResource";
+import {
+  TriggerSelectionResource,
+  type TriggerBehavior,
+} from "./triggerSelectionResource";
+
+const item: Unstable_TriggerItem = {
+  id: "file",
+  type: "file",
+  label: "file.txt",
+};
+
+const formatter: Unstable_DirectiveFormatter = {
+  serialize: () => "@file.txt",
+  parse: () => [],
+};
+
+const makeAui = (textRef: { value: string }) => {
+  const setText = vi.fn((value: string) => {
+    textRef.value = value;
+  });
+
+  return {
+    aui: {
+      composer: {
+        getState: () => ({ text: textRef.value }),
+        setText,
+      },
+    } as unknown as AssistantClient,
+    setText,
+  };
+};
+
+const render = ({
+  behavior,
+  text,
+  trigger,
+}: {
+  behavior: TriggerBehavior;
+  text: string;
+  trigger: { offset: number; query: string; endOffset: number };
+}) => {
+  const textRef = { value: text };
+  const { aui, setText } = makeAui(textRef);
+  const setCursorPosition = vi.fn();
+  const onSelected = vi.fn();
+  const root = createTapRoot(function Root() {
+    return useResource(
+      TriggerSelectionResource({
+        behavior,
+        trigger,
+        aui,
+        triggerChar: "@",
+        setCursorPosition,
+        onSelected,
+      }),
+    );
+  });
+
+  return { root, setText, setCursorPosition, onSelected };
+};
+
+describe("TriggerSelectionResource", () => {
+  it("resynchronizes the cursor after inserting a directive", () => {
+    const { root, setText, setCursorPosition, onSelected } = render({
+      behavior: { kind: "directive", formatter },
+      text: "@file tail",
+      trigger: { offset: 0, query: "file", endOffset: 5 },
+    });
+
+    root.getValue().selectItem(item);
+
+    expect(setText).toHaveBeenCalledWith("@file.txt tail", { origin: "user" });
+    expect(setCursorPosition).toHaveBeenCalledWith("@file.txt".length + 1);
+    expect(onSelected).toHaveBeenCalledOnce();
+  });
+
+  it("reports an inserted directive once a select override finishes the insertion", () => {
+    const onInserted = vi.fn();
+    const { root, setText, onSelected } = render({
+      behavior: { kind: "directive", formatter, onInserted },
+      text: "@file tail",
+      trigger: { offset: 0, query: "file", endOffset: 5 },
+    });
+    let finishInsertion: (() => void) | undefined;
+    root.getValue().registerSelectItemOverride((_, onOverrideInserted) => {
+      finishInsertion = onOverrideInserted;
+      return true;
+    });
+
+    root.getValue().selectItem(item);
+
+    expect(onInserted).not.toHaveBeenCalled();
+    expect(setText).not.toHaveBeenCalled();
+    expect(onSelected).toHaveBeenCalledOnce();
+
+    finishInsertion?.();
+
+    expect(onInserted).toHaveBeenCalledExactlyOnceWith(item);
+  });
+
+  it("resynchronizes the cursor after removing an action", () => {
+    const { root, setText, setCursorPosition } = render({
+      behavior: {
+        kind: "action",
+        formatter,
+        onExecute: vi.fn(),
+        removeOnExecute: true,
+      },
+      text: "before @file tail",
+      trigger: { offset: 7, query: "file", endOffset: 12 },
+    });
+
+    root.getValue().selectItem(item);
+
+    expect(setText).toHaveBeenCalledWith("before tail", { origin: "user" });
+    expect(setCursorPosition).toHaveBeenCalledWith(7);
+  });
+
+  it("does not rewrite composer text on a second select after insertion", () => {
+    const textRef = { value: "@fil" };
+    const { aui, setText } = makeAui(textRef);
+    const onSelected = vi.fn();
+    const root = createTapRoot(function Root() {
+      const detection = useResource(
+        TriggerDetectionResource({
+          text: textRef.value,
+          triggerChar: "@",
+        }),
+      );
+      return useResource(
+        TriggerSelectionResource({
+          behavior: { kind: "directive", formatter },
+          trigger: detection.trigger,
+          aui,
+          triggerChar: "@",
+          setCursorPosition: detection.setCursorPosition,
+          onSelected,
+        }),
+      );
+    });
+
+    flushTapSync(() => {
+      root.getValue().selectItem(item);
+    });
+    root.getValue().selectItem(item);
+
+    expect(setText).toHaveBeenCalledOnce();
+    expect(setText).toHaveBeenCalledWith("@file.txt ", { origin: "user" });
+    expect(textRef.value).toBe("@file.txt ");
+  });
+
+  it("replaces the matcher endOffset even when query is shorter", () => {
+    const { root, setText } = render({
+      behavior: { kind: "directive", formatter },
+      text: "hello @Example UK tail",
+      trigger: { offset: 6, query: "example", endOffset: 17 },
+    });
+
+    root.getValue().selectItem(item);
+
+    expect(setText).toHaveBeenCalledWith("hello @file.txt tail", {
+      origin: "user",
+    });
+  });
+});

package/src/primitives/composer/trigger/triggerSelectionResource.ts

@@ -0,0 +1,133 @@
+import { useEffectEvent, useRef } from "@ulearning/ai-tap";
+import { resource } from "@ulearning/ai-tap";
+import type {
+  Unstable_DirectiveFormatter,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+import type { AssistantClient } from "@ulearning/ai-store";
+import type { DetectedTrigger } from "./triggerDetectionResource";
+
+/**
+ * External override for selection (used by Lexical's DirectivePlugin).
+ * Returns whether it handled the item, and calls `onInserted` once the
+ * insertion has reached the composer.
+ */
+export type SelectItemOverride = (
+  item: Unstable_TriggerItem,
+  onInserted: () => void,
+) => boolean;
+
+export type TriggerBehavior =
+  | {
+      readonly kind: "directive";
+      readonly formatter: Unstable_DirectiveFormatter;
+      readonly onInserted?: (item: Unstable_TriggerItem) => void;
+    }
+  | {
+      readonly kind: "action";
+      readonly formatter: Unstable_DirectiveFormatter;
+      readonly onExecute: (item: Unstable_TriggerItem) => void;
+      readonly removeOnExecute?: boolean;
+    };
+
+export type TriggerSelectionResourceOutput = {
+  /** Select an item — runs override (if any) then applies behavior. */
+  selectItem(item: Unstable_TriggerItem): void;
+  /** Close the popover (moves cursor before trigger to deactivate detection). */
+  close(): void;
+  /** Register a Lexical-style selection override. Returns unregister fn. */
+  registerSelectItemOverride(fn: SelectItemOverride): () => void;
+};
+
+/** Owns composer text mutation + behavior dispatch on item selection. */
+const useTriggerSelectionResource = ({
+  behavior,
+  trigger,
+  aui,
+  setCursorPosition,
+  onSelected,
+}: {
+  behavior: TriggerBehavior | undefined;
+  trigger: DetectedTrigger | null;
+  aui: AssistantClient;
+  triggerChar: string;
+  setCursorPosition: (pos: number) => void;
+  /** Called after a successful selection so the parent can reset nav state. */
+  onSelected: () => void;
+}): TriggerSelectionResourceOutput => {
+  // Select-item override: lets Lexical's DirectivePlugin intercept selection
+  // and drive its own node insertion.
+  const selectItemOverrideRef = useRef<SelectItemOverride | null>(null);
+
+  const registerSelectItemOverride = useEffectEvent(
+    (fn: SelectItemOverride) => {
+      selectItemOverrideRef.current = fn;
+      return () => {
+        if (selectItemOverrideRef.current === fn) {
+          selectItemOverrideRef.current = null;
+        }
+      };
+    },
+  );
+
+  const selectItem = useEffectEvent((item: Unstable_TriggerItem) => {
+    if (!trigger || !behavior) return;
+
+    const reportInserted = () => {
+      if (behavior.kind === "directive") behavior.onInserted?.(item);
+    };
+
+    if (selectItemOverrideRef.current?.(item, reportInserted)) {
+      onSelected();
+      return;
+    }
+
+    const currentText = aui.composer.getState().text;
+    const before = currentText.slice(0, trigger.offset);
+    const after = currentText.slice(trigger.endOffset);
+
+    const insertDirective = () => {
+      const directive = behavior.formatter.serialize(item);
+      aui.composer.setText(
+        before + directive + (after.startsWith(" ") ? after : ` ${after}`),
+        { origin: "user" },
+      );
+      setCursorPosition(before.length + directive.length + 1);
+    };
+
+    if (behavior.kind === "directive") {
+      insertDirective();
+      behavior.onInserted?.(item);
+    } else {
+      if (behavior.removeOnExecute) {
+        aui.composer.setText(
+          before + (after.startsWith(" ") ? after.slice(1) : after),
+          { origin: "user" },
+        );
+        setCursorPosition(before.length);
+      } else {
+        // Leave directive chip in the composer as an audit trail
+        insertDirective();
+      }
+      behavior.onExecute(item);
+    }
+
+    onSelected();
+  });
+
+  const close = useEffectEvent(() => {
+    onSelected();
+    // Move cursor before the trigger so trigger detection deactivates
+    if (trigger) {
+      setCursorPosition(trigger.offset);
+    }
+  });
+
+  return {
+    selectItem,
+    close,
+    registerSelectItemOverride,
+  };
+};
+
+export const TriggerSelectionResource = resource(useTriggerSelectionResource);

package/src/primitives/composer/useAuiState.composer.test.tsx

@@ -0,0 +1,93 @@
+/** @vitest-environment jsdom */
+import { fireEvent, screen } from "@testing-library/dom";
+import { defineComponent, h, shallowRef } from "vue";
+import { actAsync, cleanup, render } from "../../tests/vue";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  AssistantRuntimeProvider,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type { ThreadMessage } from "@ulearning/ai-core";
+import { useAui, useAuiState } from "@ulearning/ai-store";
+
+afterEach(cleanup);
+const Input = defineComponent<{
+  value: string;
+  onChange: (value: string) => void;
+  withOwnState: boolean;
+}>(
+  (props) => {
+    const changeCount = shallowRef(0);
+    return () =>
+      h("textarea", {
+        "aria-label": "composer",
+        value: props.value,
+        "data-changes": changeCount.value,
+        onInput: (event: Event) => {
+          if (props.withOwnState) changeCount.value++;
+          props.onChange((event.target as HTMLTextAreaElement).value);
+        },
+      });
+  },
+  { props: ["value", "onChange", "withOwnState"] },
+);
+const BoundInput = defineComponent<{ withOwnState: boolean }>(
+  (props) => {
+    const aui = useAui();
+    const text = useAuiState((s) => s.composer.text);
+    return () => [
+      h(
+        "button",
+        { onClick: () => aui.composer.setText("hello world") },
+        "seed",
+      ),
+      h(Input, {
+        value: text.value,
+        onChange: (value) => aui.composer.setText(value),
+        withOwnState: props.withOwnState,
+      }),
+    ];
+  },
+  { props: ["withOwnState"] },
+);
+const App = defineComponent<{ withOwnState: boolean }>(
+  (props) => {
+    const runtime = useExternalStoreRuntime<ThreadMessage>({
+      messages: [],
+      onNew: async () => {},
+    });
+    return () =>
+      h(
+        AssistantRuntimeProvider,
+        { runtime },
+        { default: () => h(BoundInput, props) },
+      );
+  },
+  { props: ["withOwnState"] },
+);
+
+describe("composer state in controlled inputs", () => {
+  it.each([
+    ["mentions-like", true],
+    ["plain textarea", false],
+  ])(
+    "keeps the caret after typing in the middle: %s",
+    async (_, withOwnState) => {
+      await actAsync(() => render(h(App, { withOwnState })));
+      await actAsync(() =>
+        fireEvent.click(screen.getByRole("button", { name: "seed" })),
+      );
+      const input = screen.getByRole("textbox", {
+        name: "composer",
+      }) as HTMLTextAreaElement;
+      await vi.waitFor(() => expect(input.value).toBe("hello world"));
+
+      input.setSelectionRange(5, 5);
+      fireEvent.input(input, {
+        target: { value: "helloX world", selectionStart: 6, selectionEnd: 6 },
+      });
+      await vi.waitFor(() => expect(input.value).toBe("helloX world"));
+      expect(input.selectionStart).toBe(6);
+    },
+  );
+});

package/src/primitives/composer/useComposerCancelWithFocus.ts

@@ -0,0 +1,51 @@
+"use client";
+
+import { useAui } from "@ulearning/ai-store";
+import { useThreadRootElementRef } from "../thread/ThreadRootElementContext";
+import { COMPOSER_INPUT_SELECTOR } from "./composerInputSelector";
+
+const COMPOSER_SELECTOR = "[data-aui-composer-type]";
+const THREAD_SELECTOR = "[data-aui-thread-root]";
+
+export const useComposerCancelWithFocus = (cancel: () => void) => {
+  const aui = useAui();
+  const threadRootRef = useThreadRootElementRef();
+
+  const cancelWithFocus = (source: HTMLElement | null) => {
+    const root = threadRootRef?.value;
+    const doc = source?.ownerDocument;
+    const active = doc?.activeElement;
+    const composer = source?.closest(COMPOSER_SELECTOR);
+    const shouldRestore =
+      aui.composer.getState().type === "edit" &&
+      root &&
+      active &&
+      composer?.getAttribute("data-aui-composer-type") === "edit" &&
+      composer.contains(active) &&
+      composer.closest(THREAD_SELECTOR) === root;
+    const candidates = shouldRestore
+      ? Array.from(
+          root.querySelectorAll<HTMLElement>(COMPOSER_INPUT_SELECTOR),
+        ).filter(
+          (input) =>
+            input.closest(THREAD_SELECTOR) === root &&
+            input
+              .closest(COMPOSER_SELECTOR)
+              ?.getAttribute("data-aui-composer-type") === "thread",
+        )
+      : [];
+
+    cancel();
+
+    if (!doc || !active || !shouldRestore) return;
+    if (doc.activeElement !== active && doc.activeElement !== doc.body) return;
+
+    for (const input of candidates) {
+      if (!input.isConnected || input.closest("[hidden], [inert]")) continue;
+      input.focus({ preventScroll: true });
+      if (doc.activeElement !== active && doc.activeElement !== doc.body) break;
+    }
+  };
+
+  return cancelWithFocus;
+};

package/src/primitives/composer/useComposerInputState.ts

@@ -0,0 +1,58 @@
+"use client";
+
+import {
+  computed,
+  getCurrentInstance,
+  onActivated,
+  onDeactivated,
+  shallowRef,
+  toValue,
+  type MaybeRefOrGetter,
+} from "vue";
+import { useAuiState } from "@ulearning/ai-store";
+import { useTriggerPopoverActiveAriaOptional } from "./trigger/TriggerPopoverRootContext";
+
+export type TriggerPopoverAriaProps = {
+  "aria-controls"?: string;
+  "aria-expanded"?: true;
+  "aria-haspopup"?: "listbox";
+  "aria-activedescendant"?: string | undefined;
+};
+
+export function useComposerInputValue() {
+  return useAuiState((s) => (s.composer.isEditing ? s.composer.text : ""));
+}
+
+export function useComposerInputDisabled(
+  disabled?: MaybeRefOrGetter<boolean | undefined>,
+) {
+  const composerDisabled = useAuiState(
+    (s) => s.thread.isDisabled || s.composer.dictation?.inputDisabled,
+  );
+  return computed(
+    () => Boolean(composerDisabled.value) || Boolean(toValue(disabled)),
+  );
+}
+
+export function useTriggerPopoverAriaProps() {
+  const activeAria = useTriggerPopoverActiveAriaOptional();
+  const active = shallowRef(true);
+  if (getCurrentInstance()) {
+    onActivated(() => {
+      active.value = true;
+    });
+    onDeactivated(() => {
+      active.value = false;
+    });
+  }
+  return computed<TriggerPopoverAriaProps>(() =>
+    active.value && activeAria.value
+      ? {
+          "aria-controls": activeAria.value.popoverId,
+          "aria-expanded": true,
+          "aria-haspopup": "listbox",
+          "aria-activedescendant": activeAria.value.highlightedItemId,
+        }
+      : {},
+  );
+}

package/src/primitives/composer/useTextareaAutosize.ts

@@ -0,0 +1,140 @@
+import { toValue, watch, type MaybeRefOrGetter, type Ref } from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+
+export type TextareaHeightChangeMeta = { rowHeight: number };
+export type TextareaAutosizeOptions = {
+  minRows?: number | undefined;
+  maxRows?: number | undefined;
+  cacheMeasurements?: boolean | undefined;
+  onHeightChange?:
+    | ((height: number, meta: TextareaHeightChangeMeta) => void)
+    | undefined;
+};
+
+const sizingProperties = [
+  "borderBottomWidth",
+  "borderLeftWidth",
+  "borderRightWidth",
+  "borderTopWidth",
+  "boxSizing",
+  "fontFamily",
+  "fontSize",
+  "fontStyle",
+  "fontWeight",
+  "letterSpacing",
+  "lineHeight",
+  "paddingBottom",
+  "paddingLeft",
+  "paddingRight",
+  "paddingTop",
+  "tabSize",
+  "textIndent",
+  "textRendering",
+  "textTransform",
+  "width",
+  "wordBreak",
+] as const;
+
+/** Measure a separate textarea so resizing never disturbs the user's selection. */
+export function useTextareaAutosize(
+  element: Ref<HTMLTextAreaElement | null>,
+  value: MaybeRefOrGetter<string>,
+  options: TextareaAutosizeOptions,
+  enabled: () => boolean,
+  layoutInputs: () => readonly unknown[],
+) {
+  useIsomorphicLayoutEffect(() => {
+    const input = element.value;
+    if (!input || !enabled()) return undefined;
+    const doc = input.ownerDocument;
+    const view = doc.defaultView;
+    if (!view) return undefined;
+    const measure = doc.createElement("textarea");
+    measure.tabIndex = -1;
+    measure.setAttribute("aria-hidden", "true");
+    const hide = () => {
+      for (const [name, content] of Object.entries({
+        height: "0",
+        visibility: "hidden",
+        overflow: "hidden",
+        position: "absolute",
+        zIndex: "-1000",
+        top: "0",
+        left: "0",
+        minHeight: "0",
+        maxHeight: "none",
+      }))
+        measure.style.setProperty(
+          name.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`),
+          content,
+          "important",
+        );
+    };
+    doc.body.append(measure);
+    let sizing:
+      | Pick<CSSStyleDeclaration, (typeof sizingProperties)[number]>
+      | undefined;
+    let previousHeight: number | undefined;
+    const resize = () => {
+      if (!options.cacheMeasurements || !sizing) {
+        const style = view.getComputedStyle(input);
+        sizing = Object.fromEntries(
+          sizingProperties.map((key) => [key, style[key]]),
+        ) as typeof sizing;
+      }
+      if (!sizing || sizing.width === "0px") return;
+      Object.assign(measure.style, sizing);
+      hide();
+      const number = (text: string) => parseFloat(text) || 0;
+      const padding = number(sizing.paddingTop) + number(sizing.paddingBottom);
+      const border =
+        number(sizing.borderTopWidth) + number(sizing.borderBottomWidth);
+      const borderBox = sizing.boxSizing === "border-box";
+      const measuredValue = input.value || input.placeholder || "x";
+      measure.value = measuredValue;
+      // Firefox can report the previous scrollHeight on the first assignment.
+      let height = measure.scrollHeight;
+      measure.value = measuredValue;
+      height = measure.scrollHeight || height;
+      measure.value = "x";
+      const rowHeight = measure.scrollHeight - padding;
+      if (rowHeight <= 0) return;
+      height = borderBox ? height + border : height - padding;
+      const offset = borderBox ? padding + border : 0;
+      const minimum = rowHeight * (options.minRows ?? 1) + offset;
+      const maximum = rowHeight * (options.maxRows ?? Infinity) + offset;
+      height = Math.max(minimum, Math.min(maximum, height));
+      if (height === previousHeight) return;
+      previousHeight = height;
+      input.style.setProperty("height", `${height}px`, "important");
+      options.onHeightChange?.(height, { rowHeight });
+    };
+    const stop = watch(
+      () => [
+        toValue(value),
+        options.minRows,
+        options.maxRows,
+        options.cacheMeasurements,
+        ...layoutInputs(),
+      ],
+      resize,
+      { immediate: true, flush: "post" },
+    );
+    const reset = () =>
+      queueMicrotask(() => {
+        if (measure.isConnected) resize();
+      });
+    input.addEventListener("input", resize);
+    input.form?.addEventListener("reset", reset);
+    view.addEventListener("resize", resize);
+    doc.fonts?.addEventListener("loadingdone", resize);
+    return () => {
+      stop();
+      input.removeEventListener("input", resize);
+      input.form?.removeEventListener("reset", reset);
+      view.removeEventListener("resize", resize);
+      doc.fonts?.removeEventListener("loadingdone", resize);
+      measure.remove();
+    };
+  });
+}