schema-components 2.0.2 → 2.1.1

package/src/svelte/types.ts

@@ -0,0 +1,238 @@
+/**
+ * Svelte 5 adapter type surface for schema-components.
+ *
+ * Mirrors the shape of `core/renderer.ts`'s React-flavoured
+ * {@link "../core/renderer.ts".RenderProps} but adapts it for Svelte's
+ * compile-time component model: renderers are not plain functions
+ * returning VNodes — they are component constructors. The dispatcher
+ * therefore packages each "render this field" call as a
+ * {@link SvelteRenderDescriptor} pairing the component with the props
+ * it should be instantiated against; downstream the active container
+ * component (e.g. `Object.svelte`) materialises the descriptor via
+ * `<svelte:component this={component} {...props} />`.
+ *
+ * The shapes intentionally diverge from the React adapter on two axes:
+ *
+ *   1. `renderChild` returns a {@link SvelteRenderDescriptor} rather
+ *      than a `ReactNode`. Svelte cannot directly embed an object
+ *      synthesised at render time the way React embeds a JSX node — but
+ *      it can `<svelte:component>` a `{ component, props }` pair.
+ *   2. There is no synthetic event system, so `onChange` is plumbed
+ *      directly into the per-field props and invoked from raw DOM
+ *      handlers (`onchange`, `oninput`) inside each `.svelte` file.
+ *
+ * The public consumer pattern is `<SchemaComponent schema value onChange?\>` —
+ * Svelte's `bind:value` ergonomics are deliberately not forced.
+ * The function-style `onChange` callback was chosen so the
+ * adapter behaves identically across server-rendered (`SchemaView`),
+ * controlled-input, and uncontrolled-input call sites; consumers that
+ * prefer `bind:value` can wire it externally:
+ *
+ * ```svelte
+ * <SchemaComponent {schema} bind:value />
+ * ```
+ *
+ * which Svelte transparently translates into an `onChange` that mutates
+ * the bound rune-backed reference.
+ *
+ * @group Framework Adapters
+ */
+
+import type { Component } from "svelte";
+import type {
+    BaseFieldProps,
+    BaseRenderProps,
+    RenderFunction,
+} from "../core/renderer.ts";
+import type { WalkedField } from "../core/types.ts";
+
+/**
+ * Descriptor produced by {@link SvelteRenderProps.renderChild} and by
+ * the dispatcher when materialising a single field. Pairs the Svelte
+ * component constructor with the props it should be instantiated
+ * against so a parent renderer can mount it via
+ * `<svelte:component this={component} {...props} />`.
+ *
+ * Returning a descriptor (rather than a rendered DOM node) keeps the
+ * adapter compatible with Svelte's compile-time component model — the
+ * dispatcher does not own a DOM mount point and cannot fabricate
+ * rendered output the way React's `renderField` returns a `ReactNode`.
+ *
+ * `null` indicates "render nothing" — used for empty arrays in
+ * read-only mode and for the recursion-cap sentinel placeholder when
+ * the caller opts to suppress it.
+ */
+export interface SvelteRenderDescriptor {
+    /** Svelte component constructor to mount. */
+    readonly component: SvelteComponentConstructor;
+    /** Props to pass to the component instance. */
+    readonly props: SvelteRenderProps;
+}
+
+/**
+ * The raw Svelte 5 component constructor type. Aliased so consumers
+ * have a single name to import — `Component<SvelteRenderProps>` is
+ * exact, but reading {@link SvelteComponentConstructor} at call sites
+ * keeps the framework dependency localised to this module.
+ */
+export type SvelteComponentConstructor = Component<SvelteRenderProps>;
+
+/**
+ * Props passed to every Svelte 5 renderer component.
+ *
+ * Specialisation of {@link BaseRenderProps} with
+ * `Output = SvelteRenderDescriptor | null`. Each renderer receives
+ * these as `$props()` — the per-field data, the editability flags,
+ * the constraint bundle, and the `renderChild` factory it should
+ * invoke for nested structures (object fields, array elements, union
+ * options, …).
+ *
+ * Mirrors the React {@link "../core/renderer.ts".RenderProps} shape
+ * — `onChange` for value propagation, four-argument `renderChild`
+ * for recursive descent.
+ */
+export interface SvelteRenderProps extends BaseRenderProps<SvelteRenderDescriptor | null> {
+    /** Callback to update the field value. */
+    onChange: (value: unknown) => void;
+    /**
+     * Render a child field. Container renderers (object, array,
+     * tuple, record, union, discriminated union, conditional,
+     * negation) call this and mount the returned descriptor via
+     * `<svelte:component this={component} {...props} />`.
+     *
+     * @param tree - The walked field tree for the child.
+     * @param value - The child's current value.
+     * @param onChange - Callback receiving the child's next value.
+     * @param pathSuffix - Path segment from the parent (e.g. "city",
+     *   "[0]"). Joined to the parent's path with a dot, or
+     *   substituted when the parent acts as a transparent wrapper
+     *   (union options). Required for every container — without it
+     *   children inherit no path and `fieldDomId()` will throw.
+     */
+    renderChild: (
+        tree: WalkedField,
+        value: unknown,
+        onChange: (v: unknown) => void,
+        pathSuffix?: string
+    ) => SvelteRenderDescriptor | null;
+}
+
+/**
+ * Signature for a render function attached to a
+ * {@link SvelteComponentResolver}.
+ *
+ * Unlike React — where `RenderFunction` directly produces a
+ * `ReactNode` — the Svelte equivalent produces a
+ * {@link SvelteRenderDescriptor}. The descriptor pairs a component
+ * constructor with the per-field props and is mounted by the parent
+ * renderer via `<svelte:component>`. This indirection is the price
+ * of Svelte's compile-time component model: the dispatcher cannot
+ * fabricate rendered DOM at runtime, so it returns a recipe for the
+ * parent to mount.
+ *
+ * Specialisation of the generic
+ * {@link "../core/renderer.ts".RenderFunction | RenderFunction} from
+ * `core/renderer.ts` with
+ * `Output = SvelteRenderDescriptor | null` and
+ * `Props = SvelteRenderProps`.
+ */
+export type SvelteRenderFunction = RenderFunction<
+    SvelteRenderDescriptor | null,
+    SvelteRenderProps
+>;
+
+/**
+ * Helper: wrap a Svelte component constructor into the
+ * "render function" shape consumed by the dispatcher. Pairs the
+ * supplied component with the per-field props.
+ *
+ * Used by {@link "./headless.ts".headlessSvelteResolver} to register
+ * one constructor per schema type, and exposed publicly so theme
+ * adapter authors can compose their own resolver from `.svelte`
+ * files without re-implementing the wrapper.
+ *
+ * @param component - A Svelte 5 component constructor accepting
+ *   {@link SvelteRenderProps}.
+ * @returns A {@link SvelteRenderFunction} that, given props, returns
+ *   the descriptor `{ component, props }`.
+ */
+export function makeSvelteRenderer(
+    component: SvelteComponentConstructor
+): SvelteRenderFunction {
+    return (props) => ({ component, props });
+}
+
+/**
+ * Theme adapter — maps every schema field type to a Svelte
+ * {@link SvelteRenderFunction}. Unset keys fall back to the headless
+ * resolver.
+ *
+ * Pass to {@link "./contexts.ts".resolverContext} (via the
+ * `SchemaProvider` Svelte component) so a single theme drives every
+ * schema render in a subtree.
+ *
+ * Structurally parallel to
+ * {@link "../core/renderer.ts".ComponentResolver} for React, but
+ * each value is a {@link SvelteRenderFunction} returning a
+ * {@link SvelteRenderDescriptor} rather than a render function
+ * returning a `ReactNode`.
+ */
+export interface SvelteComponentResolver {
+    string?: SvelteRenderFunction;
+    number?: SvelteRenderFunction;
+    boolean?: SvelteRenderFunction;
+    null?: SvelteRenderFunction;
+    enum?: SvelteRenderFunction;
+    object?: SvelteRenderFunction;
+    array?: SvelteRenderFunction;
+    tuple?: SvelteRenderFunction;
+    record?: SvelteRenderFunction;
+    union?: SvelteRenderFunction;
+    discriminatedUnion?: SvelteRenderFunction;
+    conditional?: SvelteRenderFunction;
+    negation?: SvelteRenderFunction;
+    literal?: SvelteRenderFunction;
+    file?: SvelteRenderFunction;
+    never?: SvelteRenderFunction;
+    unknown?: SvelteRenderFunction;
+}
+
+/**
+ * Widget map — maps component hints (from `.meta({ component })`) to
+ * Svelte {@link SvelteRenderFunction}s. Mirrors the React
+ * {@link "../core/renderer.ts".WidgetMap} but each value is a
+ * Svelte-flavoured render function (typically produced via
+ * {@link makeSvelteRenderer}).
+ *
+ * Scoped at three levels in the Svelte adapter:
+ *
+ *   1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
+ *   2. **Context-scoped** — `widgets` prop on `<SchemaProvider>`
+ *   3. **Global** — `registerWidget()` (app-wide defaults)
+ */
+export type SvelteWidgetMap = ReadonlyMap<string, SvelteRenderFunction>;
+
+/**
+ * Compile-time assertion that {@link SvelteRenderFunction} is a
+ * specialisation of the generic {@link RenderFunction} contract from
+ * `core/renderer.ts`. Exercised by the type-level test in
+ * `tests/svelte/typeTest.svelte.unit.test.ts` — a regression on the
+ * alignment fails compilation rather than silently producing
+ * incompatible adapters.
+ *
+ * @internal
+ */
+export type __SvelteRenderFunctionMatchesGenericRenderFunction =
+    SvelteRenderFunction extends RenderFunction<
+        SvelteRenderDescriptor | null,
+        SvelteRenderProps
+    >
+        ? true
+        : false;
+
+/**
+ * Re-export of {@link BaseFieldProps} so consumers writing custom
+ * Svelte renderers can import a single type covering the schema-data
+ * shape without crossing the framework adapter boundary.
+ */
+export type { BaseFieldProps };

