schema-components 2.0.1 → 2.1.0

package/dist/renderer-ab9E52Bp.d.mts

@@ -0,0 +1,245 @@
+import { E as StringConstraints, f as FileConstraints, j as WalkedField, t as ArrayConstraints, w as SchemaMeta, x as ObjectConstraints, y as NumberConstraints } from "./types-BBQaEPfE.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;
+}
+/**
+ * Framework-agnostic base for the props passed to every render
+ * function. Extends {@link BaseFieldProps} with a `renderChild`
+ * callable whose return type is parameterised over `Output` — the type
+ * the framework adapter emits per field (typically `unknown` /
+ * `ReactNode` for React, `string` for HTML, framework-specific for
+ * future Vue / Solid / Svelte / Lit adapters).
+ *
+ * The base `renderChild` is declared with a `...args: never[]` rest
+ * parameter so derived adapter interfaces can override it with a
+ * richer signature carrying extra required arguments (React's
+ * `onChange`, HTML's `pathSuffix`, etc.). The `never[]` rest makes the
+ * base callable signature the bottom of the function-subtype lattice:
+ * every adapter's concrete `renderChild` is assignable to it because
+ * `never` accepts any parameter type contravariantly. The base
+ * therefore documents the shared shape — "given a `WalkedField` and a
+ * value, produce an `Output`" — without preventing adapters from
+ * adding required parameters.
+ *
+ * @typeParam Output - The type the framework adapter emits per field
+ *   (e.g. `ReactNode` / `unknown` for React, `string` for HTML).
+ */
+interface BaseRenderProps<Output = unknown> extends BaseFieldProps {
+  /**
+   * Render a child field. Theme adapters call this to recursively
+   * render nested structures (object fields, array elements, union
+   * options). Each adapter narrows the signature in its specialised
+   * variant ({@link RenderProps}, {@link HtmlRenderProps}, …) to
+   * match its native rendering primitives.
+   */
+  renderChild: (...args: never[]) => Output;
+}
+/**
+ * Props for React render functions. Extends {@link BaseRenderProps} with:
+ * - `onChange` — callback to propagate value changes back to state
+ * - `renderChild` — recursively renders a child field, threading
+ *   `onChange` through the four-argument React signature
+ */
+interface RenderProps extends BaseRenderProps {
+  /** 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 {@link BaseRenderProps} with
+ * a narrower three-argument `renderChild` and no `onChange` — HTML
+ * rendering is pure output with no event handling.
+ */
+interface HtmlRenderProps extends BaseRenderProps<string> {
+  /**
+   * 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;
+/**
+ * Generic render-function signature parameterised over the output type
+ * (`Output`) and the per-framework props shape (`Props`).
+ *
+ * The React adapter uses {@link RenderProps} with `unknown` output — see
+ * the default specialisation below — and the HTML adapter uses
+ * {@link HtmlRenderFunction} (an alias for
+ * `RenderFunction\<string, HtmlRenderProps\>`). Future framework
+ * adapters (Vue, Solid, Svelte, Lit) pick their own pairing.
+ *
+ * The default `Output = unknown, Props = RenderProps` keeps the historic
+ * React-flavoured signature compatible — any caller writing
+ * `RenderFunction` without type arguments gets exactly the previous
+ * `(props: RenderProps) =\> unknown` shape.
+ */
+type RenderFunction<Output = unknown, Props = RenderProps> = (props: Props) => Output;
+/**
+ * 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. Specialisation of the
+ * generic {@link RenderFunction} signature with `Output = string` and
+ * `Props = HtmlRenderProps`.
+ */
+type HtmlRenderFunction = RenderFunction<string, HtmlRenderProps>;
+/**
+ * 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 { typeToKey as _, HtmlRenderFunction as a, RESOLVER_KEYS as c, WidgetMap as d, buildRenderProps as f, mergeResolvers as g, mergeHtmlResolvers as h, ComponentResolver as i, RenderFunction as l, getRenderFunction as m, BaseFieldProps as n, HtmlRenderProps as o, getHtmlRenderFn as p, BaseRenderProps as r, HtmlResolver as s, AllConstraints as t, RenderProps as u };

package/dist/solid/SchemaComponent.d.mts

@@ -0,0 +1,136 @@
+import { j as WalkedField, w as SchemaMeta } from "../types-BBQaEPfE.mjs";
+import { t as Diagnostic } from "../diagnostics-mftUZI7c.mjs";
+import { r as SchemaIoSide } from "../adapter-ktQaheWB.mjs";
+import { t as SchemaError } from "../errors-DbaI04x2.mjs";
+import { f as RejectUnrepresentableZod } from "../typeInference-Y8tNEQJk.mjs";
+import { a as InferredValue, i as InferredOutputValue, n as InferSchemaValue, r as InferredInputValue, t as InferFields } from "../inferValue-eAnh50EM.mjs";
+import { SolidComponentResolver, SolidWidgetMap } from "./types.mjs";
+import { JSX } from "solid-js";
+
+//#region src/solid/SchemaComponent.d.ts
+/**
+ * Provide a theme resolver and scoped widgets to every
+ * `<SchemaComponent>` rendered inside the subtree.
+ *
+ * Wrap an application (or a region of it) with `<SchemaProvider>` so a
+ * single resolver — typically a custom Solid `SolidComponentResolver`
+ * — drives every schema render. Without a provider the headless
+ * resolver is used.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * import { SchemaProvider, SchemaComponent } from "schema-components/solid/SchemaComponent";
+ *
+ * <SchemaProvider resolver={customResolver}>
+ *   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+ * </SchemaProvider>
+ * ```
+ */
+declare function SchemaProvider(props: {
+  resolver: SolidComponentResolver;
+  widgets?: SolidWidgetMap;
+  children: JSX.Element;
+}): JSX.Element;
+/**
+ * Props accepted by {@link SchemaComponent}.
+ *
+ * Mirrors `react/SchemaComponent`'s `SchemaComponentProps` shape — the
+ * generic parameters carry the inferred schema shape through to
+ * `value`, `onChange`, and `fields` so a typed `schema` prop drives
+ * typed props on the rest of the component.
+ *
+ * @group Components
+ */
+interface SchemaComponentProps<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output"> {
+  /** Zod schema, JSON Schema object, or OpenAPI document. */
+  schema: RejectUnrepresentableZod<T>;
+  /** For OpenAPI: a ref string like `"#/components/schemas/User"`. */
+  ref?: Ref;
+  /** Which side of every transform / pipe / codec to render. */
+  io?: Mode;
+  /** Current value to render — typed against the schema's inferred shape. */
+  value?: InferSchemaValue<T, Ref, Mode>;
+  /** Called when the value changes; receives the next value. */
+  onChange?: (value: InferSchemaValue<T, Ref, Mode>) => void;
+  /** Run `safeParse` / `safeEncode` on change and route errors. */
+  validate?: boolean;
+  /** Called with the validation error when validation fails. */
+  onValidationError?: (error: unknown) => void;
+  /** Called when schema normalisation or rendering fails. */
+  onError?: (error: SchemaError) => void;
+  /** Called with each diagnostic emitted during schema processing. */
+  onDiagnostic?: (diagnostic: Diagnostic) => void;
+  /** When true, any diagnostic becomes a thrown error. */
+  strict?: boolean;
+  /** Per-field meta overrides — nested object mirroring schema shape. */
+  fields?: InferFields<T, Ref>;
+  /** Meta overrides applied to the root schema. */
+  meta?: SchemaMeta;
+  /** Convenience: sets readOnly on all fields. */
+  readOnly?: boolean;
+  /** Convenience: sets writeOnly on all fields. */
+  writeOnly?: boolean;
+  /** Convenience: sets description on the root. */
+  description?: string;
+  /** Instance-scoped widgets — override context and global widgets. */
+  widgets?: SolidWidgetMap;
+  /**
+   * Prefix used for every input `id` / label `for` in this component
+   * subtree. Defaults to a per-instance value from `createUniqueId()`
+   * so multiple `<SchemaComponent>` instances on the same page never
+   * collide. Override for deterministic ids in screenshot tests.
+   */
+  idPrefix?: string;
+}
+/**
+ * Append a child path suffix to a parent path. When the suffix is
+ * omitted (e.g. transparent wrappers like union options) the parent
+ * path is returned unchanged so the child inherits the parent's id.
+ *
+ * Bracketed array indices like `"[0]"` append directly so `tags` +
+ * `"[0]"` becomes `tags[0]` rather than `tags.[0]` — matching the
+ * canonical form used by every shared id helper in `core/idPath.ts`.
+ */
+declare function joinPath(parent: string, suffix: string | undefined): string;
+/**
+ * Normalise a `createUniqueId()` value into a DOM-id-safe prefix.
+ * Solid's `createUniqueId()` already returns a usable id, but consumers
+ * may also pass a label-derived string. Replace any run of
+ * non-alphanumeric characters with a single hyphen and trim leading
+ * and trailing hyphens.
+ */
+declare function sanitisePrefix(value: string): string;
+/**
+ * Render a single walked field through the resolved widget / resolver /
+ * headless pipeline. Used internally by {@link SchemaComponent} and
+ * exported so other Solid-side components (e.g. theme adapters) can
+ * dispatch into the same fallback chain.
+ */
+declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: SolidComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void, pathSuffix?: string) => JSX.Element, path: string, instanceWidgets?: SolidWidgetMap, contextWidgets?: SolidWidgetMap, depth?: number): JSX.Element;
+/**
+ * Render an editable (or read-only) UI from a Zod schema, JSON Schema,
+ * or OpenAPI document.
+ *
+ * Auto-detects the input format, normalises to JSON Schema via the
+ * shared adapter, walks the JSON Schema tree, and delegates per-field
+ * rendering to the {@link SolidComponentResolver} supplied via
+ * {@link SchemaProvider} — falling back to the headless renderer when
+ * no provider is present.
+ *
+ * Pass `readOnly` to render a presentational view instead of inputs.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { SchemaComponent } from "schema-components/solid/SchemaComponent";
+ *
+ * const userSchema = z.object({ name: z.string(), email: z.email() });
+ *
+ * <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+ * ```
+ */
+declare function SchemaComponent<T = unknown, Ref extends string | undefined = undefined, Mode extends SchemaIoSide = "output">(props: SchemaComponentProps<T, Ref, Mode>): JSX.Element;
+//#endregion
+export { type InferFields, type InferredInputValue, type InferredOutputValue, type InferredValue, SchemaComponent, SchemaComponentProps, SchemaProvider, joinPath, renderField, sanitisePrefix };