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

package/src/utils/Primitive.tsx

@@ -0,0 +1,363 @@
+import {
+  cloneVNode,
+  Comment,
+  createVNode,
+  defineComponent,
+  Fragment,
+  h,
+  isVNode,
+  mergeProps,
+  shallowRef,
+  type Component,
+  type ComponentPublicInstance,
+  type FunctionalComponent,
+  type VNode,
+  type VNodeChild,
+  type VNodeProps,
+  type IntrinsicElementAttributes,
+} from "vue";
+import { Primitive as RekaPrimitive, Slot, useForwardExpose } from "reka-ui";
+
+const NODES = [
+  "a",
+  "button",
+  "div",
+  "form",
+  "h2",
+  "h3",
+  "img",
+  "input",
+  "label",
+  "li",
+  "nav",
+  "ol",
+  "p",
+  "select",
+  "span",
+  "svg",
+  "ul",
+] as const;
+type PrimitiveNode = (typeof NODES)[number];
+type ElementType = Component | keyof IntrinsicElementAttributes;
+type ElementProps<T extends ElementType> =
+  T extends keyof IntrinsicElementAttributes
+    ? IntrinsicElementAttributes[T]
+    : T extends new (...args: never[]) => { $props: infer P }
+      ? P
+      : T extends FunctionalComponent<infer P>
+        ? P
+        : Record<string, unknown>;
+
+type WithRenderPropProps<T extends ElementType> = ElementProps<T> & {
+  render?: VNode | undefined;
+  asChild?: boolean | undefined;
+  children?: VNodeChild;
+};
+type PrimitiveProps<E extends PrimitiveNode> = WithRenderPropProps<E>;
+type RuntimeProps = {
+  render?: VNode | undefined;
+  asChild?: boolean | undefined;
+  children?: VNodeChild;
+};
+
+/** Outer children override even when explicitly null; absent children preserve slots. */
+function composeRenderElement(render: VNode, children: VNodeChild): VNode {
+  if (children === undefined) return cloneVNode(render);
+  const replacementChildren =
+    children == null ? [] : Array.isArray(children) ? children : [children];
+  const node = createVNode(
+    render.type,
+    render.props ? { ...render.props } : null,
+    typeof render.type === "object" || typeof render.type === "function"
+      ? { default: () => replacementChildren }
+      : replacementChildren,
+  );
+  // Preserve the caller's composed ref without rebuilding its ownership.
+  node.ref = render.ref;
+  return node;
+}
+
+type SlotAttributes = VNodeProps & Record<string, unknown>;
+
+function prepareSlotTarget(
+  child: VNode,
+  attributes: SlotAttributes,
+  ref?: VNodeProps["ref"],
+) {
+  const attrs = { ...attributes };
+  const target = cloneVNode(child);
+  for (const key of Object.keys(attributes)) {
+    if (!/^on[A-Z]/.test(key) || !attributes[key] || !child.props?.[key])
+      continue;
+    // The original Slot runs child events before SDK owner actions. Let Vue
+    // compose only those listeners; Reka retains every other merge decision.
+    target.props = {
+      ...target.props,
+      ...mergeProps({ [key]: child.props[key] }, { [key]: attributes[key] }),
+    };
+    delete attrs[key];
+  }
+  return {
+    attrs,
+    target: ref ? cloneVNode(target, { ref }, true) : target,
+  };
+}
+
+function prepareSlotChildren(
+  children: VNodeChild,
+  attributes: SlotAttributes,
+  ref: VNodeProps["ref"],
+) {
+  let attrs = attributes;
+  let selected = false;
+  const visit = (child: VNodeChild): VNodeChild => {
+    if (selected) return child;
+    if (Array.isArray(child)) return child.map(visit);
+    if (!isVNode(child) || child.type === Comment) return child;
+    if (child.type === Fragment && Array.isArray(child.children))
+      return createVNode(child, null, child.children.map(visit));
+    selected = true;
+    const prepared = prepareSlotTarget(child, attrs, ref);
+    attrs = prepared.attrs;
+    return prepared.target;
+  };
+  const content = visit(children);
+  return { attrs, children: content };
+}
+
+const wrapperInstanceFields = new Set([
+  "$",
+  "_",
+  "$data",
+  "$props",
+  "$attrs",
+  "$slots",
+  "$refs",
+  "$parent",
+  "$root",
+  "$emit",
+  "$options",
+  "$forceUpdate",
+  "$nextTick",
+  "$watch",
+  "$host",
+]);
+
+function usePublicForwardExpose(
+  expose: (value: Record<string, unknown>) => void,
+  props: RuntimeProps,
+) {
+  const target = shallowRef<Element | ComponentPublicInstance | null>(null);
+  const isElement = (value: object): value is Element =>
+    typeof Element !== "undefined" && value instanceof Element;
+  const component = () => {
+    const value = target.value;
+    return value && !isElement(value) ? value : null;
+  };
+  const currentPublicElement = () => {
+    const value = target.value;
+    return value && (isElement(value) ? value : value.$el);
+  };
+  const forwardsOwnElement = () => {
+    const value = component();
+    return (
+      !props.asChild &&
+      !isVNode(props.render) &&
+      !!value &&
+      Object.hasOwn(value, "$el")
+    );
+  };
+  const local: Record<string, unknown> = {};
+  const exposed = new Proxy(local, {
+    get(own, key, receiver) {
+      if (Object.hasOwn(own, key)) return Reflect.get(own, key, receiver);
+      if (key === "$el") return currentPublicElement();
+      if (typeof key === "string" && wrapperInstanceFields.has(key))
+        return undefined;
+      if (Object.hasOwn(props, key)) return Reflect.get(props, key);
+      const value = component();
+      return value ? Reflect.get(value, key) : undefined;
+    },
+    has(own, key) {
+      // An absent conditional child needs Vue's own comment/text root fallback.
+      if (key === "$el") return currentPublicElement() != null;
+      if (Object.hasOwn(own, key)) return true;
+      if (typeof key === "string" && wrapperInstanceFields.has(key))
+        return false;
+      if (Object.hasOwn(props, key)) return true;
+      const value = component();
+      return !!value && key in value;
+    },
+    ownKeys(own) {
+      const value = component();
+      const keys = value ? Reflect.ownKeys(value) : [];
+      return [
+        ...new Set([
+          ...Reflect.ownKeys(own),
+          ...Reflect.ownKeys(props),
+          ...(forwardsOwnElement() ? ["$el"] : []),
+          ...keys.filter(
+            (key) =>
+              key !== "$el" &&
+              !(typeof key === "string" && wrapperInstanceFields.has(key)),
+          ),
+        ]),
+      ];
+    },
+    getOwnPropertyDescriptor(own, key) {
+      const descriptor = Reflect.getOwnPropertyDescriptor(own, key);
+      if (descriptor) return descriptor;
+      // Preserve a normal component's own live root; custom render/asChild
+      // roots stay virtual so official wrappers also forward their actions.
+      if (key === "$el")
+        return forwardsOwnElement()
+          ? {
+              configurable: true,
+              enumerable: true,
+              get: currentPublicElement,
+            }
+          : undefined;
+      if (typeof key === "string" && wrapperInstanceFields.has(key))
+        return undefined;
+      if (Object.hasOwn(props, key))
+        return {
+          configurable: true,
+          enumerable: true,
+          get: () => Reflect.get(props, key),
+        };
+      const value = component();
+      if (!value || !Object.hasOwn(value, key)) return undefined;
+      return {
+        configurable: true,
+        enumerable: true,
+        get: () => {
+          const current = component();
+          return current ? Reflect.get(current, key) : undefined;
+        },
+      };
+    },
+  });
+  expose(exposed);
+  return (value: Element | ComponentPublicInstance | null) => {
+    target.value = value;
+  };
+}
+
+function renderSlot(
+  render: VNode,
+  children: VNodeChild,
+  props: VNodeProps & Record<string, unknown>,
+): VNode {
+  const { ref, ...attrs } = props;
+  // Reka owns prop/event merging. Attach refs before Slot so the target's
+  // original Vue ref and the caller's ref are both retained.
+  const prepared = prepareSlotTarget(
+    composeRenderElement(render, children),
+    attrs,
+    ref,
+  );
+  return h(Slot, prepared.attrs, { default: () => [prepared.target] });
+}
+
+function createRenderProp<P extends RuntimeProps>(
+  Component: ElementType,
+  name: string,
+) {
+  return defineComponent(
+    (props: P, { attrs, slots, expose }) => {
+      const forwardRef = usePublicForwardExpose(expose, props);
+      const forwardBaseRef = (
+        target: Element | ComponentPublicInstance | null,
+      ) => {
+        if (!props.asChild && !(props.render && isVNode(props.render)))
+          forwardRef(target);
+      };
+      return () => {
+        const children = slots.default ? slots.default() : props.children;
+        if (props.render && isVNode(props.render)) {
+          if (typeof Component !== "string") {
+            const prepared = prepareSlotTarget(
+              composeRenderElement(props.render, children),
+              attrs,
+              forwardRef,
+            );
+            return h(
+              Component,
+              { ...prepared.attrs, asChild: true },
+              {
+                default: () => [prepared.target],
+              },
+            );
+          }
+          return renderSlot(props.render, children, {
+            ...attrs,
+            ref: forwardRef,
+          });
+        }
+        const componentProps = {
+          ...attrs,
+          asChild: props.asChild,
+          ref: forwardBaseRef,
+        };
+        if (typeof Component !== "string" && props.asChild) {
+          const prepared = prepareSlotChildren(children, attrs, forwardRef);
+          return h(
+            Component,
+            { ...prepared.attrs, asChild: true },
+            { default: () => prepared.children },
+          );
+        }
+        return typeof Component === "string"
+          ? h(
+              Component,
+              { ...attrs, ref: forwardRef },
+              children == null
+                ? []
+                : Array.isArray(children)
+                  ? children
+                  : [children],
+            )
+          : h(Component, componentProps, { default: () => children });
+      };
+    },
+    { name, inheritAttrs: false, props: ["render", "asChild", "children"] },
+  );
+}
+
+function withRenderProp<T extends ElementType>(Component: T) {
+  return createRenderProp<WithRenderPropProps<T>>(
+    Component,
+    typeof Component === "string" ? Component : (Component.name ?? "Component"),
+  );
+}
+
+function createPrimitive<E extends PrimitiveNode>(node: E) {
+  const Base = defineComponent({
+    name: `Primitive.${node}`,
+    inheritAttrs: false,
+    setup(_, { attrs, slots }) {
+      const { forwardRef } = useForwardExpose();
+      return () =>
+        h(
+          RekaPrimitive,
+          {
+            as: node,
+            ...attrs,
+            // Reka selects its element/slot mode during setup.
+            key: attrs.asChild ? "slot" : node,
+            ref: forwardRef,
+          },
+          slots,
+        );
+    },
+  });
+  return createRenderProp<PrimitiveProps<E>>(Base, `Primitive.${node}`);
+}
+const Primitive = Object.fromEntries(
+  NODES.map((node) => [node, createPrimitive(node)]),
+) as {
+  [K in PrimitiveNode]: ReturnType<typeof createPrimitive<K>>;
+};
+
+export { Primitive, renderSlot, withRenderProp };
+export type { PrimitiveProps, WithRenderPropProps };

