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

package/src/primitives/composer/trigger/TriggerPopoverBehavior.test.tsx

@@ -0,0 +1,113 @@
+// @vitest-environment jsdom
+
+import { defineComponent, h, Suspense, type VNode } from "vue";
+import { cleanup, render } from "../../../tests/vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Unstable_TriggerItem } from "@ulearning/ai-core";
+import type { TriggerBehavior } from "./triggerSelectionResource";
+
+const mocks = vi.hoisted(() => ({ register: vi.fn() }));
+
+vi.mock("./TriggerPopover", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./TriggerPopover")>()),
+  useTriggerBehaviorRegistration: () => ({ register: mocks.register }),
+}));
+
+import { ComposerPrimitiveTriggerPopoverAction } from "./TriggerPopoverAction";
+import { ComposerPrimitiveTriggerPopoverDirective } from "./TriggerPopoverDirective";
+
+const item: Unstable_TriggerItem = {
+  id: "item-1",
+  type: "test",
+  label: "Item",
+};
+
+const verifyCommittedCallback = async (
+  renderBehavior: (callback: (item: Unstable_TriggerItem) => void) => VNode,
+  invoke: (behavior: TriggerBehavior) => void,
+) => {
+  let behavior: TriggerBehavior | undefined;
+  mocks.register.mockImplementation((next: TriggerBehavior) => {
+    behavior = next;
+    return () => {};
+  });
+
+  const gate = Promise.withResolvers<void>();
+  const renderProbe = vi.fn();
+  const Branch = defineComponent<{
+    callback: (item: Unstable_TriggerItem) => void;
+    pending?: boolean;
+  }>(
+    (props) => {
+      renderProbe();
+      return props.pending
+        ? gate.promise.then(() => () => renderBehavior(props.callback))
+        : () => renderBehavior(props.callback);
+    },
+    { props: ["callback", "pending"] },
+  );
+  const View = defineComponent<{
+    callback: (item: Unstable_TriggerItem) => void;
+    pending?: boolean;
+  }>(
+    (props) => () =>
+      h(Suspense, null, {
+        default: () =>
+          h(Branch, {
+            key: props.pending ? "pending" : "committed",
+            callback: props.callback,
+            pending: !!props.pending,
+          }),
+        fallback: () => null,
+      }),
+    { props: ["callback", "pending"] },
+  );
+  const committed = vi.fn();
+  const abandoned = vi.fn();
+  const view = render(h(View, { callback: committed }));
+  await vi.waitFor(() => expect(behavior).toBeDefined());
+  renderProbe.mockClear();
+  await view.rerender(h(View, { callback: abandoned, pending: true }));
+  await vi.waitFor(() => expect(renderProbe).toHaveBeenCalled());
+  invoke(behavior!);
+  expect(committed).toHaveBeenCalledExactlyOnceWith(item);
+  expect(abandoned).not.toHaveBeenCalled();
+  gate.resolve();
+  await vi.waitFor(() => expect(mocks.register).toHaveBeenCalledTimes(2));
+  invoke(behavior!);
+  expect(abandoned).toHaveBeenCalledExactlyOnceWith(item);
+};
+
+afterEach(cleanup);
+
+describe("TriggerPopover behavior callbacks", () => {
+  beforeEach(() => {
+    mocks.register.mockReset();
+  });
+
+  it("keeps the committed action callback during abandoned renders", async () => {
+    await verifyCommittedCallback(
+      (onExecute) => (
+        <ComposerPrimitiveTriggerPopoverAction onExecute={onExecute} />
+      ),
+      (behavior) => {
+        if (behavior.kind !== "action") throw new Error("Expected action");
+        behavior.onExecute(item);
+      },
+    );
+  });
+
+  it("keeps the committed directive callback during abandoned renders", async () => {
+    await verifyCommittedCallback(
+      (onInserted) => (
+        <ComposerPrimitiveTriggerPopoverDirective onInserted={onInserted} />
+      ),
+      (behavior) => {
+        if (behavior.kind !== "directive") {
+          throw new Error("Expected directive");
+        }
+        behavior.onInserted?.(item);
+      },
+    );
+  });
+});

package/src/primitives/composer/trigger/TriggerPopoverCategories.tsx

