schema-components 2.1.0 → 2.1.1

package/src/vue/SchemaField.vue

@@ -0,0 +1,178 @@
+<script setup lang="ts">
+/**
+ * `<SchemaField>` — render a single field from a schema by dot-separated
+ * path.
+ *
+ * Vue counterpart of `react/SchemaComponent.tsx`'s `<SchemaField>`.
+ * Walks the full schema tree and resolves the field at the supplied
+ * `path`, then renders only that field through the same Vue resolver
+ * pipeline as `<SchemaComponent>`.
+ *
+ * Useful for embedding individual fields inside bespoke layouts (e.g.
+ * a custom Vue form that lays out address fields manually but still
+ * wants the schema-driven rendering for each).
+ *
+ * @group Components
+ */
+import { computed, toRaw, type VNode } from "vue";
+import { walk } from "../core/walker.ts";
+import type { WalkOptions } from "../core/walkBuilders.ts";
+import { normaliseSchema } from "../core/adapter.ts";
+import {
+    resolvePath,
+    resolveValue,
+    setNestedValue,
+} from "../core/fieldPath.ts";
+import type { SchemaMeta, WalkedField } from "../core/types.ts";
+import {
+    SchemaFieldError,
+    SchemaNormalisationError,
+} from "../core/errors.ts";
+import { VueResolverContext, VueWidgetsContext } from "./contexts.ts";
+import { vueRenderField } from "./renderField.ts";
+import { deriveIdPrefix, joinPath } from "./idPrefix.ts";
+import type { VueRenderProps } from "./types.ts";
+import { VNodeHost } from "./VNodeHost.ts";
+
+const props = withDefaults(
+    defineProps<{
+        /** Dot-separated path to the field (e.g. `"address.city"`). */
+        path: string;
+        /** The schema to extract the field from. */
+        schema: unknown;
+        /** For OpenAPI: a ref string. */
+        refPath?: string;
+        /** Current value of the root object the field belongs to. */
+        modelValue?: unknown;
+        /** Explicit onChange callback. Wired alongside `update:modelValue`. */
+        onChange?: (value: unknown) => void;
+        /** Override meta for this specific field. */
+        meta?: SchemaMeta;
+        /** Deterministic id prefix. Defaults to a per-instance `useId()` value. */
+        idPrefix?: string;
+    }>(),
+    {
+        refPath: undefined,
+        modelValue: undefined,
+        onChange: undefined,
+        meta: () => ({}),
+        idPrefix: undefined,
+    }
+);
+
+const emit = defineEmits<{
+    "update:modelValue": [value: unknown];
+    change: [value: unknown];
+}>();
+
+const contextResolver = VueResolverContext.consume();
+const contextWidgets = VueWidgetsContext.consume();
+
+interface Normalised {
+    jsonSchema: Record<string, unknown>;
+    rootMeta: SchemaMeta | undefined;
+    rootDocument: Record<string, unknown>;
+}
+
+const normalised = computed<Normalised>(() => {
+    try {
+        // See the matching `toRaw` note in `SchemaComponent.vue` —
+        // Zod schemas carry non-configurable members that Vue's
+        // default reactive Proxy cannot mirror.
+        const rawSchema = toRaw(props.schema);
+        const result = normaliseSchema(rawSchema, props.refPath);
+        return {
+            jsonSchema: result.jsonSchema,
+            rootMeta: result.rootMeta,
+            rootDocument: result.rootDocument,
+        };
+    } catch (err) {
+        if (err instanceof SchemaNormalisationError) throw err;
+        throw new SchemaNormalisationError(
+            err instanceof Error ? err.message : "Failed to normalise schema",
+            toRaw(props.schema),
+            "unknown"
+        );
+    }
+});
+
+const fullTree = computed<WalkedField>(() => {
+    const n = normalised.value;
+    const walkOptions: WalkOptions = {
+        componentMeta: props.meta,
+        rootDocument: n.rootDocument,
+    };
+    if (n.rootMeta !== undefined) walkOptions.rootMeta = n.rootMeta;
+    return walk(n.jsonSchema, walkOptions);
+});
+
+const fieldTree = computed<WalkedField>(() => {
+    const found = resolvePath(fullTree.value, props.path);
+    if (found === undefined) {
+        throw new SchemaFieldError(
+            `Field not found: ${props.path}`,
+            toRaw(props.schema),
+            props.path
+        );
+    }
+    return found;
+});
+
+const fieldValue = computed<unknown>(() =>
+    resolveValue(props.modelValue, props.path)
+);
+
+const rootBase = computed(() => deriveIdPrefix(props.idPrefix));
+const rootPath = computed(() => joinPath(rootBase.value, props.path));
+
+function handleFieldChange(nextField: unknown): void {
+    const newRoot = setNestedValue(props.modelValue, props.path, nextField);
+    emit("update:modelValue", newRoot);
+    emit("change", newRoot);
+    props.onChange?.(newRoot);
+}
+
+function makeRenderChild(
+    currentDepth: number,
+    parentPath: string
+): VueRenderProps["renderChild"] {
+    return (
+        childTree: WalkedField,
+        childValue: unknown,
+        childOnChange: (v: unknown) => void,
+        pathSuffix?: string
+    ) => {
+        const childPath = joinPath(parentPath, pathSuffix);
+        return vueRenderField(
+            childTree,
+            childValue,
+            childOnChange,
+            contextResolver,
+            makeRenderChild(currentDepth + 1, childPath),
+            childPath,
+            undefined,
+            contextWidgets,
+            currentDepth + 1
+        );
+    };
+}
+
+const rootVNode = computed<VNode>(() => {
+    const renderChild = makeRenderChild(0, rootPath.value);
+    return vueRenderField(
+        fieldTree.value,
+        fieldValue.value,
+        handleFieldChange,
+        contextResolver,
+        renderChild,
+        rootPath.value,
+        undefined,
+        contextWidgets,
+        0
+    );
+});
+</script>
+
+<template>
+    <VNodeHost :node="rootVNode" />
+</template>

