@assistant-ui/vue 0.0.0-stage → 0.0.1

package/src/primitives/ThreadListKeyboardNav.test.ts

@@ -0,0 +1,298 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  createApp,
+  defineComponent,
+  h,
+  nextTick,
+  ref,
+  type Component,
+} from "vue";
+import { AuiConfig } from "@assistant-ui/store/client";
+import { RuntimeAdapter } from "@assistant-ui/core/store";
+import type { ExternalStoreAdapter } from "@assistant-ui/core";
+import {
+  AssistantRuntimeImpl,
+  ExternalStoreRuntimeCore,
+} from "@assistant-ui/core/internal";
+import { AuiProvider } from "../AuiProvider";
+import { ThreadListItemByIndexProvider } from "./threadList";
+import { ThreadListItemPrimitiveRoot } from "./ThreadListItemPrimitiveRoot";
+import { ThreadListItemPrimitiveTrigger } from "./ThreadListItemPrimitiveTrigger";
+import { ThreadListPrimitiveRoot } from "./ThreadListPrimitiveRoot";
+
+type Message = { id: string; role: "user"; text: string };
+
+const createRuntime = () => {
+  let mainThreadId = "first";
+  let core!: ExternalStoreRuntimeCore;
+  const onSwitchToThread = vi.fn((threadId: string) => {
+    mainThreadId = threadId;
+    core.setAdapter(createAdapter());
+  });
+  const createAdapter = (): ExternalStoreAdapter<Message> => ({
+    messages: [],
+    convertMessage: (message) => ({
+      id: message.id,
+      role: message.role,
+      content: [{ type: "text", text: message.text }],
+    }),
+    onNew: async () => {},
+    adapters: {
+      threadList: {
+        threadId: mainThreadId,
+        threads: ["first", "second", "third"].map((id) => ({
+          status: "regular" as const,
+          id,
+          title: id,
+        })),
+        onSwitchToThread,
+      },
+    },
+  });
+  core = new ExternalStoreRuntimeCore(createAdapter());
+  return {
+    runtime: new AssistantRuntimeImpl(core),
+    onSwitchToThread,
+  };
+};
+
+const mount = (runtime: AssistantRuntimeImpl, view: Component) => {
+  const app = createApp(
+    defineComponent({
+      setup: () => () =>
+        h(
+          AuiProvider,
+          { config: AuiConfig({ threads: RuntimeAdapter(runtime) }) },
+          { default: () => h(view) },
+        ),
+    }),
+  );
+  const el = document.createElement("div");
+  document.body.append(el);
+  app.mount(el);
+  return {
+    el,
+    unmount: () => {
+      app.unmount();
+      el.remove();
+    },
+  };
+};
+
+const keydown = (element: HTMLElement, key: string) =>
+  element.dispatchEvent(
+    new KeyboardEvent("keydown", { bubbles: true, cancelable: true, key }),
+  );
+
+const buttons = (el: HTMLElement) => [
+  ...el.querySelectorAll<HTMLButtonElement>("button"),
+];
+
+describe("thread list keyboard navigation", () => {
+  it("moves through triggers in DOM order without wrapping", async () => {
+    const { runtime } = createRuntime();
+    const View = defineComponent({
+      setup: () => () =>
+        h(
+          ThreadListPrimitiveRoot,
+          { class: "list" },
+          {
+            default: () =>
+              [0, 1, 2].map((index) =>
+                h(
+                  ThreadListItemByIndexProvider,
+                  { index, key: index },
+                  {
+                    default: () =>
+                      h(
+                        ThreadListItemPrimitiveRoot,
+                        { class: "item" },
+                        {
+                          default: () =>
+                            h(ThreadListItemPrimitiveTrigger, null, {
+                              default: () => `item ${index}`,
+                            }),
+                        },
+                      ),
+                  },
+                ),
+              ),
+          },
+        ),
+    });
+    const { el, unmount } = mount(runtime, View);
+
+    await nextTick();
+    const [first, second, third] = buttons(el);
+    const list = el.querySelector<HTMLElement>(".list")!;
+    const [firstItem, , thirdItem] = el.querySelectorAll<HTMLElement>(".item");
+    list.insertBefore(thirdItem!, firstItem!);
+
+    third!.focus();
+    expect(keydown(third!, "ArrowDown")).toBe(false);
+    expect(document.activeElement).toBe(first);
+    expect(keydown(first!, "ArrowDown")).toBe(false);
+    expect(document.activeElement).toBe(second);
+    expect(keydown(second!, "ArrowDown")).toBe(true);
+    expect(document.activeElement).toBe(second);
+    expect(keydown(first!, "ArrowUp")).toBe(false);
+    expect(document.activeElement).toBe(third);
+    expect(keydown(third!, "ArrowUp")).toBe(true);
+    expect(document.activeElement).toBe(third);
+
+    unmount();
+  });
+
+  it("lets a caller veto collection navigation", async () => {
+    const { runtime } = createRuntime();
+    const View = defineComponent({
+      setup: () => () =>
+        h(ThreadListPrimitiveRoot, null, {
+          default: () =>
+            [0, 1].map((index) =>
+              h(
+                ThreadListItemByIndexProvider,
+                { index, key: index },
+                {
+                  default: () =>
+                    h(
+                      ThreadListItemPrimitiveRoot,
+                      {
+                        onKeydown: (event: KeyboardEvent) =>
+                          event.preventDefault(),
+                      },
+                      {
+                        default: () =>
+                          h(ThreadListItemPrimitiveTrigger, null, {
+                            default: () => `item ${index}`,
+                          }),
+                      },
+                    ),
+                },
+              ),
+            ),
+        }),
+    });
+    const { el, unmount } = mount(runtime, View);
+
+    await nextTick();
+    const [first] = buttons(el);
+    first!.focus();
+    expect(keydown(first!, "ArrowDown")).toBe(false);
+    expect(document.activeElement).toBe(first);
+
+    unmount();
+  });
+
+  it("tracks the main thread on the item root", async () => {
+    const { runtime, onSwitchToThread } = createRuntime();
+    const View = defineComponent({
+      setup: () => () =>
+        h(ThreadListPrimitiveRoot, null, {
+          default: () =>
+            [0, 1].map((index) =>
+              h(
+                ThreadListItemByIndexProvider,
+                { index, key: index },
+                {
+                  default: () =>
+                    h(
+                      ThreadListItemPrimitiveRoot,
+                      { class: "item" },
+                      {
+                        default: () =>
+                          h(ThreadListItemPrimitiveTrigger, null, {
+                            default: () => `item ${index}`,
+                          }),
+                      },
+                    ),
+                },
+              ),
+            ),
+        }),
+    });
+    const { el, unmount } = mount(runtime, View);
+
+    await nextTick();
+    const items = el.querySelectorAll<HTMLElement>(".item");
+    expect(items[0]!.getAttribute("data-active")).toBe("true");
+    expect(items[0]!.getAttribute("aria-current")).toBe("true");
+    buttons(el)[1]!.click();
+    await vi.waitFor(() => {
+      expect(onSwitchToThread).toHaveBeenCalledWith("second");
+      expect(items[1]!.getAttribute("data-active")).toBe("true");
+      expect(items[1]!.getAttribute("aria-current")).toBe("true");
+    });
+    expect(items[0]!.hasAttribute("data-active")).toBe(false);
+    expect(items[0]!.hasAttribute("aria-current")).toBe(false);
+
+    unmount();
+  });
+
+  it("keeps the trigger working without either root", async () => {
+    const { runtime, onSwitchToThread } = createRuntime();
+    const View = defineComponent({
+      setup: () => () =>
+        [0, 1].map((index) =>
+          h(
+            ThreadListItemByIndexProvider,
+            { index, key: index },
+            {
+              default: () =>
+                h(ThreadListItemPrimitiveTrigger, null, {
+                  default: () => `item ${index}`,
+                }),
+            },
+          ),
+        ),
+    });
+    const { el, unmount } = mount(runtime, View);
+
+    await nextTick();
+    buttons(el)[1]!.click();
+    await vi.waitFor(() => {
+      expect(onSwitchToThread).toHaveBeenCalledWith("second");
+    });
+
+    unmount();
+  });
+
+  it("unregisters a trigger when its item unmounts", async () => {
+    const { runtime } = createRuntime();
+    const showSecond = ref(true);
+    const View = defineComponent({
+      setup: () => () =>
+        h(ThreadListPrimitiveRoot, null, {
+          default: () =>
+            [0, 1, 2]
+              .filter((index) => index !== 1 || showSecond.value)
+              .map((index) =>
+                h(
+                  ThreadListItemByIndexProvider,
+                  { index, key: index },
+                  {
+                    default: () =>
+                      h(ThreadListItemPrimitiveRoot, null, {
+                        default: () =>
+                          h(ThreadListItemPrimitiveTrigger, null, {
+                            default: () => `item ${index}`,
+                          }),
+                      }),
+                  },
+                ),
+              ),
+        }),
+    });
+    const { el, unmount } = mount(runtime, View);
+
+    await nextTick();
+    showSecond.value = false;
+    await nextTick();
+    const [first, third] = buttons(el);
+    first!.focus();
+    expect(keydown(first!, "ArrowDown")).toBe(false);
+    expect(document.activeElement).toBe(third);
+
+    unmount();
+  });
+});