@@ -0,0 +1,123 @@
+"use client";
+
+import { Primitive, type PrimitiveProps } from "../../../utils/Primitive";
+import {
+  computed,
+  defineComponent,
+  h,
+  mergeProps,
+  type ComponentPublicInstance,
+  type VNodeChild,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { useTriggerPopoverScopeContext } from "./TriggerPopover";
+import type { TriggerCategory } from "@ulearning/ai-core";
+
+export namespace ComposerPrimitiveTriggerPopoverCategories {
+  export type Element = ComponentPublicInstance;
+  export type Props = Omit<PrimitiveProps<"div">, "children"> & {
+    children?: (categories: readonly TriggerCategory[]) => VNodeChild;
+  };
+}
+
+/**
+ * Renders the top-level category list via a render function.
+ * Only renders when no category is active and search mode is off.
+ */
+export const ComposerPrimitiveTriggerPopoverCategories =
+  defineComponent<ComposerPrimitiveTriggerPopoverCategories.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      const state = useTriggerPopoverScopeContext();
+      return () =>
+        !state.value.open ||
+        state.value.activeCategoryId ||
+        state.value.isSearchMode
+          ? null
+          : h(
+              Primitive.div,
+              {
+                role: "group",
+                "aria-label": "Categories",
+                ...attrs,
+                render: props.render,
+                asChild: props.asChild,
+                ref: forwardRef,
+              },
+              {
+                default: () =>
+                  slots.default?.(state.value.categories) ??
+                  props.children?.(state.value.categories),
+              },
+            );
+    },
+    {
+      name: "ComposerPrimitiveTriggerPopoverCategories",
+      inheritAttrs: false,
+      props: ["render", "asChild", "children"],
+    },
+  );
+
+export namespace ComposerPrimitiveTriggerPopoverCategoryItem {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"button"> & {
+    categoryId: string;
+  };
+}
+
+/**
+ * A button that selects a category and triggers drill-down navigation.
+ * Automatically receives `data-highlighted` when keyboard-navigated.
+ */
+export const ComposerPrimitiveTriggerPopoverCategoryItem =
+  defineComponent<ComposerPrimitiveTriggerPopoverCategoryItem.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      const state = useTriggerPopoverScopeContext();
+      const index = computed(() =>
+        state.value.categories.findIndex(
+          (category) => category.id === props.categoryId,
+        ),
+      );
+      const highlighted = computed(
+        () =>
+          !state.value.activeCategoryId &&
+          !state.value.isSearchMode &&
+          index.value === state.value.highlightedIndex,
+      );
+      return () =>
+        h(
+          Primitive.button,
+          mergeProps(
+            {
+              type: "button",
+              role: "option",
+              id: `${state.value.popoverId}-option-${props.categoryId}`,
+              "aria-selected": highlighted.value,
+              "data-highlighted": highlighted.value ? "" : undefined,
+            },
+            attrs,
+            {
+              render: props.render,
+              asChild: props.asChild,
+              children: props.children,
+              ref: forwardRef,
+              onClick: (event: MouseEvent) => {
+                if (!event.defaultPrevented)
+                  state.value.selectCategory(props.categoryId);
+              },
+              onMousemove: (event: MouseEvent) => {
+                if (!event.defaultPrevented)
+                  state.value.highlightIndex(index.value);
+              },
+            },
+          ),
+          slots,
+        );
+    },
+    {
+      name: "ComposerPrimitiveTriggerPopoverCategoryItem",
+      inheritAttrs: false,
+      props: ["render", "asChild", "children", "categoryId"],
+    },
+  );

