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

package/src/utils/getSelectionMessageId.ts

@@ -0,0 +1,133 @@
+const QUOTE_SELECTABLE_SELECTOR = "[data-aui-quote-selectable]";
+
+const getElement = (node: Node | null): HTMLElement | null => {
+  return node instanceof HTMLElement ? node : (node?.parentElement ?? null);
+};
+
+const findMessageElement = (node: Node | null): HTMLElement | null => {
+  let el = node instanceof HTMLElement ? node : (node?.parentElement ?? null);
+  while (el) {
+    const id = el.getAttribute("data-message-id");
+    if (id) return el;
+    el = el.parentElement;
+  }
+  return null;
+};
+
+const isExcluded = (marker: Element): boolean => {
+  return marker.getAttribute("data-aui-quote-selectable") === "false";
+};
+
+const hasQuoteSelectableRegion = (messageElement: HTMLElement) => {
+  if (
+    messageElement.matches(QUOTE_SELECTABLE_SELECTOR) &&
+    !isExcluded(messageElement)
+  ) {
+    return true;
+  }
+  for (const marker of messageElement.querySelectorAll(
+    QUOTE_SELECTABLE_SELECTOR,
+  )) {
+    if (!isExcluded(marker)) return true;
+  }
+  return false;
+};
+
+const findQuoteMarker = (
+  node: Node | null,
+  messageElement: HTMLElement,
+): HTMLElement | null => {
+  const marker = getElement(node)?.closest(QUOTE_SELECTABLE_SELECTOR);
+  if (!(marker instanceof HTMLElement)) return null;
+  if (!messageElement.contains(marker)) return null;
+  return marker;
+};
+
+const normalizeRangeEnd = (range: Range): Range => {
+  if (range.endOffset !== 0 || range.collapsed) return range;
+
+  const walker = range.endContainer.ownerDocument?.createTreeWalker(
+    range.commonAncestorContainer,
+    NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+  );
+  if (!walker) return range;
+  walker.currentNode = range.endContainer;
+
+  while (walker.previousNode()) {
+    const node = walker.currentNode;
+    const offset = node instanceof Text ? node.length : node.childNodes.length;
+    if (range.comparePoint(node, offset) < 0) return range;
+    const element = node instanceof Element ? node : node.parentElement;
+    const marker = element?.closest(QUOTE_SELECTABLE_SELECTOR);
+    if (marker && isExcluded(marker) && !node.contains(range.endContainer))
+      return range;
+    if (!(node instanceof Text) || !node.data.trim()) continue;
+
+    const normalized = range.cloneRange();
+    normalized.setEnd(node, offset);
+    return normalized.collapsed ? range : normalized;
+  }
+  return range;
+};
+
+const intersectsExcluded = (
+  scope: Element,
+  ranges: readonly Range[],
+): boolean => {
+  for (const marker of scope.querySelectorAll(QUOTE_SELECTABLE_SELECTOR)) {
+    if (!isExcluded(marker)) continue;
+    if (ranges.some((range) => range.intersectsNode(marker))) return true;
+  }
+  return false;
+};
+
+export const getSelectionMessageId = (
+  selection: Selection,
+  root?: Element | null,
+): string | null => {
+  let { anchorNode, focusNode } = selection;
+  if (!anchorNode || !focusNode) return null;
+
+  const ranges = Array.from({ length: selection.rangeCount }, (_, i) =>
+    selection.getRangeAt(i),
+  );
+  if (ranges.length === 1) {
+    const range = normalizeRangeEnd(ranges[0]!);
+    if (range !== ranges[0]) {
+      ranges[0] = range;
+      anchorNode = range.startContainer;
+      focusNode = range.endContainer;
+    }
+  }
+
+  const anchorMessageElement = findMessageElement(anchorNode);
+  const focusMessageElement = findMessageElement(focusNode);
+
+  if (!anchorMessageElement || anchorMessageElement !== focusMessageElement) {
+    return null;
+  }
+  if (root && !root.contains(anchorMessageElement)) {
+    return null;
+  }
+
+  const messageId = anchorMessageElement.getAttribute("data-message-id");
+  if (!messageId) return null;
+
+  const anchorMarker = findQuoteMarker(anchorNode, anchorMessageElement);
+  const focusMarker = findQuoteMarker(focusNode, anchorMessageElement);
+
+  if (anchorMarker && isExcluded(anchorMarker)) return null;
+  if (focusMarker && isExcluded(focusMarker)) return null;
+
+  if (hasQuoteSelectableRegion(anchorMessageElement)) {
+    if (!anchorMarker || anchorMarker !== focusMarker) return null;
+  }
+
+  const scope = anchorMarker ?? anchorMessageElement;
+
+  for (const { commonAncestorContainer } of ranges) {
+    if (!scope.contains(commonAncestorContainer)) return null;
+  }
+
+  return intersectsExcluded(scope, ranges) ? null : messageId;
+};