package/src/vue/SchemaProvider.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+/**
+ * `<SchemaProvider>` — provide a theme resolver and scoped widgets to
+ * every `<SchemaComponent>` and `<SchemaView>` rendered inside the
+ * subtree.
+ *
+ * Vue counterpart of the React adapter's `SchemaProvider`. Uses the
+ * abstract `ContextPort` from `core/contexts.ts` (instantiated as
+ * `VueResolverContext` / `VueWidgetsContext` via Vue's `provide` /
+ * `inject`) so the dispatcher remains decoupled from Vue specifics —
+ * the only Vue-specific code is the `provide()` call here and the
+ * matching `inject()` calls inside the consumer SFCs.
+ *
+ * @group Components
+ */
+import { VueResolverContext, VueWidgetsContext } from "./contexts.ts";
+import type { VueComponentResolver, VueWidgetMap } from "./types.ts";
+
+const props = defineProps<{
+    /** The theme adapter that drives every nested `<SchemaComponent>`. */
+    resolver: VueComponentResolver;
+    /** Scoped widgets available to descendants. */
+    widgets?: VueWidgetMap;
+}>();
+
+// Provide both contexts before children render. `VueResolverContext.provide`
+// wraps Vue's `provide()` so the call site does not depend directly on
+// Vue's primitive — the abstraction lives in `core/contexts.ts`.
+// `null` is passed as `children` because Vue's provide model attaches
+// values to the component instance rather than wrapping a children
+// subtree; the port signature keeps the argument for React-adapter
+// compatibility.
+VueResolverContext.provide(props.resolver, null);
+VueWidgetsContext.provide(props.widgets, null);
+</script>
+
+<template>
+    <slot />
+</template>

package/src/vue/SchemaView.vue