package/src/primitives/composer/trigger/TriggerPopoverDirective.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import type { DirectiveFormatter, TriggerItem } from "@ulearning/ai-core";
+import { defaultDirectiveFormatter } from "@ulearning/ai-core";
+import { defineComponent } from "vue";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { useTriggerBehaviorRegistration } from "./TriggerPopover";
+import type { TriggerBehavior } from "./triggerSelectionResource";
+
+export namespace ComposerPrimitiveTriggerPopoverDirective {
+  export type Props = {
+    /** Defaults to `defaultDirectiveFormatter`. */
+    readonly formatter?: DirectiveFormatter | undefined;
+    /** Fires after an item has been inserted into the composer. */
+    readonly onInserted?: ((item: TriggerItem) => void) | undefined;
+  };
+}
+
+/**
+ * Configures a `<TriggerPopover>` to insert a directive chip when an item is
+ * selected. Render exactly one behavior sub-primitive per `<TriggerPopover>`.
+ *
+ * Exposed as `ComposerPrimitive.TriggerPopover.Directive`.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.TriggerPopover char="@" adapter={mentionAdapter}>
+ *   <ComposerPrimitive.TriggerPopover.Directive
+ *     formatter={defaultDirectiveFormatter}
+ *     onInserted={(item) => track("mention", item.id)}
+ *   />
+ * </ComposerPrimitive.TriggerPopover>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopoverDirective =
+  defineComponent<ComposerPrimitiveTriggerPopoverDirective.Props>(
+    (props) => {
+      const { register } = useTriggerBehaviorRegistration();
+      useIsomorphicLayoutEffect(() => {
+        const behavior: TriggerBehavior = {
+          kind: "directive",
+          get formatter() {
+            return props.formatter ?? defaultDirectiveFormatter;
+          },
+          onInserted: (item) => props.onInserted?.(item),
+        };
+        return register(behavior);
+      }, []);
+      return () => null;
+    },
+    {
+      name: "ComposerPrimitiveTriggerPopoverDirective",
+      props: ["formatter", "onInserted"],
+    },
+  );

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

@@ -0,0 +1,61 @@
+import { describe, expect, expectTypeOf, it } from "vitest";
+import * as ComposerPrimitive from "../../composer";
+import {
+  defaultDirectiveFormatter,
+  unstable_defaultDirectiveFormatter,
+  type DirectiveFormatter,
+  type TriggerAdapter,
+  type TriggerCategory,
+  type TriggerItem,
+  type Unstable_DirectiveFormatter,
+  type Unstable_TriggerBehavior,
+  type Unstable_TriggerItem,
+} from "../../../index";
+import type { TriggerBehavior } from "./triggerSelectionResource";
+
+describe("stable trigger popover exports", () => {
+  it("keeps every old composer member as an alias of its stable member", () => {
+    expect(ComposerPrimitive.Unstable_TriggerPopover).toBe(
+      ComposerPrimitive.TriggerPopover,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopover.Directive).toBe(
+      ComposerPrimitive.TriggerPopover.Directive,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopover.Action).toBe(
+      ComposerPrimitive.TriggerPopover.Action,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopoverRoot).toBe(
+      ComposerPrimitive.TriggerPopoverRoot,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopoverCategories).toBe(
+      ComposerPrimitive.TriggerPopoverCategories,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopoverCategoryItem).toBe(
+      ComposerPrimitive.TriggerPopoverCategoryItem,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopoverItems).toBe(
+      ComposerPrimitive.TriggerPopoverItems,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopoverItem).toBe(
+      ComposerPrimitive.TriggerPopoverItem,
+    );
+    expect(ComposerPrimitive.Unstable_TriggerPopoverBack).toBe(
+      ComposerPrimitive.TriggerPopoverBack,
+    );
+  });
+
+  it("keeps the old members' namespaced prop types", () => {
+    expectTypeOf<ComposerPrimitive.Unstable_TriggerPopoverItem.Props>().toEqualTypeOf<ComposerPrimitive.TriggerPopoverItem.Props>();
+    expectTypeOf<ComposerPrimitive.Unstable_TriggerPopoverBack.Element>().toEqualTypeOf<ComposerPrimitive.TriggerPopoverBack.Element>();
+  });
+
+  it("exports the stable adapter, item, category and formatter names beside the old ones", () => {
+    expect(unstable_defaultDirectiveFormatter).toBe(defaultDirectiveFormatter);
+    expectTypeOf<Unstable_TriggerItem>().toEqualTypeOf<TriggerItem>();
+    expectTypeOf<Unstable_DirectiveFormatter>().toEqualTypeOf<DirectiveFormatter>();
+    expectTypeOf<TriggerAdapter["categories"]>().returns.toEqualTypeOf<
+      readonly TriggerCategory[]
+    >();
+    expectTypeOf<Unstable_TriggerBehavior>().toEqualTypeOf<TriggerBehavior>();
+  });
+});

package/src/primitives/composer/trigger/TriggerPopoverItems.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import { Primitive, type PrimitiveProps } from "../../../utils/Primitive";
+import {
+  computed,
+  defineComponent,
+  h,
+  mergeProps,
+  type ComponentPublicInstance,
+  type VNodeChild,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { useTriggerPopoverScopeContext } from "./TriggerPopover";
+import type { TriggerItem } from "@ulearning/ai-core";
+
+export namespace ComposerPrimitiveTriggerPopoverItems {
+  export type Element = ComponentPublicInstance;
+  export type Props = Omit<PrimitiveProps<"div">, "children"> & {
+    children?: (items: readonly TriggerItem[]) => VNodeChild;
+  };
+}
+
+/**
+ * Renders the list of items within a category or search results via a render function.
+ * Only renders when a category is active or search mode is on.
+ */
+export const ComposerPrimitiveTriggerPopoverItems =
+  defineComponent<ComposerPrimitiveTriggerPopoverItems.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      const state = useTriggerPopoverScopeContext();
+      return () =>
+        !state.value.open ||
+        (!state.value.activeCategoryId && !state.value.isSearchMode)
+          ? null
+          : h(
+              Primitive.div,
+              {
+                role: "group",
+                "aria-label": "Items",
+                ...attrs,
+                render: props.render,
+                asChild: props.asChild,
+                ref: forwardRef,
+              },
+              {
+                default: () =>
+                  slots.default?.(state.value.items) ??
+                  props.children?.(state.value.items),
+              },
+            );
+    },
+    {
+      name: "ComposerPrimitiveTriggerPopoverItems",
+      inheritAttrs: false,
+      props: ["render", "asChild", "children"],
+    },
+  );
+
+export namespace ComposerPrimitiveTriggerPopoverItem {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"button"> & {
+    item: TriggerItem;
+    index?: number | undefined;
+  };
+}
+
+/**
+ * A button that selects a trigger item.
+ * Automatically receives `data-highlighted` when keyboard-navigated.
+ */
+export const ComposerPrimitiveTriggerPopoverItem =
+  defineComponent<ComposerPrimitiveTriggerPopoverItem.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      const state = useTriggerPopoverScopeContext();
+      const index = computed(
+        () =>
+          props.index ??
+          state.value.items.findIndex((item) => item.id === props.item.id),
+      );
+      const highlighted = computed(
+        () =>
+          (state.value.isSearchMode || state.value.activeCategoryId !== null) &&
+          index.value === state.value.highlightedIndex,
+      );
+      return () =>
+        h(
+          Primitive.button,
+          mergeProps(
+            {
+              type: "button",
+              role: "option",
+              id: `${state.value.popoverId}-option-${props.item.id}`,
+              "aria-selected": highlighted.value,
+              "data-highlighted": highlighted.value ? "" : undefined,
+            },
+            attrs,
+            {
+              render: props.render,
+              asChild: props.asChild,
+              children: props.children,
+              ref: forwardRef,
+              onClick: (event: MouseEvent) => {
+                if (!event.defaultPrevented) state.value.selectItem(props.item);
+              },
+              onMousemove: (event: MouseEvent) => {
+                if (!event.defaultPrevented)
+                  state.value.highlightIndex(index.value);
+              },
+            },
+          ),
+          slots,
+        );
+    },
+    {
+      name: "ComposerPrimitiveTriggerPopoverItem",
+      inheritAttrs: false,
+      props: ["render", "asChild", "children", "item", "index"],
+    },
+  );

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

