schema-components 0.0.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+## 1.0.0 (2026-05-14)
+
+### Features
+
+* add accessibility attributes to HTML renderers ([ea49b72](https://github.com/Mearman/schema-components/commit/ea49b7264b3dd496afba851d6bcee6a103e688fb))
+* add default stylesheet for sc- prefixed HTML classes ([44d1a91](https://github.com/Mearman/schema-components/commit/44d1a91ce9f986567552070f6d698d3f3d78f7b1))
+* add html renderer — render schemas to raw html strings ([a803cfb](https://github.com/Mearman/schema-components/commit/a803cfb4fb8a881115dc224abe15cb4325844fbb))
+* add renderChild to RenderProps for theme adapter recursion ([24305a2](https://github.com/Mearman/schema-components/commit/24305a2793d80d7a29384ba5fda2c46861479952))
+* add shadcn adapter, schema caching, and update readme/package ([fff4082](https://github.com/Mearman/schema-components/commit/fff40825bdb6e3820010dd7faa48a307549af7c9))
+* add Storybook with GitHub Pages deployment ([eae9817](https://github.com/Mearman/schema-components/commit/eae98178e565fa10ba1c2f258887fafb08cafd37))
+* add streaming HTML renderer with three output formats ([5d3fa4a](https://github.com/Mearman/schema-components/commit/5d3fa4a20b3c65af83059ab2b111fda9392085c1))
+* add type-safe openapi components with generic inference ([683e950](https://github.com/Mearman/schema-components/commit/683e950cf08a52538bbfa873400386616ec98756))
+* add typed errors, onError callback, and React error boundary ([893f9a1](https://github.com/Mearman/schema-components/commit/893f9a1fc251159c80a73b45fbc1d6f63f99a857))
+* add unit tests and fix schema passthrough bug ([23092cc](https://github.com/Mearman/schema-components/commit/23092ccdac3cd37068b0eae08753ba654c50359a))
+* flatten nested fields prop for walker field overrides ([a72ffbe](https://github.com/Mearman/schema-components/commit/a72ffbe776feb830830bf7bf68dd6fc9b0deb8d0))
+* implement core library — walker, adapter, renderer, React components ([2c95a2e](https://github.com/Mearman/schema-components/commit/2c95a2e448b2646c4d6c4565ceb30e99500ce732))
+* replace string templates with typed h() builder ([83525b1](https://github.com/Mearman/schema-components/commit/83525b115f77b39c949e566d4838332dae5f92ae))
+* type-safe fields prop with generic SchemaComponent<T, Ref> ([3ea1495](https://github.com/Mearman/schema-components/commit/3ea14950e3d20eb80d8b16186803f3ab0ed28f84))
+* type-safe path prop on generic SchemaField ([8d5fef7](https://github.com/Mearman/schema-components/commit/8d5fef7405d6c4b2f914e0481e501eaf633ddc5b))
+* wire adapter, resolver, and SchemaField into SchemaComponent ([cbc2ce1](https://github.com/Mearman/schema-components/commit/cbc2ce158c080a1a84a940781b81d9d065e055b1))
+
+### Bug Fixes
+
+* propagate field key as path in HTML renderChild ([e3f471c](https://github.com/Mearman/schema-components/commit/e3f471c2ee308edf1e6406c1fc6f70bfac8c6b37))
+* readOnly/writeOnly overrides propagate correctly to nested fields ([a809b62](https://github.com/Mearman/schema-components/commit/a809b62bbe08ae44d3fdaa9b277a3ded07c6009d))
+
+### Refactoring
+
+* centralise type guards, resolver lookup, and resolver merge ([be354ac](https://github.com/Mearman/schema-components/commit/be354ac35b6d73ec0bbc746fae58c35758991ce0))
+* remove duplicate ComponentResolver types from types.ts ([39702c5](https://github.com/Mearman/schema-components/commit/39702c5ab622be825ad7f1ad222c07dca85c57a4))
+* unify RenderProps and HtmlRenderProps via BaseFieldProps ([a408da9](https://github.com/Mearman/schema-components/commit/a408da9a2f4b4bacf81f0a85f6aad117fa69bb8a))
+* use json schema as authoritative internal representation ([6a996c5](https://github.com/Mearman/schema-components/commit/6a996c53517d18f39cb341f10ed3fafdd7777547))
+
+### Documentation
+
+* add README for schema-components design document ([c1251e4](https://github.com/Mearman/schema-components/commit/c1251e4eea39e0154c3e8cc91e5482271bb4ce95))
+* rewrite README to match actual API ([a8fc57f](https://github.com/Mearman/schema-components/commit/a8fc57fe5e650c9f4f886f0525c8c58e309a70aa))
+* update readme for json schema walker architecture ([9649430](https://github.com/Mearman/schema-components/commit/9649430f76f2fbef6d0ea7a8d9fd81ff478f644f))
+* update README with h() builder, streaming, accessibility, errors ([01d2a9f](https://github.com/Mearman/schema-components/commit/01d2a9f32dcdf3827ce117901cd1b6ff9c3e3d26))
+
+### Tests
+
+* add parser unit tests and integration tests ([338dba3](https://github.com/Mearman/schema-components/commit/338dba368007dd2d34172a8dacfdb76606a588c6))
+
+### Chores
+
+* add mit license and contributing guide ([7d51c29](https://github.com/Mearman/schema-components/commit/7d51c2957ab06fdd6c8bb4a384b3906e453ae786))
+* **build:** remove barrel files, use direct module exports ([08d4f21](https://github.com/Mearman/schema-components/commit/08d4f2148e3e06c95fd1db3a9c5a733a419f3fdc))
+* **build:** replace tsc with tsdown for library bundling ([38951b2](https://github.com/Mearman/schema-components/commit/38951b2ef0b770ec883f18fe9f3d4f4bf7181a5a))
+* pin all GitHub Actions to latest versions, fix CI types ([29c5b6e](https://github.com/Mearman/schema-components/commit/29c5b6e156c9a3b59e656a26c4bf147a1e5b5321))
+* rename to schema-components, adopt OIDC trusted publishing ([61e5c75](https://github.com/Mearman/schema-components/commit/61e5c753d5d103538213157f6fd4810572480d72))
+* set up repo devops ([1042810](https://github.com/Mearman/schema-components/commit/1042810992bf4cb45e77efd680008c184f307210))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joseph Mearman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,526 @@
+# schema-components
+
+React components that render UI from Zod schemas, JSON Schema, and OpenAPI documents.
+
+Define your data model once. Get presentational views, input fields, and editable forms — no manual wiring.
+
+## Install
+
+```bash
+npm install schema-components
+```
+
+Peer dependencies: `zod@^4.0.0`, `react@^18.0.0 || ^19.0.0`.
+
+## Quick start
+
+```tsx
+import { z } from "zod";
+import { SchemaComponent } from "schema-components/react/SchemaComponent";
+
+const userSchema = z.object({
+  name: z.string().min(1).meta({ description: "Full name" }),
+  email: z.email().meta({ description: "Email address" }),
+  role: z.enum(["admin", "editor", "viewer"]).meta({ description: "Role" }),
+  active: z.boolean().meta({ description: "Active" }),
+});
+
+function UserCard() {
+  const [user, setUser] = useState({
+    name: "Ada Lovelace",
+    email: "ada@example.com",
+    role: "admin",
+    active: true,
+  });
+
+  return (
+    <SchemaComponent
+      schema={userSchema}
+      value={user}
+      onChange={setUser}
+    />
+  );
+}
+```
+
+Renders every field as an editable input. Add `readOnly` to the component for a read-only view:
+
+```tsx
+<SchemaComponent schema={userSchema} value={user} readOnly />
+```
+
+## How it works
+
+```
+Zod schema ─── z.toJSONSchema() ──→ JSON Schema ──────────┐
+                                                           ▼
+JSON Schema ─────────────────────────────────────────► JSON Schema ──► walker ──► React
+                                                           ▲
+OpenAPI doc ── extract schemas ───────────────────────────┘
+```
+
+One walker, one input format. The walker reads standard JSON Schema keywords (Draft 2020-12) — decoupled from Zod's internal API. `z.toJSONSchema()` is lossless: it preserves `readOnly`, `writeOnly`, custom `.meta()` properties, constraints, formats, and defaults.
+
+`z.fromJSONSchema()` is used **only for validation** — converting JSON Schema / OpenAPI inputs back to Zod when `validate` is true and the original wasn't a Zod schema.
+
+## Component editability
+
+Fields render in one of three states, controlled by `readOnly` and `writeOnly` from three sources:
+
+| State | Rendering |
+|---|---|
+| **Presentation** | Read-only display. Formatted text, links, badges. No inputs. |
+| **Input** | Empty field. Blank inputs, "Select…" dropdowns, unchecked toggles. |
+| **Editable** | Pre-populated input the user can change. |
+
+### Three sources, priority order
+
+1. **Schema property** (`.meta({ readOnly: true })`) — always wins
+2. **Component props** (`readOnly` / `writeOnly` on `<SchemaComponent>`) — rendering context
+3. **Schema root** (`.meta({ readOnly: true })` on root schema) — fallback default
+4. Neither → Editable
+
+### Overriding with `readOnly: false`
+
+A field override can explicitly opt out of a higher-level `readOnly`:
+
+```tsx
+<SchemaComponent
+  schema={userSchema}
+  value={user}
+  readOnly                         // everything presentation
+  fields={{
+    address: {
+      readOnly: false,            // address subtree: editable
+      city: { readOnly: true },   // city: still presentation
+    },
+  }}
+/>
+```
+
+## Type-safe field overrides
+
+The `fields` prop type is inferred from the schema:
+
+```tsx
+// Zod — full autocomplete
+<SchemaComponent
+  schema={userSchema}
+  fields={{
+    name: { readOnly: true },            // ✓ type-safe
+    address: {
+      city: { description: "City" },     // ✓ nested, type-safe
+    },
+    // nme: { readOnly: true },          // ✗ TypeScript error: unknown key
+  }}
+/>
+
+// JSON Schema as const — full autocomplete
+const jsonSchema = {
+  type: "object" as const,
+  properties: {
+    name: { type: "string" as const },
+    email: { type: "string" as const, format: "email" },
+  },
+  required: ["name"],
+} as const;
+
+<SchemaComponent
+  schema={jsonSchema}
+  fields={{
+    name: { readOnly: true },            // ✓ inferred from as const
+    // nme: { readOnly: true },          // ✗ TypeScript error
+  }}
+/>
+
+// OpenAPI as const + ref — full autocomplete
+const spec = {
+  openapi: "3.1.0",
+  components: {
+    schemas: {
+      User: {
+        type: "object" as const,
+        properties: {
+          id: { type: "string" as const },
+          name: { type: "string" as const },
+        },
+        required: ["id", "name"],
+      },
+    },
+  },
+} as const;
+
+<SchemaComponent
+  schema={spec}
+  ref="#/components/schemas/User"
+  fields={{
+    id: { readOnly: true },              // ✓ inferred through ref
+  }}
+/>
+```
+
+## Individual fields
+
+```tsx
+import { SchemaField } from "schema-components/react/SchemaComponent";
+
+// Type-safe path — only valid dot-paths accepted
+<SchemaField
+  schema={userSchema}
+  path="address.city"      // ✓ type-safe
+  // path="address.cty"   // ✗ TypeScript error
+  value={user}
+  onChange={setUser}
+/>
+```
+
+When the schema is a Zod schema or typed `as const`, only valid dot-paths like `"address.city"` are accepted. Invalid paths trigger TypeScript errors. Runtime schemas accept any string.
+
+## All input formats
+
+`<SchemaComponent>` auto-detects the input format:
+
+```tsx
+// Zod schema
+<SchemaComponent schema={z.object({ name: z.string() })} value={data} />
+
+// JSON Schema
+<SchemaComponent
+  schema={{ type: "object", properties: { name: { type: "string" } } }}
+  value={data}
+/>
+
+// OpenAPI document + ref
+<SchemaComponent
+  schema={openApiSpec}
+  ref="#/components/schemas/User"
+  value={data}
+/>
+```
+
+## OpenAPI components
+
+Render API operations with type-safe field overrides:
+
+```tsx
+import { ApiOperation } from "schema-components/openapi/components";
+import type { ApiRequestBodyProps } from "schema-components/openapi/components";
+
+const petStore = {
+  openapi: "3.1.0",
+  paths: {
+    "/pets": {
+      post: {
+        requestBody: {
+          content: {
+            "application/json": {
+              schema: {
+                type: "object" as const,
+                properties: {
+                  name: { type: "string" as const },
+                  tag: { type: "string" as const },
+                },
+                required: ["name"],
+              },
+            },
+          },
+        },
+        responses: { "201": { description: "Created" } },
+      },
+    },
+  },
+} as const;
+
+// Full operation — parameters, request body, responses
+<ApiOperation schema={petStore} path="/pets" method="post" />
+
+// Just the request body with type-safe fields
+<ApiRequestBody
+  schema={petStore}
+  path="/pets"
+  method="post"
+  fields={{
+    name: { description: "Pet name" },    // ✓ inferred from as const
+    // nme: { description: "X" },         // ✗ TypeScript error
+  }}
+/>
+
+// Just parameters with type-safe overrides
+<ApiParameters
+  schema={petStore}
+  path="/pets"
+  method="get"
+  overrides={{
+    limit: { description: "Max results" }, // ✓ inferred parameter names
+  }}
+/>
+
+// Response schema
+<ApiResponse schema={petStore} path="/pets" method="get" status="200" />
+```
+
+## Theme adapters
+
+Headless by default (plain HTML). Wrap with a theme adapter for styled components:
+
+```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>
+```
+
+Write a custom adapter:
+
+```tsx
+import type { RenderProps, ComponentResolver } from "schema-components/core/renderer";
+
+const myResolver: ComponentResolver = {
+  string: (props: RenderProps) => {
+    if (props.readOnly) return <span>{props.value}</span>;
+    return <input value={props.value} onChange={(e) => props.onChange(e.target.value)} />;
+  },
+  object: (props: RenderProps) => {
+    // props.renderChild recursively renders each field
+    return (
+      <div>
+        {props.fields && Object.entries(props.fields).map(([key, field]) => (
+          <div key={key}>
+            <label>{field.meta.description}</label>
+            {props.renderChild(field, (props.value as Record<string, unknown>)?.[key], (v) => {
+              props.onChange({ ...(props.value as object), [key]: v });
+            })}
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+```
+
+Every render function receives `props.renderChild` for recursive rendering — no need to know about the resolver or rendering context.
+
+## Raw HTML
+
+Render schemas to HTML strings — no React needed. Useful for server-side rendering, email templates, static sites, and non-React environments.
+
+```tsx
+import { renderToHtml } from "schema-components/html/renderToHtml";
+
+const userSchema = z.object({
+  name: z.string().meta({ description: "Name" }),
+  email: z.email().meta({ description: "Email" }),
+  role: z.enum(["admin", "editor", "viewer"]).meta({ description: "Role" }),
+});
+
+// Read-only display
+const html = renderToHtml(userSchema, {
+  value: { name: "Ada Lovelace", email: "ada@example.com", role: "admin" },
+  readOnly: true,
+});
+// → <dl class="sc-object">
+//     <dt class="sc-label">Name</dt><dd class="sc-value"><span class="sc-value">Ada Lovelace</span></dd>
+//     <dt class="sc-label">Email</dt><dd class="sc-value"><a class="sc-value" href="mailto:ada@example.com">ada@example.com</a></dd>
+//     <dt class="sc-label">Role</dt><dd class="sc-value"><span class="sc-value">admin</span></dd>
+//   </dl>
+
+// Editable form
+const formHtml = renderToHtml(userSchema, {
+  value: { name: "Ada Lovelace", email: "ada@example.com", role: "admin" },
+});
+// → <fieldset class="sc-object">
+//     <div class="sc-field">
+//       <label class="sc-label" for="sc-name">Name</label>
+//       <input class="sc-input" type="text" name="" value="Ada Lovelace">
+//     </div>
+//     ...
+//   </fieldset>
+```
+
+All HTML output uses `sc-` prefixed classes for styling hooks. HTML is properly escaped by the serialiser — no manual escaping needed.
+
+A default stylesheet is included:
+
+```html
+<link rel="stylesheet" href="node_modules/schema-components/dist/html/styles.css">
+```
+
+Or import in JS:
+
+```ts
+import "schema-components/styles.css";
+```
+
+### Structured HTML construction
+
+The HTML renderer uses a typed `h()` builder instead of string templates. This gives compile-time safety and automatic escaping:
+
+```ts
+import { h, serialize, raw } from "schema-components/html/html";
+
+// Build elements — attrs are type-checked, values auto-escaped
+const input = h("input", { type: "text", id: "name", value: userValue });
+serialize(input); // → <input type="text" id="name" value="Ada">
+
+// Embed pre-serialised HTML (from child renderers)
+const div = h("div", { class: "field" }, raw(childHtml));
+serialize(div);
+```
+
+The builder handles void elements (`<input>`, `<br>`, etc.), boolean attributes (`checked`, `disabled`), fragments, and nested children.
+
+### Streaming HTML
+
+Three output formats for incremental rendering:
+
+```ts
+import { renderToHtmlChunks } from "schema-components/html/renderToHtmlStream";
+import { renderToHtmlStream } from "schema-components/html/renderToHtmlStream";
+import { renderToHtmlReadable } from "schema-components/html/renderToHtmlStream";
+
+// Sync iterable — chunks yielded at field/item/entry boundaries
+const chunks: string[] = [...renderToHtmlChunks(schema, { value })];
+
+// Async iterable — yields control to event loop between chunks
+for await (const chunk of renderToHtmlStream(schema, { value })) {
+  res.write(chunk);
+}
+
+// Web ReadableStream — for Response, TransformStream, etc.
+return new Response(renderToHtmlReadable(schema, { value }), {
+  headers: { "Content-Type": "text/html" },
+});
+```
+
+Concatenating all chunks produces identical output to `renderToHtml`.
+
+### Accessibility
+
+The HTML renderer produces WAI-ARIA-compliant markup:
+
+| Attribute | When |
+|---|---|
+| `id="<key>"` | All editable inputs |
+| `aria-required="true"` | Required fields (`isOptional === false`) |
+| `aria-describedby="<id>-hint"` | Fields with constraints (min/max/length/pattern) |
+| `aria-readonly="true"` | Read-only presentation spans |
+| `aria-label="<description>"` | Checkboxes (no visible text node) |
+| `role="group"` | Record containers |
+| `aria-label` on `<fieldset>` | Object with description |
+| `<small class="sc-hint">` | Constraint hint text |
+| `<span class="sc-required" aria-hidden="true">*` | Required field indicator |
+
+### Custom HTML resolver
+
+```ts
+import { renderToHtml } from "schema-components/html/renderToHtml";
+import type { HtmlResolver, HtmlRenderProps } from "schema-components/html/renderToHtml";
+
+const tailwindResolver: HtmlResolver = {
+  string: (props: HtmlRenderProps) => {
+    if (props.readOnly) {
+      return `<span class="text-sm text-gray-700">${typeof props.value === "string" ? props.value : ""}</span>`;
+    }
+    return `<input class="border rounded px-2 py-1" type="text" value="${typeof props.value === "string" ? props.value : "">">`;
+  },
+};
+
+const html = renderToHtml(schema, { value, readOnly: true, resolver: tailwindResolver });
+```
+
+Custom resolvers fall back to the default for any type you don't override.
+
+## Custom widgets
+
+Register widgets by `.meta({ component })` hint:
+
+```tsx
+import { registerWidget } from "schema-components/react/SchemaComponent";
+
+registerWidget("richtext", ({ value, onChange }) => (
+  <RichTextEditor value={value} onChange={onChange} />
+));
+
+// In schema
+const schema = z.object({
+  bio: z.string().meta({ component: "richtext" }),
+});
+```
+
+Resolution order: `.meta({ component })` → registered widget → theme adapter → headless default.
+
+## Validation
+
+```tsx
+<SchemaComponent
+  schema={userSchema}
+  value={user}
+  onChange={setUser}
+  validate
+  onValidationError={(error) => console.error(error)}
+/>
+```
+
+Validation uses the original Zod schema (if input was Zod) or `z.fromJSONSchema()` (if input was JSON Schema / OpenAPI).
+
+## Error handling
+
+Typed errors with `onError` callback for graceful degradation:
+
+```tsx
+import { SchemaErrorBoundary } from "schema-components/react/SchemaErrorBoundary";
+import { SchemaComponent } from "schema-components/react/SchemaComponent";
+
+// Error boundary catches render errors from theme adapters
+<SchemaErrorBoundary fallback={(error, reset) => <p>Error: {error.message}</p>}>
+  <SchemaComponent schema={schema} value={data} />
+</SchemaErrorBoundary>
+
+// Per-component error callback
+<SchemaComponent
+  schema={schema}
+  value={data}
+  onError={(error) => {
+    console.error(error);
+    return null; // graceful degradation
+  }}
+/>
+```
+
+Without `onError`, errors re-throw. Error hierarchy: `SchemaError` → `SchemaNormalisationError` | `SchemaRenderError` | `SchemaFieldError`.
+
+## Architecture
+
+```
+schema-components
+├── core            # JSON Schema walker, ComponentResolver, RenderProps, typed errors, type guards
+├── react           # SchemaComponent, SchemaProvider, SchemaField, headless renderer, error boundary
+├── openapi         # Document parser, ApiOperation, ApiParameters, ApiRequestBody, ApiResponse
+├── html            # h() builder, renderToHtml, streaming renderers, ARIA helpers
+└── themes          # shadcn, MUI, custom adapters (separate packages)
+```
+
+## Source files
+
+Every module is imported directly — no barrel files.
+
+| File | Role |
+|---|---|
+| `core/types.ts` | SchemaMeta, Editability, WalkedField, FieldConstraints, FieldOverrides, FromJSONSchema, PathOfType |
+| `core/walker.ts` | JSON Schema walker (Draft 2020-12), `$ref` resolution, `allOf` merging, nullable/discriminated union detection |
+| `core/adapter.ts` | Normalises all inputs to JSON Schema. WeakMap schema cache. |
+| `core/renderer.ts` | `BaseFieldProps`, `RenderProps`, `HtmlRenderProps`, `ComponentResolver`, `HtmlResolver`, `mergeResolvers` |
+| `core/guards.ts` | Shared type guards: `isObject`, `getProperty`, `hasProperty`, `toRecord` |
+| `core/errors.ts` | `SchemaError`, `SchemaNormalisationError`, `SchemaRenderError`, `SchemaFieldError` |
+| `react/SchemaComponent.tsx` | Generic `<SchemaComponent<T, Ref>>`, `SchemaProvider`, `registerWidget`, `SchemaField<P>` |
+| `react/headless.tsx` | Headless default resolver, `createHeadlessResolver(renderChild)` factory |
+| `react/SchemaErrorBoundary.tsx` | React error boundary catching render errors |
+| `html/html.ts` | Typed `h()` builder — `serialize()`, `serializeChunks()`, `raw()`, `text()`, `fragment()` |
+| `html/a11y.ts` | ARIA helpers — `ariaRequiredAttrs()`, `ariaDescribedByAttrs()`, `buildHintElement()`, `requiredIndicator()` |
+| `html/renderToHtml.ts` | `renderToHtml()`, `defaultHtmlResolver` — schema → HTML string via `h()` builder |
+| `html/renderToHtmlStream.ts` | `renderToHtmlChunks()` (sync), `renderToHtmlStream()` (async), `renderToHtmlReadable()` (web ReadableStream) |
+| `openapi/parser.ts` | OpenAPI document parsing, operation extraction, `$ref` resolution |
+| `openapi/components.tsx` | `ApiOperation`, `ApiParameters`, `ApiRequestBody`, `ApiResponse` with generic type inference |
+| `themes/shadcn.tsx` | shadcn/ui theme adapter |

package/dist/core/adapter.d.mts

@@ -0,0 +1,19 @@
+import { l as JsonObject, m as SchemaMeta } from "../types-BU0ETFHk.mjs";
+
+//#region src/core/adapter.d.ts
+type SchemaInput = Record<string, unknown>;
+type SchemaKind = "zod4" | "zod3" | "jsonSchema" | "openapi";
+declare function detectSchemaKind(input: unknown): SchemaKind;
+interface NormalisedSchema {
+  /** JSON Schema object — the authoritative schema for rendering. */
+  jsonSchema: JsonObject;
+  /** Original Zod schema, if input was Zod. Used for validation. */
+  zodSchema?: unknown;
+  /** Root-level metadata. */
+  rootMeta: SchemaMeta | undefined;
+  /** The root document for $ref resolution. */
+  rootDocument: JsonObject;
+}
+declare function normaliseSchema(input: unknown, ref?: string): NormalisedSchema;
+//#endregion
+export { type JsonObject, NormalisedSchema, SchemaInput, SchemaKind, type SchemaMeta, detectSchemaKind, normaliseSchema };