@@ -0,0 +1,198 @@
+<script setup lang="ts">
+/**
+ * `<SchemaView>` — read-only Vue renderer.
+ *
+ * Vue counterpart of `react/SchemaView.tsx`. Always renders read-only
+ * output; the dispatch loop is identical to `<SchemaComponent>` but
+ * the `onChange` callback handed to the dispatcher is a noop and
+ * `mergedMeta.readOnly` is forced to `true`.
+ *
+ * SSR story: Vue ships a server renderer (`@vue/server-renderer`)
+ * that emits HTML strings from the same render functions, so this
+ * SFC is safe to use inside a Nuxt server component or a custom
+ * `renderToString` pipeline. Unlike the React Server Component
+ * version, there is no separate RSC restriction — Vue components
+ * have a single rendering model that works in both environments.
+ *
+ * @group Components
+ */
+import { computed, h, toRaw, type VNode } from "vue";
+import { walk } from "../core/walker.ts";
+import type { WalkOptions } from "../core/walkBuilders.ts";
+import { normaliseSchema } from "../core/adapter.ts";
+import type { SchemaMeta, WalkedField } from "../core/types.ts";
+import type { Diagnostic, DiagnosticsOptions } from "../core/diagnostics.ts";
+import { SchemaNormalisationError } from "../core/errors.ts";
+import { toRecordOrUndefined } from "../core/guards.ts";
+import { vueRenderField } from "./renderField.ts";
+import { deriveIdPrefix, joinPath } from "./idPrefix.ts";
+import type {
+    VueComponentResolver,
+    VueRenderProps,
+    VueWidgetMap,
+} from "./types.ts";
+import { VNodeHost } from "./VNodeHost.ts";
+
+const props = withDefaults(
+    defineProps<{
+        /** Zod schema, JSON Schema object, or OpenAPI document. */
+        schema: unknown;
+        /** For OpenAPI: a ref string. */
+        refPath?: string;
+        /** Current value to render. */
+        value?: unknown;
+        /** Meta overrides applied to the root schema. */
+        meta?: SchemaMeta;
+        /** Convenience: sets `description` on the root. */
+        description?: string;
+        /** Per-field meta overrides — nested object mirroring schema shape. */
+        fields?: Record<string, unknown>;
+        /**
+         * Theme resolver. In a Server Component environment you pass
+         * this explicitly because the context-based `<SchemaProvider>`
+         * may not be mounted on the server.
+         */
+        resolver?: VueComponentResolver;
+        /** Instance-scoped widgets. */
+        widgets?: VueWidgetMap;
+        /** Deterministic id prefix. Defaults to a per-instance `useId()` value. */
+        idPrefix?: string;
+        /** Called with each diagnostic emitted during schema processing. */
+        onDiagnostic?: (diagnostic: Diagnostic) => void;
+        /** When `true`, any diagnostic becomes a thrown error. */
+        strict?: boolean;
+    }>(),
+    {
+        refPath: undefined,
+        value: undefined,
+        meta: () => ({}),
+        description: undefined,
+        fields: undefined,
+        resolver: undefined,
+        widgets: undefined,
+        idPrefix: undefined,
+        onDiagnostic: undefined,
+        strict: false,
+    }
+);
+
+const rootPath = computed(() => deriveIdPrefix(props.idPrefix));
+
+const mergedMeta = computed<SchemaMeta>(() => {
+    const merged: SchemaMeta = { ...props.meta, readOnly: true };
+    if (props.description !== undefined) merged.description = props.description;
+    return merged;
+});
+
+const diagnostics = computed<DiagnosticsOptions | undefined>(() => {
+    if (props.onDiagnostic === undefined && !props.strict) return undefined;
+    const opts: DiagnosticsOptions = {};
+    if (props.onDiagnostic !== undefined) opts.diagnostics = props.onDiagnostic;
+    if (props.strict) opts.strict = true;
+    return opts;
+});
+
+interface Normalised {
+    jsonSchema: Record<string, unknown>;
+    rootMeta: SchemaMeta | undefined;
+    rootDocument: Record<string, unknown>;
+}
+
+const normalised = computed<Normalised>(() => {
+    const opts =
+        diagnostics.value !== undefined
+            ? { diagnostics: diagnostics.value }
+            : undefined;
+    try {
+        // `toRaw` peels off Vue's reactive proxy before the schema
+        // crosses into `normaliseSchema`, which expects the bare
+        // object (Zod schemas in particular have non-configurable
+        // `_zod` data members that Vue's default Proxy cannot mirror).
+        // See the matching comment in `SchemaComponent.vue`.
+        const rawSchema = toRaw(props.schema);
+        const result = normaliseSchema(rawSchema, props.refPath, opts);
+        return {
+            jsonSchema: result.jsonSchema,
+            rootMeta: result.rootMeta,
+            rootDocument: result.rootDocument,
+        };
+    } catch (err) {
+        if (err instanceof SchemaNormalisationError) throw err;
+        throw new SchemaNormalisationError(
+            err instanceof Error ? err.message : "Failed to normalise schema",
+            toRaw(props.schema),
+            "unknown"
+        );
+    }
+});
+
+const tree = computed<WalkedField>(() => {
+    const n = normalised.value;
+    const walkOptions: WalkOptions = {
+        componentMeta: mergedMeta.value,
+        rootDocument: n.rootDocument,
+    };
+    if (n.rootMeta !== undefined) walkOptions.rootMeta = n.rootMeta;
+    const fieldsRecord = toRecordOrUndefined(props.fields);
+    if (fieldsRecord !== undefined) walkOptions.fieldOverrides = fieldsRecord;
+    if (diagnostics.value !== undefined)
+        walkOptions.diagnostics = diagnostics.value;
+    return walk(n.jsonSchema, walkOptions);
+});
+
+/** Noop onChange — SchemaView never propagates value changes. */
+function noopChange(): void {
+    /* intentional no-op */
+}
+
+function makeRenderChild(
+    currentDepth: number,
+    parentPath: string
+): VueRenderProps["renderChild"] {
+    return (
+        childTree: WalkedField,
+        childValue: unknown,
+        _childOnChange: (v: unknown) => void,
+        pathSuffix?: string
+    ) => {
+        const childPath = joinPath(parentPath, pathSuffix);
+        return vueRenderField(
+            childTree,
+            childValue,
+            noopChange,
+            props.resolver,
+            makeRenderChild(currentDepth + 1, childPath),
+            childPath,
+            props.widgets,
+            undefined,
+            currentDepth + 1
+        );
+    };
+}
+
+const rootVNode = computed<VNode>(() => {
+    const t = tree.value;
+    const renderChild = makeRenderChild(0, rootPath.value);
+    return vueRenderField(
+        t,
+        props.value ?? t.defaultValue,
+        noopChange,
+        props.resolver,
+        renderChild,
+        rootPath.value,
+        props.widgets,
+        undefined,
+        0
+    );
+});
+
+// Silence the `h` import: kept available for downstream theme adapters
+// that wrap `<SchemaView>` and need to compose extra structure around
+// the render output. The SFC body itself only consumes the computed
+// VNode through `<VNodeHost>`.
+void h;
+</script>
+
+<template>
+    <VNodeHost :node="rootVNode" />
+</template>