package/src/primitives/ThreadListPrimitiveRoot.ts

@@ -0,0 +1,18 @@
+import {
+  defineComponent,
+  h,
+  mergeProps,
+  type SlotsType,
+  type VNodeChild,
+} from "vue";
+import { provideThreadListCollection } from "./threadListFocusGroup";
+
+export const ThreadListPrimitiveRoot = defineComponent({
+  name: "ThreadListPrimitiveRoot",
+  inheritAttrs: false,
+  slots: Object as SlotsType<{ default?: () => VNodeChild[] }>,
+  setup(_, { attrs, slots }) {
+    provideThreadListCollection();
+    return () => h("div", mergeProps(attrs), slots.default?.());
+  },
+});

package/src/primitives/ThreadPrimitiveMessages.ts

@@ -0,0 +1,40 @@
+import { defineComponent, h, type SlotsType, type VNodeChild } from "vue";
+import type {} from "@assistant-ui/core/store";
+import { useAuiState } from "../useAuiState";
+import { MessageByIdProvider } from "./MessageByIdProvider";
+import { useStableKeys } from "./stableKeys";
+
+/**
+ * Renders the default slot once per message in the current thread, each
+ * instance scoped to its message through {@link MessageByIdProvider} and
+ * keyed by the message id: an edit or reload that replaces the occupant of a
+ * slot remounts that row, so `<TransitionGroup>` and per-row component state
+ * follow message identity. The empty optimistic placeholder that precedes a
+ * response is its own identity, so the arrival of the real assistant message
+ * remounts that one row (a leave/enter pair under `<TransitionGroup>`).
+ *
+ * @example
+ * ```html
+ * <ThreadPrimitiveMessages>
+ *   <ChatMessage />
+ * </ThreadPrimitiveMessages>
+ * ```
+ */
+export const ThreadPrimitiveMessages = defineComponent({
+  name: "ThreadPrimitiveMessages",
+  slots: Object as SlotsType<{ default?: () => VNodeChild[] }>,
+  setup(_, { slots }) {
+    const messages = useAuiState((s) => s.thread.messages);
+    const ids = useStableKeys(() =>
+      messages.value.map((message) => message.id),
+    );
+    return () =>
+      ids.value.map((id) =>
+        h(
+          MessageByIdProvider,
+          { id, key: id },
+          { default: () => slots.default?.() },
+        ),
+      );
+  },
+});