package/src/utils/hooks/useManagedRef.ts

@@ -0,0 +1,19 @@
+import { shallowRef } from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+
+export const useManagedRef = <TNode>(
+  callback: (node: TNode) => (() => void) | undefined,
+  dependencies?: () => readonly unknown[],
+) => {
+  const element = shallowRef<TNode | null>(null);
+  useIsomorphicLayoutEffect(
+    () => {
+      if (element.value !== null) return callback(element.value);
+      return undefined;
+    },
+    dependencies ? () => [element.value, ...dependencies()] : undefined,
+  );
+  return (node: TNode | null) => {
+    element.value = node;
+  };
+};

package/src/utils/hooks/useMediaQuery.test.tsx

@@ -0,0 +1,60 @@
+import { shallowRef } from "vue";
+// @vitest-environment jsdom
+
+import { act, cleanup, renderHook } from "../../tests/vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { useMediaQuery } from "./useMediaQuery";
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+it("updates when a media query changes after mounting", () => {
+  const media = Object.assign(new EventTarget(), {
+    matches: false,
+    media: "(prefers-reduced-motion: reduce)",
+  });
+  vi.stubGlobal(
+    "matchMedia",
+    vi.fn(() => media),
+  );
+  const { result } = renderHook(() => useMediaQuery(media.media));
+  expect(result.current).toBe(false);
+
+  act(() => {
+    media.matches = true;
+    media.dispatchEvent(new Event("change"));
+  });
+  expect(result.current).toBe(true);
+
+  act(() => {
+    media.matches = false;
+    media.dispatchEvent(new Event("change"));
+  });
+  expect(result.current).toBe(false);
+});
+
+it("switches queries, releases listeners, and ignores stale callbacks after unmount", () => {
+  const first = Object.assign(new EventTarget(), { matches: true });
+  const second = Object.assign(new EventTarget(), { matches: false });
+  const removeFirst = vi.spyOn(first, "removeEventListener");
+  const removeSecond = vi.spyOn(second, "removeEventListener");
+  vi.stubGlobal(
+    "matchMedia",
+    vi.fn((query: string) => (query === "first" ? first : second)),
+  );
+  const query = shallowRef<string | null>("first");
+  const { result, unmount } = renderHook(() => useMediaQuery(query));
+  expect(result.current).toBe(true);
+  query.value = "second";
+  expect(result.current).toBe(false);
+  expect(removeFirst).toHaveBeenCalledOnce();
+  first.dispatchEvent(new Event("change"));
+  expect(result.current).toBe(false);
+  unmount();
+  expect(removeSecond).toHaveBeenCalledOnce();
+  second.matches = true;
+  second.dispatchEvent(new Event("change"));
+  expect(result.current).toBe(false);
+});

package/src/utils/hooks/useMediaQuery.ts

@@ -0,0 +1,44 @@
+"use client";
+
+import {
+  shallowReadonly,
+  shallowRef,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+} from "vue";
+
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+
+export const useMediaQuery = (query: MaybeRefOrGetter<string | null>) => {
+  const matches = shallowRef(false);
+  // Media queries have no server snapshot. Start after mount to preserve hydration.
+  useIsomorphicLayoutEffect(() => {
+    return watch(
+      () => toValue(query),
+      (value, _, onCleanup) => {
+        if (
+          typeof window === "undefined" ||
+          value === null ||
+          !window.matchMedia
+        ) {
+          matches.value = false;
+          return;
+        }
+        const media = window.matchMedia(value);
+        let active = true;
+        const refresh = () => {
+          if (active) matches.value = media.matches;
+        };
+        media.addEventListener("change", refresh);
+        refresh();
+        onCleanup(() => {
+          active = false;
+          media.removeEventListener("change", refresh);
+        });
+      },
+      { immediate: true, flush: "sync" },
+    );
+  }, []);
+  return shallowReadonly(matches);
+};

