schema-components 2.0.1 → 2.1.0

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();
+}