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

package/src/spec/vue/SpecRenderer.tsx

@@ -0,0 +1,544 @@
+import {
+  computed,
+  defineComponent,
+  Fragment,
+  h,
+  inject,
+  onActivated,
+  onBeforeUnmount,
+  onDeactivated,
+  onErrorCaptured,
+  onMounted,
+  onUpdated,
+  provide,
+  shallowRef,
+  watch,
+  type Component,
+  type ComputedRef,
+  type InjectionKey,
+  type VNodeChild,
+} from "vue";
+import {
+  createActionDispatcher,
+  type ActionDispatcher,
+  type ActionHandler,
+  type ActionSource,
+} from "../actions";
+import type { Catalog } from "../catalog";
+import {
+  evaluateCondition,
+  resolveProps,
+  type ExpressionContext,
+} from "../expressions";
+import {
+  animatePendingDots,
+  PENDING_DOT_STYLE,
+  PENDING_STYLE,
+} from "../pending";
+import { getAtPointer } from "../pointer";
+import { rejectedPropType } from "../resolved";
+import { createStateStore, type SpecStateStore } from "../state";
+import { childIdsOf, repeatItems, safePointer } from "../tree";
+import type { Spec, SpecElement } from "../types";
+export type SpecComponentProps<
+  P extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  id: string;
+  element: SpecElement;
+  props: P;
+  /** The rendered default slot, also supplied as a native Vue default slot. */
+  children: VNodeChild;
+  /** Named slot nodes, also supplied as native Vue named slots. */
+  slots: Record<string, VNodeChild>;
+  emit(event: string, payload?: unknown): void;
+  setProp(name: string, value: unknown): void;
+  bindings: Record<string, string>;
+  state: SpecStateStore;
+  streaming: boolean;
+};
+export type SpecComponents = Record<string, Component>;
+export type SpecPlaceholderProps = {
+  id: string;
+  reason:
+    | "missing"
+    | "pending"
+    | "unknown-type"
+    | "invalid-props"
+    | "cycle"
+    | "error";
+  message: string;
+};
+export type SpecRendererProps = {
+  spec: Spec;
+  components: SpecComponents;
+  catalog?: Catalog;
+  state?: SpecStateStore;
+  handlers?: Record<string, ActionHandler>;
+  onAction?: (
+    name: string,
+    params: Record<string, unknown>,
+    context: ActionSource & { state: SpecStateStore },
+  ) => unknown;
+  onError?: (error: Error, context: { elementId?: string }) => void;
+  streaming?: boolean;
+  placeholder?: Component;
+};
+type RenderContext = {
+  spec: Spec;
+  components: SpecComponents;
+  catalog: Catalog | undefined;
+  store: SpecStateStore;
+  state: Record<string, unknown>;
+  dispatch: ActionDispatcher;
+  streaming: boolean;
+  placeholder: Component;
+  invalid: (element: SpecElement) => string | undefined;
+  onError: SpecRendererProps["onError"];
+};
+const SpecContext: InjectionKey<ComputedRef<RenderContext>> =
+  Symbol("SpecRenderer");
+type Scope = Pick<ExpressionContext, "item" | "index" | "itemPath">;
+const PendingDots = defineComponent({
+  setup() {
+    const host = shallowRef<HTMLSpanElement | null>(null);
+    let stop: (() => void) | undefined;
+    const start = () => {
+      stop?.();
+      stop = host.value ? animatePendingDots(host.value) : undefined;
+    };
+    onMounted(start);
+    onActivated(start);
+    onDeactivated(() => {
+      stop?.();
+      stop = undefined;
+    });
+    onBeforeUnmount(() => {
+      stop?.();
+      stop = undefined;
+    });
+    return () =>
+      h(
+        "span",
+        {
+          ref: host,
+          "data-gf-spec-placeholder": "pending",
+          "aria-hidden": "true",
+          style: PENDING_STYLE,
+        },
+        Array.from({ length: 3 }, (_, key) =>
+          h("span", { key, style: PENDING_DOT_STYLE }),
+        ),
+      );
+  },
+});
+export const SpecPlaceholder = defineComponent(
+  (props: SpecPlaceholderProps) => () =>
+    props.reason === "pending"
+      ? h(PendingDots)
+      : h(
+          "div",
+          {
+            "data-gf-spec-placeholder": props.reason,
+            role: "note",
+            title: props.id + ": " + props.message,
+            style: {
+              fontSize: "12px",
+              padding: "4px 8px",
+              margin: "2px 0",
+              border: "1px dashed currentColor",
+              borderRadius: "6px",
+              opacity: 0.6,
+            },
+          },
+          props.message,
+        ),
+  { name: "SpecPlaceholder", props: ["id", "reason", "message"] },
+);
+type BoundaryProps = {
+  element: SpecElement;
+  onError: (error: Error) => void;
+  fallback: (error: Error) => VNodeChild;
+};
+const ElementBoundary = defineComponent(
+  (props: BoundaryProps, { slots }) => {
+    const error = shallowRef<Error | null>(null);
+    watch(
+      () => props.element,
+      () => {
+        error.value = null;
+      },
+      { flush: "sync" },
+    );
+    onErrorCaptured((cause) => {
+      const caught = cause instanceof Error ? cause : new Error(String(cause));
+      error.value = caught;
+      props.onError(caught);
+      return false;
+    });
+    return () =>
+      error.value ? props.fallback(error.value) : slots.default?.();
+  },
+  { name: "SpecElementBoundary", props: ["element", "onError", "fallback"] },
+);
+function renderChildren(
+  ids: readonly unknown[],
+  scope: Scope,
+  ancestors: readonly string[],
+): VNodeChild[] {
+  const occurrences = new Map<string, number>();
+  return ids.map((id) => {
+    if (typeof id !== "string") return null;
+    const occurrence = occurrences.get(id) ?? 0;
+    occurrences.set(id, occurrence + 1);
+    return h(ElementView, { key: id + ":" + occurrence, id, scope, ancestors });
+  });
+}
+const ElementView = defineComponent(
+  (props: { id: string; scope: Scope; ancestors: readonly string[] }) => {
+    const context = inject(SpecContext)!;
+    let last: SpecElement | undefined;
+    let accepted: SpecElement | undefined;
+    const commit = () => {
+      if (accepted !== undefined) last = accepted;
+    };
+    onMounted(commit);
+    onUpdated(commit);
+    return () => {
+      const ctx = context.value;
+      const { id, scope, ancestors } = props;
+      const Placeholder = ctx.placeholder;
+      const raw = Object.hasOwn(ctx.spec.elements, id)
+        ? ctx.spec.elements[id]
+        : undefined;
+      const element =
+        raw && typeof raw === "object" && typeof raw.type === "string"
+          ? raw
+          : undefined;
+      const invalid = element && ctx.invalid(element);
+      accepted = invalid ? undefined : element;
+      if (ancestors.includes(id))
+        return h(Placeholder, {
+          id,
+          reason: "cycle",
+          message: '"' + id + '" contains itself',
+        });
+      if (!element)
+        return ctx.streaming
+          ? null
+          : h(Placeholder, {
+              id,
+              reason: "missing",
+              message: 'Missing element "' + id + '"',
+            });
+      if (!evaluateCondition(element.visible, { ...scope, state: ctx.state }))
+        return null;
+      const Impl = Object.hasOwn(ctx.components, element.type)
+        ? ctx.components[element.type]
+        : undefined;
+      if (!Impl || (ctx.catalog && !ctx.catalog.component(element.type)))
+        return ctx.streaming
+          ? null
+          : h(Placeholder, {
+              id,
+              reason: "unknown-type",
+              message: 'Unknown component "' + element.type + '"',
+            });
+      if (invalid && !ctx.streaming)
+        return h(Placeholder, {
+          id,
+          reason: "invalid-props",
+          message: invalid,
+        });
+      const shown = invalid ? last : element;
+      if (shown?.type !== element.type) return null;
+      return h(
+        ElementBoundary,
+        {
+          element: shown,
+          onError: (error) => context.value.onError?.(error, { elementId: id }),
+          fallback: (error) =>
+            context.value.streaming
+              ? null
+              : h(context.value.placeholder, {
+                  id,
+                  reason: "error",
+                  message: shown.type + " failed: " + error.message,
+                }),
+        },
+        {
+          default: () =>
+            h(ResolvedElement, {
+              key: shown.type,
+              id,
+              element: shown,
+              Impl,
+              scope,
+              ancestors: [...ancestors, id],
+            }),
+        },
+      );
+    };
+  },
+  { name: "SpecElement", props: ["id", "scope", "ancestors"] },
+);
+type Resolved = ReturnType<typeof resolveProps>;
+const ResolvedElement = defineComponent(
+  (input: {
+    id: string;
+    element: SpecElement;
+    Impl: Component;
+    scope: Scope;
+    ancestors: readonly string[];
+  }) => {
+    const context = inject(SpecContext)!;
+    const resolved = computed(() =>
+      resolveProps(input.element.props, {
+        ...input.scope,
+        state: context.value.state,
+      }),
+    );
+    const rejected = computed(() =>
+      rejectedPropType(
+        context.value.catalog?.propsSchema(input.element.type),
+        resolved.value.props,
+      ),
+    );
+    let last: Resolved | undefined;
+    const shown = computed(() => (rejected.value ? last : resolved.value));
+    const commit = () => {
+      if (!rejected.value) last = resolved.value;
+    };
+    onMounted(commit);
+    onUpdated(commit);
+    let previousWatch: Map<string, unknown> | undefined;
+    watch(
+      () => ({
+        state: context.value.state,
+        element: input.element,
+        scope: input.scope,
+        dispatch: context.value.dispatch,
+      }),
+      () => {
+        const ctx = context.value;
+        const next = new Map<string, unknown>();
+        for (const path of Object.keys(input.element.watch ?? {})) {
+          const value = getAtPointer(ctx.state, safePointer(path));
+          next.set(path, value);
+          if (
+            previousWatch?.has(path) &&
+            !Object.is(previousWatch.get(path), value)
+          )
+            void ctx.dispatch(input.element.watch![path], {
+              ...input.scope,
+              elementId: input.id,
+              trigger: path,
+              kind: "watch",
+            });
+        }
+        previousWatch = next;
+      },
+      { immediate: true, flush: "post" },
+    );
+    const emit = (event: string, payload?: unknown) => {
+      const bound = input.element.on?.[event];
+      if (bound)
+        void context.value.dispatch(bound, {
+          ...input.scope,
+          elementId: input.id,
+          trigger: event,
+          kind: "event",
+          payload,
+        });
+    };
+    const setProp = (name: string, value: unknown) => {
+      const path = shown.value?.bindings[name];
+      if (path !== undefined) context.value.store.set(path, value, "replace");
+    };
+    return () => {
+      const ctx = context.value;
+      const { id, element, Impl, scope, ancestors } = input;
+      if (rejected.value && !ctx.streaming)
+        return h(ctx.placeholder, {
+          id,
+          reason: "invalid-props",
+          message: element.type + ": " + rejected.value,
+        });
+      const current = shown.value;
+      if (!current) return null;
+      const children =
+        element.repeat && typeof element.repeat.path === "string"
+          ? (repeatItems(element.repeat, ctx.state)?.map((item) =>
+              h(
+                Fragment,
+                { key: item.key },
+                renderChildren(
+                  childIdsOf(element, "default"),
+                  item.scope,
+                  ancestors,
+                ),
+              ),
+            ) ?? null)
+          : renderChildren(childIdsOf(element, "default"), scope, ancestors);
+      const named: Record<string, VNodeChild> = {};
+      for (const [name, ids] of Object.entries(element.slots ?? {}))
+        if (Array.isArray(ids))
+          named[name] = renderChildren(ids, scope, ancestors);
+      const slots = Object.fromEntries(
+        Object.entries(named).map(([name, nodes]) => [name, () => nodes]),
+      );
+      return h(
+        Impl,
+        {
+          id,
+          element,
+          props: current.props,
+          children,
+          bindings: current.bindings,
+          slots: named,
+          emit,
+          setProp,
+          state: ctx.store,
+          streaming: ctx.streaming,
+        },
+        { ...slots, default: () => children },
+      );
+    };
+  },
+  {
+    name: "ResolvedSpecElement",
+    props: ["id", "element", "Impl", "scope", "ancestors"],
+  },
+);
+export const SpecRenderer = defineComponent(
+  (props: SpecRendererProps) => {
+    const emptyState: Record<string, unknown> = {};
+    const ownStore = createStateStore(props.spec.state ?? emptyState);
+    const store = computed(() => props.state ?? ownStore);
+    const snapshot = shallowRef(store.value.getState());
+    const active = shallowRef(false);
+    onMounted(() => {
+      active.value = true;
+    });
+    onActivated(() => {
+      active.value = true;
+    });
+    onDeactivated(() => {
+      active.value = false;
+    });
+    onBeforeUnmount(() => {
+      active.value = false;
+    });
+    watch(
+      [store, active],
+      ([current, enabled], _old, onCleanup) => {
+        snapshot.value = current.getState();
+        if (!enabled) return;
+        let subscribed = true;
+        const stop = current.subscribe(() => {
+          if (subscribed) snapshot.value = current.getState();
+        });
+        snapshot.value = current.getState();
+        onCleanup(() => {
+          subscribed = false;
+          stop();
+        });
+      },
+      { immediate: true, flush: "sync" },
+    );
+    watch(
+      () => [props.state, props.spec.state] as const,
+      ([external, seed]) => {
+        if (!external) ownStore.seed(seed ?? emptyState);
+      },
+      { flush: "pre" },
+    );
+    const dispatch = computed(() =>
+      createActionDispatcher({
+        store: store.value,
+        ...(props.catalog ? { catalog: props.catalog } : {}),
+        onAction: (name, params, context) => {
+          if (props.handlers && Object.hasOwn(props.handlers, name))
+            return props.handlers[name]!(params, context);
+          if (!props.onAction)
+            throw new Error('No handler for action "' + name + '"');
+          return props.onAction(name, params, context);
+        },
+        onError: (error) => {
+          if (props.onError) props.onError(error, {});
+          else console.warn("[generative-frame]", error.message);
+        },
+      }),
+    );
+    const invalid = computed(() => {
+      const catalog = props.catalog;
+      const cache = new WeakMap<SpecElement, string | null>();
+      return (element: SpecElement): string | undefined => {
+        if (!catalog) return undefined;
+        let message = cache.get(element);
+        if (message === undefined) {
+          const issues = catalog.validateProps(element.type, element.props);
+          message = issues.length
+            ? element.type +
+              ": " +
+              issues
+                .slice(0, 2)
+                .map(
+                  (issue) =>
+                    (issue.path === "/" ? "props" : issue.path.slice(1)) +
+                    " " +
+                    issue.message,
+                )
+                .join("; ")
+            : null;
+          cache.set(element, message);
+        }
+        return message ?? undefined;
+      };
+    });
+    const ctx = computed<RenderContext>(() => ({
+      spec: props.spec,
+      components: props.components,
+      catalog: props.catalog,
+      store: store.value,
+      state: snapshot.value,
+      dispatch: dispatch.value,
+      streaming: props.streaming ?? false,
+      placeholder: props.placeholder ?? SpecPlaceholder,
+      invalid: invalid.value,
+      onError: props.onError,
+    }));
+    provide(SpecContext, ctx);
+    return () => [
+      props.spec.root
+        ? h(ElementView, {
+            key: "root",
+            id: props.spec.root,
+            scope: {},
+            ancestors: [],
+          })
+        : null,
+      props.streaming
+        ? h(props.placeholder ?? SpecPlaceholder, {
+            key: "pending",
+            id: "",
+            reason: "pending",
+            message: "The spec is streaming",
+          })
+        : null,
+    ];
+  },
+  {
+    name: "SpecRenderer",
+    props: [
+      "spec",
+      "components",
+      "catalog",
+      "state",
+      "handlers",
+      "onAction",
+      "onError",
+      "streaming",
+      "placeholder",
+    ],
+  },
+);