package/src/utils/hooks/useOnScrollToBottom.ts

@@ -0,0 +1,23 @@
+"use client";
+
+import { unref, type Ref } from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import type { ThreadViewportState } from "../../context/stores/ThreadViewport";
+import { useThreadViewport } from "../../context/vue/ThreadViewportContext";
+
+type ScrollCallback = (config: { behavior: ScrollBehavior }) => void;
+export const useOnScrollToBottom = (
+  callback: ScrollCallback | Ref<ScrollCallback>,
+) => {
+  const onScrollToBottom = useThreadViewport({
+    optional: true,
+    selector: (vp: ThreadViewportState) => vp.onScrollToBottom,
+  });
+  useIsomorphicLayoutEffect(
+    () =>
+      onScrollToBottom.value?.((config: Parameters<ScrollCallback>[0]) =>
+        unref(callback)(config),
+      ),
+    () => [onScrollToBottom.value],
+  );
+};

package/src/utils/hooks/useSizeHandle.ts

@@ -0,0 +1,39 @@
+"use client";
+
+import { unref, type MaybeRef } from "vue";
+import { useManagedRef } from "./useManagedRef";
+import type { SizeHandle } from "../../context/stores/ThreadViewport";
+
+/**
+ * Hook that creates a ref for tracking element size via a SizeHandle.
+ * Automatically sets up ResizeObserver and reports height changes.
+ *
+ * @param register - Function that returns a SizeHandle (e.g., registerContentInset)
+ * @param getHeight - Optional function to compute height (defaults to el.offsetHeight)
+ * @returns A ref callback to attach to the element
+ */
+export const useSizeHandle = (
+  register: MaybeRef<(() => SizeHandle) | null | undefined>,
+  getHeight?: (el: HTMLElement) => number,
+) => {
+  return useManagedRef((el: HTMLElement) => {
+    const registerHandle = unref(register);
+    if (!registerHandle) return;
+
+    const sizeHandle = registerHandle();
+
+    const updateHeight = () => {
+      const height = getHeight ? getHeight(el) : el.offsetHeight;
+      sizeHandle.setHeight(height);
+    };
+
+    const ro = new ResizeObserver(updateHeight);
+    ro.observe(el);
+    updateHeight();
+
+    return () => {
+      ro.disconnect();
+      sizeHandle.unregister();
+    };
+  });
+};

package/src/utils/isCompositionKey.ts

@@ -0,0 +1,5 @@
+// A keydown that ends an IME composition can arrive after compositionend with
+// isComposing false and keyCode 229, as the Enter that commits one does in
+// Safari.
+export const isCompositionKey = (event: KeyboardEvent) =>
+  event.isComposing || event.keyCode === 229;

package/src/utils/smooth/SmoothContext.test.tsx