package/src/primitives/ThreadPrimitiveScrollToBottom.ts

@@ -0,0 +1,65 @@
+import {
+  defineComponent,
+  h,
+  inject,
+  mergeProps,
+  type PropType,
+  type SlotsType,
+  type VNodeChild,
+} from "vue";
+import { isDevelopment } from "@assistant-ui/core/store/internal";
+import { isAttrDisabled } from "./attrDisabled";
+import { viewportInjectionKey } from "./viewportContext";
+
+let warnedOutsideViewport = false;
+
+export const clearScrollToBottomWarningForTesting = () => {
+  warnedOutsideViewport = false;
+};
+
+/**
+ * A button that scrolls the surrounding {@link ThreadPrimitiveViewport} to
+ * the bottom. Disabled while the viewport is already at the bottom, or when
+ * no viewport provides the channel.
+ */
+export const ThreadPrimitiveScrollToBottom = defineComponent({
+  name: "ThreadPrimitiveScrollToBottom",
+  inheritAttrs: false,
+  props: {
+    behavior: {
+      type: String as PropType<ScrollBehavior>,
+      default: "auto",
+    },
+  },
+  slots: Object as SlotsType<{ default?: () => VNodeChild[] }>,
+  setup(props, { attrs, slots }) {
+    const viewport = inject(viewportInjectionKey, null);
+    if (isDevelopment && !viewport && !warnedOutsideViewport) {
+      warnedOutsideViewport = true;
+      console.warn(
+        "ThreadPrimitiveScrollToBottom: no surrounding ThreadPrimitiveViewport provides the scroll channel; the button stays disabled. Place it inside the viewport.",
+      );
+    }
+    const onClick = (event: MouseEvent) => {
+      if (
+        event.defaultPrevented ||
+        !viewport ||
+        viewport.isAtBottom.value ||
+        isAttrDisabled(attrs)
+      )
+        return;
+      viewport.scrollToBottom(props.behavior);
+    };
+    return () =>
+      h(
+        "button",
+        mergeProps(attrs, {
+          type: "button",
+          disabled:
+            !viewport || viewport.isAtBottom.value || isAttrDisabled(attrs),
+          onClick,
+        }),
+        slots.default?.(),
+      );
+  },
+});