package/src/spec/vue/__tests__/harness.ts

@@ -0,0 +1,50 @@
+import { createApp, nextTick, shallowRef, type VNode } from "vue";
+import {
+  getQueriesForElement,
+  fireEvent as domFireEvent,
+} from "@testing-library/dom";
+const disposers = new Set<() => void>();
+export function cleanup() {
+  for (const dispose of [...disposers]) dispose();
+}
+export async function act(callback: () => unknown) {
+  await callback();
+  await nextTick();
+}
+export const fireEvent = {
+  async click(element: Element, options?: Record<string, unknown>) {
+    domFireEvent.click(element, options);
+    await nextTick();
+  },
+  async change(element: Element, options?: Record<string, unknown>) {
+    domFireEvent.change(element, options);
+    await nextTick();
+  },
+};
+export function render(initial: VNode) {
+  const vnode = shallowRef(initial);
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ setup: () => () => vnode.value });
+  app.config.warnHandler = (message, instance, trace) =>
+    console.warn(message, instance, trace);
+  app.mount(container);
+  let mounted = true;
+  const unmount = () => {
+    if (!mounted) return;
+    mounted = false;
+    app.unmount();
+    container.remove();
+    disposers.delete(unmount);
+  };
+  disposers.add(unmount);
+  return {
+    ...getQueriesForElement(container),
+    container,
+    unmount,
+    async rerender(next: VNode) {
+      vnode.value = next;
+      await nextTick();
+    },
+  };
+}