@@ -0,0 +1,224 @@
+// @vitest-environment jsdom
+import {
+  KeepAlive,
+  Suspense,
+  defineComponent,
+  h,
+  nextTick,
+  shallowRef,
+} from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { TextMessagePartProvider } from "../../context/providers/TextMessagePartProvider";
+import { useMessagePartText } from "../../primitives/messagePart/useMessagePartText";
+import { cleanup, render } from "../../tests/vue";
+import {
+  SmoothContextProvider,
+  useSmoothStatus,
+  useSmoothStatusStore,
+} from "./SmoothContext";
+import { useSmooth } from "./useSmooth";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+const clock = () => {
+  let now = 0,
+    id = 0;
+  const frames = new Map<number, FrameRequestCallback>();
+  vi.spyOn(performance, "now").mockImplementation(() => now);
+  vi.spyOn(globalThis, "requestAnimationFrame").mockImplementation(
+    (callback) => {
+      frames.set(++id, callback);
+      return id;
+    },
+  );
+  vi.spyOn(globalThis, "cancelAnimationFrame").mockImplementation((handle) => {
+    frames.delete(handle);
+  });
+  return {
+    frames,
+    frame() {
+      now += 16;
+      const callbacks = [...frames.values()];
+      frames.clear();
+      callbacks.forEach((callback) => callback(now));
+    },
+  };
+};
+it("shares the outer smooth store, keeps running while draining, and restores the exact settled status", async () => {
+  const animation = clock();
+  const text = shallowRef("Hi");
+  const running = shallowRef(false);
+  let outer!: ReturnType<typeof useSmoothStatusStore>;
+  let nested!: ReturnType<typeof useSmoothStatusStore>;
+  let settled!: unknown;
+  const Reader = defineComponent({
+    setup() {
+      outer = useSmoothStatusStore();
+      const part = useMessagePartText();
+      const smooth = useSmooth(part, { maxCharsPerFrame: 1 });
+      const status = useSmoothStatus();
+      return () => {
+        settled = part.value.status;
+        return h("p", { "data-status": status.value.type }, smooth.value.text);
+      };
+    },
+  });
+  const Nested = defineComponent({
+    setup() {
+      nested = useSmoothStatusStore();
+      return () => null;
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup: () => () =>
+          h(
+            TextMessagePartProvider,
+            { text: text.value, isRunning: running.value },
+            {
+              default: () =>
+                h(SmoothContextProvider, null, {
+                  default: () => [
+                    h(Reader),
+                    h(SmoothContextProvider, null, {
+                      default: () => h(Nested),
+                    }),
+                  ],
+                }),
+            },
+          ),
+      }),
+    ),
+  );
+  expect(nested).toBe(outer);
+  if (!outer) throw new Error("SmoothContextProvider did not supply its store");
+  expect(view.container.textContent).toBe("Hi");
+  flushTapSync(() => {
+    text.value = "Hi!!";
+    running.value = true;
+  });
+  await nextTick();
+  expect(view.container.textContent).toBe("Hi");
+  expect(outer.getState().type).toBe("running");
+  flushTapSync(() => {
+    running.value = false;
+  });
+  await nextTick();
+  expect(outer.getState().type).toBe("running");
+  animation.frame();
+  await nextTick();
+  expect(view.container.textContent).toBe("Hi!");
+  animation.frame();
+  await nextTick();
+  expect(view.container.textContent).toBe("Hi!!");
+  expect(outer.getState()).toBe(settled);
+  expect(view.container.querySelector("p")!.dataset.status).toBe("complete");
+  expect(animation.frames.size).toBe(0);
+});
+it("cancels frames and media listeners while deactivated and after unmount", async () => {
+  const animation = clock();
+  const media = Object.assign(new EventTarget(), { matches: false });
+  const remove = vi.spyOn(media, "removeEventListener");
+  vi.stubGlobal(
+    "matchMedia",
+    vi.fn(() => media),
+  );
+  const active = shallowRef(true);
+  const text = shallowRef("hello");
+  let setups = 0;
+  const Reader = defineComponent({
+    setup() {
+      setups++;
+      const smooth = useSmooth(useMessagePartText(), { maxCharsPerFrame: 1 });
+      return () => h("p", smooth.value.text);
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup: () => () =>
+          h(
+            TextMessagePartProvider,
+            { text: text.value, isRunning: true },
+            {
+              default: () =>
+                h(KeepAlive, null, {
+                  default: () => (active.value ? h(Reader) : null),
+                }),
+            },
+          ),
+      }),
+    ),
+  );
+  expect(animation.frames.size).toBe(1);
+  active.value = false;
+  await nextTick();
+  expect(animation.frames.size).toBe(0);
+  expect(remove).toHaveBeenCalledOnce();
+  flushTapSync(() => {
+    text.value = "hello world";
+  });
+  await nextTick();
+  expect(animation.frames.size).toBe(0);
+  active.value = true;
+  await nextTick();
+  expect(setups).toBe(1);
+  expect(animation.frames.size).toBe(1);
+  animation.frame();
+  await nextTick();
+  expect(view.container.textContent).toBe("h");
+  view.unmount();
+  expect(animation.frames.size).toBe(0);
+  expect(remove).toHaveBeenCalledTimes(2);
+  media.matches = true;
+  media.dispatchEvent(new Event("change"));
+  animation.frame();
+  expect(animation.frames.size).toBe(0);
+});
+it("does not animate an abandoned Suspense branch after its gate resolves", async () => {
+  const animation = clock();
+  let resolve!: () => void;
+  const gate = new Promise<void>((finish) => {
+    resolve = finish;
+  });
+  const pending = shallowRef(true);
+  const Reader = defineComponent({
+    async setup() {
+      const smooth = useSmooth(useMessagePartText(), true);
+      await gate;
+      return () => h("p", smooth.value.text);
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup: () => () =>
+          h(
+            TextMessagePartProvider,
+            { text: "hello", isRunning: true },
+            {
+              default: () =>
+                h(Suspense, null, {
+                  default: () =>
+                    pending.value ? h(Reader) : h("p", "replacement"),
+                  fallback: () => h("i", "pending"),
+                }),
+            },
+          ),
+      }),
+    ),
+  );
+  expect(animation.frames.size).toBe(0);
+  pending.value = false;
+  await nextTick();
+  resolve();
+  await gate;
+  await nextTick();
+  expect(view.container.textContent).toBe("replacement");
+  expect(animation.frames.size).toBe(0);
+});

