schema-components 2.0.2 → 2.1.1

package/dist/core/renderField.d.mts

@@ -0,0 +1,147 @@
+import { j as WalkedField } from "../types-BBQaEPfE.mjs";
+import { l as RenderFunction } from "../renderer-ab9E52Bp.mjs";
+
+//#region src/core/renderField.d.ts
+/**
+ * Per-adapter configuration consumed by {@link dispatchRenderField}.
+ *
+ * Each adapter (React, HTML, future Vue / Solid / Svelte / Lit) supplies
+ * one of these to plug its own per-field-props shape, output type, and
+ * fallback/error behaviour into the shared dispatch loop without having
+ * the dispatcher hardcode any framework-specific imports.
+ *
+ * @typeParam Props - The shape of the per-field props passed to render
+ *   functions and widgets (e.g. `RenderProps` for React,
+ *   `HtmlRenderProps` for HTML).
+ * @typeParam Output - The type each render function and widget emits
+ *   for a single field (e.g. `unknown` / `ReactNode` for React,
+ *   `string` for HTML).
+ * @typeParam Resolver - The resolver shape that maps schema types to
+ *   render functions (e.g. `ComponentResolver` for React,
+ *   `HtmlResolver` for HTML).
+ */
+interface DispatchConfig<Props, Output, Resolver> {
+  /**
+   * Build the per-field props handed to the render function or widget
+   * when it is about to be invoked. Called at most once per dispatch
+   * — adapters that need the same props for both the widget lookup
+   * and the resolver lookup may call it twice through the
+   * `dispatchRenderField` boundary.
+   */
+  buildProps: (tree: WalkedField, path: string) => Props;
+  /**
+   * Look up a render function for `tree.type` in the resolver. Each
+   * adapter wires this to its own `getRenderFunction` /
+   * `getHtmlRenderFn` lookup so the dispatcher does not need to know
+   * which resolver shape applies.
+   *
+   * The returned render function's output is typed `unknown` rather
+   * than `Output` so adapters whose render functions historically
+   * returned a broader type (React's
+   * `RenderFunction\<unknown, RenderProps\>`) compose naturally. The
+   * dispatcher hands the `unknown` return value to
+   * {@link DispatchConfig.coerceResult}, which narrows it to
+   * `Output` once per dispatch.
+   */
+  lookupRenderFn: (type: WalkedField["type"], resolver: Resolver) => RenderFunction<unknown, Props> | undefined;
+  /**
+   * Produce the output emitted when the dispatcher hits
+   * {@link MAX_RENDER_DEPTH}. Adapters return their own sentinel
+   * (React: a `<fieldset>` element; HTML: the `recursionSentinelHtml`
+   * string; etc.) so the caller decides how to mark recursive
+   * positions in the rendered output.
+   */
+  recursionSentinel: (tree: WalkedField) => Output;
+  /**
+   * Produce the output emitted when no widget or resolver render
+   * function handled the field. Most adapters either return a
+   * `<span>` of the stringified value (React) or throw — the
+   * dispatcher does not interpret the return value, only forwards
+   * it.
+   */
+  fallback: (tree: WalkedField, value: unknown, path: string) => Output;
+  /**
+   * Coerce the raw `unknown` return value of a render function or
+   * widget into the adapter's `Output` type, or `undefined` if the
+   * result should be discarded (so the dispatcher falls through to
+   * the next step).
+   *
+   * The `step` argument identifies which dispatch stage produced
+   * the result — `"widget"` for a `.meta({ component })` match,
+   * `"resolver"` for the per-type render function. The two cases
+   * historically differed in how they treated `null` /
+   * `undefined` returns (widget falls through; resolver
+   * short-circuits with `null` so empty-array suppressions render
+   * nothing), and adapters can preserve that asymmetry by
+   * branching on `step`.
+   *
+   * Each adapter applies its own validity check here — React
+   * narrows via `isValidElement`/string/number, HTML treats every
+   * string as valid, etc. Returning `undefined` makes the
+   * dispatcher behave as if no renderer produced output.
+   */
+  coerceResult: (result: unknown, step: "widget" | "resolver") => Output | undefined;
+  /**
+   * Optional widget-lookup hook. When present, the dispatcher
+   * consults it before the resolver lookup. Called once per
+   * dispatch with the value of `tree.meta.component`; should
+   * return the registered render function or `undefined` if no
+   * widget matches. The returned function's output type matches
+   * the resolver lookup (`unknown`) — see
+   * {@link DispatchConfig.lookupRenderFn}.
+   */
+  lookupWidget?: (name: string) => RenderFunction<unknown, Props> | undefined;
+  /**
+   * Wrap a render-time error in a {@link SchemaRenderError} (or a
+   * caller-specified subclass) so every adapter routes thrown
+   * errors through the same structured path. Called only for
+   * errors thrown by the resolver render function — widget errors
+   * propagate without wrapping, matching the historic React
+   * behaviour where widgets are user code at the application
+   * boundary.
+   */
+  wrapRenderError?: (err: unknown, tree: WalkedField, path: string) => Error;
+}
+/**
+ * Arguments accepted by {@link dispatchRenderField}.
+ *
+ * @typeParam Props - The per-field props shape.
+ * @typeParam Output - The adapter's per-field output type.
+ * @typeParam Resolver - The resolver shape mapping schema types to
+ *   render functions.
+ */
+interface DispatchArgs<Props, Output, Resolver> {
+  /** The walked field to render. */
+  tree: WalkedField;
+  /** The data value at this position in the tree. */
+  value: unknown;
+  /** Dot-separated path from the schema root. */
+  path: string;
+  /** Recursion depth — incremented by callers as they descend. */
+  depth: number;
+  /** The merged resolver to look up the per-type render function on. */
+  resolver: Resolver;
+  /** The dispatch configuration for the active adapter. */
+  config: DispatchConfig<Props, Output, Resolver>;
+}
+/**
+ * Framework-agnostic dispatch loop shared by the React, HTML, and
+ * future adapters. See the module-level documentation for the fixed
+ * dispatch order.
+ *
+ * The dispatcher itself is intentionally side-effect free — it never
+ * imports React, never builds HTML strings, and never reads any global
+ * state. Adapter-specific work (widget registry lookup, recursion
+ * sentinel construction, result coercion, error wrapping) is supplied
+ * via the {@link DispatchConfig} argument.
+ *
+ * @typeParam Props - The per-field props shape.
+ * @typeParam Output - The adapter's per-field output type.
+ * @typeParam Resolver - The resolver shape.
+ * @returns The output produced by the matched widget, render function,
+ *   or fallback — exactly one of the four dispatch steps always emits
+ *   a value.
+ */
+declare function dispatchRenderField<Props, Output, Resolver>(args: DispatchArgs<Props, Output, Resolver>): Output;
+//#endregion
+export { DispatchArgs, DispatchConfig, dispatchRenderField };

