schema-components 2.0.2 → 2.1.0

package/README.md

@@ -12,7 +12,7 @@ React components that render UI from Zod schemas, JSON Schema, and OpenAPI docum
 npm install schema-components
 ```
 
-Peer dependencies: `zod@^4.0.0`, `react@^18.0.0 || ^19.0.0`.
+Peer dependencies: `zod@^4.0.0`, `react@^18.0.0 || ^19.0.0`. `preact@>=10.0.0` is also accepted as an optional peer for the Preact entry point — see [Preact support](#preact-support).
 
 ### Zod version requirement
 
@@ -20,6 +20,103 @@ schema-components requires **Zod 4**. If you are on Zod 3, see the [Zod 4 migrat
 
 Schemas from other libraries that conform to the [Standard Schema](https://standardschema.dev/) spec (valibot, arktype, ...) are also detected and rejected. When the input advertises a `~standard.vendor` field, the error message includes the vendor name so consumers know which library produced the input.
 
+### Preact support
+
+Preact is supported as an optional peer dependency via `preact/compat` aliasing. The Preact entry point (`schema-components/preact/*`) re-exports every public symbol from the React entry point (`SchemaComponent`, `SchemaProvider`, `SchemaField`, `SchemaView`, `SchemaErrorBoundary`, `registerWidget`, `headlessResolver`). The renderer tree is identical — `preact/compat` translates React-style `onChange` to `onInput` at render time, matching the "fires on every keystroke" semantics the controlled inputs rely on.
+
+Import from `schema-components/preact/*` instead of `schema-components/react/*`, then configure your bundler to alias `react` and `react-dom` to `preact/compat`.
+
+```tsx
+import { SchemaComponent } from "schema-components/preact/SchemaComponent";
+```
+
+#### Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    resolve: {
+        alias: {
+            "react-dom/test-utils": "preact/test-utils",
+            "react-dom/client": "preact/compat/client",
+            "react-dom/server": "preact/compat/server",
+            "react-dom": "preact/compat",
+            "react/jsx-runtime": "preact/jsx-runtime",
+            "react/jsx-dev-runtime": "preact/jsx-dev-runtime",
+            react: "preact/compat",
+        },
+    },
+});
+```
+
+The order matters: longer, path-specific entries (`react-dom/client`, `react/jsx-runtime`) must come before the bare entries (`react`, `react-dom`) so they get a chance to claim the request first.
+
+#### Next.js
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+
+const config: NextConfig = {
+    webpack(webpackConfig) {
+        webpackConfig.resolve.alias = {
+            ...webpackConfig.resolve.alias,
+            "react-dom/test-utils": "preact/test-utils",
+            "react-dom/client": "preact/compat/client",
+            "react-dom/server": "preact/compat/server",
+            "react-dom": "preact/compat",
+            "react/jsx-runtime": "preact/jsx-runtime",
+            "react/jsx-dev-runtime": "preact/jsx-dev-runtime",
+            react: "preact/compat",
+        };
+        return webpackConfig;
+    },
+};
+
+export default config;
+```
+
+#### Node (without a bundler)
+
+Use the package manager's overrides field to swap the resolved package at install time. For npm:
+
+```jsonc
+// package.json
+{
+    "overrides": {
+        "react": "npm:@preact/compat@*",
+        "react-dom": "npm:@preact/compat@*"
+    }
+}
+```
+
+For pnpm:
+
+```jsonc
+// package.json
+{
+    "pnpm": {
+        "overrides": {
+            "react": "npm:@preact/compat@*",
+            "react-dom": "npm:@preact/compat@*"
+        }
+    }
+}
+```
+
+For yarn, use the `resolutions` field with the same value.
+
+#### Known limitations
+
+1. **React Server Components is React-only.** `<SchemaView>` runs as a client component under Preact, losing the zero-client-JS deployment story documented in [Server Components](#server-components). The component still renders correctly — it just executes in the browser rather than at request time on the server.
+2. **`onChange` semantics requires `preact/compat`.** Raw `preact` (without `compat`) fires `onChange` on commit / blur, matching the DOM standard. `preact/compat` aliases `onChange` to `onInput` so the controlled inputs fire on every keystroke, matching React's behaviour. Importing from `schema-components/preact/*` without aliasing `react` to `preact/compat` will leave events misrouted.
+3. **HTML serialization differs slightly.** Preact emits HTML5 boolean-attribute shorthand (`value` for an empty string) where React emits `value=""`. The semantics are identical; only string snapshots that match the exact React form will need adjusting under Preact.
+4. **Vnode prop shape differs.** Preact-compat rewrites React-style event prop names (`onChange`, `onBlur`) to lowercase DOM event names (`oninput`, `onfocusout`) on the vnode prop bag during rendering. Tests that inspect a React element's `.props` directly (rather than the rendered DOM) need to expect the lowercase form when running under Preact.
+
+The test suite is parametrised with a `unit-preact` Vitest project that runs the same files under `preact/compat` aliasing. Run it via `pnpm test:preact` from the repo root, or directly with `pnpm exec vitest run --project=unit-preact` from `packages/core`. A small set of tests (the ones bound to the three known limitations above) fail intentionally; the remaining ~99% pass under both runtimes and establish the cross-runtime regression boundary.
+
 ## `SchemaComponent`
 
 The single entry point. Accepts Zod schemas, JSON Schema objects, or OpenAPI documents:

package/dist/SchemaComponent-B__6-5-E.d.mts

@@ -0,0 +1,277 @@
+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 { d as WidgetMap, i as ComponentResolver, u as RenderProps } from "./renderer-ab9E52Bp.mjs";
+import { t as SchemaError } from "./errors-DbaI04x2.mjs";
+import { d as PathOfType, f as RejectUnrepresentableZod, r as FromJSONSchema } from "./typeInference-Y8tNEQJk.mjs";
+import { n as InferSchemaValue, t as InferFields } from "./inferValue-eAnh50EM.mjs";
+import { z } from "zod";
+import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import { ReactNode } from "react";
+
+//#region src/react/SchemaComponent.d.ts
+/**
+ * Provide a theme resolver and scoped widgets to every `<SchemaComponent>`
+ * and `<SchemaView>` rendered inside the subtree.
+ *
+ * Wrap an application (or a region of it) with `<SchemaProvider>` so a
+ * single theme — typically one of the bundled adapters
+ * (`shadcnResolver`, `muiResolver`, `mantineResolver`, `radixResolver`)
+ * or a custom one — drives every schema render. Without a provider,
+ * schema-components fall back to the headless HTML renderer.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * import { SchemaProvider } from "schema-components/react/SchemaComponent";
+ * import { shadcnResolver } from "schema-components/themes/shadcn";
+ *
+ * <SchemaProvider resolver={shadcnResolver}>
+ *   <SchemaComponent schema={userSchema} value={user} onChange={setUser} />
+ * </SchemaProvider>
+ * ```
+ */
+declare function SchemaProvider({
+  resolver,
+  widgets,
+  children
+}: {
+  resolver: ComponentResolver; /** Scoped widgets available to all SchemaComponents in this subtree. */
+  widgets?: WidgetMap;
+  children: ReactNode;
+}): _$react_jsx_runtime0.JSX.Element;
+/**
+ * Register a widget globally. The widget is resolved when a schema field
+ * has `.meta({ component: name })`.
+ *
+ * For scoped registration, use the `widgets` prop on `<SchemaComponent>`
+ * or `<SchemaProvider>` instead.
+ */
+declare function registerWidget(name: string, render: (props: RenderProps) => unknown): void;
+/**
+ * Clear every globally registered widget. Intended for test isolation —
+ * `registerWidget` writes to module-level state and that state otherwise
+ * leaks across test cases, making the test suite order-dependent. Tests
+ * should call this from an `afterEach` hook.
+ *
+ * @internal
+ */
+declare function __clearGlobalWidgets(): void;
+/**
+ * Props accepted by {@link SchemaComponent}.
+ *
+ * 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.
+   *
+   * Zod 4 types that cannot round-trip through `z.toJSONSchema()`
+   * (bigint, date, map, set, symbol, function, undefined, void, nan,
+   * codec) are rejected at the type level via
+   * {@link RejectUnrepresentableZod}. Runtime conversion would throw
+   * `SchemaNormalisationError` with kind `zod-type-unrepresentable`
+   * — the static rejection surfaces the same failure at compile time.
+   */
+  schema: RejectUnrepresentableZod<T>;
+  /** For OpenAPI: a ref string like "#/components/schemas/User" or "/users/post". */
+  ref?: Ref;
+  /**
+   * Which side of every transform / pipe / codec to render.
+   *
+   * - `"output"` (default) — renderer draws the OUTPUT side of the
+   *   schema. For a `z.codec(z.string(), z.number(), …)` chain
+   *   this renders a number input. `value` and `onChange` therefore
+   *   carry the OUTPUT shape, and `validate` runs `safeEncode`
+   *   (the reverse direction) so user-supplied OUTPUT values are
+   *   validated against the codec.
+   * - `"input"` — renderer draws the INPUT side instead. For the
+   *   same codec this renders a string input, `value` and
+   *   `onChange` carry the INPUT shape, and `validate` runs
+   *   `safeParse` (the forward direction).
+   *
+   * The choice is propagated through `normaliseSchema` →
+   * `normaliseZod4` → `z.toJSONSchema(..., { io })` so a single
+   * source of truth drives both the rendered JSON Schema shape and
+   * the validation direction. Has no effect for plain JSON Schema
+   * or OpenAPI inputs — those advertise a single canonical shape.
+   */
+  io?: Mode;
+  /**
+   * Current value to render. Typed against
+   * `InferSchemaValue<T, Ref, Mode>` so the prop tracks the schema's
+   * inferred shape for the chosen `io` direction.
+   *
+   * Falls back to `unknown` when the schema's value type cannot be
+   * statically inferred (runtime `Record<string, unknown>` JSON
+   * Schemas, OpenAPI documents without a ref, etc.), so untyped
+   * call sites still compile.
+   *
+   * Use {@link InferredOutputValue} or {@link InferredInputValue}
+   * to narrow a value declared at the call site:
+   *
+   * ```tsx
+   * const user: InferredOutputValue<typeof userSchema> = { ... };
+   * <SchemaComponent schema={userSchema} value={user} readOnly />
+   * ```
+   */
+  value?: InferSchemaValue<T, Ref, Mode>;
+  /**
+   * Called when the value changes (editable fields). The parameter
+   * shares the same shape as {@link SchemaComponentProps.value} so
+   * a controlled component can round-trip the value through React
+   * state without re-shaping.
+   *
+   * Falls back to `unknown` for schemas whose value type cannot be
+   * statically inferred — see {@link SchemaComponentProps.value}.
+   */
+  onChange?: (value: InferSchemaValue<T, Ref, Mode>) => void;
+  /** Run schema.safeParse() on change and surface errors via onValidationError. */
+  validate?: boolean;
+  /** Called with the ZodError 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?: WidgetMap;
+  /**
+   * Prefix used for every input `id`/label `htmlFor` in this component
+   * subtree. Defaults to a per-instance value from `useId()` so multiple
+   * `<SchemaComponent>` instances on the same page never collide. Override
+   * for deterministic ids in screenshot tests.
+   */
+  idPrefix?: string;
+}
+/**
+ * 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
+ * adapter, walks the JSON Schema tree, and delegates per-field rendering
+ * to the {@link ComponentResolver} supplied via {@link SchemaProvider} —
+ * falling back to a headless HTML renderer when no provider is present.
+ *
+ * Pass `readOnly` to render a presentational view instead of inputs, or
+ * wrap with `<SchemaProvider resolver={…}>` to swap the theme.
+ *
+ * @group Components
+ * @example
+ * ```tsx
+ * import { z } from "zod";
+ * import { SchemaComponent } from "schema-components/react/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>): ReactNode;
+/**
+ * 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 `html/a11y.ts` `joinPath` and `core/fieldPath.ts` `resolvePath`,
+ * which already parses bracket notation when navigating WalkedField trees.
+ */
+declare function joinPath(parent: string, suffix: string | undefined): string;
+/**
+ * Normalise a `useId()` value into a DOM-id-safe prefix. React's `useId`
+ * returns values containing `:` characters (e.g. `«:r0:»`) which are
+ * invalid in CSS selectors. Replace any run of non-alphanumeric characters
+ * with a single hyphen and trim leading/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 {@link SchemaField}, exported so other
+ * React-side components (e.g. the OpenAPI renderers) can dispatch
+ * into the same fallback chain.
+ *
+ * Thin React-flavoured wrapper around the framework-agnostic
+ * `dispatchRenderField` (from `core/renderField`): it constructs a
+ * React-shaped `DispatchConfig` (widget lookup against the
+ * instance → context → global chain, recursion sentinel as a React
+ * `<fieldset>`, fallback as a `<span>`-wrapped value) and forwards
+ * the call.
+ */
+declare function renderField(tree: WalkedField, value: unknown, onChange: (v: unknown) => void, userResolver: ComponentResolver | undefined, renderChild: (tree: WalkedField, value: unknown, onChange: (v: unknown) => void, pathSuffix?: string) => ReactNode, path: string, instanceWidgets?: WidgetMap, contextWidgets?: WidgetMap, depth?: number): ReactNode;
+/**
+ * Infer the schema's output type for SchemaField path inference.
+ */
+type InferSchemaType<T> = T extends z.ZodType ? z.infer<T> : T extends object ? unknown extends FromJSONSchema<T> ? unknown : FromJSONSchema<T> : unknown;
+/**
+ * Props accepted by {@link SchemaField}. The generic `P` constrains
+ * `path` to dot-paths reachable through the schema's inferred value
+ * type — typed schemas get autocomplete; runtime schemas fall back to
+ * `string`.
+ *
+ * @group Components
+ */
+interface SchemaFieldProps<T = unknown, Ref extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)> {
+  /**
+   * Dot-separated path to the field (e.g. "address.city").
+   * When the schema is a Zod schema or typed `as const`, only valid
+   * paths are accepted. Falls back to `string` for runtime schemas.
+   */
+  path: P;
+  /**
+   * The schema to extract the field from. Subject to the same
+   * unrepresentable-Zod rejection as {@link SchemaComponentProps.schema}.
+   */
+  schema: RejectUnrepresentableZod<T>;
+  /** For OpenAPI: a ref string. */
+  ref?: Ref;
+  /** Current value of the field at the given path. */
+  value?: unknown;
+  /** Called with the updated root value when this field changes. */
+  onChange?: (value: unknown) => void;
+  /** Override meta for this specific field. */
+  meta?: SchemaMeta;
+  /** Run validation on change. */
+  validate?: boolean;
+  onValidationError?: (error: unknown) => void;
+}
+/**
+ * Render a single field from a schema by dot-separated `path`.
+ *
+ * Walks the full schema tree and resolves the field at the supplied
+ * `path`, then renders only that field through the same resolver
+ * pipeline as {@link SchemaComponent}. Useful for embedding individual
+ * fields inside bespoke layouts.
+ *
+ * @group Components
+ */
+declare function SchemaField<T = unknown, Ref extends string | undefined = undefined, P extends string = PathOfType<InferSchemaType<T>> | (string extends PathOfType<InferSchemaType<T>> ? string : never)>({
+  path,
+  schema: schemaInput,
+  ref: refInput,
+  value,
+  onChange,
+  meta: fieldMeta,
+  validate,
+  onValidationError
+}: SchemaFieldProps<T, Ref, P>): ReactNode;
+//#endregion
+export { SchemaProvider as a, registerWidget as c, SchemaFieldProps as i, renderField as l, SchemaComponentProps as n, __clearGlobalWidgets as o, SchemaField as r, joinPath as s, SchemaComponent as t, sanitisePrefix as u };