package/src/utils/RequireAtLeastOne.ts

@@ -0,0 +1,7 @@
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<
+  T,
+  Exclude<keyof T, Keys>
+> &
+  {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+  }[Keys];

package/src/utils/createActionButton.child-cancel.test.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  defineComponent,
+  h,
+  shallowRef,
+  type ComponentPublicInstance,
+} from "vue";
+import { cleanup, render } from "../tests/vue";
+import { createActionButton } from "./createActionButton";
+
+afterEach(cleanup);
+
+describe("createActionButton retained child cancellation", () => {
+  it.each(["asChild", "render"] as const)(
+    "lets the %s child prevent the SDK action before the caller observes the same event",
+    (mode) => {
+      const action = vi.fn();
+      const cancelled = shallowRef(true);
+      const target = shallowRef<HTMLButtonElement | null>(null);
+      const exposed = shallowRef<ComponentPublicInstance | null>(null);
+      const child = vi.fn((event: MouseEvent) => {
+        if (cancelled.value) event.preventDefault();
+      });
+      const observations: boolean[] = [];
+      const caller = vi.fn((event: MouseEvent) =>
+        observations.push(event.defaultPrevented),
+      );
+      const Button = createActionButton("ChildCancelable", () => action);
+      const view = render(
+        h(
+          defineComponent(() => () => {
+            const element = h(
+              "button",
+              {
+                ref: target,
+                "aria-label": "Run retained action",
+                onClick: child,
+              },
+              "Run",
+            );
+            return mode === "render"
+              ? h(Button, { ref: exposed, render: element, onClick: caller })
+              : h(
+                  Button,
+                  { ref: exposed, asChild: true, onClick: caller },
+                  { default: () => element },
+                );
+          }),
+        ),
+      );
+      const button = view.container.querySelector<HTMLButtonElement>("button");
+      if (!button) throw new Error("Actual action button target missing");
+      expect(button.getAttribute("type")).toBe("button");
+      expect(target.value).toBe(button);
+      expect(exposed.value?.$el).toBe(button);
+      const prevented = new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+      });
+      expect(button.dispatchEvent(prevented)).toBe(false);
+      expect(child).toHaveBeenCalledExactlyOnceWith(prevented);
+      expect(caller).toHaveBeenCalledExactlyOnceWith(prevented);
+      expect(action).not.toHaveBeenCalled();
+      expect(observations).toEqual([true]);
+      cancelled.value = false;
+      const allowed = new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+      });
+      expect(button.dispatchEvent(allowed)).toBe(true);
+      expect(action).toHaveBeenCalledExactlyOnceWith(allowed);
+      expect(child).toHaveBeenCalledTimes(2);
+      expect(caller).toHaveBeenCalledTimes(2);
+      expect(observations).toEqual([true, false]);
+      view.unmount();
+      expect(target.value).toBeNull();
+      expect(exposed.value).toBeNull();
+      expect(button.isConnected).toBe(false);
+    },
+  );
+});