package/dist/core/renderField.mjs

@@ -0,0 +1,115 @@
+import "./limits.mjs";
+import { SchemaRenderError } from "./errors.mjs";
+//#region src/core/renderField.ts
+/**
+* Framework-generic render-field dispatcher.
+*
+* Centralises the dispatch loop shared by the React `SchemaComponent` /
+* `SchemaView` renderers, the synchronous HTML renderer in
+* `renderToHtml`, the streaming HTML renderer in `streamRenderers.ts`
+* (for its leaf path — see "Streaming integration" below), and (in
+* the future) Vue / Solid / Svelte / Lit adapters. The dispatcher is
+* intentionally framework-agnostic: it neither imports React nor
+* produces HTML strings directly. Each adapter supplies a small
+* {@link DispatchConfig} describing how to build per-field props, how
+* to handle a successful or absent resolver lookup, and (optionally)
+* how to handle widget overrides and the recursion-depth cap.
+*
+* The dispatch order is fixed and matches the historic React-side
+* behaviour so the React, HTML, and future adapters all observe the
+* same resolution chain:
+*
+*   1. Depth cap — when `depth >= MAX_RENDER_DEPTH`, return the
+*      adapter's recursion sentinel without invoking any renderer.
+*   2. Widget override — if a `.meta({ component })` hint matches a
+*      registered widget, call it. A non-empty result short-circuits.
+*   3. Resolver render function — look up `tree.type` in the supplied
+*      resolver and call it. Render-time errors are wrapped via
+*      {@link DispatchConfig.wrapRenderError} so every adapter routes
+*      thrown errors through the same {@link SchemaRenderError} path.
+*   4. Fallback — when no renderer produced output, return the
+*      adapter's `fallback` output.
+*
+* The helpers that find render functions, merge resolvers, and build
+* the per-field props live in {@link "./renderer.ts"} and are reused
+* here — `core/renderField.ts` is purely the dispatch shell.
+*
+* # Streaming integration (design choice B)
+*
+* The streaming HTML renderer (`html/streamRenderers.ts` +
+* `html/renderToHtmlStream.ts`) consumes this dispatcher for leaf
+* field types — `string`, `number`, `boolean`, `enum`, `literal`,
+* `file`, `unknown` — and for variants without a dedicated streaming
+* generator (`null`, `tuple`, `conditional`, `negation`, `never`).
+* Container types (`object`, `array`, `record`, `union`,
+* `discriminatedUnion`) keep bespoke generator implementations
+* because the dispatcher's single-output contract cannot express the
+* "yield opening tag → recurse into children → yield closing tag"
+* chunk-boundary semantics that streaming depends on.
+*
+* We deliberately chose this approach (the Phase 1 agent's "option
+* B" — leaves dispatch through the shared loop, containers keep their
+* own iteration) over the alternative of building a generator-output
+* mode into the dispatcher itself. Approach B preserves the existing
+* chunk boundaries byte-for-byte while still eliminating the duplicate
+* resolver-lookup logic that previously lived in `renderLeaf`. A
+* generator-aware dispatcher would require either a parallel "stream
+* resolver" shape or a unified return type wide enough to cover both
+* single-output and iterable cases — neither of which is justified by
+* the small amount of dispatch logic the leaf path needs.
+*
+* The streaming `streamField` function performs its own depth check
+* before invoking the dispatcher for leaf paths. The check appears
+* textually in both places (streamField and this dispatcher) but at
+* runtime fires exactly once per recursion step: streamField's guard
+* filters the streaming path, and the dispatcher's guard remains in
+* place for the sync HTML and React callers that do not pre-filter
+* depth themselves. See `html/streamRenderers.ts` for the matching
+* commentary.
+*/
+/**
+* Framework-agnostic dispatch loop shared by the React, HTML, and
+* future adapters. See the module-level documentation for the fixed
+* dispatch order.
+*
+* The dispatcher itself is intentionally side-effect free — it never
+* imports React, never builds HTML strings, and never reads any global
+* state. Adapter-specific work (widget registry lookup, recursion
+* sentinel construction, result coercion, error wrapping) is supplied
+* via the {@link DispatchConfig} argument.
+*
+* @typeParam Props - The per-field props shape.
+* @typeParam Output - The adapter's per-field output type.
+* @typeParam Resolver - The resolver shape.
+* @returns The output produced by the matched widget, render function,
+*   or fallback — exactly one of the four dispatch steps always emits
+*   a value.
+*/
+function dispatchRenderField(args) {
+	const { tree, value, path, depth, resolver, config } = args;
+	if (depth >= 10) return config.recursionSentinel(tree);
+	const componentHint = tree.meta.component;
+	if (config.lookupWidget !== void 0 && typeof componentHint === "string") {
+		const widget = config.lookupWidget(componentHint);
+		if (widget !== void 0) {
+			const rawResult = widget(config.buildProps(tree, path));
+			const coerced = config.coerceResult(rawResult, "widget");
+			if (coerced !== void 0) return coerced;
+		}
+	}
+	const renderFn = config.lookupRenderFn(tree.type, resolver);
+	if (renderFn !== void 0) {
+		let rawResult;
+		try {
+			rawResult = renderFn(config.buildProps(tree, path));
+		} catch (err) {
+			if (config.wrapRenderError !== void 0) throw config.wrapRenderError(err, tree, path);
+			throw new SchemaRenderError(err instanceof Error ? err.message : `Render function threw for type "${tree.type}"`, tree, tree.type, err);
+		}
+		const coerced = config.coerceResult(rawResult, "resolver");
+		if (coerced !== void 0) return coerced;
+	}
+	return config.fallback(tree, value, path);
+}
+//#endregion
+export { dispatchRenderField };

