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

package/src/primitives/composer/trigger/TriggerPopover.native.test.ts

@@ -0,0 +1,309 @@
+// @vitest-environment jsdom
+import {
+  defineComponent,
+  h,
+  KeepAlive,
+  nextTick,
+  shallowRef,
+  type ComponentPublicInstance,
+} from "vue";
+import { afterEach, expect, it, vi } from "vitest";
+import { flushTapSync } from "@ulearning/ai-tap";
+import { useAui } from "@ulearning/ai-store";
+import {
+  AssistantRuntimeProvider,
+  useExternalStoreRuntime,
+} from "@ulearning/ai-core/vue";
+import type {
+  ThreadMessage,
+  TriggerAdapter,
+  TriggerItem,
+} from "@ulearning/ai-core";
+import { cleanup, render } from "../../../tests/vue";
+import { ComposerPrimitiveInput } from "../ComposerInput";
+import { ComposerPrimitiveRoot } from "../ComposerRoot";
+import {
+  ComposerPrimitiveTriggerPopoverRoot,
+  useTriggerPopoverRootContext,
+} from "./TriggerPopoverRootContext";
+import { ComposerPrimitiveTriggerPopover } from "./TriggerPopover";
+import { ComposerPrimitiveTriggerPopoverDirective } from "./TriggerPopoverDirective";
+import { ComposerPrimitiveTriggerPopoverAction } from "./TriggerPopoverAction";
+import {
+  ComposerPrimitiveTriggerPopoverCategories,
+  ComposerPrimitiveTriggerPopoverCategoryItem,
+} from "./TriggerPopoverCategories";
+import {
+  ComposerPrimitiveTriggerPopoverItems,
+  ComposerPrimitiveTriggerPopoverItem,
+} from "./TriggerPopoverItems";
+import { ComposerPrimitiveTriggerPopoverBack } from "./TriggerPopoverBack";
+
+afterEach(cleanup);
+const items: TriggerItem[] = [
+  { id: "alpha", type: "file", label: "Alpha" },
+  { id: "beta", type: "file", label: "Beta" },
+];
+const adapter: TriggerAdapter = {
+  categories: () => [{ id: "files", label: "Files" }],
+  categoryItems: () => items,
+};
+
+async function mountTrigger(
+  action = false,
+  mode: "default" | "asChild" | "render" = "default",
+) {
+  const shown = shallowRef(true);
+  const active = shallowRef(true);
+  const popoverRef = shallowRef<ComponentPublicInstance | null>(null);
+  const callback = shallowRef(vi.fn());
+  let aui!: ReturnType<typeof useAui>;
+  let registry!: ReturnType<typeof useTriggerPopoverRootContext>;
+  const Content = defineComponent({
+    setup() {
+      aui = useAui();
+      registry = useTriggerPopoverRootContext();
+      return () => [
+        shown.value
+          ? h(
+              ComposerPrimitiveTriggerPopover,
+              {
+                char: "@",
+                adapter,
+                ref: popoverRef,
+                ...(mode === "asChild" ? { asChild: true } : {}),
+                ...(mode === "render"
+                  ? { render: h("section", { "data-custom": "render" }) }
+                  : {}),
+              },
+              {
+                default: () => {
+                  const content = [
+                    action
+                      ? h(ComposerPrimitiveTriggerPopoverAction, {
+                          onExecute: callback.value,
+                          removeOnExecute: true,
+                        })
+                      : h(ComposerPrimitiveTriggerPopoverDirective, {
+                          formatter: {
+                            serialize: (item) => `@${item.label}`,
+                            parse: () => [],
+                          },
+                          onInserted: callback.value,
+                        }),
+                    h(ComposerPrimitiveTriggerPopoverCategories, null, {
+                      default: (
+                        categories: ReturnType<TriggerAdapter["categories"]>,
+                      ) =>
+                        categories.map((category) =>
+                          h(
+                            ComposerPrimitiveTriggerPopoverCategoryItem,
+                            { categoryId: category.id },
+                            () => category.label,
+                          ),
+                        ),
+                    }),
+                    h(ComposerPrimitiveTriggerPopoverItems, null, {
+                      default: (entries: readonly TriggerItem[]) =>
+                        entries.map((item) =>
+                          h(
+                            ComposerPrimitiveTriggerPopoverItem,
+                            { item },
+                            () => item.label,
+                          ),
+                        ),
+                    }),
+                    h(ComposerPrimitiveTriggerPopoverBack, null, () => "Back"),
+                  ];
+                  return mode === "asChild"
+                    ? h("section", { "data-custom": "asChild" }, content)
+                    : content;
+                },
+              },
+            )
+          : null,
+        h(ComposerPrimitiveRoot, null, {
+          default: () =>
+            h(ComposerPrimitiveInput, { "aria-label": "Composer" }),
+        }),
+      ];
+    },
+  });
+  const view = render(
+    h(
+      defineComponent({
+        setup() {
+          const runtime = useExternalStoreRuntime<ThreadMessage>({
+            messages: [],
+            onNew: async () => {},
+          });
+          return () =>
+            h(
+              AssistantRuntimeProvider,
+              { runtime },
+              {
+                default: () =>
+                  h(ComposerPrimitiveTriggerPopoverRoot, null, {
+                    default: () =>
+                      h(KeepAlive, null, {
+                        default: () => (active.value ? h(Content) : null),
+                      }),
+                  }),
+              },
+            );
+        },
+      }),
+    ),
+  );
+  await nextTick();
+  const input = view.container.querySelector("textarea")!;
+  const type = async (text: string) => {
+    flushTapSync(() => {
+      input.value = text;
+      input.setSelectionRange(text.length, text.length);
+      input.dispatchEvent(new InputEvent("input", { bubbles: true }));
+    });
+    await nextTick();
+  };
+  const key = async (key: string) => {
+    const event = new KeyboardEvent("keydown", {
+      key,
+      bubbles: true,
+      cancelable: true,
+    });
+    flushTapSync(() => input.dispatchEvent(event));
+    await nextTick();
+    return event;
+  };
+  return {
+    ...view,
+    shown,
+    active,
+    popoverRef,
+    callback,
+    input,
+    type,
+    key,
+    get aui() {
+      return aui;
+    },
+    get registry() {
+      return registry;
+    },
+  };
+}
+
+it("navigates real categories and items, publishes ARIA, and inserts the selected directive", async () => {
+  const view = await mountTrigger();
+  await view.type("@");
+  await vi.waitFor(() =>
+    expect(view.input.getAttribute("aria-expanded")).toBe("true"),
+  );
+  const popover = view.container.querySelector('[role="listbox"]')!;
+  expect(view.input.getAttribute("aria-controls")).toBe(popover.id);
+  expect(view.registry.getTriggers().size).toBe(1);
+  expect(view.registry.getTriggers().get("@")!.resource.open).toBe(true);
+  expect((await view.key("Enter")).defaultPrevented).toBe(true);
+  await vi.waitFor(() =>
+    expect(view.container.querySelectorAll('[role="option"]')).toHaveLength(2),
+  );
+  await view.key("ArrowDown");
+  await vi.waitFor(() =>
+    expect(view.input.getAttribute("aria-activedescendant")).toBe(
+      `${popover.id}-option-beta`,
+    ),
+  );
+  expect((await view.key("Tab")).defaultPrevented).toBe(true);
+  await vi.waitFor(() => expect(view.input.value).toBe("@Beta "));
+  expect(view.callback.value).toHaveBeenCalledExactlyOnceWith(items[1]);
+  expect(view.aui.composer.getState().text).toBe("@Beta ");
+  await vi.waitFor(() =>
+    expect(view.input.hasAttribute("aria-expanded")).toBe(false),
+  );
+});
+
+it.each(["asChild", "render"] as const)(
+  "preserves the %s host ref and behavior across opening and closing",
+  async (mode) => {
+    const view = await mountTrigger(true, mode);
+    await view.type("@Beta");
+    await vi.waitFor(() =>
+      expect(view.input.getAttribute("aria-expanded")).toBe("true"),
+    );
+    const host = view.container.querySelector('[role="listbox"]')!;
+    expect(host.tagName).toBe("SECTION");
+    expect(host.getAttribute("data-custom")).toBe(mode);
+    expect(view.popoverRef.value?.$el).toBe(host);
+    const behavior = view.registry.getTriggers().get("@")!.behavior;
+    await view.key("Enter");
+    await vi.waitFor(() => expect(view.input.value).toBe(""));
+    expect(view.container.querySelector('[role="listbox"]')).toBeNull();
+    expect(view.registry.getTriggers().get("@")!.behavior).toBe(behavior);
+    await view.type("@Beta");
+    await vi.waitFor(() =>
+      expect(view.input.getAttribute("aria-expanded")).toBe("true"),
+    );
+    expect(view.registry.getTriggers().get("@")!.behavior).toBe(behavior);
+    await view.key("Enter");
+    expect(view.callback.value).toHaveBeenCalledTimes(2);
+  },
+);
+
+it("releases plugins and ARIA on KeepAlive deactivation and restores a single registration", async () => {
+  const view = await mountTrigger(true);
+  await view.type("@Beta");
+  await vi.waitFor(() => expect(view.registry.getActiveAria()).not.toBeNull());
+  await vi.waitFor(() =>
+    expect(view.input.getAttribute("aria-expanded")).toBe("true"),
+  );
+  const controls = view.input.getAttribute("aria-controls");
+  expect(controls).not.toBeNull();
+  view.active.value = false;
+  await nextTick();
+  await vi.waitFor(() => expect(view.registry.getTriggers().size).toBe(0));
+  expect(view.registry.getActiveAria()).toBeNull();
+  for (const attribute of [
+    "aria-expanded",
+    "aria-controls",
+    "aria-haspopup",
+    "aria-activedescendant",
+  ])
+    expect(view.input.hasAttribute(attribute), attribute).toBe(false);
+  view.active.value = true;
+  await nextTick();
+  await vi.waitFor(() => expect(view.registry.getTriggers().size).toBe(1));
+  expect(view.container.querySelector("textarea")).toBe(view.input);
+  await vi.waitFor(() =>
+    expect(view.input.getAttribute("aria-expanded")).toBe("true"),
+  );
+  expect(view.input.getAttribute("aria-controls")).toBe(controls);
+  await view.type("@Beta");
+  await vi.waitFor(() =>
+    expect(view.input.getAttribute("aria-expanded")).toBe("true"),
+  );
+  await view.key("Enter");
+  expect(view.callback.value).toHaveBeenCalledExactlyOnceWith(items[1]);
+});
+
+it("uses a changed action callback, removes trigger text, and releases registrations when removed", async () => {
+  const view = await mountTrigger(true);
+  const original = view.callback.value;
+  const latest = vi.fn();
+  view.callback.value = latest;
+  await nextTick();
+  await view.type("@Beta");
+  await vi.waitFor(() =>
+    expect(view.container.querySelectorAll('[role="option"]')).toHaveLength(1),
+  );
+  await view.key("Enter");
+  await vi.waitFor(() => expect(view.input.value).toBe(""));
+  expect(latest).toHaveBeenCalledExactlyOnceWith(items[1]);
+  expect(original).not.toHaveBeenCalled();
+  view.shown.value = false;
+  await nextTick();
+  expect(view.registry.getTriggers().size).toBe(0);
+  await view.type("@Beta");
+  expect(view.input.hasAttribute("aria-expanded")).toBe(false);
+  await view.key("Enter");
+  expect(latest).toHaveBeenCalledTimes(1);
+});

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

