schema-components 0.0.0 → 1.1.0

package/dist/html/renderToHtmlStream.mjs

@@ -0,0 +1,285 @@
+import { isObject } from "../core/guards.mjs";
+import { normaliseSchema } from "../core/adapter.mjs";
+import { getHtmlRenderFn, mergeHtmlResolvers } from "../core/renderer.mjs";
+import { walk } from "../core/walker.mjs";
+import { VOID_ELEMENTS, h, raw, serialize, serializeAttributes } from "./html.mjs";
+import { ariaLabelAttrs, buildHintElement, buildInputId, requiredIndicator } from "./a11y.mjs";
+import { defaultHtmlResolver } from "./renderToHtml.mjs";
+//#region src/html/renderToHtmlStream.ts
+/**
+* Streaming HTML renderer — yields HTML chunks incrementally.
+*
+* Same rendering pipeline as `renderToHtml` but yields string fragments
+* as each field/element is produced instead of building the entire string
+* in memory. Use for server-side rendering where you want to start
+* flushing the response before the full schema is rendered.
+*
+* Three output formats:
+*
+* - `renderToHtmlChunks(schema, options)` → sync `Iterable<string>`
+* - `renderToHtmlStream(schema, options)` → async `AsyncIterable<string>`
+* - `renderToHtmlReadable(schema, options)` → web `ReadableStream<string>`
+*
+* Chunk boundaries:
+* - Object: opening tag, one chunk per field, closing tag
+* - Array: opening tag, one chunk per item, closing tag
+* - Record: opening tag, one chunk per entry, closing tag
+* - Leaf types (string, number, boolean, enum, literal, unknown):
+*   rendered entirely as one chunk
+*
+* All HTML construction uses `h()` from `html.ts` — the streaming module
+* manually yields the opening tag, then children, then the closing tag.
+*/
+/**
+* Yield the opening tag of an element (e.g. `<fieldset class="sc-object">`).
+* For void elements, yields the complete self-closing tag.
+*/
+function yieldOpen(el) {
+	const attrs = serializeAttributes(el.attributes);
+	return `<${el.tag}${attrs}>`;
+}
+/**
+* Yield the closing tag of an element (e.g. `</fieldset>`).
+* Returns empty string for void elements.
+*/
+function yieldClose(el) {
+	if (VOID_ELEMENTS.has(el.tag)) return "";
+	return `</${el.tag}>`;
+}
+/**
+* Render a schema to HTML string chunks, yielded incrementally.
+*
+* Each yielded chunk is a self-contained HTML fragment. Concatenating
+* all chunks produces the same output as `renderToHtml`.
+*
+* @returns Sync iterable of HTML string chunks
+*/
+function* renderToHtmlChunks(schema, options = {}) {
+	const tree = prepareTree(schema, options);
+	const resolver = options.resolver ?? defaultHtmlResolver;
+	const mergedResolver = mergeHtmlResolvers(resolver, defaultHtmlResolver);
+	yield* streamField(tree, options.value, mergedResolver, "", resolver);
+}
+/**
+* Render a schema to HTML string chunks asynchronously.
+*
+* Identical chunk boundaries to `renderToHtmlChunks` but yields via
+* an async generator. Use with `for await...of` or pipe to a response.
+*
+* @returns Async iterable of HTML string chunks
+*/
+async function* renderToHtmlStream(schema, options = {}) {
+	const tree = prepareTree(schema, options);
+	const resolver = options.resolver ?? defaultHtmlResolver;
+	const mergedResolver = mergeHtmlResolvers(resolver, defaultHtmlResolver);
+	for (const chunk of streamField(tree, options.value, mergedResolver, "", resolver)) {
+		yield chunk;
+		await schedulerYield();
+	}
+}
+/**
+* No-op await that yields control to the event loop.
+*/
+function schedulerYield() {
+	return Promise.resolve(void 0);
+}
+/**
+* Render a schema to a web `ReadableStream<string>`.
+*
+* ```ts
+* return new Response(renderToHtmlReadable(schema, { value }), {
+*     headers: { "Content-Type": "text/html" },
+* });
+* ```
+*/
+function renderToHtmlReadable(schema, options = {}) {
+	const iterator = renderToHtmlChunks(schema, options)[Symbol.iterator]();
+	return new ReadableStream({
+		pull(controller) {
+			const result = iterator.next();
+			if (result.done) controller.close();
+			else controller.enqueue(result.value);
+		},
+		cancel() {
+			if (iterator.return !== void 0) iterator.return();
+		}
+	});
+}
+function prepareTree(schema, options) {
+	const mergedMeta = { ...options.meta };
+	if (options.readOnly === true) mergedMeta.readOnly = true;
+	if (options.writeOnly === true) mergedMeta.writeOnly = true;
+	if (options.description !== void 0) mergedMeta.description = options.description;
+	const { jsonSchema, rootMeta, rootDocument } = normaliseSchema(schema, options.ref);
+	return walk(jsonSchema, {
+		componentMeta: mergedMeta,
+		rootMeta,
+		fieldOverrides: options.fields,
+		rootDocument
+	});
+}
+function* streamField(tree, value, mergedResolver, path, rawResolver) {
+	const type = tree.type;
+	if (type === "string" || type === "number" || type === "boolean" || type === "enum" || type === "literal" || type === "file" || type === "unknown") {
+		yield renderLeaf(tree, value, mergedResolver, path);
+		return;
+	}
+	if (type === "union" || type === "discriminatedUnion") {
+		yield* streamUnion(tree, value, mergedResolver, path, rawResolver);
+		return;
+	}
+	if (type === "object") {
+		yield* streamObject(tree, value, mergedResolver, path, rawResolver);
+		return;
+	}
+	if (type === "array") {
+		yield* streamArray(tree, value, mergedResolver, path, rawResolver);
+		return;
+	}
+	if (type === "record") {
+		yield* streamRecord(tree, value, mergedResolver, path, rawResolver);
+		return;
+	}
+	yield renderLeaf(tree, value, mergedResolver, path);
+}
+function* streamObject(tree, value, mergedResolver, path, rawResolver) {
+	const fields = tree.fields;
+	if (fields === void 0) return;
+	const obj = isObject(value) ? value : {};
+	const readOnly = tree.editability === "presentation";
+	const descriptionText = typeof tree.meta.description === "string" ? tree.meta.description : void 0;
+	const labelAttrs = ariaLabelAttrs(descriptionText);
+	if (readOnly) {
+		const dlAttrs = { class: "sc-object" };
+		Object.assign(dlAttrs, labelAttrs);
+		const dl = h("dl", dlAttrs);
+		const legend = descriptionText !== void 0 ? serialize(h("legend", {}, descriptionText)) : "";
+		yield `${yieldOpen(dl)}${legend}`;
+		for (const [key, field] of Object.entries(fields)) {
+			const label = typeof field.meta.description === "string" ? field.meta.description : key;
+			const childValue = obj[key];
+			const childHtml = renderFieldSync(field, childValue, mergedResolver, key, rawResolver);
+			yield `${serialize(h("dt", { class: "sc-label" }, label))}${serialize(h("dd", { class: "sc-value" }, raw(childHtml)))}`;
+		}
+		yield yieldClose(dl);
+	} else {
+		const fieldsetAttrs = { class: "sc-object" };
+		Object.assign(fieldsetAttrs, labelAttrs);
+		const fieldset = h("fieldset", fieldsetAttrs);
+		const legend = descriptionText !== void 0 ? serialize(h("legend", {}, descriptionText)) : "";
+		yield `${yieldOpen(fieldset)}${legend}`;
+		for (const [key, field] of Object.entries(fields)) {
+			const label = typeof field.meta.description === "string" ? field.meta.description : key;
+			const fieldId = buildInputId(path, key);
+			const childValue = obj[key];
+			const childChunks = [...streamField(field, childValue, mergedResolver, key, rawResolver)].join("");
+			const required = requiredIndicator(field);
+			const labelContent = [label];
+			if (required !== void 0) labelContent.push(required);
+			const fieldChildren = [h("label", {
+				class: "sc-label",
+				for: fieldId
+			}, ...labelContent), raw(childChunks)];
+			const hint = buildHintElement(key, field.constraints);
+			if (hint !== void 0) fieldChildren.push(hint);
+			yield serialize(h("div", { class: "sc-field" }, ...fieldChildren));
+		}
+		yield yieldClose(fieldset);
+	}
+}
+function* streamArray(tree, value, mergedResolver, path, rawResolver) {
+	const arr = Array.isArray(value) ? value : [];
+	const element = tree.element;
+	if (element === void 0) return;
+	const readOnly = tree.editability === "presentation";
+	const elementPath = typeof element.meta.description === "string" ? element.meta.description : "";
+	if (readOnly) {
+		const ul = h("ul", { class: "sc-array" });
+		yield yieldOpen(ul);
+		for (const item of arr) yield serialize(h("li", { class: "sc-item" }, raw(renderFieldSync(element, item, mergedResolver, elementPath, rawResolver))));
+		yield yieldClose(ul);
+	} else {
+		const div = h("div", { class: "sc-array" });
+		yield yieldOpen(div);
+		for (const item of arr) yield serialize(h("div", {}, raw(renderFieldSync(element, item, mergedResolver, elementPath, rawResolver))));
+		yield yieldClose(div);
+	}
+}
+function* streamRecord(tree, value, mergedResolver, path, rawResolver) {
+	const obj = isObject(value) ? value : {};
+	const valueType = tree.valueType;
+	if (valueType === void 0) return;
+	const readOnly = tree.editability === "presentation";
+	const attrs = {
+		class: "sc-record",
+		role: "group"
+	};
+	if (readOnly) {
+		const dl = h("dl", attrs);
+		yield yieldOpen(dl);
+		for (const [key, val] of Object.entries(obj)) {
+			const childHtml = renderFieldSync(valueType, val, mergedResolver, key, rawResolver);
+			yield `${serialize(h("dt", { class: "sc-label" }, key))}${serialize(h("dd", { class: "sc-value" }, raw(childHtml)))}`;
+		}
+		yield yieldClose(dl);
+	} else {
+		const container = h("div", attrs);
+		yield yieldOpen(container);
+		for (const [key, val] of Object.entries(obj)) {
+			const childHtml = renderFieldSync(valueType, val, mergedResolver, key, rawResolver);
+			yield serialize(h("div", { class: "sc-field" }, h("label", { class: "sc-label" }, key), raw(childHtml)));
+		}
+		yield yieldClose(container);
+	}
+}
+function* streamUnion(tree, value, mergedResolver, path, rawResolver) {
+	const options = tree.options;
+	if (options === void 0 || options.length === 0) {
+		if (value === void 0 || value === null) yield serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
+		else yield serialize(h("span", { class: "sc-value" }, JSON.stringify(value)));
+		return;
+	}
+	const target = matchUnionOption(options, value) ?? options[0];
+	if (target !== void 0) yield* streamField(target, value, mergedResolver, typeof target.meta.description === "string" ? target.meta.description : "", rawResolver);
+	else yield serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
+}
+function renderLeaf(tree, value, mergedResolver, path) {
+	const renderFn = getHtmlRenderFn(tree.type, mergedResolver);
+	if (renderFn !== void 0) {
+		const props = {
+			value,
+			readOnly: tree.editability === "presentation",
+			writeOnly: tree.editability === "input",
+			meta: tree.meta,
+			constraints: tree.constraints,
+			path,
+			tree,
+			renderChild: () => ""
+		};
+		if (tree.enumValues !== void 0) props.enumValues = tree.enumValues;
+		if (tree.element !== void 0) props.element = tree.element;
+		if (tree.fields !== void 0) props.fields = tree.fields;
+		if (tree.options !== void 0) props.options = tree.options;
+		if (tree.discriminator !== void 0) props.discriminator = tree.discriminator;
+		if (tree.keyType !== void 0) props.keyType = tree.keyType;
+		if (tree.valueType !== void 0) props.valueType = tree.valueType;
+		return renderFn(props);
+	}
+	if (value === void 0 || value === null) return serialize(h("span", { class: "sc-value sc-value--empty" }, "—"));
+	return serialize(h("span", { class: "sc-value" }, typeof value === "string" ? value : JSON.stringify(value)));
+}
+/**
+* Render a field synchronously to a string, recursively streaming children.
+*/
+function renderFieldSync(tree, value, mergedResolver, path, rawResolver) {
+	return [...streamField(tree, value, mergedResolver, path, rawResolver)].join("");
+}
+function matchUnionOption(options, value) {
+	if (typeof value === "string") return options.find((o) => o.type === "string" || o.type === "enum");
+	if (typeof value === "number") return options.find((o) => o.type === "number");
+	if (typeof value === "boolean") return options.find((o) => o.type === "boolean");
+	if (Array.isArray(value)) return options.find((o) => o.type === "array");
+	if (typeof value === "object" && value !== null) return options.find((o) => o.type === "object");
+}
+//#endregion
+export { renderToHtmlChunks, renderToHtmlReadable, renderToHtmlStream };