package/src/utils/createActionButton.test.tsx

@@ -0,0 +1,114 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  computed,
+  defineComponent,
+  h,
+  nextTick,
+  shallowRef,
+  type ComponentPublicInstance,
+} from "vue";
+import { renderToString } from "@vue/server-renderer";
+import { cleanup, render } from "../tests/vue";
+import { createActionButton } from "./createActionButton";
+
+const TestButton = createActionButton("TestButton", () => () => {});
+afterEach(cleanup);
+
+describe("createActionButton", () => {
+  it("defaults to type=button", async () => {
+    const html = await renderToString(h(TestButton));
+    expect(html).toContain('type="button"');
+  });
+
+  it("allows the caller to override type", async () => {
+    const html = await renderToString(h(TestButton, { type: "submit" }));
+    expect(html).toContain('type="submit"');
+    expect(html).not.toContain('type="button"');
+  });
+
+  it("follows reactive action availability and options with one setup and the same DOM node", async () => {
+    const enabled = shallowRef(true);
+    const amount = shallowRef(1);
+    const calls: number[] = [];
+    let setups = 0;
+    const Button = createActionButton(
+      "Counter",
+      (options: { amount?: number }) => {
+        setups++;
+        return computed(() =>
+          enabled.value ? () => calls.push(options.amount ?? 0) : null,
+        );
+      },
+      ["amount"],
+    );
+    const view = render(
+      h(
+        defineComponent({
+          setup: () => () =>
+            h(
+              Button,
+              { amount: amount.value, class: "action" },
+              { default: () => "run" },
+            ),
+        }),
+      ),
+    );
+    const button = view.container.querySelector("button")!;
+    expect(button.textContent).toBe("run");
+    expect(button.hasAttribute("amount")).toBe(false);
+    button.click();
+    expect(calls).toEqual([1]);
+    amount.value = 3;
+    await nextTick();
+    button.click();
+    expect(calls).toEqual([1, 3]);
+    enabled.value = false;
+    await nextTick();
+    expect(button.disabled).toBe(true);
+    button.click();
+    expect(calls).toEqual([1, 3]);
+    enabled.value = true;
+    await nextTick();
+    expect(button.disabled).toBe(false);
+    expect(view.container.querySelector("button")).toBe(button);
+    expect(setups).toBe(1);
+  });
+
+  it("honors caller cancellation and native disabled, forwards refs, and preserves render elements", async () => {
+    const action = vi.fn();
+    const prevented = shallowRef(true);
+    const disabled = shallowRef(false);
+    const exposed = shallowRef<ComponentPublicInstance | null>(null);
+    const Button = createActionButton("Cancelable", () => action);
+    const view = render(
+      h(
+        defineComponent({
+          setup: () => () =>
+            h(Button, {
+              ref: exposed,
+              disabled: disabled.value,
+              render: h("button", { "aria-label": "target" }),
+              onClick: (event: MouseEvent) => {
+                if (prevented.value) event.preventDefault();
+              },
+            }),
+        }),
+      ),
+    );
+    const button = view.container.querySelector("button")!;
+    expect(exposed.value?.$el).toBe(button);
+    expect(button.getAttribute("aria-label")).toBe("target");
+    button.click();
+    expect(action).not.toHaveBeenCalled();
+    prevented.value = false;
+    button.click();
+    expect(action).toHaveBeenCalledTimes(1);
+    disabled.value = true;
+    await nextTick();
+    button.click();
+    expect(action).toHaveBeenCalledTimes(1);
+    view.unmount();
+    expect(exposed.value).toBe(null);
+  });
+});