@@ -0,0 +1,248 @@
+"use client";
+
+import { useAui, useAuiState } from "@ulearning/ai-store";
+import { useResource, useTapRoot } from "@ulearning/ai-tap";
+import type { TriggerAdapter } from "@ulearning/ai-core";
+import {
+  computed,
+  defineComponent,
+  h,
+  inject,
+  provide,
+  shallowRef,
+  Teleport,
+  useId,
+  type ComponentPublicInstance,
+  type InjectionKey,
+  type ShallowRef,
+  type VNodeProps,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { useIsomorphicLayoutEffect } from "@ulearning/ai-store/internal";
+import { Primitive, type PrimitiveProps } from "../../../utils/Primitive";
+import { useComposerInputPluginRegistryOptional } from "../ComposerInputPluginContext";
+import {
+  TriggerPopoverResource,
+  type TriggerPopoverResourceOutput,
+} from "./TriggerPopoverResource";
+import type { TriggerBehavior } from "./triggerSelectionResource";
+import {
+  useTriggerPopoverAriaPublish,
+  useTriggerPopoverRootContext,
+} from "./TriggerPopoverRootContext";
+import type { TriggerMatcher } from "./detectTrigger";
+
+const TriggerPopoverScopeContext: InjectionKey<
+  Readonly<ShallowRef<TriggerPopoverResourceOutput>>
+> = Symbol("TriggerPopoverScope");
+export const useTriggerPopoverScopeContextOptional = () =>
+  inject(TriggerPopoverScopeContext, null);
+export const useTriggerPopoverScopeContext = () => {
+  const ctx = useTriggerPopoverScopeContextOptional();
+  if (!ctx)
+    throw new Error(
+      "useTriggerPopoverScopeContext must be used within ComposerPrimitive.TriggerPopover",
+    );
+  return ctx;
+};
+export type TriggerBehaviorRegistration = {
+  register(behavior: TriggerBehavior): () => void;
+};
+const TriggerBehaviorRegistrationContext: InjectionKey<TriggerBehaviorRegistration> =
+  Symbol("TriggerBehaviorRegistration");
+export const useTriggerBehaviorRegistration = () => {
+  const ctx = inject(TriggerBehaviorRegistrationContext, null);
+  if (!ctx)
+    throw new Error(
+      "TriggerPopover.Directive / TriggerPopover.Action must be rendered inside ComposerPrimitive.TriggerPopover",
+    );
+  return ctx;
+};
+
+export namespace ComposerPrimitiveTriggerPopover {
+  export type Element = ComponentPublicInstance;
+  export type Props = Omit<PrimitiveProps<"div">, "onSelect"> & {
+    /** The character(s) that activate this trigger (e.g. `"@"`, `"/"`). Also serves as the trigger identity within the root. */
+    readonly char: string;
+    /** Overrides trigger detection for both textarea and Lexical inputs. `endOffset` is the exclusive replace bound. */
+    readonly matcher?: TriggerMatcher | undefined;
+    /** Adapter providing categories and items. */
+    readonly adapter?: TriggerAdapter | undefined;
+    /** Whether the adapter is resolving items, surfaced to the popover scope for async sources. @default false */
+    readonly isLoading?: boolean | undefined;
+  };
+}
+
+/**
+ * Declares a trigger and renders its popover container. The popover only
+ * renders its DOM (and children) when the trigger character is active in the
+ * composer input and a behavior sub-primitive has been registered.
+ *
+ * A behavior is contributed by rendering exactly one of
+ * `<TriggerPopover.Directive>` or `<TriggerPopover.Action>` as a child. Without
+ * a behavior the trigger stays closed.
+ *
+ * Must be placed inside `ComposerPrimitive.TriggerPopoverRoot`.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.TriggerPopover
+ *   char="@"
+ *   adapter={mentionAdapter}
+ * >
+ *   <ComposerPrimitive.TriggerPopover.Directive formatter={formatter} />
+ *   <ComposerPrimitive.TriggerPopoverCategories>
+ *     {(cats) => cats.map(...)}
+ *   </ComposerPrimitive.TriggerPopoverCategories>
+ *   <ComposerPrimitive.TriggerPopoverItems>
+ *     {(items) => items.map(...)}
+ *   </ComposerPrimitive.TriggerPopoverItems>
+ * </ComposerPrimitive.TriggerPopover>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopover =
+  defineComponent<ComposerPrimitiveTriggerPopover.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef, currentElement } = useForwardExpose();
+      const aui = useAui();
+      const text = useAuiState((s) => s.composer.text);
+      const popoverId = useId();
+      if (popoverId === undefined)
+        throw new Error(
+          "ComposerPrimitive.TriggerPopover requires a Vue component owner.",
+        );
+      const behavior = shallowRef<TriggerBehavior | null>(null);
+      let registrationCount = 0;
+      const registration: TriggerBehaviorRegistration = {
+        register(next) {
+          registrationCount++;
+          if (process.env.NODE_ENV !== "production" && registrationCount > 1)
+            console.warn(
+              `[assistant-ui] TriggerPopover "${props.char}" received more than one behavior child. Exactly one <TriggerPopover.Directive> or <TriggerPopover.Action> is allowed per TriggerPopover; the last registration wins.`,
+            );
+          behavior.value = next;
+          let active = true;
+          return () => {
+            if (!active) return;
+            active = false;
+            registrationCount--;
+            if (behavior.value === next) behavior.value = null;
+          };
+        },
+      };
+      const controller = useTapRoot(function useTriggerPopoverRootResource() {
+        return useResource(
+          TriggerPopoverResource({
+            text: text.value,
+            triggerChar: props.char,
+            adapter: props.adapter,
+            matcher: props.matcher,
+            behavior: behavior.value ?? undefined,
+            aui,
+            popoverId,
+            isLoading: props.isLoading ?? false,
+          }),
+        );
+      });
+      const state = shallowRef(controller.getValue());
+      useIsomorphicLayoutEffect(() => {
+        const refresh = () => {
+          state.value = controller.getValue();
+        };
+        const unsubscribe = controller.subscribe(refresh);
+        refresh();
+        return unsubscribe;
+      }, []);
+      provide(TriggerBehaviorRegistrationContext, registration);
+      provide(TriggerPopoverScopeContext, state);
+      const root = useTriggerPopoverRootContext();
+      useIsomorphicLayoutEffect(
+        () =>
+          root.register({
+            char: props.char,
+            ...(props.matcher ? { matcher: props.matcher } : {}),
+            ...(behavior.value ? { behavior: behavior.value } : {}),
+            get resource() {
+              return state.value;
+            },
+          }),
+        () => [props.char, props.matcher, behavior.value],
+      );
+      const plugins = useComposerInputPluginRegistryOptional();
+      useIsomorphicLayoutEffect(
+        () =>
+          plugins?.register({
+            handleKeyDown: (event) =>
+              controller.getValue().handleKeyDown(event),
+            setCursorPosition: (position) =>
+              controller.getValue().setCursorPosition(position),
+          }),
+        [],
+      );
+      const open = computed(() => behavior.value !== null && state.value.open);
+      const aria = useTriggerPopoverAriaPublish();
+      useIsomorphicLayoutEffect(() => {
+        const char = props.char;
+        if (!open.value) return undefined;
+        aria.setActiveAria(char, {
+          popoverId,
+          highlightedItemId: state.value.highlightedItemId,
+        });
+        return () => aria.setActiveAria(char, null);
+      });
+      return () => {
+        const children = slots.default?.() ?? props.children;
+        const highlightedItemId = state.value.highlightedItemId;
+        const render = props.render;
+        const asChild = props.asChild;
+        const containerProps = {
+          role: "listbox",
+          id: popoverId,
+          "aria-label": "Suggestions",
+          ...(highlightedItemId !== undefined
+            ? { "aria-activedescendant": highlightedItemId }
+            : {}),
+          "data-state": "open",
+          ...attrs,
+          ...(render !== undefined ? { render } : {}),
+          ...(asChild !== undefined ? { asChild } : {}),
+          ref: forwardRef,
+        } satisfies PrimitiveProps<"div"> &
+          VNodeProps &
+          Record<string, unknown>;
+        if (props.asChild && !props.render) {
+          return h(
+            Primitive.div,
+            open.value ? containerProps : { asChild: true },
+            { default: () => children },
+          );
+        }
+        // Moving the same children preserves behavior registrations when the
+        // container appears. Recreating them would close and reopen the trigger.
+        return [
+          open.value ? h(Primitive.div, containerProps) : null,
+          h(
+            Teleport,
+            {
+              to: currentElement.value ?? "body",
+              disabled: !open.value || !currentElement.value,
+            },
+            Array.isArray(children) ? children : [children],
+          ),
+        ];
+      };
+    },
+    {
+      name: "ComposerPrimitive.TriggerPopover",
+      inheritAttrs: false,
+      props: [
+        "char",
+        "matcher",
+        "adapter",
+        "isLoading",
+        "render",
+        "asChild",
+        "children",
+      ],
+    },
+  );

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

@@ -0,0 +1,61 @@
+"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 ComposerPrimitiveTriggerPopoverAction {
+  export type Props = {
+    /** Defaults to `defaultDirectiveFormatter`. */
+    readonly formatter?: DirectiveFormatter | undefined;
+    /** Fires the moment an item is selected; runs regardless of `removeOnExecute`. */
+    readonly onExecute: (item: TriggerItem) => void;
+    /** When true, strips the trigger text after executing. Defaults to `false` (keeps audit-trail chip). */
+    readonly removeOnExecute?: boolean | undefined;
+  };
+}
+
+/**
+ * Configures a `<TriggerPopover>` to fire a handler when an item is selected,
+ * optionally leaving a directive chip behind as an audit trail. Render exactly
+ * one behavior sub-primitive per `<TriggerPopover>`.
+ *
+ * Exposed as `ComposerPrimitive.TriggerPopover.Action`.
+ *
+ * @example
+ * ```tsx
+ * <ComposerPrimitive.TriggerPopover char="/" adapter={slashAdapter}>
+ *   <ComposerPrimitive.TriggerPopover.Action
+ *     onExecute={(item) => commandHandlers[item.id]?.()}
+ *     removeOnExecute={false}
+ *   />
+ * </ComposerPrimitive.TriggerPopover>
+ * ```
+ */
+export const ComposerPrimitiveTriggerPopoverAction =
+  defineComponent<ComposerPrimitiveTriggerPopoverAction.Props>(
+    (props) => {
+      const { register } = useTriggerBehaviorRegistration();
+      useIsomorphicLayoutEffect(() => {
+        const behavior: TriggerBehavior = {
+          kind: "action",
+          get formatter() {
+            return props.formatter ?? defaultDirectiveFormatter;
+          },
+          onExecute: (item) => props.onExecute(item),
+          get removeOnExecute() {
+            return props.removeOnExecute ?? false;
+          },
+        };
+        return register(behavior);
+      }, []);
+      return () => null;
+    },
+    {
+      name: "ComposerPrimitiveTriggerPopoverAction",
+      props: ["formatter", "onExecute", "removeOnExecute"],
+    },
+  );

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