package/src/svelte/widget.ts

@@ -0,0 +1,62 @@
+/**
+ * Global widget registry for the Svelte adapter.
+ *
+ * Mirrors the React adapter's `registerWidget()` / `globalWidgets`
+ * pair in `react/SchemaComponent.tsx`. Each registered entry is a
+ * Svelte component constructor (`Component<SvelteRenderProps>`)
+ * matched against `.meta({ component })` hints on a walked field.
+ *
+ * Resolution order (from {@link "./SchemaComponent.svelte" |
+ * SchemaComponent}'s dispatch wiring): instance widgets → context
+ * widgets → global widgets → resolver render fn → headless fallback.
+ *
+ * The global registry is module-level mutable state; tests should
+ * clear it with {@link __clearGlobalWidgets} to avoid leaking
+ * registrations across cases.
+ *
+ * @group Framework Adapters
+ */
+
+import type { SvelteRenderFunction } from "./types.ts";
+
+const globalWidgets = new Map<string, SvelteRenderFunction>();
+
+/**
+ * Register a Svelte widget globally. The widget is resolved when a
+ * schema field has `.meta({ component: name })` and no per-instance
+ * or context-scoped widget map provides a matching entry.
+ *
+ * For scoped registration, supply the `widgets` prop on
+ * `<SchemaComponent>` or `<SchemaProvider>` instead.
+ */
+export function registerWidget(
+    name: string,
+    component: SvelteRenderFunction
+): void {
+    globalWidgets.set(name, component);
+}
+
+/**
+ * Look up a globally registered Svelte widget by hint name. Returns
+ * `undefined` when nothing matches — callers fall back to the
+ * resolver chain.
+ *
+ * @internal Used by the Svelte dispatcher wiring inside
+ *   `SchemaComponent.svelte`; not part of the public surface.
+ */
+export function lookupGlobalWidget(
+    name: string
+): SvelteRenderFunction | undefined {
+    return globalWidgets.get(name);
+}
+
+/**
+ * Clear every globally registered Svelte widget. Intended for test
+ * isolation — `registerWidget` writes to module-level state and that
+ * state otherwise leaks across test cases.
+ *
+ * @internal
+ */
+export function __clearGlobalWidgets(): void {
+    globalWidgets.clear();
+}