package/src/utils/createActionButton.tsx

@@ -0,0 +1,75 @@
+import {
+  defineComponent,
+  h,
+  mergeProps,
+  shallowReactive,
+  unref,
+  watchEffect,
+  type ComponentPublicInstance,
+  type MaybeRef,
+} from "vue";
+import { useForwardExpose } from "reka-ui";
+import { Primitive, type PrimitiveProps } from "./Primitive";
+
+type ActionHandler = (event: MouseEvent) => void;
+
+type ActionButtonCallback<TProps> = (
+  props: TProps,
+) => MaybeRef<ActionHandler | null>;
+
+type PrimitiveButtonProps = PrimitiveProps<"button">;
+
+export type ActionButtonProps<THook> = PrimitiveButtonProps &
+  (THook extends (props: infer TProps) => unknown ? TProps : never);
+
+export type ActionButtonElement = ComponentPublicInstance;
+
+export const createActionButton = <TProps,>(
+  displayName: string,
+  useActionButton: ActionButtonCallback<TProps>,
+  forwardProps: Extract<keyof NonNullable<TProps>, string>[] = [],
+) => {
+  return defineComponent<PrimitiveButtonProps & TProps>(
+    (props, { attrs, slots }) => {
+      const { forwardRef } = useForwardExpose();
+      const options = shallowReactive<Record<string, unknown>>({});
+      watchEffect(
+        () => {
+          for (const key of forwardProps)
+            options[key] = Reflect.get(props, key);
+        },
+        { flush: "sync" },
+      );
+      const callback = useActionButton(options as TProps);
+      const invoke = (event: MouseEvent) => {
+        if (!event.defaultPrevented) unref(callback)?.(event);
+      };
+      return () =>
+        h(
+          Primitive.button,
+          {
+            type: "button",
+            ...attrs,
+            render: props.render,
+            asChild: props.asChild,
+            children: props.children,
+            ref: forwardRef,
+            disabled:
+              attrs.disabled === "" || !!attrs.disabled || !unref(callback),
+            ...mergeProps({ onClick: attrs.onClick }, { onClick: invoke }),
+          },
+          slots,
+        );
+    },
+    {
+      name: displayName,
+      inheritAttrs: false,
+      props: [
+        "render",
+        "asChild",
+        "children",
+        ...forwardProps,
+      ] as (keyof (PrimitiveButtonProps & TProps))[],
+    },
+  );
+};