schema-components 2.0.1 → 2.1.0

package/src/svelte/SchemaErrorBoundary.svelte

@@ -0,0 +1,66 @@
+<!--
+    Svelte 5 error boundary for schema-components.
+
+    Uses Svelte 5's native `<svelte:boundary>` primitive (introduced
+    in Svelte 5) — the structural equivalent of the React class
+    component `componentDidCatch` / `getDerivedStateFromError`
+    pattern from `react/SchemaErrorBoundary.tsx`.
+
+    Catches synchronous render errors thrown by descendant
+    components (including `<SchemaComponent>` / `<SchemaView>` and
+    any custom theme adapter renderers). The boundary surfaces the
+    caught `Error` to the supplied `fallback` snippet alongside a
+    `reset` callback that clears the error state — Svelte's boundary
+    primitive owns the state internally; the snippet just receives
+    whichever helpers Svelte passes to it.
+
+    Mirrors the React boundary's documentation: this primitive does
+    NOT catch errors thrown from event handlers, async work, or
+    server-side rendering. Those must be handled at the host
+    application boundary.
+-->
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    import { SchemaError } from "../core/errors.ts";
+
+    interface Props {
+        /** Rendered while no error is in flight. */
+        children: Snippet;
+        /**
+         * Rendered when the boundary catches an error. Receives the
+         * thrown `Error` and a `reset` thunk that re-renders the
+         * children once the underlying problem is fixed (e.g. a
+         * corrected `schema` prop).
+         */
+        fallback: Snippet<[Error, () => void]>;
+    }
+
+    const { children, fallback }: Props = $props();
+
+    function logIfUnexpected(error: unknown): void {
+        // Non-SchemaError thrown values are forwarded to the
+        // console so the application has at least one signal in the
+        // logs. SchemaError instances are presumed handled by the
+        // `onError` callback on `<SchemaComponent>` / `<SchemaView>`.
+        if (!(error instanceof SchemaError)) {
+            // Diagnostic surface mirroring the React adapter — the
+            // boundary's contract is "log the unexpected, surface
+            // structured errors through `failed`".
+            console.error("[schema-components] Unhandled render error:", error);
+        }
+    }
+</script>
+
+<svelte:boundary
+    onerror={(error) => {
+        logIfUnexpected(error);
+    }}
+>
+    {@render children()}
+    {#snippet failed(error, reset)}
+        {@render fallback(
+            error instanceof Error ? error : new Error(String(error)),
+            reset
+        )}
+    {/snippet}
+</svelte:boundary>

package/src/svelte/SchemaField.svelte

@@ -0,0 +1,216 @@
+<!--
+    Render a single field from a schema by dot-separated `path`.
+    Mirror of `react/SchemaComponent.tsx :: SchemaField`.
+
+    Walks the full schema tree, resolves the field at `path`, and
+    renders only that subtree. Useful for embedding individual
+    fields inside bespoke layouts when `<SchemaComponent>` would
+    render too much.
+-->
+<script lang="ts" generics="T = unknown, Ref extends string | undefined = undefined">
+    import { walk } from "../core/walker.ts";
+    import type { WalkOptions } from "../core/walkBuilders.ts";
+    import {
+        normaliseSchema,
+        type SchemaIoSide,
+    } from "../core/adapter.ts";
+    import {
+        SchemaNormalisationError,
+        SchemaFieldError,
+    } from "../core/errors.ts";
+    import type { SchemaMeta, WalkedField } from "../core/types.ts";
+    import {
+        resolvePath,
+        resolveValue,
+        setNestedValue,
+    } from "../core/fieldPath.ts";
+    import { resolverContext, widgetsContext } from "./contexts.ts";
+    import { renderFieldSvelte } from "./dispatch.ts";
+    import RecursionSentinel from "./renderers/RecursionSentinel.svelte";
+    import Fallback from "./renderers/Fallback.svelte";
+    import Mount from "./renderers/Mount.svelte";
+    import type {
+        SvelteRenderDescriptor,
+        SvelteRenderProps,
+    } from "./types.ts";
+
+    interface Props {
+        /** Dot-separated path (e.g. "address.city"). */
+        path: string;
+        /** The schema to extract the field from. */
+        schema: T;
+        /** OpenAPI ref string. */
+        ref?: Ref;
+        /** Direction (`"output"` / `"input"`) for codec / transform schemas. */
+        io?: SchemaIoSide;
+        /** Current value of the root schema. */
+        value?: unknown;
+        /** Called with the updated root value when this field changes. */
+        onChange?: (value: unknown) => void;
+        /** Override meta for this specific field. */
+        meta?: SchemaMeta;
+        /**
+         * Prefix used for every input `id` / label `for` in this
+         * subtree. Defaults to a sanitised, mount-stable counter.
+         */
+        idPrefix?: string;
+    }
+
+    const {
+        path,
+        schema,
+        ref,
+        io,
+        value,
+        onChange,
+        meta: fieldMeta,
+        idPrefix,
+    }: Props = $props();
+
+    const userResolver = resolverContext.consume();
+    const contextWidgets = widgetsContext.consume();
+
+    const fallbackPrefix = `sc-svelte-field-${String(nextFieldInstanceId())}`;
+    const rootPath = $derived(joinPath(idPrefix ?? fallbackPrefix, path));
+
+    interface NormalisedShape {
+        jsonSchema: Record<string, unknown>;
+        rootMeta: SchemaMeta | undefined;
+        rootDocument: Record<string, unknown>;
+    }
+
+    const normalisedResult = $derived<NormalisedShape>(
+        normaliseOrThrow(schema, ref, io)
+    );
+
+    const walkOptions = $derived<WalkOptions>({
+        ...(fieldMeta !== undefined ? { componentMeta: fieldMeta } : {}),
+        ...(normalisedResult.rootMeta !== undefined
+            ? { rootMeta: normalisedResult.rootMeta }
+            : {}),
+        rootDocument: normalisedResult.rootDocument,
+    });
+
+    const fullTree = $derived(walk(normalisedResult.jsonSchema, walkOptions));
+
+    const fieldTree = $derived<WalkedField>(
+        resolvePathOrThrow(fullTree, path, schema)
+    );
+
+    const fieldValue = $derived(resolveValue(value, path));
+
+    function handleChange(nextFieldValue: unknown): void {
+        const newRootValue = setNestedValue(value, path, nextFieldValue);
+        onChange?.(newRootValue);
+    }
+
+    function makeRenderChild(
+        currentDepth: number,
+        parentPath: string
+    ): SvelteRenderProps["renderChild"] {
+        return (
+            childTree: WalkedField,
+            childValue: unknown,
+            childOnChange: (v: unknown) => void,
+            pathSuffix?: string
+        ): SvelteRenderDescriptor | null => {
+            const childPath = joinPath(parentPath, pathSuffix);
+            return renderFieldSvelte(
+                childTree,
+                childValue,
+                childOnChange,
+                userResolver,
+                makeRenderChild(currentDepth + 1, childPath),
+                childPath,
+                undefined,
+                contextWidgets,
+                currentDepth + 1,
+                Fallback,
+                RecursionSentinel
+            );
+        };
+    }
+
+    const renderChild = $derived(makeRenderChild(0, rootPath));
+
+    const rootDescriptor = $derived<SvelteRenderDescriptor | null>(
+        renderFieldSvelte(
+            fieldTree,
+            fieldValue,
+            handleChange,
+            userResolver,
+            renderChild,
+            rootPath,
+            undefined,
+            contextWidgets,
+            0,
+            Fallback,
+            RecursionSentinel
+        )
+    );
+
+    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}`;
+    }
+
+    function normaliseOrThrow(
+        schemaInput: unknown,
+        refInput: string | undefined,
+        ioSide: SchemaIoSide | undefined
+    ): NormalisedShape {
+        try {
+            const opts =
+                ioSide !== undefined ? { io: ioSide } : undefined;
+            const out = normaliseSchema(schemaInput, refInput, opts);
+            return out;
+        } catch (err: unknown) {
+            if (err instanceof SchemaNormalisationError) throw err;
+            throw new SchemaNormalisationError(
+                err instanceof Error
+                    ? err.message
+                    : "Failed to normalise schema",
+                schemaInput,
+                "unknown"
+            );
+        }
+    }
+
+    function resolvePathOrThrow(
+        tree: WalkedField,
+        p: string,
+        schemaInput: unknown
+    ): WalkedField {
+        const resolved = resolvePath(tree, p);
+        if (resolved === undefined) {
+            throw new SchemaFieldError(
+                `Field not found: ${p}`,
+                schemaInput,
+                p
+            );
+        }
+        return resolved;
+    }
+</script>
+
+<script lang="ts" module>
+    let fieldInstanceCounter = 0;
+    /**
+     * Module-scoped counter feeding the default `idPrefix` for every
+     * `<SchemaField>` instance. Separate from the `<SchemaComponent>`
+     * and `<SchemaView>` counters so the three namespaces never
+     * overlap.
+     *
+     * @returns The next per-instance integer (1, 2, …).
+     */
+    export function nextFieldInstanceId(): number {
+        fieldInstanceCounter += 1;
+        return fieldInstanceCounter;
+    }
+</script>
+
+{#if rootDescriptor !== null}
+    <Mount descriptor={rootDescriptor} />
+{/if}

package/src/svelte/SchemaProvider.svelte

@@ -0,0 +1,46 @@
+<!--
+    Provide a theme resolver and scoped widgets to every
+    `<SchemaComponent>` and `<SchemaView>` rendered inside the
+    subtree. Mirror of `react/SchemaComponent.tsx :: SchemaProvider`
+    for Svelte 5.
+
+    Sets the resolver and widget map via `setContext()`
+    (`./contexts.ts :: resolverContext`, `widgetsContext`) so any
+    descendant calling `resolverContext.consume()` or
+    `widgetsContext.consume()` receives the supplied values.
+    `<SchemaComponent>` calls those consume hooks on mount and will
+    therefore pick up the provided theme automatically.
+-->
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    import { resolverContext, widgetsContext } from "./contexts.ts";
+    import type { SvelteComponentResolver, SvelteWidgetMap } from "./types.ts";
+
+    interface Props {
+        /** Theme resolver to install for the subtree. */
+        resolver: SvelteComponentResolver;
+        /** Scoped widgets — override per-instance and global widgets. */
+        widgets?: SvelteWidgetMap;
+        children: Snippet;
+    }
+
+    const { resolver, widgets, children }: Props = $props();
+
+    // Svelte's `setContext` is one-shot per component mount; the
+    // provide port returns its `children` argument so the call site
+    // gets a familiar value-returning shape, but the actual context
+    // wiring happens as a side effect. Reactive updates to
+    // `resolver` / `widgets` after mount intentionally do not
+    // propagate — matches the React adapter's
+    // `<UserResolverContext.Provider value={resolver}>` semantics
+    // where re-rendering the provider with a new value would update
+    // consumers; here we contract the value as mount-fixed and
+    // recommend re-mounting the subtree when the theme changes.
+
+    /* svelte-ignore state_referenced_locally */
+    resolverContext.provide(resolver, undefined);
+    /* svelte-ignore state_referenced_locally */
+    widgetsContext.provide(widgets, undefined);
+</script>
+
+{@render children()}

package/src/svelte/SchemaView.svelte

@@ -0,0 +1,244 @@
+<!--
+    Read-only Svelte 5 schema renderer — counterpart to
+    `<SchemaComponent>` for SSR / hydration / display-only use.
+
+    Mirror of `react/SchemaView.tsx`. Receives the same prop bag but
+    drops `onChange`, `validate`, `onValidationError`, and `onError`
+    — the read-only path has no interactive state and no validation
+    to dispatch. The theme adapter is passed via the `resolver` prop
+    rather than `<SchemaProvider>` so the component remains usable in
+    Svelte's SSR pass without depending on context propagation.
+
+    Internally, the dispatcher chain is identical to
+    `<SchemaComponent>` — `renderFieldSvelte` from `./dispatch.ts`
+    handles the depth cap, widget overrides, resolver dispatch, and
+    recursion sentinel. The only differences are:
+
+      - `readOnly` is forced to `true` on the merged meta.
+      - `onChange` is a noop (no event handlers fire; every renderer
+        observes `readOnly === true` and skips wiring DOM handlers).
+      - No global widget lookup — Svelte SSR mustn't read
+        module-level mutable state.
+-->
+<script lang="ts" generics="T = unknown, Ref extends string | undefined = undefined">
+    import { walk } from "../core/walker.ts";
+    import type { WalkOptions } from "../core/walkBuilders.ts";
+    import {
+        normaliseSchema,
+        type SchemaIoSide,
+    } from "../core/adapter.ts";
+    import { SchemaNormalisationError } from "../core/errors.ts";
+    import type { SchemaMeta, WalkedField } from "../core/types.ts";
+    import { toRecordOrUndefined } from "../core/guards.ts";
+    import type {
+        DiagnosticsOptions,
+        Diagnostic,
+    } from "../core/diagnostics.ts";
+    import type {
+        InferFields,
+        InferredValue,
+    } from "../core/inferValue.ts";
+    import { renderFieldSvelte } from "./dispatch.ts";
+    import RecursionSentinel from "./renderers/RecursionSentinel.svelte";
+    import Fallback from "./renderers/Fallback.svelte";
+    import Mount from "./renderers/Mount.svelte";
+    import type {
+        SvelteComponentResolver,
+        SvelteRenderDescriptor,
+        SvelteRenderProps,
+        SvelteWidgetMap,
+    } from "./types.ts";
+
+    interface Props {
+        schema: T;
+        ref?: Ref;
+        io?: SchemaIoSide;
+        value?: InferredValue<T, Ref, undefined, "output">;
+        fields?: InferFields<T, Ref>;
+        meta?: SchemaMeta;
+        description?: string;
+        /** Theme resolver — Svelte SSR has no context fallthrough, pass explicitly. */
+        resolver?: SvelteComponentResolver;
+        /** Instance-scoped widgets. */
+        widgets?: SvelteWidgetMap;
+        onDiagnostic?: (diagnostic: Diagnostic) => void;
+        strict?: boolean;
+        idPrefix?: string;
+    }
+
+    const {
+        schema,
+        ref,
+        io,
+        value,
+        fields,
+        meta: componentMeta,
+        description,
+        resolver,
+        widgets,
+        onDiagnostic,
+        strict,
+        idPrefix,
+    }: Props = $props();
+
+    /**
+     * Per-mount fallback prefix — matches `<SchemaComponent>`'s
+     * default so a `<SchemaView>` and a sibling `<SchemaComponent>`
+     * on the same page can never collide.
+     */
+    const fallbackPrefix = `sc-svelte-view-${String(nextViewInstanceId())}`;
+    const rootPath = $derived(idPrefix ?? fallbackPrefix);
+
+    const mergedMeta = $derived<SchemaMeta>({
+        ...componentMeta,
+        readOnly: true,
+        ...(description !== undefined ? { description } : {}),
+    });
+
+    const diagnostics: DiagnosticsOptions | undefined = $derived(
+        onDiagnostic !== undefined || strict === true
+            ? {
+                  ...(onDiagnostic !== undefined
+                      ? { diagnostics: onDiagnostic }
+                      : {}),
+                  ...(strict !== undefined ? { strict } : {}),
+              }
+            : undefined
+    );
+
+    interface NormalisedShape {
+        jsonSchema: Record<string, unknown>;
+        rootMeta: SchemaMeta | undefined;
+        rootDocument: Record<string, unknown>;
+    }
+
+    const normalisedResult = $derived<NormalisedShape>(
+        normaliseOrThrow(schema, ref, io, diagnostics)
+    );
+
+    const fieldsRecord = $derived(toRecordOrUndefined(fields));
+
+    const walkOptions = $derived<WalkOptions>({
+        componentMeta: mergedMeta,
+        ...(normalisedResult.rootMeta !== undefined
+            ? { rootMeta: normalisedResult.rootMeta }
+            : {}),
+        ...(fieldsRecord !== undefined
+            ? { fieldOverrides: fieldsRecord }
+            : {}),
+        rootDocument: normalisedResult.rootDocument,
+        ...(diagnostics !== undefined ? { diagnostics } : {}),
+    });
+
+    const tree = $derived<WalkedField>(
+        walk(normalisedResult.jsonSchema, walkOptions)
+    );
+
+    function readOnlyOnChange(_v: unknown): void {
+        /* intentional no-op — SchemaView is read-only. */
+    }
+
+    function makeRenderChild(
+        currentDepth: number,
+        parentPath: string
+    ): SvelteRenderProps["renderChild"] {
+        return (
+            childTree: WalkedField,
+            childValue: unknown,
+            _childOnChange: (v: unknown) => void,
+            pathSuffix?: string
+        ): SvelteRenderDescriptor | null => {
+            const childPath = joinPath(parentPath, pathSuffix);
+            return renderFieldSvelte(
+                childTree,
+                childValue,
+                readOnlyOnChange,
+                resolver,
+                makeRenderChild(currentDepth + 1, childPath),
+                childPath,
+                widgets,
+                undefined,
+                currentDepth + 1,
+                Fallback,
+                RecursionSentinel
+            );
+        };
+    }
+
+    const renderChild = $derived(makeRenderChild(0, rootPath));
+
+    const rootDescriptor = $derived<SvelteRenderDescriptor | null>(
+        renderFieldSvelte(
+            tree,
+            value ?? tree.defaultValue,
+            readOnlyOnChange,
+            resolver,
+            renderChild,
+            rootPath,
+            widgets,
+            undefined,
+            0,
+            Fallback,
+            RecursionSentinel
+        )
+    );
+
+    /**
+     * Path-suffix join, mirror of `SchemaComponent.svelte :: joinPath`
+     * and `react/SchemaComponent.tsx :: joinPath`.
+     */
+    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}`;
+    }
+
+    function normaliseOrThrow(
+        schemaInput: unknown,
+        refInput: string | undefined,
+        ioSide: SchemaIoSide | undefined,
+        diags: DiagnosticsOptions | undefined
+    ): NormalisedShape {
+        try {
+            const opts =
+                diags !== undefined || ioSide !== undefined
+                    ? {
+                          ...(diags !== undefined ? { diagnostics: diags } : {}),
+                          ...(ioSide !== undefined ? { io: ioSide } : {}),
+                      }
+                    : undefined;
+            const out = normaliseSchema(schemaInput, refInput, opts);
+            return out;
+        } catch (err: unknown) {
+            if (err instanceof SchemaNormalisationError) throw err;
+            throw new SchemaNormalisationError(
+                err instanceof Error
+                    ? err.message
+                    : "Failed to normalise schema",
+                schemaInput,
+                "unknown"
+            );
+        }
+    }
+</script>
+
+<script lang="ts" module>
+    let viewInstanceCounter = 0;
+    /**
+     * Module-scoped counter feeding the default `idPrefix` for every
+     * `<SchemaView>` instance. Separate from the `<SchemaComponent>`
+     * counter so the two namespaces never overlap; ids stay unique
+     * across all schema-driven Svelte components on a page.
+     *
+     * @returns The next per-instance integer (1, 2, …).
+     */
+    export function nextViewInstanceId(): number {
+        viewInstanceCounter += 1;
+        return viewInstanceCounter;
+    }
+</script>
+
+{#if rootDescriptor !== null}
+    <Mount descriptor={rootDescriptor} />
+{/if}

package/src/svelte/a11y.ts

@@ -0,0 +1,112 @@
+/**
+ * Shared ARIA attribute helpers for Svelte 5 renderers.
+ *
+ * Mirror of `react/a11y.ts` returning the same shapes — plain
+ * `Record<string, string>` spreadable attribute bags and a
+ * {@link HintInfo} descriptor for the constraint-hint `<small>`
+ * element — so theme adapters compose around the same accessibility
+ * primitives the headless renderer emits.
+ *
+ * Keep this module aligned with `react/a11y.ts` and `html/a11y.ts` —
+ * all renderers must emit the same accessibility metadata for the
+ * same schema field. The constraint-hint text builder
+ * (`core/constraintHint.ts`) is the single source of truth for hint
+ * copy; this module wires it into Svelte-flavoured attribute bags
+ * and hint descriptors.
+ */
+
+import type { AllConstraints } from "../core/renderer.ts";
+import type { WalkedField } from "../core/types.ts";
+import { hintIdFor } from "../core/idPath.ts";
+import { constraintHint as coreConstraintHint } from "../core/constraintHint.ts";
+
+/**
+ * Build the ARIA attribute bundle for a Svelte renderer.
+ *
+ * - `aria-required="true"` whenever the field is non-optional.
+ * - `aria-describedby=<hint-id>` whenever a constraint hint applies.
+ * - `aria-label=<description>` when a non-empty description is
+ *   supplied via the `description` argument.
+ *
+ * Returns a plain `Record<string, string>` so callers can spread the
+ * result into any HTML element type without per-element TypeScript
+ * widening. Svelte's `{...attrs}` spread accepts the record directly.
+ */
+export function buildAriaAttrs(
+    tree: WalkedField,
+    description?: unknown,
+    inputId?: string,
+    constraints?: AllConstraints
+): Record<string, string> {
+    const attrs: Record<string, string> = {};
+    if (tree.isOptional === false) {
+        attrs["aria-required"] = "true";
+    }
+    if (
+        inputId !== undefined &&
+        constraints !== undefined &&
+        coreConstraintHint(constraints) !== undefined
+    ) {
+        attrs["aria-describedby"] = hintIdFor(inputId);
+    }
+    if (typeof description === "string" && description.length > 0) {
+        attrs["aria-label"] = description;
+    }
+    return attrs;
+}
+
+/**
+ * Description for a constraint hint emitted alongside an input.
+ *
+ * Returned by {@link buildHintInfo} when the field carries one or
+ * more constraint keywords worth announcing (min / max length,
+ * pattern without format, item count, …). Theme adapters render this
+ * as a `<small>` wired to the input via `aria-describedby`.
+ */
+export interface HintInfo {
+    /** DOM id matching {@link hintIdFor}(inputId) on the host input. */
+    readonly id: string;
+    /** Human-readable hint text. */
+    readonly hint: string;
+    /** Same value as {@link id}, exposed under the React-aligned name. */
+    readonly ariaDescribedBy: string;
+}
+
+/**
+ * Build {@link HintInfo} for a field at `inputId` given its declared
+ * constraints. Returns `undefined` when no constraint message would
+ * be produced — the Svelte renderers then skip emitting the hint
+ * element entirely so consumers don't see an empty `<small>`.
+ */
+export function buildHintInfo(
+    inputId: string,
+    constraints: AllConstraints
+): HintInfo | undefined {
+    const hint = coreConstraintHint(constraints);
+    if (hint === undefined) return undefined;
+    const id = hintIdFor(inputId);
+    return { id, hint, ariaDescribedBy: id };
+}
+
+/**
+ * Narrow `meta.description` (typed `unknown`) to a string value safe
+ * to pass into an `aria-label` attribute. Returns `undefined` for
+ * non-string or empty-string descriptions so Svelte drops the
+ * attribute rather than stringifying e.g. `{}` to
+ * `"[object Object]"`.
+ */
+export function ariaLabel(description: unknown): string | undefined {
+    if (typeof description !== "string") return undefined;
+    if (description.length === 0) return undefined;
+    return description;
+}
+
+/**
+ * True when the supplied field is non-optional and therefore
+ * deserves a visual required indicator alongside its label. Exposed
+ * as a predicate (rather than a built element) so theme adapters can
+ * choose any presentation.
+ */
+export function isFieldRequired(tree: WalkedField): boolean {
+    return tree.isOptional === false;
+}