@@ -0,0 +1,51 @@
+"use client";
+
+import { Primitive, type PrimitiveProps } from "../../../utils/Primitive";
+import {
+  defineComponent,
+  h,
+  mergeProps,
+  type ComponentPublicInstance,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { useTriggerPopoverScopeContext } from "./TriggerPopover";
+
+export namespace ComposerPrimitiveTriggerPopoverBack {
+  export type Element = ComponentPublicInstance;
+  export type Props = PrimitiveProps<"button">;
+}
+
+/**
+ * A button that navigates back from category items to the category list.
+ * Only renders when a category is active (drill-down view).
+ */
+export const ComposerPrimitiveTriggerPopoverBack =
+  defineComponent<ComposerPrimitiveTriggerPopoverBack.Props>(
+    (props, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      const state = useTriggerPopoverScopeContext();
+      return () =>
+        !state.value.open ||
+        !state.value.activeCategoryId ||
+        state.value.isSearchMode
+          ? null
+          : h(
+              Primitive.button,
+              mergeProps({ type: "button" }, attrs, {
+                render: props.render,
+                asChild: props.asChild,
+                children: props.children,
+                ref: forwardRef,
+                onClick: (event: MouseEvent) => {
+                  if (!event.defaultPrevented) state.value.goBack();
+                },
+              }),
+              slots,
+            );
+    },
+    {
+      name: "ComposerPrimitive.TriggerPopoverBack",
+      inheritAttrs: false,
+      props: ["render", "asChild", "children"],
+    },
+  );