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

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

@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { matchesTriggerItemQuery } from "./matchesTriggerItemQuery";
+import type { Unstable_TriggerItem } from "@ulearning/ai-core";
+
+const item = (
+  overrides: Partial<Unstable_TriggerItem>,
+): Unstable_TriggerItem => ({
+  id: "summarize",
+  type: "command",
+  label: "Summarize",
+  ...overrides,
+});
+
+describe("matchesTriggerItemQuery", () => {
+  it("matches every item on an empty query", () => {
+    expect(matchesTriggerItemQuery(item({}), "")).toBe(true);
+  });
+
+  it("matches case-insensitively against the id", () => {
+    expect(
+      matchesTriggerItemQuery(item({ id: "SummArize", label: "y" }), "marize"),
+    ).toBe(true);
+  });
+
+  it("matches case-insensitively against the label", () => {
+    expect(
+      matchesTriggerItemQuery(
+        item({ id: "x", label: "Translate Text" }),
+        "late",
+      ),
+    ).toBe(true);
+  });
+
+  it("matches against the description when present", () => {
+    expect(
+      matchesTriggerItemQuery(
+        item({ id: "x", label: "y", description: "Condense the thread" }),
+        "condense",
+      ),
+    ).toBe(true);
+  });
+
+  it("does not match when no field contains the query", () => {
+    expect(
+      matchesTriggerItemQuery(item({ description: "nothing here" }), "zzz"),
+    ).toBe(false);
+  });
+
+  it("does not throw on items without a description", () => {
+    expect(matchesTriggerItemQuery(item({}), "zzz")).toBe(false);
+  });
+});

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

@@ -0,0 +1,13 @@
+import type { Unstable_TriggerItem } from "@ulearning/ai-core";
+
+export function matchesTriggerItemQuery(
+  item: Unstable_TriggerItem,
+  lowerQuery: string,
+): boolean {
+  if (!lowerQuery) return true;
+  return (
+    item.id.toLowerCase().includes(lowerQuery) ||
+    item.label.toLowerCase().includes(lowerQuery) ||
+    (item.description?.toLowerCase().includes(lowerQuery) ?? false)
+  );
+}

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

@@ -0,0 +1,47 @@
+import { useMemo, useState } from "@ulearning/ai-tap";
+import { resource } from "@ulearning/ai-tap";
+import {
+  detectTrigger,
+  type TriggerMatch,
+  type TriggerMatcher,
+} from "./detectTrigger";
+
+/** Detected trigger position within the composer text. */
+export type DetectedTrigger = TriggerMatch;
+
+export type TriggerDetectionResourceOutput = {
+  /** Detected trigger (or `null` when inactive). */
+  readonly trigger: DetectedTrigger | null;
+  /** Current query string (empty when no trigger active). */
+  readonly query: string;
+  /** Update the tracked cursor position (wired to composer input). */
+  setCursorPosition(pos: number): void;
+};
+
+/** Tracks cursor position and derives the active trigger + query from composer text. */
+const useTriggerDetectionResource = ({
+  text,
+  triggerChar,
+  matcher,
+}: {
+  text: string;
+  triggerChar: string;
+  matcher?: TriggerMatcher | undefined;
+}): TriggerDetectionResourceOutput => {
+  const [cursorPosition, setCursorPosition] = useState(text.length);
+
+  const trigger = useMemo(() => {
+    const pos = Math.min(cursorPosition, text.length);
+    return detectTrigger(text, triggerChar, pos, matcher);
+  }, [cursorPosition, matcher, text, triggerChar]);
+
+  const query = trigger?.query ?? "";
+
+  return {
+    trigger,
+    query,
+    setCursorPosition,
+  };
+};
+
+export const TriggerDetectionResource = resource(useTriggerDetectionResource);

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