@@ -0,0 +1,146 @@
+import { useEffectEvent } from "@ulearning/ai-tap";
+import { useResource, resource } from "@ulearning/ai-tap";
+import type {
+  Unstable_TriggerAdapter,
+  Unstable_TriggerCategory,
+  Unstable_TriggerItem,
+} from "@ulearning/ai-core";
+import type { AssistantClient } from "@ulearning/ai-store";
+import { TriggerDetectionResource } from "./triggerDetectionResource";
+import { TriggerKeyboardResource } from "./triggerKeyboardResource";
+import { TriggerNavigationResource } from "./triggerNavigationResource";
+import {
+  TriggerSelectionResource,
+  type SelectItemOverride,
+  type TriggerBehavior,
+} from "./triggerSelectionResource";
+import type { TriggerMatcher } from "./detectTrigger";
+
+export type { SelectItemOverride, TriggerBehavior };
+export type { TriggerPopoverKeyEvent } from "./triggerKeyboardResource";
+
+/** @deprecated Use `TriggerBehavior`. */
+export type OnSelectBehavior = TriggerBehavior;
+
+export type TriggerPopoverResourceOutput = {
+  readonly open: boolean;
+  readonly query: string;
+  readonly activeCategoryId: string | null;
+  readonly categories: readonly Unstable_TriggerCategory[];
+  readonly items: readonly Unstable_TriggerItem[];
+  readonly highlightedIndex: number;
+  readonly isSearchMode: boolean;
+  /** Whether the adapter is currently resolving items (async sources). */
+  readonly isLoading: boolean;
+  /** Stable ID prefix for generating accessible element IDs. */
+  readonly popoverId: string;
+  /** ID of the currently highlighted item (for aria-activedescendant). */
+  readonly highlightedItemId: string | undefined;
+
+  selectCategory(categoryId: string): void;
+  goBack(): void;
+  selectItem(item: Unstable_TriggerItem): void;
+  close(): void;
+  /** Move the highlight to an entry index (e.g. from pointer hover). Out-of-range values are ignored. */
+  highlightIndex(index: number): void;
+  handleKeyDown(e: {
+    readonly key: string;
+    readonly shiftKey: boolean;
+    preventDefault(): void;
+  }): boolean;
+
+  setCursorPosition(pos: number): void;
+  registerSelectItemOverride(fn: SelectItemOverride): () => void;
+};
+
+/** Composes detection, navigation, keyboard, and selection sub-resources. */
+const useTriggerPopoverResource = ({
+  adapter,
+  text,
+  triggerChar,
+  matcher,
+  behavior,
+  aui,
+  popoverId,
+  isLoading,
+}: {
+  adapter: Unstable_TriggerAdapter | undefined;
+  text: string;
+  triggerChar: string;
+  matcher: TriggerMatcher | undefined;
+  behavior: TriggerBehavior | undefined;
+  aui: AssistantClient;
+  /** Stable ID for accessible element IDs (pass React's useId() from component layer). */
+  popoverId: string;
+  isLoading: boolean;
+}): TriggerPopoverResourceOutput => {
+  const detection = useResource(
+    TriggerDetectionResource({ text, triggerChar, matcher }),
+  );
+
+  const open =
+    detection.trigger !== null &&
+    adapter !== undefined &&
+    behavior !== undefined;
+
+  const navigation = useResource(
+    TriggerNavigationResource({
+      adapter,
+      query: detection.query,
+      open,
+    }),
+  );
+
+  const onSelected = useEffectEvent(() => {
+    navigation.goBack();
+  });
+
+  const selection = useResource(
+    TriggerSelectionResource({
+      behavior,
+      trigger: detection.trigger,
+      aui,
+      triggerChar,
+      setCursorPosition: detection.setCursorPosition,
+      onSelected,
+    }),
+  );
+
+  const keyboard = useResource(
+    TriggerKeyboardResource({
+      navigableList: navigation.navigableList,
+      isSearchMode: navigation.isSearchMode,
+      activeCategoryId: navigation.activeCategoryId,
+      query: detection.query,
+      popoverId,
+      open,
+      selectItem: selection.selectItem,
+      selectCategory: navigation.selectCategory,
+      goBack: navigation.goBack,
+      close: selection.close,
+    }),
+  );
+
+  return {
+    open,
+    query: detection.query,
+    activeCategoryId: navigation.activeCategoryId,
+    categories: navigation.categories,
+    items: navigation.items,
+    highlightedIndex: keyboard.highlightedIndex,
+    isSearchMode: navigation.isSearchMode,
+    isLoading,
+    popoverId,
+    highlightedItemId: keyboard.highlightedItemId,
+    selectCategory: navigation.selectCategory,
+    goBack: navigation.goBack,
+    selectItem: selection.selectItem,
+    close: selection.close,
+    highlightIndex: keyboard.highlightIndex,
+    handleKeyDown: keyboard.handleKeyDown,
+    setCursorPosition: detection.setCursorPosition,
+    registerSelectItemOverride: selection.registerSelectItemOverride,
+  };
+};
+
+export const TriggerPopoverResource = resource(useTriggerPopoverResource);