package/src/vue/VNodeHost.ts

@@ -0,0 +1,32 @@
+/**
+ * Functional Vue component whose sole job is to render a supplied
+ * `VNode` as its output. The SFC entry points (`SchemaComponent.vue`,
+ * `SchemaView.vue`, `SchemaField.vue`) compute their render output as
+ * a VNode in `setup()` and pass it through a `<VNodeHost :node="vnode" />`
+ * tag so the template body remains a single declarative anchor while
+ * the actual rendering work happens in the dispatcher.
+ *
+ * Why this exists: Vue's `<component :is>` directive expects a
+ * component definition or a tag name string — it does not accept a
+ * bare `VNode`. Returning a render function from a `<script setup>`
+ * block is also not a Vue idiom (the SFC compiler treats the setup
+ * block's exposed bindings as values to surface to the template). A
+ * functional component is the idiomatic seam: it accepts a `node`
+ * prop and returns it from its render function unchanged.
+ *
+ * Functional components in Vue 3 are pure render functions — no
+ * lifecycle, no reactive state — so the only cost is the function
+ * call itself; reactivity continues to flow through the parent SFC's
+ * computed VNode.
+ */
+
+import type { FunctionalComponent, VNode } from "vue";
+
+export const VNodeHost: FunctionalComponent<{ node: VNode }> = (props) => {
+    return props.node;
+};
+
+// Vue's runtime reads `props` off functional components for prop
+// validation; declaring them keeps the warning-free contract that the
+// SFC compiler enforces.
+VNodeHost.props = ["node"];

package/src/vue/contexts.ts