package/src/vue/SchemaComponent.vue

@@ -0,0 +1,274 @@
+<script setup lang="ts">
+/**
+ * `<SchemaComponent>` — Vue counterpart of the React `<SchemaComponent>`.
+ *
+ * Auto-detects the input format, normalises to JSON Schema via the
+ * adapter, walks the JSON Schema tree, and delegates per-field
+ * rendering to the {@link VueComponentResolver} supplied via
+ * `<SchemaProvider>` — falling back to the headless renderer when no
+ * provider is present.
+ *
+ * `onChange` semantics: the component accepts BOTH a `v-model`
+ * binding (Vue-idiomatic — `modelValue` prop +
+ * `update:modelValue` emit) and an explicit `onChange` callback prop
+ * (matching the React adapter). It also emits a `change` event for
+ * Vue authors who prefer event listeners. All three surfaces fire
+ * together so consumers may use whichever idiom suits them.
+ *
+ * @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 { VueResolverContext, VueWidgetsContext } from "./contexts.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 like `#/components/schemas/User`. */
+        refPath?: string;
+        /** v-model binding for the current value. */
+        modelValue?: unknown;
+        /**
+         * Explicit `onChange` callback — wired in parallel with
+         * `update:modelValue` so consumers may use either surface.
+         */
+        onChange?: (value: unknown) => void;
+        /** Convenience: sets `readOnly` on all fields. */
+        readOnly?: boolean;
+        /** Convenience: sets `writeOnly` on all fields. */
+        writeOnly?: boolean;
+        /** Convenience: sets `description` on the root. */
+        description?: string;
+        /** Meta overrides applied to the root schema. */
+        meta?: SchemaMeta;
+        /** Per-field meta overrides — nested object mirroring schema shape. */
+        fields?: Record<string, unknown>;
+        /** Theme resolver. Overrides the context resolver when supplied. */
+        resolver?: VueComponentResolver;
+        /** Instance-scoped widgets — override context and global 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;
+        /** Called when schema normalisation fails. */
+        onError?: (error: SchemaNormalisationError) => void;
+    }>(),
+    {
+        refPath: undefined,
+        modelValue: undefined,
+        onChange: undefined,
+        readOnly: false,
+        writeOnly: false,
+        description: undefined,
+        meta: () => ({}),
+        fields: undefined,
+        resolver: undefined,
+        widgets: undefined,
+        idPrefix: undefined,
+        onDiagnostic: undefined,
+        strict: false,
+        onError: undefined,
+    }
+);
+
+const emit = defineEmits<{
+    "update:modelValue": [value: unknown];
+    change: [value: unknown];
+}>();
+
+// Consume the resolver and widget contexts. Both ports return
+// `undefined` when no provider is mounted in scope — the dispatcher
+// then falls through to the headless resolver.
+const contextResolver = VueResolverContext.consume();
+const contextWidgets = VueWidgetsContext.consume();
+
+const rootPath = computed(() => deriveIdPrefix(props.idPrefix));
+
+const mergedMeta = computed<SchemaMeta>(() => {
+    const merged: SchemaMeta = { ...props.meta };
+    if (props.readOnly) merged.readOnly = true;
+    if (props.writeOnly) merged.writeOnly = 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>;
+    error?: SchemaNormalisationError;
+}
+
+const normalised = computed<Normalised>(() => {
+    try {
+        const opts =
+            diagnostics.value !== undefined
+                ? { diagnostics: diagnostics.value }
+                : undefined;
+        // Vue wraps every reactive prop in a Proxy. Zod 4 schemas
+        // carry non-configurable internal data members (`_zod`) that
+        // the default reactivity proxy cannot mirror — accessing them
+        // through the proxy throws. `toRaw` recovers the original
+        // object before passing it into `normaliseSchema`, which does
+        // not need (and should not see) Vue's reactivity layer. The
+        // same fix is applied to `props.modelValue` further down for
+        // consistency with the React adapter, which receives raw
+        // values directly.
+        const rawSchema = toRaw(props.schema);
+        const result = normaliseSchema(rawSchema, props.refPath, opts);
+        return {
+            jsonSchema: result.jsonSchema,
+            rootMeta: result.rootMeta,
+            rootDocument: result.rootDocument,
+        };
+    } catch (err) {
+        const error =
+            err instanceof SchemaNormalisationError
+                ? err
+                : new SchemaNormalisationError(
+                      err instanceof Error
+                          ? err.message
+                          : "Failed to normalise schema",
+                      toRaw(props.schema),
+                      "unknown"
+                  );
+        return {
+            jsonSchema: {},
+            rootMeta: undefined,
+            rootDocument: {},
+            error,
+        };
+    }
+});
+
+const tree = computed<WalkedField | undefined>(() => {
+    const n = normalised.value;
+    if (n.error !== undefined) return undefined;
+    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);
+});
+
+const effectiveValue = computed<unknown>(() => {
+    if (props.modelValue !== undefined) return props.modelValue;
+    return tree.value?.defaultValue;
+});
+
+function handleChange(next: unknown): void {
+    emit("update:modelValue", next);
+    // Vue auto-wires any `onChange="…"` template attribute as a
+    // `change` event listener (the same `on<Event>` convention React
+    // uses for synthetic events). To avoid invoking the same handler
+    // twice — once via `emit("change", …)` and once via
+    // `props.onChange(…)` — we emit the event when no explicit prop
+    // handler was supplied, and call the prop directly otherwise.
+    // Both paths are observable to consumers but never overlap.
+    if (props.onChange !== undefined) {
+        props.onChange(next);
+    } else {
+        emit("change", next);
+    }
+}
+
+/**
+ * Build the recursive `renderChild` closure. Each invocation increments
+ * the depth counter so the dispatcher's `MAX_RENDER_DEPTH` cap fires
+ * on truly recursive structures rather than on shallow trees.
+ */
+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,
+            props.resolver ?? contextResolver,
+            makeRenderChild(currentDepth + 1, childPath),
+            childPath,
+            props.widgets,
+            contextWidgets,
+            currentDepth + 1
+        );
+    };
+}
+
+/**
+ * Reactive root VNode. Recomputed whenever any reactive dependency
+ * (props, contexts, tree) changes. The template renders it via
+ * `<component :is="rootVNode">` — Vue accepts a VNode object as the
+ * target of `:is`, which lets us drive the render from a render
+ * function while keeping the SFC `<template>` block as the single
+ * mount point.
+ */
+const rootVNode = computed<VNode>(() => {
+    const t = tree.value;
+    if (t === undefined) {
+        const err = normalised.value.error;
+        if (err !== undefined) {
+            if (props.onError !== undefined) {
+                props.onError(err);
+                return h("span", { style: { display: "none" } });
+            }
+            throw err;
+        }
+        return h("span", { style: { display: "none" } });
+    }
+    const renderChild = makeRenderChild(0, rootPath.value);
+    return vueRenderField(
+        t,
+        effectiveValue.value,
+        handleChange,
+        props.resolver ?? contextResolver,
+        renderChild,
+        rootPath.value,
+        props.widgets,
+        contextWidgets,
+        0
+    );
+});
+</script>
+
+<template>
+    <VNodeHost :node="rootVNode" />
+</template>

