schema-components 2.1.0 → 3.0.0

package/src/vue/idPrefix.ts

@@ -0,0 +1,79 @@
+/**
+ * Per-instance id-prefix derivation, parallel to
+ * `react/SchemaComponent.tsx`'s {@link sanitisePrefix}.
+ *
+ * Vue 3.5 introduced `useId()` for stable per-instance ids inside
+ * `setup()`. The helper below normalises whatever Vue returns into a
+ * DOM-id-safe string (no colons, parens, or other punctuation that
+ * breaks CSS selectors) so the result composes with the canonical
+ * `sc-` prefix from `core/cssClasses.ts`.
+ *
+ * Older Vue versions (before 3.5) do not expose `useId()`; the SFCs that
+ * consume the helper therefore prefer it when available and fall back
+ * to a monotonic counter scoped to the module. Both branches produce
+ * deterministic, sanitised prefixes.
+ */
+
+import { useId as vueUseId } from "vue";
+
+let fallbackCounter = 0;
+
+/**
+ * Sanitise a raw id value into a DOM-id-safe prefix. Mirrors the
+ * sanitiser used by the React adapter so prefixes derived from
+ * `useId()` survive every CSS selector and `aria-controls` reference.
+ */
+export function sanitisePrefix(value: string): string {
+    const sanitised = value
+        .replace(/[^a-zA-Z0-9_]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (sanitised.length === 0) {
+        throw new Error(
+            `Cannot derive a DOM-safe id prefix from "${value}". Pass an explicit idPrefix prop.`
+        );
+    }
+    return sanitised;
+}
+
+/**
+ * Append a child path suffix to a parent path. When the suffix is
+ * omitted (e.g. transparent wrappers like union options), the parent
+ * path is returned unchanged so the child inherits the parent's id.
+ *
+ * Mirror of `react/SchemaComponent.tsx` `joinPath` — bracketed array
+ * indices like `[0]` append directly so `tags` + `[0]` becomes
+ * `tags[0]`, matching the canonical form used by `html/a11y.ts` and
+ * `core/fieldPath.ts`.
+ */
+export function joinPath(parent: string, suffix: string | undefined): string {
+    if (suffix === undefined || suffix.length === 0) return parent;
+    if (parent.length === 0) return suffix;
+    if (suffix.startsWith("[")) return `${parent}${suffix}`;
+    return `${parent}.${suffix}`;
+}
+
+/**
+ * Derive the per-instance id prefix used by the Vue SFCs.
+ *
+ * Prefers Vue 3.5+ `useId()` (which guarantees per-component
+ * uniqueness across SSR/CSR hydration). Older Vue runtimes expose
+ * `useId` as a function returning `undefined` or omit it entirely
+ * — the helper falls back to a monotonic counter scoped to this
+ * module so the resulting prefix is still deterministic and
+ * collision-free within a single render tree.
+ *
+ * Must be called from within a `setup()` invocation: Vue's `useId`
+ * only resolves inside an active component instance.
+ */
+export function deriveIdPrefix(explicit: string | undefined): string {
+    if (explicit !== undefined) return sanitisePrefix(explicit);
+    // Vue's `useId` is typed to always return a string in 3.5+. The
+    // runtime check guards older Vue versions where the export may
+    // be `undefined`.
+    const raw = typeof vueUseId === "function" ? vueUseId() : undefined;
+    if (typeof raw === "string" && raw.length > 0) {
+        return sanitisePrefix(raw);
+    }
+    fallbackCounter += 1;
+    return `sc-vue-${String(fallbackCounter)}`;
+}

package/src/vue/renderField.ts

@@ -0,0 +1,182 @@
+/**
+ * Vue-flavoured wrapper around the framework-agnostic
+ * `dispatchRenderField` from `core/renderField.ts`.
+ *
+ * Constructs a Vue-shaped {@link DispatchConfig} (widget lookup against
+ * the instance → context → global chain, recursion sentinel as a Vue
+ * `<fieldset>` {@link VNode}, fallback as a `<span>`-wrapped value) and
+ * forwards the call. Used by the `<SchemaComponent>` and `<SchemaView>`
+ * SFCs and exported so other Vue surfaces (future API operation
+ * components, etc.) can dispatch into the same fallback chain.
+ *
+ * The widget-lookup contract matches the React adapter exactly:
+ * instance map first, then context map, then global registry. The
+ * dispatcher itself remains agnostic to how widget maps are scoped —
+ * the resolution chain is expressed here in the `lookupWidget`
+ * closure.
+ */
+
+import { h, isVNode, type VNode } from "vue";
+import { dispatchRenderField } from "../core/renderField.ts";
+import type { WalkedField } from "../core/types.ts";
+import { EM_DASH } from "../core/cssClasses.ts";
+import { getVueRenderFunction, mergeVueResolvers } from "./resolver.ts";
+import { headlessVueResolver } from "./headless.ts";
+import type {
+    VueComponentResolver,
+    VueRenderProps,
+    VueWidgetMap,
+} from "./types.ts";
+import { lookupGlobalWidget } from "./widget.ts";
+
+/**
+ * Build the {@link VueRenderProps} object handed to a Vue render
+ * function or widget. Mirrors `buildRenderProps` in `core/renderer.ts`
+ * but emits Vue's `VNode`-returning `renderChild` signature directly so
+ * the dispatcher does not need to cross-cast between React and Vue
+ * shapes at the resolver boundary.
+ */
+function buildVueRenderProps(
+    tree: WalkedField,
+    value: unknown,
+    onChange: (next: unknown) => void,
+    renderChild: VueRenderProps["renderChild"],
+    path: string
+): VueRenderProps {
+    const isReadOnly = tree.editability === "presentation";
+    const isWriteOnly = tree.editability === "input";
+    const props: VueRenderProps = {
+        value,
+        onChange,
+        readOnly: isReadOnly,
+        writeOnly: isWriteOnly,
+        meta: tree.meta,
+        constraints: tree.constraints,
+        path,
+        tree,
+        renderChild,
+    };
+    if (tree.examples !== undefined) props.examples = tree.examples;
+    return props;
+}
+
+/**
+ * Render a single walked field through the resolved widget / resolver
+ * / headless pipeline.
+ *
+ * Thin Vue-flavoured wrapper around {@link dispatchRenderField}: it
+ * constructs a Vue-shaped {@link DispatchConfig} and returns the
+ * dispatcher's {@link VNode} output.
+ *
+ * @param tree - The walked field tree node to render.
+ * @param value - The current value at this position.
+ * @param onChange - Callback invoked when the field emits a change. For
+ *   read-only renders (e.g. `<SchemaView>`) pass a noop.
+ * @param userResolver - User-supplied resolver, or `undefined` to use
+ *   the headless resolver alone.
+ * @param renderChild - Recursive child renderer threaded through
+ *   the {@link VueRenderProps} `renderChild` field.
+ * @param path - Dot-separated structural path; non-empty.
+ * @param instanceWidgets - Per-instance widget map (highest priority).
+ * @param contextWidgets - Context-scoped widget map (middle priority).
+ * @param depth - Recursion depth used by the depth cap in
+ *   {@link dispatchRenderField}.
+ */
+export function vueRenderField(
+    tree: WalkedField,
+    value: unknown,
+    onChange: (v: unknown) => void,
+    userResolver: VueComponentResolver | undefined,
+    renderChild: VueRenderProps["renderChild"],
+    path: string,
+    instanceWidgets?: VueWidgetMap,
+    contextWidgets?: VueWidgetMap,
+    depth = 0
+): VNode {
+    if (path.length === 0) {
+        throw new Error(
+            "vueRenderField requires a non-empty path. Pass the root path " +
+                "(derived from `idPrefix` or `useId()`) for the root field, " +
+                "and use renderChild's pathSuffix to derive child paths."
+        );
+    }
+
+    // Build the merged resolver once per dispatch — user overrides on
+    // top of the headless fallback, mirroring the historic React
+    // behaviour.
+    const resolver: VueComponentResolver =
+        userResolver !== undefined
+            ? mergeVueResolvers(userResolver, headlessVueResolver)
+            : headlessVueResolver;
+
+    return dispatchRenderField<VueRenderProps, VNode, VueComponentResolver>({
+        tree,
+        value,
+        path,
+        depth,
+        resolver,
+        config: {
+            buildProps: (fieldTree, fieldPath) =>
+                buildVueRenderProps(
+                    fieldTree,
+                    value,
+                    onChange,
+                    renderChild,
+                    fieldPath
+                ),
+            lookupRenderFn: (type, mergedResolver) =>
+                getVueRenderFunction(type, mergedResolver),
+            // Widget lookup follows the canonical Vue resolution
+            // order: instance → context → global. Pulled out as a
+            // closure so the dispatcher remains agnostic to how
+            // widget maps are scoped.
+            lookupWidget: (name) =>
+                instanceWidgets?.get(name) ??
+                contextWidgets?.get(name) ??
+                lookupGlobalWidget(name),
+            recursionSentinel: (fieldTree) => {
+                const label =
+                    typeof fieldTree.meta.description === "string"
+                        ? fieldTree.meta.description
+                        : "schema";
+                return h("fieldset", undefined, [
+                    h("em", undefined, `↻ ${label} (recursive)`),
+                ]);
+            },
+            fallback: (_fieldTree, fieldValue) => {
+                if (fieldValue === undefined || fieldValue === null)
+                    return h("span", undefined, EM_DASH);
+                return h(
+                    "span",
+                    undefined,
+                    typeof fieldValue === "string"
+                        ? fieldValue
+                        : JSON.stringify(fieldValue)
+                );
+            },
+            coerceResult: (result, step) => {
+                if (step === "widget") {
+                    if (result === undefined || result === null)
+                        return undefined;
+                    if (isVNode(result)) return result;
+                    // Widget returned a value but not in a Vue-renderable
+                    // shape — wrap it in a span so the output remains a
+                    // valid VNode rather than falling through to the
+                    // resolver.
+                    if (
+                        typeof result === "string" ||
+                        typeof result === "number"
+                    )
+                        return h("span", undefined, String(result));
+                    return h("span");
+                }
+                if (result === undefined || result === null)
+                    return h("span", { style: { display: "none" } });
+                if (isVNode(result)) return result;
+                if (typeof result === "string" || typeof result === "number")
+                    return h("span", undefined, String(result));
+                return undefined;
+            },
+        },
+    });
+}