@@ -0,0 +1,116 @@
+/**
+ * Vue implementations of the abstract {@link ContextPort} from
+ * `core/contexts.ts`.
+ *
+ * Each adapter implements the provide / consume port against its native
+ * context primitive. The Vue 3 implementation uses Vue's `provide` and
+ * `inject` (https://vuejs.org/guide/components/provide-inject.html)
+ * keyed by a unique {@link InjectionKey} {@link Symbol} per context so
+ * the two contexts never collide.
+ *
+ * `provide(value, children)` is called from inside a component's
+ * `setup()` (typically the `<SchemaProvider>` SFC) — Vue's `provide`
+ * works on the current component instance and makes the value available
+ * to every descendant calling `inject` with the same key. The `children`
+ * argument is therefore unused by the Vue port (no provider component
+ * is wrapped around children) but kept for {@link ContextPort}
+ * compatibility with React-style ports that DO wrap children. Callers
+ * outside a `setup()` (e.g. ad-hoc render functions) should still go
+ * through this port so future framework changes flow through one place.
+ */
+
+import { inject, provide, type InjectionKey } from "vue";
+import type {
+    ContextPort,
+    ResolverContextShape,
+    WidgetsContextShape,
+} from "../core/contexts.ts";
+
+// ---------------------------------------------------------------------------
+// Injection keys
+// ---------------------------------------------------------------------------
+
+/**
+ * Vue {@link InjectionKey} for the active {@link ResolverContextShape}.
+ *
+ * Exported so theme adapters and downstream Vue components can read or
+ * provide the resolver directly through Vue's `inject` / `provide` —
+ * the {@link VueResolverContext} port wraps these calls but the raw
+ * symbol is available for callers that need custom composition (e.g.
+ * a Pinia store that wants to read the active resolver in an action).
+ */
+export const VUE_RESOLVER_KEY: InjectionKey<ResolverContextShape> = Symbol(
+    "schema-components.vue.resolver"
+);
+
+/**
+ * Vue {@link InjectionKey} for the active {@link WidgetsContextShape}.
+ *
+ * Exported so callers can read or provide the scoped widget map directly
+ * through Vue's `inject` / `provide`.
+ */
+export const VUE_WIDGETS_KEY: InjectionKey<WidgetsContextShape> = Symbol(
+    "schema-components.vue.widgets"
+);
+
+// ---------------------------------------------------------------------------
+// Ports
+// ---------------------------------------------------------------------------
+
+/**
+ * Vue implementation of {@link ContextPort} for the
+ * {@link ResolverContextShape}.
+ *
+ * `provide(value, _children)` calls Vue's `provide(VUE_RESOLVER_KEY, value)`
+ * on the current component instance. The `_children` argument is unused
+ * — Vue's provide model attaches the value to the component instance
+ * rather than wrapping children in a new component — but kept for
+ * {@link ContextPort} compatibility. Returns `undefined` because Vue's
+ * `provide` does not produce a renderable wrapper.
+ *
+ * `consume()` calls `inject(VUE_RESOLVER_KEY, undefined)` and returns
+ * the active resolver, or `undefined` when no provider is mounted in
+ * scope (matching the React adapter's `undefined`-default behaviour).
+ *
+ * Must be called from inside a component's `setup()` — Vue's `provide`
+ * and `inject` both rely on the current component instance, which is
+ * only available during component setup.
+ */
+export const VueResolverContext: ContextPort<ResolverContextShape> = {
+    provide(value: ResolverContextShape, children: unknown): unknown {
+        provide(VUE_RESOLVER_KEY, value);
+        // `children` is unused — Vue's `provide()` attaches the value
+        // to the component instance rather than wrapping a children
+        // subtree — but the {@link ContextPort} signature carries it
+        // for React-style adapters that DO wrap children. `void`
+        // discards the value without triggering the unused-args rule.
+        void children;
+        return undefined;
+    },
+    consume(): ResolverContextShape {
+        return inject(VUE_RESOLVER_KEY, undefined);
+    },
+};
+
+/**
+ * Vue implementation of {@link ContextPort} for the
+ * {@link WidgetsContextShape}. Mirrors {@link VueResolverContext}: a
+ * thin wrapper around Vue's `provide` / `inject` keyed by
+ * {@link VUE_WIDGETS_KEY}.
+ *
+ * Must be called from inside a component's `setup()`.
+ */
+export const VueWidgetsContext: ContextPort<WidgetsContextShape> = {
+    provide(value: WidgetsContextShape, children: unknown): unknown {
+        provide(VUE_WIDGETS_KEY, value);
+        // See the matching `void children` note in
+        // {@link VueResolverContext} — Vue's `provide()` does not wrap
+        // children, but the port keeps the argument for React-style
+        // adapter compatibility.
+        void children;
+        return undefined;
+    },
+    consume(): WidgetsContextShape {
+        return inject(VUE_WIDGETS_KEY, undefined);
+    },
+};