package/src/primitives/ThreadPrimitiveViewport.ts

@@ -0,0 +1,233 @@
+import {
+  defineComponent,
+  h,
+  onMounted,
+  onScopeDispose,
+  provide,
+  shallowRef,
+  watch,
+  type SlotsType,
+  type VNodeChild,
+} from "vue";
+import type {} from "@assistant-ui/core/store";
+import { useAuiEvent } from "../useAuiEvent";
+import { useAuiState } from "../useAuiState";
+import {
+  isUserScrollUp,
+  isViewportAtBottom,
+  observeContentResize,
+  viewportOverflows,
+} from "@assistant-ui/store/client";
+import { viewportInjectionKey } from "./viewportContext";
+
+/**
+ * A scrollable container that keeps the thread pinned to the bottom: content
+ * growth scrolls back down while the user sits at the bottom, a run start
+ * scrolls down, and scrolling up unpins until the user returns to the bottom.
+ * The four options mirror the React hook and are independent: `autoScroll`
+ * covers follow-on-content-growth, and the other three gate the
+ * first-messages, run-start, and thread-switch scrolls. Provides the
+ * scroll-to-bottom channel that {@link ThreadPrimitiveScrollToBottom} drives;
+ * the React viewport's top-anchor system stays in the React viewport store
+ * and is not ported.
+ */
+export const ThreadPrimitiveViewport = defineComponent({
+  name: "ThreadPrimitiveViewport",
+  props: {
+    autoScroll: {
+      type: Boolean,
+      default: true,
+    },
+    scrollToBottomOnInitialize: {
+      type: Boolean,
+      default: true,
+    },
+    scrollToBottomOnRunStart: {
+      type: Boolean,
+      default: true,
+    },
+    scrollToBottomOnThreadSwitch: {
+      type: Boolean,
+      default: true,
+    },
+  },
+  slots: Object as SlotsType<{ default?: () => VNodeChild[] }>,
+  setup(props, { slots }) {
+    const divRef = shallowRef<HTMLElement | null>(null);
+    const contentInset = shallowRef(0);
+    const contentInsetEntries = new Map<symbol, number>();
+    let intent: ScrollBehavior | null = null;
+    const isAtBottom = shallowRef(true);
+    let lastScrollTop = 0;
+    let lastScrollHeight = 0;
+    let lastObservedScrollHeight = 0;
+    let lastObservedClientHeight = 0;
+    let frame: number | null = null;
+
+    const scrollToBottom = (behavior: ScrollBehavior) => {
+      const div = divRef.value;
+      if (!div) return;
+      intent = behavior;
+      div.scrollTo?.({ top: div.scrollHeight, behavior });
+    };
+
+    const scheduleScrollToBottom = (behavior: ScrollBehavior) => {
+      intent = behavior;
+      // The immediate watch below runs synchronously during SSR, where no
+      // frame scheduler exists.
+      if (typeof requestAnimationFrame === "undefined") return;
+      if (frame !== null) cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        frame = null;
+        scrollToBottom(behavior);
+      });
+    };
+
+    const handleScroll = () => {
+      const div = divRef.value;
+      if (!div) return;
+
+      const newIsAtBottom = isViewportAtBottom(div, contentInset.value);
+      const inFlightDownward = !newIsAtBottom && lastScrollTop < div.scrollTop;
+      if (!inFlightDownward) {
+        if (newIsAtBottom) {
+          // At-bottom is ambiguous while the viewport does not overflow; keep
+          // the intent alive until content can actually scroll.
+          if (viewportOverflows(div, contentInset.value)) intent = null;
+        } else if (
+          isUserScrollUp(
+            { scrollTop: lastScrollTop, scrollHeight: lastScrollHeight },
+            div,
+          )
+        ) {
+          intent = null;
+        }
+        if (newIsAtBottom || intent === null) isAtBottom.value = newIsAtBottom;
+      }
+
+      lastScrollTop = div.scrollTop;
+      lastScrollHeight = div.scrollHeight;
+    };
+
+    const updateContentInset = () => {
+      let total = 0;
+      for (const height of contentInsetEntries.values()) total += height;
+      if (contentInset.value === total) return;
+      const grew = total > contentInset.value;
+      contentInset.value = total;
+      // A growing inset obscures content a pinned viewport was showing, so it
+      // follows like a content resize; a shrinking inset reveals content and
+      // must not move the viewport.
+      if (grew) {
+        if (intent) {
+          scrollToBottom(intent);
+        } else if (props.autoScroll && isAtBottom.value) {
+          scrollToBottom("instant");
+        }
+      }
+      handleScroll();
+    };
+
+    const registerContentInset = () => {
+      const id = Symbol();
+      contentInsetEntries.set(id, 0);
+
+      return {
+        setHeight: (height: number) => {
+          if (contentInsetEntries.get(id) === height) return;
+          contentInsetEntries.set(id, height);
+          updateContentInset();
+        },
+        unregister: () => {
+          if (!contentInsetEntries.delete(id)) return;
+          updateContentInset();
+        },
+      };
+    };
+
+    const onContentResize = () => {
+      const div = divRef.value;
+      if (!div) return;
+      const { scrollHeight, clientHeight } = div;
+      if (
+        scrollHeight === lastObservedScrollHeight &&
+        clientHeight === lastObservedClientHeight
+      ) {
+        return;
+      }
+      lastObservedScrollHeight = scrollHeight;
+      lastObservedClientHeight = clientHeight;
+
+      if (intent) {
+        scrollToBottom(intent);
+      } else if (props.autoScroll && isAtBottom.value) {
+        scrollToBottom("instant");
+      }
+      handleScroll();
+    };
+
+    // A pointer gesture invalidates pending bottom-scroll intent; otherwise an
+    // intent kept alive by a non-overflowing thread hijacks the next content
+    // growth. Unlike the React hook, an already scheduled frame is cancelled
+    // too, so the gesture also wins the race against a just-planted intent.
+    const onPointerdown = () => {
+      intent = null;
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+        frame = null;
+      }
+    };
+
+    let disconnect: (() => void) | undefined;
+    onMounted(() => {
+      const div = divRef.value;
+      if (!div) return;
+      disconnect = observeContentResize(div, onContentResize);
+    });
+    onScopeDispose(() => {
+      disconnect?.();
+      if (frame !== null) cancelAnimationFrame(frame);
+    });
+
+    const hasMessages = useAuiState((s) => s.thread.messages.length > 0);
+    let initialized = false;
+    watch(
+      [hasMessages, () => props.scrollToBottomOnInitialize],
+      ([has, enabled]) => {
+        if (!has) {
+          initialized = false;
+          return;
+        }
+        if (!enabled || initialized) return;
+        initialized = true;
+        if (intent !== null) return;
+        scheduleScrollToBottom("instant");
+      },
+      { immediate: true },
+    );
+
+    useAuiEvent("thread.runStart", () => {
+      if (!props.scrollToBottomOnRunStart) return;
+      scheduleScrollToBottom("auto");
+    });
+
+    useAuiEvent("threads.selectionChanged", () => {
+      if (!props.scrollToBottomOnThreadSwitch) return;
+      scheduleScrollToBottom("instant");
+    });
+
+    provide(viewportInjectionKey, {
+      isAtBottom,
+      scrollToBottom: (behavior: ScrollBehavior = "auto") =>
+        scrollToBottom(behavior),
+      registerContentInset,
+    });
+
+    return () =>
+      h(
+        "div",
+        { ref: divRef, onScroll: handleScroll, onPointerdown },
+        slots.default?.(),
+      );
+  },
+});