@@ -0,0 +1,233 @@
+import { describe, it, expect, vi } from "vitest";
+import { createTapRoot, flushTapSync, useResource } from "@ulearning/ai-tap";
+import type {
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+import { TriggerKeyboardResource } from "./triggerKeyboardResource";
+
+const item = (id: string): Unstable_TriggerItem => ({
+  id,
+  type: "command",
+  label: id,
+});
+
+const category = (id: string): Unstable_TriggerCategory => ({
+  id,
+  label: id,
+});
+
+const makeKeyEvent = (key: string, shiftKey = false) => ({
+  key,
+  shiftKey,
+  preventDefault: vi.fn(),
+});
+
+const render = (
+  overrides: Partial<Parameters<typeof TriggerKeyboardResource>[0]> = {},
+) => {
+  const props = {
+    navigableList: [item("a"), item("b"), item("c")],
+    isSearchMode: false,
+    activeCategoryId: null as string | null,
+    query: "",
+    popoverId: "popover",
+    open: true,
+    selectItem: vi.fn(),
+    selectCategory: vi.fn(),
+    goBack: vi.fn(),
+    close: vi.fn(),
+    ...overrides,
+  };
+  const root = createTapRoot(function Root() {
+    return useResource(TriggerKeyboardResource(props));
+  });
+  return { sub: root, props };
+};
+
+describe("TriggerKeyboardResource", () => {
+  it("selects highlighted item on Tab", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Tab");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.selectItem).toHaveBeenCalledWith(props.navigableList[0]);
+    expect(props.selectCategory).not.toHaveBeenCalled();
+  });
+
+  it("selects category on Tab when entry is a category", () => {
+    const { sub, props } = render({
+      navigableList: [category("cat-1"), item("b")],
+    });
+
+    const consumed = sub.getValue().handleKeyDown(makeKeyEvent("Tab"));
+
+    expect(consumed).toBe(true);
+    expect(props.selectCategory).toHaveBeenCalledWith("cat-1");
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("lets Shift+Tab pass through for native focus traversal", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Tab", true);
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("swallows Tab when the navigable list is empty", () => {
+    const { sub, props } = render({ navigableList: [] });
+    const e = makeKeyEvent("Tab");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+    expect(props.selectCategory).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when the popover is closed", () => {
+    const { sub, props } = render({ open: false });
+    const e = makeKeyEvent("Tab");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("moves the highlight forward on ArrowDown", () => {
+    const { sub } = render();
+
+    const consumed = flushTapSync(() =>
+      sub.getValue().handleKeyDown(makeKeyEvent("ArrowDown")),
+    );
+
+    expect(consumed).toBe(true);
+    expect(sub.getValue().highlightedIndex).toBe(1);
+  });
+
+  it("wraps the highlight to the top on ArrowDown past the last entry", () => {
+    const { sub } = render();
+    const handle = sub.getValue().handleKeyDown;
+
+    flushTapSync(() => {
+      handle(makeKeyEvent("ArrowDown"));
+      handle(makeKeyEvent("ArrowDown"));
+      handle(makeKeyEvent("ArrowDown"));
+    });
+
+    expect(sub.getValue().highlightedIndex).toBe(0);
+  });
+
+  it("moves the highlight backward on ArrowUp", () => {
+    const { sub } = render();
+    const handle = sub.getValue().handleKeyDown;
+
+    flushTapSync(() => handle(makeKeyEvent("ArrowDown")));
+    flushTapSync(() => handle(makeKeyEvent("ArrowUp")));
+
+    expect(sub.getValue().highlightedIndex).toBe(0);
+  });
+
+  it("wraps the highlight to the bottom on ArrowUp from the first entry", () => {
+    const { sub } = render();
+
+    flushTapSync(() => sub.getValue().handleKeyDown(makeKeyEvent("ArrowUp")));
+
+    expect(sub.getValue().highlightedIndex).toBe(2);
+  });
+
+  it("keeps the highlight at 0 on ArrowDown when navigableList is empty", () => {
+    const { sub } = render({ navigableList: [] });
+    const e = makeKeyEvent("ArrowDown");
+
+    const consumed = flushTapSync(() => sub.getValue().handleKeyDown(e));
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(sub.getValue().highlightedIndex).toBe(0);
+  });
+
+  it("selects the highlighted item on Enter", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Enter");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.selectItem).toHaveBeenCalledWith(props.navigableList[0]);
+  });
+
+  it("lets Shift+Enter pass through for newline insertion", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Enter", true);
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.selectItem).not.toHaveBeenCalled();
+  });
+
+  it("closes the popover on Escape", () => {
+    const { sub, props } = render();
+    const e = makeKeyEvent("Escape");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.close).toHaveBeenCalled();
+  });
+
+  it("drills back on Backspace when a category is active and the query is empty", () => {
+    const { sub, props } = render({
+      activeCategoryId: "cat-1",
+      query: "",
+    });
+    const e = makeKeyEvent("Backspace");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(true);
+    expect(e.preventDefault).toHaveBeenCalled();
+    expect(props.goBack).toHaveBeenCalled();
+  });
+
+  it("lets Backspace pass through when the query is non-empty", () => {
+    const { sub, props } = render({
+      activeCategoryId: "cat-1",
+      query: "foo",
+    });
+    const e = makeKeyEvent("Backspace");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(e.preventDefault).not.toHaveBeenCalled();
+    expect(props.goBack).not.toHaveBeenCalled();
+  });
+
+  it("lets Backspace pass through when no category is active", () => {
+    const { sub, props } = render({
+      activeCategoryId: null,
+      query: "",
+    });
+    const e = makeKeyEvent("Backspace");
+
+    const consumed = sub.getValue().handleKeyDown(e);
+
+    expect(consumed).toBe(false);
+    expect(props.goBack).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,150 @@
+import { useEffectEvent, useState } from "@ulearning/ai-tap";
+import { resource } from "@ulearning/ai-tap";
+import type {
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+
+/** Relies on `Unstable_TriggerCategory` never carrying a `type` field. */
+function isTriggerItem(
+  x: Unstable_TriggerItem | Unstable_TriggerCategory,
+): x is Unstable_TriggerItem {
+  return "type" in x;
+}
+
+/** Key event shape accepted by the keyboard handler. */
+export type TriggerPopoverKeyEvent = {
+  readonly key: string;
+  readonly shiftKey: boolean;
+  preventDefault(): void;
+};
+
+export type TriggerKeyboardResourceOutput = {
+  /** Index of the currently highlighted entry within the navigable list. */
+  readonly highlightedIndex: number;
+  /** ID of the currently highlighted item (for `aria-activedescendant`). */
+  readonly highlightedItemId: string | undefined;
+  /** Move the highlight to an entry index (e.g. from pointer hover). Out-of-range values are ignored. */
+  highlightIndex(index: number): void;
+  /** Handle a key event; returns `true` if it was consumed. */
+  handleKeyDown(e: TriggerPopoverKeyEvent): boolean;
+};
+
+/**
+ * Owns keyboard-driven highlight state for the popover. Delegates selection,
+ * category drill-in, back, and close to the callbacks supplied by the parent.
+ */
+const useTriggerKeyboardResource = ({
+  navigableList,
+  isSearchMode,
+  activeCategoryId,
+  query,
+  popoverId,
+  open,
+  selectItem,
+  selectCategory,
+  goBack,
+  close,
+}: {
+  navigableList: readonly (Unstable_TriggerCategory | Unstable_TriggerItem)[];
+  isSearchMode: boolean;
+  activeCategoryId: string | null;
+  query: string;
+  popoverId: string;
+  open: boolean;
+  selectItem: (item: Unstable_TriggerItem) => void;
+  selectCategory: (categoryId: string) => void;
+  goBack: () => void;
+  close: () => void;
+}): TriggerKeyboardResourceOutput => {
+  const [highlightedIndex, setHighlightedIndex] = useState(0);
+  const [highlightScope, setHighlightScope] = useState({
+    navigableList,
+    isSearchMode,
+    activeCategoryId,
+  });
+
+  if (
+    highlightScope.navigableList !== navigableList ||
+    highlightScope.isSearchMode !== isSearchMode ||
+    highlightScope.activeCategoryId !== activeCategoryId
+  ) {
+    setHighlightScope({ navigableList, isSearchMode, activeCategoryId });
+    setHighlightedIndex(0);
+  }
+
+  const highlightIndex = useEffectEvent((index: number) => {
+    if (index < 0 || index >= navigableList.length) return;
+    if (index === highlightedIndex) return;
+    setHighlightedIndex(index);
+  });
+
+  const handleKeyDown = useEffectEvent((e: TriggerPopoverKeyEvent): boolean => {
+    if (!open) return false;
+
+    switch (e.key) {
+      case "ArrowDown": {
+        e.preventDefault();
+        setHighlightedIndex((prev) => {
+          const len = navigableList.length;
+          if (len === 0) return 0;
+          return prev < len - 1 ? prev + 1 : 0;
+        });
+        return true;
+      }
+      case "ArrowUp": {
+        e.preventDefault();
+        setHighlightedIndex((prev) => {
+          const len = navigableList.length;
+          if (len === 0) return 0;
+          return prev > 0 ? prev - 1 : len - 1;
+        });
+        return true;
+      }
+      case "Enter":
+      case "Tab": {
+        if (e.shiftKey) return false;
+        e.preventDefault();
+        const item = navigableList[highlightedIndex];
+        if (!item) return true;
+
+        if (isTriggerItem(item)) {
+          selectItem(item);
+        } else {
+          selectCategory(item.id);
+        }
+        return true;
+      }
+      case "Escape": {
+        e.preventDefault();
+        close();
+        return true;
+      }
+      case "Backspace": {
+        if (activeCategoryId && query === "") {
+          e.preventDefault();
+          goBack();
+          return true;
+        }
+        return false;
+      }
+      default:
+        return false;
+    }
+  });
+
+  const highlightedEntry = navigableList[highlightedIndex];
+  const highlightedItemId =
+    open && highlightedEntry
+      ? `${popoverId}-option-${highlightedEntry.id}`
+      : undefined;
+
+  return {
+    highlightedIndex,
+    highlightedItemId,
+    highlightIndex,
+    handleKeyDown,
+  };
+};
+
+export const TriggerKeyboardResource = resource(useTriggerKeyboardResource);

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

@@ -0,0 +1,129 @@
+import { useEffectEvent, useMemo, useState } from "@ulearning/ai-tap";
+import { resource } from "@ulearning/ai-tap";
+import type {
+  Unstable_TriggerAdapter,
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+import { matchesTriggerItemQuery } from "./matchesTriggerItemQuery";
+
+export type TriggerNavigationResourceOutput = {
+  /** Filtered categories visible in the list (empty in search mode). */
+  readonly categories: readonly Unstable_TriggerCategory[];
+  /** Filtered items visible in the list. */
+  readonly items: readonly Unstable_TriggerItem[];
+  /** `true` when the current list is search results rather than categories. */
+  readonly isSearchMode: boolean;
+  /** Currently drilled-into category id (or `null` for the top level). */
+  readonly activeCategoryId: string | null;
+  /** Flat list used for keyboard navigation (categories or items). */
+  readonly navigableList: readonly (
+    | Unstable_TriggerCategory
+    | Unstable_TriggerItem
+  )[];
+  /** Drill into a category. */
+  selectCategory(categoryId: string): void;
+  /** Return to the top-level category list. */
+  goBack(): void;
+};
+
+/**
+ * Computes categories, items, search results, and navigation state from the
+ * adapter + current query. Pure derivation — no side effects on the composer.
+ */
+const useTriggerNavigationResource = ({
+  adapter,
+  query,
+  open,
+}: {
+  adapter: Unstable_TriggerAdapter | undefined;
+  query: string;
+  open: boolean;
+}): TriggerNavigationResourceOutput => {
+  const [activeCategoryId, setActiveCategoryId] = useState<string | null>(null);
+  const [wasOpen, setWasOpen] = useState(open);
+
+  if (wasOpen !== open) {
+    setWasOpen(open);
+    if (!open) setActiveCategoryId(null);
+  }
+
+  const categories = useMemo<readonly Unstable_TriggerCategory[]>(() => {
+    if (!open || !adapter) return [];
+    return adapter.categories();
+  }, [open, adapter]);
+
+  const effectiveActiveCategoryId = open ? activeCategoryId : null;
+
+  const allItems = useMemo<readonly Unstable_TriggerItem[]>(() => {
+    if (!effectiveActiveCategoryId || !adapter) return [];
+    return adapter.categoryItems(effectiveActiveCategoryId);
+  }, [effectiveActiveCategoryId, adapter]);
+
+  const searchResults = useMemo<readonly Unstable_TriggerItem[] | null>(() => {
+    if (!open || !adapter || effectiveActiveCategoryId) return null;
+    // If categories exist and query is empty, show categories first (not search)
+    if (!query && categories.length > 0) return null;
+    if (adapter.search) return adapter.search(query);
+
+    // fallback: no adapter.search
+    const all: Unstable_TriggerItem[] = [];
+    const lower = query.toLowerCase();
+    for (const cat of categories) {
+      for (const item of adapter.categoryItems(cat.id)) {
+        if (matchesTriggerItemQuery(item, lower)) {
+          all.push(item);
+        }
+      }
+    }
+    return all;
+  }, [open, adapter, query, effectiveActiveCategoryId, categories]);
+
+  const isSearchMode = searchResults !== null;
+
+  const filteredCategories = useMemo(() => {
+    if (isSearchMode) return [];
+    if (!query) return categories;
+    const lower = query.toLowerCase();
+    return categories.filter((cat) => cat.label.toLowerCase().includes(lower));
+  }, [categories, query, isSearchMode]);
+
+  const filteredItems = useMemo(() => {
+    if (isSearchMode) return searchResults ?? [];
+    if (!query) return allItems;
+    const lower = query.toLowerCase();
+    return allItems.filter((item) => matchesTriggerItemQuery(item, lower));
+  }, [allItems, query, isSearchMode, searchResults]);
+
+  const navigableList = useMemo(() => {
+    if (isSearchMode) return searchResults ?? [];
+    if (effectiveActiveCategoryId) return filteredItems;
+    return filteredCategories;
+  }, [
+    isSearchMode,
+    searchResults,
+    effectiveActiveCategoryId,
+    filteredItems,
+    filteredCategories,
+  ]);
+
+  const selectCategory = useEffectEvent((categoryId: string) => {
+    setActiveCategoryId(categoryId);
+  });
+
+  const goBack = useEffectEvent(() => {
+    setActiveCategoryId(null);
+  });
+
+  return {
+    categories: filteredCategories,
+    items: filteredItems,
+    isSearchMode,
+    activeCategoryId: effectiveActiveCategoryId,
+    navigableList,
+    selectCategory,
+    goBack,
+  };
+};
+
+export const TriggerNavigationResource = resource(useTriggerNavigationResource);