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

package/src/primitives/reasoning/useScrollLock.ts

@@ -0,0 +1,160 @@
+"use client";
+
+import {
+  getCurrentInstance,
+  onActivated,
+  onDeactivated,
+  onScopeDispose,
+  toValue,
+  type MaybeRefOrGetter,
+} from "vue";
+
+const findScrollableAncestor = (element: HTMLElement | null) => {
+  let current = element;
+  while (current) {
+    const { overflowY } = getComputedStyle(current);
+    if (overflowY === "scroll" || overflowY === "auto") return current;
+    current = current.parentElement;
+  }
+  return null;
+};
+
+const scrollLocks = new WeakMap<
+  HTMLElement,
+  { count: number; restore: () => void }
+>();
+
+const acquireScrollLock = (scrollContainer: HTMLElement) => {
+  const existing = scrollLocks.get(scrollContainer);
+  if (existing) {
+    existing.count++;
+    return existing;
+  }
+
+  const scrollPosition = scrollContainer.scrollTop;
+  const scrollbarWidth = scrollContainer.style.scrollbarWidth;
+
+  // Hiding the scrollbar collapses its gutter on classic scrollbars, which
+  // shifts centered content horizontally; compensate with padding on the
+  // side the scrollbar occupies (the left side in RTL).
+  const computed = getComputedStyle(scrollContainer);
+  const paddingSide =
+    computed.direction === "rtl" ? "paddingLeft" : "paddingRight";
+  const previousPadding = scrollContainer.style[paddingSide];
+  const elementScrollbarSize =
+    scrollContainer.offsetWidth -
+    scrollContainer.clientWidth -
+    parseFloat(computed.borderLeftWidth) -
+    parseFloat(computed.borderRightWidth);
+  // A root element's offsetWidth already excludes the viewport scrollbar, so
+  // the element formula reports zero once the scroll propagates to the
+  // viewport, and only then does the viewport measure apply. A body that
+  // scrolls in its own right is measured by the element formula like any
+  // other scroller, whether or not the viewport is scrolling too.
+  const ownerDocument = scrollContainer.ownerDocument;
+  const isRootScroller =
+    scrollContainer === ownerDocument.documentElement ||
+    scrollContainer === ownerDocument.body;
+  const scrollbarSize =
+    isRootScroller && elementScrollbarSize <= 0
+      ? (ownerDocument.defaultView?.innerWidth ?? 0) -
+        ownerDocument.documentElement.clientWidth
+      : elementScrollbarSize;
+
+  scrollContainer.style.scrollbarWidth = "none";
+  if (scrollbarSize > 0) {
+    scrollContainer.style[paddingSide] = `${
+      parseFloat(computed[paddingSide]) + scrollbarSize
+    }px`;
+  }
+
+  const restoreStyles = () => {
+    scrollContainer.style.scrollbarWidth = scrollbarWidth;
+    scrollContainer.style[paddingSide] = previousPadding;
+  };
+
+  const resetPosition = () => (scrollContainer.scrollTop = scrollPosition);
+  scrollContainer.addEventListener("scroll", resetPosition);
+
+  const lock = {
+    count: 1,
+    restore: () => {
+      scrollContainer.removeEventListener("scroll", resetPosition);
+      restoreStyles();
+    },
+  };
+  scrollLocks.set(scrollContainer, lock);
+  return lock;
+};
+
+/**
+ * Locks scroll position during collapsible/height animations and hides scrollbar.
+ *
+ * This utility prevents page jumps when content height changes during animations,
+ * providing a smooth user experience. It finds the nearest scrollable ancestor and
+ * temporarily locks its scroll position while the animation completes.
+ *
+ * - Prevents forced reflows: no layout reads, mutations scoped to scrollable parent only
+ * - Reactive: only intercepts scroll events when browser actually adjusts
+ * - Cleans up automatically after animation duration
+ *
+ * @param animatedElementRef - Ref to the animated element
+ * @param animationDuration - Lock duration in milliseconds
+ * @returns Function to activate the scroll lock
+ *
+ * @example
+ * ```tsx
+ * const collapsibleRef = shallowRef<HTMLDivElement | null>(null);
+ * const lockScroll = useScrollLock(collapsibleRef, 200);
+ *
+ * const handleCollapse = () => {
+ *   lockScroll(); // Lock scroll before collapsing
+ *   setIsOpen(false);
+ * };
+ * ```
+ */
+export const useScrollLock = <T extends HTMLElement = HTMLElement>(
+  animatedElementRef: MaybeRefOrGetter<T | null>,
+  animationDuration: MaybeRefOrGetter<number>,
+) => {
+  let cleanup: (() => void) | null = null;
+  let active = true;
+  onScopeDispose(() => {
+    active = false;
+    cleanup?.();
+  });
+  if (getCurrentInstance()) {
+    onActivated(() => {
+      active = true;
+    });
+    onDeactivated(() => {
+      active = false;
+      cleanup?.();
+    });
+  }
+
+  const lockScroll = () => {
+    cleanup?.();
+    if (!active) return;
+
+    const scrollContainer = findScrollableAncestor(toValue(animatedElementRef));
+    if (!scrollContainer) {
+      return;
+    }
+
+    const lock = acquireScrollLock(scrollContainer);
+
+    const timeoutId = setTimeout(() => cleanup?.(), toValue(animationDuration));
+
+    cleanup = () => {
+      clearTimeout(timeoutId);
+      if (--lock.count === 0) {
+        lock.restore();
+        scrollLocks.delete(scrollContainer);
+      }
+      cleanup = null;
+    };
+  };
+
+  return lockScroll;
+};

