schema-components 0.0.0 → 1.1.0

package/dist/core/walker.mjs

@@ -0,0 +1,366 @@
+import { isObject } from "./guards.mjs";
+import { resolveEditability } from "./types.mjs";
+//#region src/core/walker.ts
+function getString(obj, key) {
+	const value = obj[key];
+	return typeof value === "string" ? value : void 0;
+}
+function getNumber(obj, key) {
+	const value = obj[key];
+	return typeof value === "number" ? value : void 0;
+}
+function getArray(obj, key) {
+	const value = obj[key];
+	return Array.isArray(value) ? value : void 0;
+}
+function getObject(obj, key) {
+	const value = obj[key];
+	return isObject(value) ? value : void 0;
+}
+const MAX_REF_DEPTH = 10;
+function resolveRef(schema, rootDocument, visited) {
+	const ref = getString(schema, "$ref");
+	if (ref === void 0) return schema;
+	if (visited.has(ref)) return { type: "unknown" };
+	if (visited.size >= MAX_REF_DEPTH) return { type: "unknown" };
+	const resolved = dereference(ref, rootDocument);
+	if (resolved === void 0) return { type: "unknown" };
+	const nextVisited = new Set(visited);
+	nextVisited.add(ref);
+	return resolveRef(resolved, rootDocument, nextVisited);
+}
+function dereference(ref, root) {
+	if (!ref.startsWith("#/")) return void 0;
+	const parts = ref.slice(2).split("/");
+	let current = root;
+	for (const part of parts) {
+		if (!isObject(current)) return void 0;
+		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
+		current = current[decoded];
+	}
+	return isObject(current) ? current : void 0;
+}
+/**
+* Merge multiple JSON Schema objects from allOf into one.
+* Merges: properties, required, meta fields, and constraints.
+*/
+function mergeAllOf(schemas) {
+	const merged = {};
+	const properties = {};
+	const required = [];
+	for (const entry of schemas) {
+		if (!isObject(entry)) continue;
+		const props = getObject(entry, "properties");
+		if (props !== void 0) for (const [key, value] of Object.entries(props)) properties[key] = value;
+		const req = getArray(entry, "required");
+		if (req !== void 0) {
+			for (const r of req) if (typeof r === "string" && !required.includes(r)) required.push(r);
+		}
+		for (const [key, value] of Object.entries(entry)) {
+			if (key === "properties" || key === "required" || key === "allOf" || key === "type") continue;
+			if (!(key in merged)) merged[key] = value;
+		}
+		if (!("type" in merged)) {
+			const type = getString(entry, "type");
+			if (type !== void 0) merged.type = type;
+		}
+	}
+	if (Object.keys(properties).length > 0) merged.properties = properties;
+	if (required.length > 0) merged.required = required;
+	return merged;
+}
+/**
+* Detect `anyOf: [T, { type: "null" }]` → nullable T.
+* Returns the non-null schema and a nullable flag.
+*/
+function normaliseAnyOf(options) {
+	if (options.length !== 2) return void 0;
+	let inner;
+	let hasNull = false;
+	for (const opt of options) {
+		if (!isObject(opt)) return void 0;
+		if (opt.type === "null") hasNull = true;
+		else inner = opt;
+	}
+	if (!hasNull || inner === void 0) return void 0;
+	return {
+		inner,
+		isNullable: true
+	};
+}
+/**
+* Detect oneOf where every option is an object with a property
+* that has a `const` value → discriminated union.
+*/
+function detectDiscriminated(options) {
+	if (options.length === 0) return void 0;
+	let discriminator;
+	for (const opt of options) {
+		if (!isObject(opt)) return void 0;
+		const props = getObject(opt, "properties");
+		if (props === void 0) return void 0;
+		let foundKey;
+		for (const [key, value] of Object.entries(props)) if (isObject(value) && "const" in value) {
+			foundKey = key;
+			break;
+		}
+		if (foundKey === void 0) return void 0;
+		if (discriminator === void 0) discriminator = foundKey;
+		else if (discriminator !== foundKey) return;
+	}
+	if (discriminator === void 0) return void 0;
+	return {
+		options: options.filter(isObject),
+		discriminator
+	};
+}
+const META_KEYWORDS = new Set([
+	"readOnly",
+	"writeOnly",
+	"description",
+	"title",
+	"deprecated",
+	"default",
+	"component",
+	"example",
+	"examples"
+]);
+function extractMetaFromJson(schema) {
+	const meta = {};
+	for (const [key, value] of Object.entries(schema)) if (META_KEYWORDS.has(key)) meta[key] = value;
+	return meta;
+}
+function extractConstraintsFromJson(schema) {
+	const constraints = {};
+	const minLength = getNumber(schema, "minLength");
+	if (minLength !== void 0) constraints.minLength = minLength;
+	const maxLength = getNumber(schema, "maxLength");
+	if (maxLength !== void 0) constraints.maxLength = maxLength;
+	const minimum = getNumber(schema, "minimum");
+	if (minimum !== void 0) constraints.minimum = minimum;
+	const maximum = getNumber(schema, "maximum");
+	if (maximum !== void 0) constraints.maximum = maximum;
+	const pattern = getString(schema, "pattern");
+	if (pattern !== void 0) constraints.pattern = pattern;
+	const format = getString(schema, "format");
+	if (format !== void 0) constraints.format = format;
+	const minItems = getNumber(schema, "minItems");
+	if (minItems !== void 0) constraints.minItems = minItems;
+	const maxItems = getNumber(schema, "maxItems");
+	if (maxItems !== void 0) constraints.maxItems = maxItems;
+	if (format === "binary") {
+		const contentMediaType = getString(schema, "contentMediaType");
+		if (contentMediaType !== void 0) constraints.mimeTypes = [contentMediaType];
+	}
+	return constraints;
+}
+const OVERRIDE_META_KEYS = new Set([
+	"readOnly",
+	"writeOnly",
+	"description",
+	"title",
+	"deprecated",
+	"component"
+]);
+function extractSchemaMetaFields(overrides) {
+	if (overrides === void 0) return void 0;
+	const meta = {};
+	for (const key of Object.keys(overrides)) if (OVERRIDE_META_KEYS.has(key)) meta[key] = overrides[key];
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
+function extractChildOverride(overrides, key) {
+	if (overrides === void 0) return void 0;
+	const child = overrides[key];
+	if (child === void 0 || child === null) return void 0;
+	if (typeof child !== "object" || Array.isArray(child)) return void 0;
+	const result = {};
+	for (const [k, v] of Object.entries(child)) result[k] = v;
+	return Object.keys(result).length > 0 ? result : void 0;
+}
+function walk(schema, options = {}) {
+	const { componentMeta, rootMeta, fieldOverrides, rootDocument } = options;
+	if (!isObject(schema)) return {
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
+	const doc = rootDocument ?? schema;
+	return walkNode(resolveRef(schema, doc, /* @__PURE__ */ new Set()), {
+		componentMeta,
+		rootMeta,
+		fieldOverrides,
+		rootDocument: doc,
+		isNullable: false,
+		isOptional: false,
+		defaultValue: void 0
+	});
+}
+function walkNode(schema, ctx) {
+	const allOf = getArray(schema, "allOf");
+	if (allOf !== void 0 && allOf.length > 0) return walkNode(mergeAllOf(allOf), ctx);
+	const anyOf = getArray(schema, "anyOf");
+	if (anyOf !== void 0) {
+		const nullable = normaliseAnyOf(anyOf);
+		if (nullable !== void 0) return walkNode(nullable.inner, {
+			...ctx,
+			isNullable: true
+		});
+		return walkUnion(anyOf, ctx);
+	}
+	const oneOf = getArray(schema, "oneOf");
+	if (oneOf !== void 0) {
+		const discriminated = detectDiscriminated(oneOf);
+		if (discriminated !== void 0) return walkDiscriminatedUnion(discriminated, ctx);
+		return walkUnion(oneOf, ctx);
+	}
+	const resolved = resolveRef(schema, ctx.rootDocument, /* @__PURE__ */ new Set());
+	const enumValues = getArray(resolved, "enum");
+	if (enumValues !== void 0) return walkEnum(resolved, enumValues, ctx);
+	if ("const" in resolved) return walkLiteral(resolved, ctx);
+	const type = getString(resolved, "type");
+	if (type === void 0) return buildField(resolved, "unknown", ctx);
+	if (type === "string") return walkString(resolved, ctx);
+	if (type === "number" || type === "integer") return walkNumber(resolved, ctx);
+	if (type === "boolean") return walkBoolean(resolved, ctx);
+	if (type === "null") return buildField(resolved, "null", ctx);
+	if (type === "object") {
+		const properties = getObject(resolved, "properties");
+		if (properties !== void 0) return walkObject(resolved, properties, ctx);
+		const additionalProps = getObject(resolved, "additionalProperties");
+		if (additionalProps !== void 0) return walkRecord(resolved, additionalProps, ctx);
+		return buildField(resolved, "object", ctx);
+	}
+	if (type === "array") return walkArray(resolved, ctx);
+	return buildField(resolved, "unknown", ctx);
+}
+function walkString(schema, ctx) {
+	if (getString(schema, "format") === "binary") return buildField(schema, "file", ctx);
+	return buildField(schema, "string", ctx);
+}
+function walkNumber(schema, ctx) {
+	return buildField(schema, "number", ctx);
+}
+function walkBoolean(schema, ctx) {
+	return buildField(schema, "boolean", ctx);
+}
+function walkEnum(schema, enumValues, ctx) {
+	return {
+		...buildField(schema, "enum", ctx),
+		enumValues: enumValues.filter((v) => typeof v === "string")
+	};
+}
+function walkLiteral(schema, ctx) {
+	const constValue = schema.const;
+	const values = isPrimitive(constValue) ? [constValue] : [];
+	return {
+		...buildField(schema, "literal", ctx),
+		literalValues: values
+	};
+}
+function walkObject(schema, properties, ctx) {
+	const base = buildField(schema, "object", ctx);
+	const required = getArray(schema, "required");
+	const fields = {};
+	for (const [key, propSchema] of Object.entries(properties)) {
+		const childOverride = extractChildOverride(ctx.fieldOverrides, key);
+		const isRequired = required?.includes(key) === true;
+		const childCtx = {
+			...ctx,
+			fieldOverrides: childOverride,
+			isOptional: !isRequired
+		};
+		const overrideMeta = extractSchemaMetaFields(childOverride);
+		if (overrideMeta !== void 0 && ("readOnly" in overrideMeta || "writeOnly" in overrideMeta)) childCtx.componentMeta = void 0;
+		if (isObject(propSchema)) fields[key] = walkNode(propSchema, childCtx);
+		else fields[key] = {
+			type: "unknown",
+			editability: "editable",
+			meta: {},
+			constraints: {}
+		};
+	}
+	return {
+		...base,
+		fields
+	};
+}
+function walkRecord(schema, valueSchema, ctx) {
+	const base = buildField(schema, "record", ctx);
+	const propertyNames = getObject(schema, "propertyNames");
+	const keyType = propertyNames !== void 0 ? walkNode(propertyNames, ctx) : {
+		type: "string",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
+	const valueType = walkNode(valueSchema, ctx);
+	return {
+		...base,
+		keyType,
+		valueType
+	};
+}
+function walkArray(schema, ctx) {
+	const base = buildField(schema, "array", ctx);
+	const items = getObject(schema, "items");
+	if (items !== void 0) {
+		const elementOverride = extractChildOverride(ctx.fieldOverrides, "[]");
+		return {
+			...base,
+			element: walkNode(items, {
+				...ctx,
+				fieldOverrides: elementOverride
+			})
+		};
+	}
+	return base;
+}
+function walkUnion(options, ctx) {
+	const optionsArray = options.filter(isObject);
+	return {
+		...buildField({}, "union", ctx),
+		options: optionsArray.map((opt) => walkNode(opt, {
+			...ctx,
+			fieldOverrides: void 0
+		}))
+	};
+}
+function walkDiscriminatedUnion(discriminated, ctx) {
+	return {
+		...buildField({}, "discriminatedUnion", ctx),
+		options: discriminated.options.map((opt) => walkNode(opt, {
+			...ctx,
+			fieldOverrides: void 0
+		})),
+		discriminator: discriminated.discriminator
+	};
+}
+function buildField(schema, type, ctx) {
+	const propertyMeta = extractMetaFromJson(schema);
+	const overrideMeta = extractSchemaMetaFields(ctx.fieldOverrides);
+	const mergedMeta = {
+		...propertyMeta,
+		...overrideMeta
+	};
+	const defaultValue = "default" in schema ? schema.default : void 0;
+	const editability = resolveEditability(mergedMeta, ctx.componentMeta, ctx.rootMeta);
+	if ((overrideMeta !== void 0 && ("readOnly" in overrideMeta || "writeOnly" in overrideMeta) || Boolean(propertyMeta.readOnly) || Boolean(propertyMeta.writeOnly)) && ctx.componentMeta !== void 0) ctx = {
+		...ctx,
+		componentMeta: void 0
+	};
+	return {
+		type,
+		editability,
+		meta: mergedMeta,
+		isOptional: ctx.isOptional,
+		isNullable: ctx.isNullable,
+		defaultValue: defaultValue ?? ctx.defaultValue,
+		constraints: extractConstraintsFromJson(schema)
+	};
+}
+function isPrimitive(value) {
+	return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null;
+}
+//#endregion
+export { walk };

package/dist/errors-DIKI2C78.d.mts

@@ -0,0 +1,57 @@
+//#region src/core/errors.d.ts
+/**
+ * Structured error types for schema-components.
+ *
+ * Every error produced by the library is one of these three types:
+ *
+ * - SchemaNormalisationError — the adapter failed to convert the input
+ *   to JSON Schema (invalid Zod, bad OpenAPI ref, malformed schema)
+ * - SchemaRenderError — a theme adapter's render function threw
+ * - SchemaFieldError — a field path couldn't be resolved
+ *
+ * All extend `SchemaError` so consumers can catch the base class.
+ */
+/**
+ * Base class for all schema-components errors.
+ * Catch this to handle any library error uniformly.
+ */
+declare class SchemaError extends Error {
+  /** The schema input that caused the error. */
+  readonly schema: unknown;
+  constructor(message: string, schema: unknown);
+}
+/**
+ * The adapter failed to convert the input schema to JSON Schema.
+ *
+ * Causes: invalid Zod schema, Zod 3 schema (unsupported), malformed
+ * JSON Schema, missing OpenAPI ref, unsupported ref format.
+ */
+declare class SchemaNormalisationError extends SchemaError {
+  readonly kind: "invalid-zod" | "zod3-unsupported" | "invalid-json-schema" | "openapi-missing-ref" | "openapi-invalid" | "unknown";
+  constructor(message: string, schema: unknown, kind: SchemaNormalisationError["kind"]);
+}
+/**
+ * A theme adapter's render function threw during rendering.
+ *
+ * The `cause` is the original error from the render function.
+ */
+declare class SchemaRenderError extends SchemaError {
+  /** The schema type being rendered when the error occurred. */
+  readonly schemaType: string;
+  /** The original error from the render function. */
+  readonly cause: unknown;
+  constructor(message: string, schema: unknown, schemaType: string, cause: unknown);
+}
+/**
+ * A field path couldn't be resolved against the walked schema tree.
+ *
+ * This is produced by `<SchemaField>` when the `path` prop doesn't
+ * match any field in the schema.
+ */
+declare class SchemaFieldError extends SchemaError {
+  /** The unresolvable dot-separated path. */
+  readonly path: string;
+  constructor(message: string, schema: unknown, path: string);
+}
+//#endregion
+export { SchemaRenderError as i, SchemaFieldError as n, SchemaNormalisationError as r, SchemaError as t };

package/dist/html/a11y.d.mts

@@ -0,0 +1,47 @@
+import { _ as WalkedField, n as FieldConstraints } from "../types-BU0ETFHk.mjs";
+import { HtmlAttributes, HtmlNode } from "./html.mjs";
+
+//#region src/html/a11y.d.ts
+/**
+ * Build the input ID for a field at a given path.
+ */
+declare function buildInputId(path: string, key: string): string;
+/**
+ * Derive the hint element ID from the input ID.
+ */
+declare function buildHintId(inputId: string): string;
+/**
+ * Build a human-readable constraint description string.
+ * Returns undefined if no constraints are present.
+ */
+declare function constraintHint(c: FieldConstraints): string | undefined;
+/**
+ * Build `aria-required` attribute for required fields.
+ * Returns an object to spread into `h()` attributes, or empty object.
+ */
+declare function ariaRequiredAttrs(tree: WalkedField): Pick<HtmlAttributes, "aria-required"> | undefined;
+/**
+ * Build `aria-describedby` attribute pointing to the constraint hint element.
+ * Only present when constraints exist.
+ */
+declare function ariaDescribedByAttrs(inputId: string, constraints: FieldConstraints): Pick<HtmlAttributes, "aria-describedby"> | undefined;
+/**
+ * Build `aria-readonly` attribute for read-only presentation.
+ */
+declare function ariaReadonlyAttrs(): Pick<HtmlAttributes, "aria-readonly">;
+/**
+ * Build `aria-label` attribute from description, if present.
+ */
+declare function ariaLabelAttrs(description: unknown): Pick<HtmlAttributes, "aria-label"> | undefined;
+/**
+ * Build a `<small class="sc-hint">` element for constraint hints.
+ * Returns undefined if no constraints are present.
+ */
+declare function buildHintElement(inputId: string, constraints: FieldConstraints): HtmlNode;
+/**
+ * Build the required-field asterisk indicator for labels.
+ * Returns undefined if the field is optional.
+ */
+declare function requiredIndicator(field: WalkedField): HtmlNode;
+//#endregion
+export { ariaDescribedByAttrs, ariaLabelAttrs, ariaReadonlyAttrs, ariaRequiredAttrs, buildHintElement, buildHintId, buildInputId, constraintHint, requiredIndicator };

package/dist/html/a11y.mjs

@@ -0,0 +1,81 @@
+import { h } from "./html.mjs";
+//#region src/html/a11y.ts
+/**
+* Build the input ID for a field at a given path.
+*/
+function buildInputId(path, key) {
+	return `sc-${path ? `${path}-${key}` : key}`;
+}
+/**
+* Derive the hint element ID from the input ID.
+*/
+function buildHintId(inputId) {
+	return `${inputId}-hint`;
+}
+/**
+* Build a human-readable constraint description string.
+* Returns undefined if no constraints are present.
+*/
+function constraintHint(c) {
+	const parts = [];
+	if (c.minLength !== void 0) parts.push(`Minimum ${String(c.minLength)} characters`);
+	if (c.maxLength !== void 0) parts.push(`Maximum ${String(c.maxLength)} characters`);
+	if (c.minimum !== void 0) parts.push(`Minimum ${String(c.minimum)}`);
+	if (c.maximum !== void 0) parts.push(`Maximum ${String(c.maximum)}`);
+	if (c.pattern !== void 0 && c.format === void 0) parts.push("Must match pattern");
+	if (c.minItems !== void 0) parts.push(`Minimum ${String(c.minItems)} items`);
+	if (c.maxItems !== void 0) parts.push(`Maximum ${String(c.maxItems)} items`);
+	if (parts.length === 0) return void 0;
+	return parts.join(". ");
+}
+/**
+* Build `aria-required` attribute for required fields.
+* Returns an object to spread into `h()` attributes, or empty object.
+*/
+function ariaRequiredAttrs(tree) {
+	if (tree.isOptional === false) return { "aria-required": "true" };
+}
+/**
+* Build `aria-describedby` attribute pointing to the constraint hint element.
+* Only present when constraints exist.
+*/
+function ariaDescribedByAttrs(inputId, constraints) {
+	if (constraintHint(constraints) === void 0) return void 0;
+	return { "aria-describedby": buildHintId(inputId) };
+}
+/**
+* Build `aria-readonly` attribute for read-only presentation.
+*/
+function ariaReadonlyAttrs() {
+	return { "aria-readonly": "true" };
+}
+/**
+* Build `aria-label` attribute from description, if present.
+*/
+function ariaLabelAttrs(description) {
+	if (typeof description === "string" && description.length > 0) return { "aria-label": description };
+}
+/**
+* Build a `<small class="sc-hint">` element for constraint hints.
+* Returns undefined if no constraints are present.
+*/
+function buildHintElement(inputId, constraints) {
+	const hint = constraintHint(constraints);
+	if (hint === void 0) return void 0;
+	return h("small", {
+		class: "sc-hint",
+		id: buildHintId(inputId)
+	}, hint);
+}
+/**
+* Build the required-field asterisk indicator for labels.
+* Returns undefined if the field is optional.
+*/
+function requiredIndicator(field) {
+	if (field.isOptional === false) return h("span", {
+		class: "sc-required",
+		"aria-hidden": "true"
+	}, " *");
+}
+//#endregion
+export { ariaDescribedByAttrs, ariaLabelAttrs, ariaReadonlyAttrs, ariaRequiredAttrs, buildHintElement, buildHintId, buildInputId, constraintHint, requiredIndicator };

package/dist/html/html.d.mts

@@ -0,0 +1,135 @@
+//#region src/html/html.d.ts
+/**
+ * Typed HTML builder — structured HTML construction with compile-time safety.
+ *
+ * Instead of string templates, renderers call `h(tag, attrs, ...children)` to
+ * build an AST, then `serialize()` converts it to an HTML string. This gives:
+ *
+ * - Compile-time checking of tag names and attribute keys
+ * - Automatic HTML escaping (serialiser handles it — callers never escape manually)
+ * - Streaming via `serializeChunks()` which yields at element boundaries
+ * - Zero dependencies
+ *
+ * Usage:
+ *
+ *     import { h, serialize } from "./html.ts";
+ *
+ *     const el = h("input", { type: "text", id: "name", "aria-required": true });
+ *     serialize(el); // → '<input type="text" id="name" aria-required>'
+ *
+ *     const form = h("form", {},
+ *         h("label", { for: "name" }, "Name"),
+ *         h("input", { type: "text", id: "name" }),
+ *     );
+ *     serialize(form); // → '<form><label for="name">Name</label><input type="text" id="name"></form>'
+ */
+/**
+ * An HTML element node. Void elements (input, br, etc.) have no children
+ * in the serialiser regardless of what's passed.
+ */
+interface HtmlElement {
+  readonly tag: string;
+  readonly attributes: Readonly<HtmlAttributes>;
+  readonly children: readonly (HtmlElement | HtmlText | HtmlRaw | string)[];
+}
+/**
+ * A text node. The `text` value is stored raw (unescaped) — the serialiser
+ * escapes it during output. Callers should NOT pre-escape.
+ */
+interface HtmlText {
+  readonly text: string;
+}
+/**
+ * A raw HTML node. The `html` value is emitted verbatim — NOT escaped.
+ * Use for embedding already-serialised HTML from resolvers or external sources.
+ * Never use for user-supplied data.
+ */
+interface HtmlRaw {
+  readonly html: string;
+}
+/**
+ * Any node that can appear in the HTML tree.
+ * - `string` is treated as a text node (will be escaped by the serialiser)
+ * - `HtmlElement` and `HtmlText` are structured nodes
+ * - `undefined` and `null` are silently dropped (useful for conditional children)
+ * - `false` is silently dropped (useful for `{condition && h(...)}`)
+ */
+type HtmlNode = HtmlElement | HtmlText | HtmlRaw | string | undefined | null | false;
+/**
+ * Attribute value types. `true` renders as a boolean attribute (`disabled`),
+ * `false` and `undefined` are omitted. Numbers are converted to strings.
+ */
+type AttrValue = string | number | boolean | undefined;
+/**
+ * HTML attributes. Standard attributes are typed per-element via overloads;
+ * arbitrary `data-*` and `aria-*` keys are allowed via index signature.
+ */
+type HtmlAttributes = Record<string, AttrValue>;
+declare const VOID_ELEMENTS: Set<string>;
+/**
+ * Build an HTML element node.
+ *
+ * - Tag name is type-checked (must be a known HTML tag)
+ * - Attributes are collected as a record — callers get IntelliSense for
+ *   common attributes but can also pass `aria-*`, `data-*` etc.
+ * - Children are flattened; `undefined`, `null`, and `false` are dropped.
+ * - For void elements (input, img, etc.), children are ignored.
+ *
+ * @param tag - HTML element tag name
+ * @param attrs - Optional attributes (class, id, aria-*, etc.)
+ * @param children - Child nodes (strings are escaped by the serialiser)
+ */
+declare function h(tag: string, attrs?: HtmlAttributes, ...children: HtmlNode[]): HtmlElement;
+/**
+ * Create a text node. The value is NOT escaped — the serialiser handles it.
+ * Use this for dynamic text that must appear in the output.
+ */
+declare function text(value: string): HtmlText;
+/**
+ * Create a raw HTML node. The value is emitted verbatim — NOT escaped.
+ * Use for embedding already-serialised HTML (e.g. from child renderers).
+ * Never use for user-supplied data.
+ */
+declare function raw(html: string): HtmlRaw;
+/**
+ * Serialise an HTML node to a string.
+ *
+ * - Text content is automatically escaped
+ * - Void elements are self-closing
+ * - Boolean attributes render as just the name (`disabled`, `checked`)
+ * - `false`/`undefined` attribute values are omitted
+ *
+ * @param node - An HtmlElement, HtmlText, or string to serialise
+ * @returns HTML string
+ */
+declare function serialize(node: HtmlNode): string;
+declare function serializeElement(el: HtmlElement): string;
+declare function serializeAttributes(attrs: HtmlAttributes): string;
+/**
+ * Serialise an HTML node to chunks, yielded at natural element boundaries.
+ *
+ * - Each top-level child element becomes its own chunk
+ * - Leaf text within an element stays with its parent
+ * - Void elements are single chunks
+ *
+ * This is used by the streaming renderer to produce incremental output.
+ *
+ * @param node - An HTML node to serialise
+ * @returns Iterable of HTML string chunks
+ */
+declare function serializeChunks(node: HtmlNode): Iterable<string, void, undefined>;
+/**
+ * Escape a string for safe inclusion in HTML text content or attribute values.
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Create a fragment: children rendered sequentially with no wrapping element.
+ * Useful when a renderer needs to return multiple top-level nodes.
+ */
+declare function fragment(...children: HtmlNode[]): HtmlElement;
+/**
+ * Serialise a node, treating fragments (empty tag) as just their children.
+ */
+declare function serializeFragment(node: HtmlNode): string;
+//#endregion
+export { AttrValue, HtmlAttributes, HtmlElement, HtmlNode, HtmlRaw, HtmlText, VOID_ELEMENTS, escapeHtml, fragment, h, raw, serialize, serializeAttributes, serializeChunks, serializeElement, serializeFragment, text };