//#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:
 *
 * ```ts
 * 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>;
/** HTML5 void-element tag names — self-closing, must not carry children. */
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;
/**
 * Serialise a single {@link HtmlElement} to a string, taking care of
 * void-element self-closing, attribute serialisation, and recursive
 * child rendering. Use {@link serialize} for arbitrary nodes.
 */
declare function serializeElement(el: HtmlElement): string;
/**
 * Serialise an attribute map to the `key="value"` form used inside an
 * opening tag. `false` / `undefined` values are omitted; `true` renders
 * as a boolean attribute (just the name).
 */
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 };