package/src/primitives/selectionToolbar/SelectionToolbarQuote.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import {
+  defineComponent,
+  h,
+  mergeProps,
+  type ComponentPublicInstance,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { Primitive, type PrimitiveProps } from "../../utils/Primitive";
+import { useAui } from "@ulearning/ai-store";
+import { useSelectionToolbarInfo } from "./SelectionToolbarRoot";
+export namespace SelectionToolbarPrimitiveQuote {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"button">;
+}
+/** Quotes the captured selection in the current thread composer. */
+export const SelectionToolbarPrimitiveQuote = defineComponent(
+  (props: SelectionToolbarPrimitiveQuote.Props, { attrs, slots }) => {
+    const { forwardRef } = useForwardExpose();
+    const aui = useAui();
+    const info = useSelectionToolbarInfo();
+    const onClick = (event: MouseEvent) => {
+      const current = info?.value;
+      if (event.defaultPrevented || !current) return;
+      aui.thread
+        .composer()
+        .setQuote({ text: current.text, messageId: current.messageId });
+      const element = event.currentTarget;
+      if (element instanceof Element)
+        element.ownerDocument.defaultView?.getSelection()?.removeAllRanges();
+    };
+    return () =>
+      h(
+        Primitive.button,
+        mergeProps(
+          {
+            type: "button",
+            ...attrs,
+            render: props.render,
+            asChild: props.asChild,
+            children: props.children,
+            disabled: attrs.disabled === "" || !!attrs.disabled || !info?.value,
+            ref: forwardRef,
+          },
+          { onClick },
+        ),
+        slots,
+      );
+  },
+  {
+    name: "SelectionToolbarPrimitive.Quote",
+    inheritAttrs: false,
+    props: ["render", "asChild", "children"],
+  },
+);

package/src/primitives/selectionToolbar/SelectionToolbarRoot.test.tsx

@@ -0,0 +1,439 @@
+/** @vitest-environment jsdom */
+import {
+  defineComponent,
+  h as vnode,
+  KeepAlive,
+  nextTick,
+  shallowRef,
+} from "vue";
+import { fireEvent } from "@testing-library/dom";
+import { actAsync as act, cleanup, render } from "../../tests/vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type * as StoreModule from "@ulearning/ai-store";
+import { ThreadPrimitiveRoot } from "../thread/ThreadRoot";
+import { SelectionToolbarPrimitiveRoot } from "./SelectionToolbarRoot";
+import { SelectionToolbarPrimitiveQuote } from "./SelectionToolbarQuote";
+
+const h = vi.hoisted(() => ({
+  aui: {
+    thread: {
+      source: null,
+      getState: () => ({ speech: undefined }),
+      stopSpeaking: vi.fn(),
+      composer: () => ({ setQuote: h.setQuote }),
+    },
+  },
+  setQuote: vi.fn(),
+}));
+
+vi.mock("@ulearning/ai-store", async (importOriginal) => ({
+  ...(await importOriginal<typeof StoreModule>()),
+  useAui: () => h.aui,
+}));
+
+let selectionMessage: HTMLDivElement;
+
+beforeEach(() => {
+  selectionMessage = document.createElement("div");
+  selectionMessage.dataset.messageId = "m1";
+  selectionMessage.textContent = "selected text";
+  document.body.append(selectionMessage);
+  const selectedNode = selectionMessage.firstChild;
+  vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+    cb(0);
+    return 0;
+  });
+  vi.spyOn(window, "getSelection").mockReturnValue({
+    isCollapsed: false,
+    anchorNode: selectedNode,
+    focusNode: selectedNode,
+    rangeCount: 1,
+    toString: () => "selected text",
+    getRangeAt: () => ({
+      commonAncestorContainer: selectedNode,
+      getBoundingClientRect: () =>
+        ({ top: 100, left: 50, width: 20 }) as DOMRect,
+    }),
+  } as unknown as Selection);
+});
+
+afterEach(() => {
+  cleanup();
+  selectionMessage.remove();
+  vi.restoreAllMocks();
+});
+
+const setupToolbar = async (onMouseDown?: (e: MouseEvent) => void) => {
+  render(
+    <SelectionToolbarPrimitiveRoot
+      data-testid="toolbar"
+      {...(onMouseDown === undefined ? {} : { onMousedown: onMouseDown })}
+    />,
+  );
+  await fireEvent.mouseUp(document);
+  const toolbar = document.querySelector('[data-testid="toolbar"]');
+  expect(toolbar).not.toBeNull();
+  return toolbar as HTMLElement;
+};
+
+describe("SelectionToolbarPrimitiveRoot onMouseDown composition", () => {
+  it("runs the consumer handler on an un-prevented event before preventing default", async () => {
+    let observedDefaultPrevented: boolean | undefined;
+    const onMouseDown = vi.fn((event: MouseEvent) => {
+      observedDefaultPrevented = event.defaultPrevented;
+    });
+    const toolbar = await setupToolbar(onMouseDown);
+
+    const notPrevented = await fireEvent.mouseDown(toolbar);
+
+    expect(onMouseDown).toHaveBeenCalledTimes(1);
+    expect(observedDefaultPrevented).toBe(false);
+    expect(notPrevented).toBe(false);
+  });
+
+  it("keeps the event prevented when the consumer prevents default", async () => {
+    const onMouseDown = vi.fn((event: MouseEvent) => {
+      event.preventDefault();
+    });
+    const toolbar = await setupToolbar(onMouseDown);
+
+    const notPrevented = await fireEvent.mouseDown(toolbar);
+
+    expect(onMouseDown).toHaveBeenCalledTimes(1);
+    expect(notPrevented).toBe(false);
+  });
+});
+
+describe("SelectionToolbarPrimitiveRoot selection changes", () => {
+  it("closes an open toolbar when the selection collapses", async () => {
+    render(<SelectionToolbarPrimitiveRoot data-testid="toolbar" />);
+    await fireEvent(document, new Event("selectionchange"));
+    expect(document.querySelector('[data-testid="toolbar"]')).not.toBeNull();
+
+    vi.mocked(window.getSelection).mockReturnValueOnce({
+      isCollapsed: true,
+    } as Selection);
+    await fireEvent(document, new Event("selectionchange"));
+
+    expect(document.querySelector('[data-testid="toolbar"]')).toBeNull();
+  });
+
+  it("opens only inside the thread that owns the selection", async () => {
+    const { getByTestId } = render(
+      <>
+        <ThreadPrimitiveRoot>
+          <div data-message-id="m1">
+            <span data-testid="first-message">first</span>
+          </div>
+          <SelectionToolbarPrimitiveRoot data-testid="first-toolbar" />
+        </ThreadPrimitiveRoot>
+        <ThreadPrimitiveRoot>
+          <div data-message-id="m1">
+            <span data-testid="second-message">second</span>
+          </div>
+          <SelectionToolbarPrimitiveRoot data-testid="second-toolbar" />
+        </ThreadPrimitiveRoot>
+      </>,
+    );
+    const selectedNode = getByTestId("first-message").firstChild;
+    vi.mocked(window.getSelection).mockReturnValue({
+      isCollapsed: false,
+      anchorNode: selectedNode,
+      focusNode: selectedNode,
+      rangeCount: 1,
+      toString: () => "first",
+      getRangeAt: () => ({
+        commonAncestorContainer: selectedNode,
+        getBoundingClientRect: () =>
+          ({ top: 100, left: 50, width: 20 }) as DOMRect,
+      }),
+    } as unknown as Selection);
+
+    await fireEvent(document, new Event("selectionchange"));
+
+    expect(
+      document.querySelector('[data-testid="first-toolbar"]'),
+    ).not.toBeNull();
+    expect(document.querySelector('[data-testid="second-toolbar"]')).toBeNull();
+
+    const secondSelectedNode = getByTestId("second-message").firstChild;
+    vi.mocked(window.getSelection).mockReturnValue({
+      isCollapsed: false,
+      anchorNode: secondSelectedNode,
+      focusNode: secondSelectedNode,
+      rangeCount: 1,
+      toString: () => "second",
+      getRangeAt: () => ({
+        commonAncestorContainer: secondSelectedNode,
+        getBoundingClientRect: () =>
+          ({ top: 100, left: 50, width: 20 }) as DOMRect,
+      }),
+    } as unknown as Selection);
+
+    await fireEvent(document, new Event("selectionchange"));
+
+    expect(document.querySelector('[data-testid="first-toolbar"]')).toBeNull();
+    expect(
+      document.querySelector('[data-testid="second-toolbar"]'),
+    ).not.toBeNull();
+  });
+
+  it("warns when a custom thread root does not forward its ref", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const RefDroppingRoot = defineComponent({
+      setup:
+        (_, { slots }) =>
+        () => [vnode("div", slots.default?.()), vnode("span")],
+    });
+    const { getByTestId } = render(
+      <ThreadPrimitiveRoot render={<RefDroppingRoot />}>
+        <div data-message-id="m1">
+          <span data-testid="message">text</span>
+        </div>
+        <SelectionToolbarPrimitiveRoot data-testid="toolbar" />
+      </ThreadPrimitiveRoot>,
+    );
+    const selectedNode = getByTestId("message").firstChild;
+    vi.mocked(window.getSelection).mockReturnValue({
+      isCollapsed: false,
+      anchorNode: selectedNode,
+      focusNode: selectedNode,
+      rangeCount: 1,
+      toString: () => "text",
+      getRangeAt: () => ({
+        commonAncestorContainer: selectedNode,
+        getBoundingClientRect: () =>
+          ({ top: 100, left: 50, width: 20 }) as DOMRect,
+      }),
+    } as unknown as Selection);
+
+    await fireEvent(document, new Event("selectionchange"));
+
+    expect(document.querySelector('[data-testid="toolbar"]')).not.toBeNull();
+    expect(warn).toHaveBeenCalledWith(
+      "[SelectionToolbarPrimitive.Root] ThreadPrimitive.Root did not provide a DOM element, so the selection cannot be scoped to its thread. Ensure a custom root child forwards its ref.",
+    );
+  });
+});
+
+describe("SelectionToolbarPrimitiveRoot frame cleanup", () => {
+  // Defer the frame instead of running it inline, so the window between the
+  // selection event and the frame is observable.
+  const deferFrames = () => {
+    const frames: FrameRequestCallback[] = [];
+    let nextHandle = 1;
+    vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+      frames.push(cb);
+      return nextHandle++;
+    });
+    const cancelAnimationFrame = vi
+      .spyOn(window, "cancelAnimationFrame")
+      .mockImplementation(() => {});
+    return { frames, cancelAnimationFrame };
+  };
+
+  it("ignores a cancelled frame after scroll and releases a cached owner's queued work", async () => {
+    const { frames, cancelAnimationFrame } = deferFrames();
+    const visible = shallowRef(true);
+    const Owner = defineComponent({
+      setup: () => () =>
+        vnode(SelectionToolbarPrimitiveRoot, { "data-testid": "toolbar" }),
+    });
+    const view = render(
+      vnode(
+        defineComponent({
+          setup: () => () =>
+            vnode(KeepAlive, null, {
+              default: () => (visible.value ? vnode(Owner) : null),
+            }),
+        }),
+      ),
+    );
+    await fireEvent(document, new Event("selectionchange"));
+    await fireEvent.scroll(document);
+    await act(() => frames[0]?.(0));
+    expect(document.querySelector('[data-testid="toolbar"]')).toBeNull();
+    await fireEvent(document, new Event("selectionchange"));
+    visible.value = false;
+    await nextTick();
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(2);
+    await act(() => frames[1]?.(0));
+    expect(document.querySelector('[data-testid="toolbar"]')).toBeNull();
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(2);
+    visible.value = true;
+    await nextTick();
+    await fireEvent(document, new Event("selectionchange"));
+    await act(() => frames[2]?.(0));
+    expect(document.querySelector('[data-testid="toolbar"]')).not.toBeNull();
+    view.unmount();
+    expect(document.querySelector('[data-testid="toolbar"]')).toBeNull();
+  });
+
+  it("quotes the captured text exactly once and permits the caller to cancel", async () => {
+    const removeAllRanges = vi.fn();
+    const selection = window.getSelection()!;
+    vi.mocked(window.getSelection).mockReturnValue({
+      ...selection,
+      removeAllRanges,
+    } as Selection);
+    const cancel = shallowRef(true);
+    const view = render(
+      vnode(
+        defineComponent({
+          setup: () => () =>
+            vnode(
+              SelectionToolbarPrimitiveRoot,
+              { "data-testid": "toolbar" },
+              {
+                default: () =>
+                  vnode(
+                    SelectionToolbarPrimitiveQuote,
+                    {
+                      onClick: (event: MouseEvent) => {
+                        if (cancel.value) event.preventDefault();
+                      },
+                    },
+                    { default: () => "Quote" },
+                  ),
+              },
+            ),
+        }),
+      ),
+    );
+    await fireEvent(document, new Event("selectionchange"));
+    const button = document.querySelector<HTMLButtonElement>(
+      '[data-testid="toolbar"] button',
+    )!;
+    expect(button.type).toBe("button");
+    await fireEvent.click(button);
+    expect(h.setQuote).not.toHaveBeenCalled();
+    expect(removeAllRanges).not.toHaveBeenCalled();
+    cancel.value = false;
+    await nextTick();
+    await fireEvent.click(button);
+    expect(h.setQuote).toHaveBeenCalledExactlyOnceWith({
+      text: "selected text",
+      messageId: "m1",
+    });
+    expect(removeAllRanges).toHaveBeenCalledOnce();
+    view.unmount();
+  });
+
+  it("cancels a queued selection frame when the toolbar unmounts", async () => {
+    const { frames, cancelAnimationFrame } = deferFrames();
+    const { unmount } = render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent.mouseUp(document);
+    expect(frames).toHaveLength(1);
+
+    unmount();
+
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(1);
+  });
+
+  it("cancels the previous frame when another selection event arrives", async () => {
+    const { frames, cancelAnimationFrame } = deferFrames();
+    const { unmount } = render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent.mouseUp(document);
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(2);
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(1);
+
+    unmount();
+
+    expect(cancelAnimationFrame).toHaveBeenCalledTimes(2);
+    expect(cancelAnimationFrame).toHaveBeenLastCalledWith(2);
+  });
+
+  it("waits until mouseup to measure a drag selection", async () => {
+    const { frames } = deferFrames();
+    render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent.mouseDown(document);
+    await fireEvent(document, new Event("selectionchange"));
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(0);
+
+    await fireEvent.mouseUp(document);
+    expect(frames).toHaveLength(1);
+  });
+
+  it("recovers when a drag ends without mouseup", async () => {
+    const { frames } = deferFrames();
+    render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent.mouseDown(document);
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(0);
+
+    await fireEvent(document, new Event("dragend"));
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(2);
+  });
+
+  it("shows the toolbar when the window blurs during a drag", async () => {
+    const { frames } = deferFrames();
+    render(<SelectionToolbarPrimitiveRoot data-testid="toolbar" />);
+
+    await fireEvent.mouseDown(document);
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(0);
+
+    await fireEvent.blur(window);
+    expect(frames).toHaveLength(1);
+
+    await act(() => frames[0]?.(0));
+
+    expect(document.querySelector('[data-testid="toolbar"]')).not.toBeNull();
+  });
+
+  it("does not reopen a toolbar hidden by scroll on an unrelated window blur", async () => {
+    render(<SelectionToolbarPrimitiveRoot data-testid="toolbar" />);
+
+    await fireEvent(document, new Event("selectionchange"));
+    expect(document.querySelector('[data-testid="toolbar"]')).not.toBeNull();
+
+    await fireEvent.scroll(document);
+    expect(document.querySelector('[data-testid="toolbar"]')).toBeNull();
+
+    await fireEvent.blur(window);
+    expect(document.querySelector('[data-testid="toolbar"]')).toBeNull();
+  });
+
+  it("recovers when a context menu consumes the mouseup of a press", async () => {
+    const { frames } = deferFrames();
+    render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent.mouseDown(document, { button: 2 });
+    await fireEvent.contextMenu(document);
+    await fireEvent(document, new Event("selectionchange"));
+    expect(frames).toHaveLength(1);
+  });
+
+  it("cancels a queued selection frame when the page scrolls", async () => {
+    const { frames, cancelAnimationFrame } = deferFrames();
+    render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent(document, new Event("selectionchange"));
+    await fireEvent.scroll(document);
+
+    expect(frames).toHaveLength(1);
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(1);
+  });
+
+  it("cancels a queued frame when the selection collapses", async () => {
+    const { frames, cancelAnimationFrame } = deferFrames();
+    render(<SelectionToolbarPrimitiveRoot />);
+
+    await fireEvent(document, new Event("selectionchange"));
+    vi.mocked(window.getSelection).mockReturnValueOnce({
+      isCollapsed: true,
+    } as Selection);
+    await fireEvent(document, new Event("selectionchange"));
+
+    expect(frames).toHaveLength(1);
+    expect(cancelAnimationFrame).toHaveBeenCalledWith(1);
+  });
+});