package/dist/html/styles.css

@@ -0,0 +1,151 @@
+/**
+ * Default styles for Schema Components HTML output.
+ *
+ * All classes use the `sc-` prefix to avoid collisions.
+ * Import this stylesheet when using the HTML renderer without
+ * a custom theme adapter.
+ *
+ * ```html
+ * <link rel="stylesheet" href="node_modules/@scalar/schema-components/dist/styles.css">
+ * ```
+ */
+
+/* ---------------------------------------------------------------------- */
+/* Object containers                                                      */
+/* ---------------------------------------------------------------------- */
+
+.sc-object {
+    border: 1px solid #e2e8f0;
+    border-radius: 0.375rem;
+    padding: 1rem;
+}
+
+.sc-object legend {
+    font-weight: 600;
+    font-size: 0.875rem;
+    color: #334155;
+    padding: 0 0.25rem;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Fields                                                                 */
+/* ---------------------------------------------------------------------- */
+
+.sc-field {
+    margin-bottom: 0.75rem;
+}
+
+.sc-field:last-child {
+    margin-bottom: 0;
+}
+
+.sc-label {
+    display: block;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: #374151;
+    margin-bottom: 0.25rem;
+}
+
+.sc-required {
+    color: #dc2626;
+    font-weight: 600;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Inputs                                                                 */
+/* ---------------------------------------------------------------------- */
+
+.sc-input {
+    width: 100%;
+    padding: 0.375rem 0.5rem;
+    border: 1px solid #d1d5db;
+    border-radius: 0.25rem;
+    font-size: 0.875rem;
+    line-height: 1.25rem;
+    color: #111827;
+    background-color: #fff;
+    box-sizing: border-box;
+}
+
+.sc-input:focus {
+    outline: 2px solid #3b82f6;
+    outline-offset: -1px;
+    border-color: transparent;
+}
+
+.sc-input[type="checkbox"] {
+    width: auto;
+    margin: 0;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Read-only values                                                       */
+/* ---------------------------------------------------------------------- */
+
+.sc-value {
+    font-size: 0.875rem;
+    color: #111827;
+}
+
+.sc-value--empty {
+    color: #9ca3af;
+}
+
+.sc-value--boolean {
+    font-weight: 500;
+}
+
+.sc-value[href] {
+    color: #2563eb;
+    text-decoration: none;
+}
+
+.sc-value[href]:hover {
+    text-decoration: underline;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Arrays                                                                 */
+/* ---------------------------------------------------------------------- */
+
+.sc-array {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+
+.sc-array > div {
+    margin-bottom: 0.375rem;
+}
+
+.sc-array > div:last-child {
+    margin-bottom: 0;
+}
+
+.sc-item {
+    margin-bottom: 0.375rem;
+}
+
+.sc-item:last-child {
+    margin-bottom: 0;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Records                                                                */
+/* ---------------------------------------------------------------------- */
+
+.sc-record {
+    margin: 0;
+}
+
+/* ---------------------------------------------------------------------- */
+/* Constraint hints                                                       */
+/* ---------------------------------------------------------------------- */
+
+.sc-hint {
+    display: block;
+    font-size: 0.75rem;
+    color: #6b7280;
+    margin-top: 0.25rem;
+}

package/dist/openapi/components.d.mts

@@ -0,0 +1,76 @@
+import { c as InferResponseFields, m as SchemaMeta, o as InferParameterOverrides, r as FieldOverride, s as InferRequestBodyFields } from "../types-BU0ETFHk.mjs";
+import { ReactNode } from "react";
+
+//#region src/openapi/components.d.ts
+interface ApiOperationProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+  schema: Doc;
+  path: Path;
+  method: Method;
+  requestBodyValue?: unknown;
+  onRequestBodyChange?: (value: unknown) => void;
+  responseValue?: unknown;
+  meta?: SchemaMeta;
+  requestBodyFields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+}
+declare function ApiOperation<Doc = unknown, Path extends string = string, Method extends string = string>({
+  schema: doc,
+  path,
+  method,
+  requestBodyValue,
+  onRequestBodyChange,
+  responseValue,
+  meta,
+  requestBodyFields
+}: ApiOperationProps<Doc, Path, Method>): ReactNode;
+interface ApiParametersProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+  schema: Doc;
+  path: Path;
+  method: Method;
+  meta?: SchemaMeta;
+  overrides?: Doc extends Record<string, unknown> ? InferParameterOverrides<Doc, Path, Method> : Record<string, FieldOverride>;
+}
+declare function ApiParameters<Doc = unknown, Path extends string = string, Method extends string = string>({
+  schema: doc,
+  path,
+  method,
+  meta,
+  overrides
+}: ApiParametersProps<Doc, Path, Method>): ReactNode;
+interface ApiRequestBodyProps<Doc = unknown, Path extends string = string, Method extends string = string> {
+  schema: Doc;
+  path: Path;
+  method: Method;
+  value?: unknown;
+  onChange?: (value: unknown) => void;
+  meta?: SchemaMeta;
+  fields?: Doc extends Record<string, unknown> ? InferRequestBodyFields<Doc, Path, Method> : Record<string, FieldOverride>;
+}
+declare function ApiRequestBody<Doc = unknown, Path extends string = string, Method extends string = string>({
+  schema: doc,
+  path,
+  method,
+  value,
+  onChange,
+  meta,
+  fields
+}: ApiRequestBodyProps<Doc, Path, Method>): ReactNode;
+interface ApiResponseProps<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string> {
+  schema: Doc;
+  path: Path;
+  method: Method;
+  status: Status;
+  value?: unknown;
+  meta?: SchemaMeta;
+  fields?: Doc extends Record<string, unknown> ? InferResponseFields<Doc, Path, Method, Status> : Record<string, FieldOverride>;
+}
+declare function ApiResponse<Doc = unknown, Path extends string = string, Method extends string = string, Status extends string = string>({
+  schema: doc,
+  path,
+  method,
+  status,
+  value,
+  meta,
+  fields
+}: ApiResponseProps<Doc, Path, Method, Status>): ReactNode;
+//#endregion
+export { ApiOperation, ApiOperationProps, ApiParameters, ApiParametersProps, ApiRequestBody, ApiRequestBodyProps, ApiResponse, ApiResponseProps };