package/dist/core/renderer.d.mts

@@ -1,199 +1,2 @@
-import { E as StringConstraints, f as FileConstraints, j as WalkedField, t as ArrayConstraints, w as SchemaMeta, x as ObjectConstraints, y as NumberConstraints } from "../types-BrYbjC7_.mjs";
-
-//#region src/core/renderer.d.ts
-/**
- * Flat intersection of all constraint types.
- * Used in renderer props where the render function receives the union
- * but knows (by resolver key) which subset applies.
- *
- * The walker's discriminated WalkedField enforces type-correct constraints
- * at construction time; the renderer consumes them as this flat type.
- */
-type AllConstraints = StringConstraints & NumberConstraints & ArrayConstraints & ObjectConstraints & FileConstraints;
-/**
- * Properties available on every schema field, regardless of rendering target.
- * Both React and HTML renderers receive these.
- *
- * Per-type schema data — enum values, object fields, array element schema,
- * union options, record key/value types, tuple `prefixItems`, conditional
- * if/then/else clauses, negation `negated`, recursive `refTarget`, literal
- * values — lives on the discriminated `tree`. Renderers narrow on
- * `tree.type` and read from the matching variant; there are no duplicate
- * sibling fields on these props.
- */
-interface BaseFieldProps {
-  /** Current field value. */
-  value: unknown;
-  /** Whether to render as read-only display. */
-  readOnly: boolean;
-  /** Whether to render as an empty input. */
-  writeOnly: boolean;
-  /** Schema metadata for this field. */
-  meta: SchemaMeta;
-  /** Constraints from schema checks. */
-  constraints: AllConstraints;
-  /** Dot-separated path from root (e.g. "address.city"). */
-  path: string;
-  /** Example values from the schema's `examples` keyword. */
-  examples?: unknown[];
-  /** Walked field tree for recursive rendering. */
-  tree: WalkedField;
-}
-/**
- * Props for React render functions. Extends BaseFieldProps with:
- * - `onChange` — callback to propagate value changes back to state
- * - `renderChild` — recursively renders a child field, threading onChange
- */
-interface RenderProps extends BaseFieldProps {
-  /** Callback to update the field value. */
-  onChange: (value: unknown) => void;
-  /**
-   * Render a child field. Theme adapters call this to recursively render
-   * nested structures (object fields, array elements, union options).
-   * The resolver and rendering context are already wired in.
-   *
-   * @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 `inputId()` will throw.
-   */
-  renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void, pathSuffix?: string) => unknown;
-}
-/**
- * Props for HTML render functions. Extends BaseFieldProps with:
- * - `renderChild` — recursively renders a child field to HTML string
- *
- * No `onChange` — HTML rendering is pure output with no event handling.
- */
-interface HtmlRenderProps extends BaseFieldProps {
-  /**
-   * Render a child field to an HTML string. Theme adapters call this
-   * to recursively render nested structures.
-   *
-   * @param tree - The walked field tree for the child
-   * @param value - The child's current value
-   * @param pathSuffix - Path segment from the parent (e.g. "city",
-   *   "[0]"). When omitted, the child's description is used as fallback.
-   */
-  renderChild: (tree: WalkedField, value: unknown, pathSuffix?: string) => string;
-}
-/**
- * Build the `RenderProps` object handed to a resolver render function or a
- * widget. Used by both the server-side `<SchemaView>` (which has no
- * `onChange`) and the client-side `<SchemaComponent>` (which threads an
- * `onChange` callback).
- *
- * When `onChange` is `undefined` the caller is rendering in read-only mode:
- * a noop `onChange` is wired up, `readOnly` is forced to `true`, and
- * `writeOnly` is forced to `false`. Otherwise the editability is taken
- * from `tree.editability`.
- */
-declare function buildRenderProps(tree: WalkedField, value: unknown, onChange: ((next: unknown) => void) | undefined, renderChild: RenderProps["renderChild"], path: string): RenderProps;
-/**
- * Signature for a React render function attached to a
- * {@link ComponentResolver}. Receives the per-field {@link RenderProps}
- * built by the walker and returns any ReactNode-compatible value.
- */
-type RenderFunction = (props: RenderProps) => unknown;
-/**
- * Widget map — maps component hints (from `.meta({ component })`) to render
- * functions. A per-render bag consumed by every renderer surface that
- * dispatches widget overrides; conceptually parallel to
- * {@link ComponentResolver} but keyed by user-supplied hint names rather
- * than schema types.
- *
- * Scoped at three levels in the React renderer:
- *
- * 1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
- * 2. **Context-scoped** — `widgets` prop on `<SchemaProvider>`
- * 3. **Global** — `registerWidget()` (app-wide defaults)
- *
- * Resolution order: instance → context → global → resolver → headless.
- */
-type WidgetMap = ReadonlyMap<string, RenderFunction>;
-/**
- * Theme adapter — maps every schema field type to its React renderer.
- * Unset keys fall back to the headless resolver. Pass to
- * `SchemaProvider` (or `SchemaView.resolver`) to drive every
- * schema-driven render with a specific theme.
- */
-interface ComponentResolver {
-  string?: RenderFunction;
-  number?: RenderFunction;
-  boolean?: RenderFunction;
-  null?: RenderFunction;
-  enum?: RenderFunction;
-  object?: RenderFunction;
-  array?: RenderFunction;
-  tuple?: RenderFunction;
-  record?: RenderFunction;
-  union?: RenderFunction;
-  discriminatedUnion?: RenderFunction;
-  conditional?: RenderFunction;
-  negation?: RenderFunction;
-  literal?: RenderFunction;
-  file?: RenderFunction;
-  never?: RenderFunction;
-  unknown?: RenderFunction;
-}
-/** An HTML render function returns a string. */
-type HtmlRenderFunction = (props: HtmlRenderProps) => string;
-/**
- * HTML resolver — maps schema types to HTML string renderers.
- * Structurally mirrors ComponentResolver but produces strings.
- */
-interface HtmlResolver {
-  string?: HtmlRenderFunction;
-  number?: HtmlRenderFunction;
-  boolean?: HtmlRenderFunction;
-  null?: HtmlRenderFunction;
-  enum?: HtmlRenderFunction;
-  object?: HtmlRenderFunction;
-  array?: HtmlRenderFunction;
-  tuple?: HtmlRenderFunction;
-  record?: HtmlRenderFunction;
-  union?: HtmlRenderFunction;
-  discriminatedUnion?: HtmlRenderFunction;
-  conditional?: HtmlRenderFunction;
-  negation?: HtmlRenderFunction;
-  literal?: HtmlRenderFunction;
-  file?: HtmlRenderFunction;
-  never?: HtmlRenderFunction;
-  unknown?: HtmlRenderFunction;
-}
-/**
- * Canonical list of resolver keys, one per {@link WalkedField} variant.
- * Iterated by the resolver merge helpers so adding a new key here is the
- * single point of change when a new field variant is introduced.
- */
-declare const RESOLVER_KEYS: readonly ["string", "number", "boolean", "null", "enum", "object", "array", "tuple", "record", "union", "discriminatedUnion", "conditional", "negation", "literal", "file", "never", "unknown"];
-type ResolverKey = (typeof RESOLVER_KEYS)[number];
-/**
- * Map a schema type to the resolver key that handles it.
- * Every WalkedField variant has a direct resolver key — exhaustive switch
- * ensures new variants surface as a type error rather than silently
- * falling through to "unknown".
- */
-declare function typeToKey(type: WalkedField["type"]): ResolverKey;
-/**
- * Look up the render function for a schema type in a ComponentResolver.
- */
-declare function getRenderFunction(type: WalkedField["type"], resolver: ComponentResolver): RenderFunction | undefined;
-/**
- * Look up the render function for a schema type in an HtmlResolver.
- */
-declare function getHtmlRenderFn(type: WalkedField["type"], resolver: HtmlResolver): HtmlRenderFunction | undefined;
-/**
- * Merge two ComponentResolvers — user values take priority, fallback fills gaps.
- */
-declare function mergeResolvers(user: ComponentResolver, fallback: ComponentResolver): ComponentResolver;
-/**
- * Merge two HtmlResolvers — user values take priority, fallback fills gaps.
- */
-declare function mergeHtmlResolvers(user: HtmlResolver, fallback: HtmlResolver): HtmlResolver;
-//#endregion
-export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, WidgetMap, buildRenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };
+import { _ as typeToKey, a as HtmlRenderFunction, c as RESOLVER_KEYS, d as WidgetMap, f as buildRenderProps, g as mergeResolvers, h as mergeHtmlResolvers, i as ComponentResolver, l as RenderFunction, m as getRenderFunction, n as BaseFieldProps, o as HtmlRenderProps, p as getHtmlRenderFn, r as BaseRenderProps, s as HtmlResolver, t as AllConstraints, u as RenderProps } from "../renderer-ab9E52Bp.mjs";
+export { AllConstraints, BaseFieldProps, BaseRenderProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, WidgetMap, buildRenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/swagger2.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-BTrm3O6J.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-mftUZI7c.mjs";
 import { NodeTransform } from "./normalise.mjs";
 
 //#region src/core/swagger2.d.ts