package/src/vue/eventTargets.ts

@@ -0,0 +1,35 @@
+/**
+ * Narrowing helpers for DOM event targets used by the Vue renderers.
+ *
+ * Vue's DOM event handlers receive `Event` whose `target` is typed
+ * `EventTarget | null`. The renderers need the concrete `HTMLInputElement`
+ * / `HTMLSelectElement` to read `value`, `checked`, or `files`. Plain
+ * `event.target as HTMLInputElement` is banned by the project lint
+ * rules (`@typescript-eslint/consistent-type-assertions`), so the
+ * narrowing happens here through `instanceof` checks.
+ *
+ * Returning `undefined` when the target is not the expected element
+ * type lets each caller decide whether to skip the value-extraction
+ * step or treat it as a no-op — both branches are documented at the
+ * call site rather than masked behind a sentinel default.
+ */
+
+/**
+ * Narrow an event to its `HTMLInputElement` target, or `undefined`
+ * when the event was fired on a different element type.
+ */
+export function inputTarget(event: Event): HTMLInputElement | undefined {
+    const target = event.target;
+    if (target instanceof HTMLInputElement) return target;
+    return undefined;
+}
+
+/**
+ * Narrow an event to its `HTMLSelectElement` target, or `undefined`
+ * when the event was fired on a different element type.
+ */
+export function selectTarget(event: Event): HTMLSelectElement | undefined {
+    const target = event.target;
+    if (target instanceof HTMLSelectElement) return target;
+    return undefined;
+}

package/src/vue/headless.ts

@@ -0,0 +1,61 @@
+/**
+ * Vue headless renderer — the default {@link VueComponentResolver}
+ * implementation.
+ *
+ * Produces plain Vue {@link VNode}s for every schema field type. Theme
+ * adapters replace this by implementing {@link VueComponentResolver}
+ * with their own components.
+ *
+ * Composes the resolver from the individual render functions in
+ * `vue/renderers.ts`. Every {@link WalkedField} variant the walker can
+ * emit has a registered renderer — missing a registration causes
+ * {@link getVueRenderFunction} to return `undefined` and the field to
+ * render as nothing.
+ */
+
+import type { VueComponentResolver } from "./types.ts";
+import {
+    renderArray,
+    renderBoolean,
+    renderConditional,
+    renderDiscriminatedUnion,
+    renderEnum,
+    renderFile,
+    renderLiteral,
+    renderNegation,
+    renderNever,
+    renderNull,
+    renderNumber,
+    renderObject,
+    renderRecord,
+    renderString,
+    renderTuple,
+    renderUnion,
+    renderUnknown,
+} from "./renderers.ts";
+
+/**
+ * The Vue headless resolver. Maps every {@link WalkedField} variant to
+ * its default render function. Mirrors `react/headless.tsx`'s
+ * `headlessResolver` so consumers can switch between adapters without
+ * losing field coverage.
+ */
+export const headlessVueResolver: VueComponentResolver = {
+    string: renderString,
+    number: renderNumber,
+    boolean: renderBoolean,
+    null: renderNull,
+    enum: renderEnum,
+    object: renderObject,
+    record: renderRecord,
+    array: renderArray,
+    tuple: renderTuple,
+    union: renderUnion,
+    discriminatedUnion: renderDiscriminatedUnion,
+    conditional: renderConditional,
+    negation: renderNegation,
+    literal: renderLiteral,
+    file: renderFile,
+    never: renderNever,
+    unknown: renderUnknown,
+};