package/src/utils/smooth/SmoothContext.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import {
+  defineComponent,
+  h,
+  inject,
+  provide,
+  type Component,
+  type FunctionalComponent,
+  type InjectionKey,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { createStore } from "zustand/vanilla";
+import type { ReadonlyStore } from "../../context/ReadonlyStore";
+import type {
+  MessagePartStatus,
+  ToolCallMessagePartStatus,
+} from "@ulearning/ai-core";
+import { useAui } from "@ulearning/ai-store";
+import { createContextStoreHook } from "../../context/vue/utils/createContextStoreHook";
+
+type SmoothContextValue = {
+  useSmoothStatus: ReadonlyStore<MessagePartStatus | ToolCallMessagePartStatus>;
+};
+const SmoothContext: InjectionKey<SmoothContextValue> = Symbol("SmoothContext");
+
+export const SmoothContextProvider = defineComponent({
+  name: "SmoothContextProvider",
+  setup(_, { slots }) {
+    const outer = useSmoothContext({ optional: true });
+    if (!outer) {
+      const aui = useAui();
+      const store = createStore<MessagePartStatus | ToolCallMessagePartStatus>(
+        () => aui.part.getState().status,
+      );
+      provide(SmoothContext, { useSmoothStatus: store });
+    }
+    return () => slots.default?.();
+  },
+});
+
+type ComponentProps<C> = C extends new (...args: never[]) => {
+  $props: infer P extends object;
+}
+  ? P
+  : C extends FunctionalComponent<infer P extends object>
+    ? P
+    : Record<string, unknown>;
+
+export const withSmoothContextProvider = <C extends Component>(Component: C) =>
+  defineComponent(
+    (props: ComponentProps<C>, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      return () =>
+        h(SmoothContextProvider, null, {
+          default: () =>
+            h(Component, { ...attrs, ...props, ref: forwardRef }, slots),
+        });
+    },
+    {
+      name: Component.name ?? "SmoothContextProviderWrapper",
+      inheritAttrs: false,
+      props: [],
+    },
+  );
+function useSmoothContext(options?: { optional?: false }): SmoothContextValue;
+function useSmoothContext(options?: {
+  optional?: boolean;
+}): SmoothContextValue | null;
+function useSmoothContext(options?: { optional?: boolean }) {
+  const context = inject(SmoothContext, null);
+  if (!options?.optional && !context)
+    throw new Error(
+      "This component must be used within a SmoothContextProvider.",
+    );
+  return context;
+}
+
+export const { useSmoothStatus, useSmoothStatusStore } = createContextStoreHook(
+  useSmoothContext,
+  "useSmoothStatus",
+);