package/src/vue/SchemaErrorBoundary.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+/**
+ * `<SchemaErrorBoundary>` — Vue counterpart of the React
+ * `SchemaErrorBoundary`.
+ *
+ * Uses Vue 3's `onErrorCaptured` lifecycle hook
+ * (https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured)
+ * to catch render-time errors thrown by any descendant — including
+ * the dispatcher-wrapped `SchemaRenderError` from theme adapters that
+ * throw inside their render function. Returning `false` from
+ * `onErrorCaptured` halts further propagation up the component tree.
+ *
+ * The fallback slot is invoked with the captured error and a `reset`
+ * callback. Calling `reset()` clears the captured error so the
+ * children re-render (e.g. after fixing a bad schema prop).
+ *
+ * Like the React boundary, this captures render-time and lifecycle
+ * errors but NOT errors thrown from event handlers (Vue routes those
+ * through a separate `errorHandler` on the app instance) or async
+ * code that escapes the component tree.
+ *
+ * @group Components
+ */
+import { onErrorCaptured, ref } from "vue";
+
+const captured = ref<Error | undefined>(undefined);
+
+defineSlots<{
+    /**
+     * Default slot — rendered when no error has been captured.
+     */
+    default(): unknown;
+    /**
+     * Fallback slot — invoked with the captured error and a `reset`
+     * callback. Use it to render an error UI; call `reset` to clear
+     * the captured state and let the children re-render.
+     */
+    fallback(props: { error: Error; reset: () => void }): unknown;
+}>();
+
+onErrorCaptured((err) => {
+    captured.value =
+        err instanceof Error ? err : new Error("Unknown render error");
+    return false;
+});
+
+function reset(): void {
+    captured.value = undefined;
+}
+</script>
+
+<template>
+    <slot
+        v-if="captured !== undefined"
+        name="fallback"
+        :error="captured"
+        :reset="reset"
+    />
+    <slot v-else />
+</template>