@neumorphism-ui/elements 0.0.0-stage → 1.0.0-next.0

package/dist/core/dom.js

@@ -0,0 +1,51 @@
+/** Writes text only when it changed, so hydrated nodes are not replaced needlessly. */
+export function setText(el, text) {
+    if (el && el.textContent !== text)
+        el.textContent = text;
+}
+/** Sets the attribute when value is non-empty and removes it otherwise. */
+export function setOptionalAttribute(el, name, value) {
+    if (!el)
+        return;
+    if (value === '')
+        el.removeAttribute(name);
+    else if (el.getAttribute(name) !== value)
+        el.setAttribute(name, value);
+}
+/**
+ * True while `el` is the focused element of its tree. It stays true when only the window or frame
+ * loses focus, which also fires blur on the element; it is false once focus moved elsewhere.
+ */
+export function isActiveInRoot(el) {
+    return el.getRootNode().activeElement === el;
+}
+/** Dispatches a bubbling, composed event from a host (spec §6.4). */
+export function dispatch(target, type) {
+    target.dispatchEvent(new Event(type, { bubbles: true, composed: true }));
+}
+/**
+ * Runs `run` once `event` has finished dispatching — after every listener, including those on
+ * window — or on the next task if propagation was stopped before window. Runs exactly once.
+ *
+ * A one-shot bubble listener on window catches this same event object, so `run` lands within the
+ * dispatch, after the listeners on the way up, and sees their preventDefault(). Not a microtask:
+ * for a trusted event the microtask queue drains between listeners. An event that never reaches
+ * window (stopPropagation, bubbles: false, a disconnected target) is finished by the timeout.
+ */
+export function afterDispatch(event, run) {
+    let done = false;
+    const finish = () => {
+        if (done)
+            return;
+        done = true;
+        window.removeEventListener(event.type, onWindow);
+        clearTimeout(fallback);
+        run();
+    };
+    const onWindow = (other) => {
+        if (other === event)
+            finish();
+    };
+    window.addEventListener(event.type, onWindow);
+    const fallback = setTimeout(finish, 0);
+}

package/dist/core/form-control.d.ts

@@ -0,0 +1,35 @@
+import { NeuElement } from './neu-element.js';
+/** Records that the user is trying to submit `form` in this task, so validation errors may show. */
+export declare function markSubmitAttempt(form: HTMLFormElement): void;
+/**
+ * A static brand on button-like classes whose type="submit" submits their form (NeuButton), so
+ * subclasses count under any tag. Symbol.for: two copies of the library on one page agree.
+ */
+export declare const SUBMITS: unique symbol;
+/** A button that submits its form when activated: native submit buttons and branded ones with type=submit. */
+export declare function isSubmitButton(el: Element): boolean;
+/** Base for every control that has a value (spec §6.6). */
+export declare abstract class FormControlElement extends NeuElement {
+    static formAssociated: boolean;
+    private interacted;
+    constructor();
+    get form(): HTMLFormElement | null;
+    get validity(): ValidityState;
+    get validationMessage(): string;
+    get willValidate(): boolean;
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null): void;
+    protected abstract formValue(): string | null;
+    /** What the browser saves to restore the control after navigation; null saves nothing. */
+    protected formState(): string | null;
+    protected abstract validate(): void;
+    protected abstract resetToDefault(): void;
+    protected abstract restoreState(state: string): void;
+    /** Pushes the current value and validity to the form. Call after every value change. */
+    protected commit(): void;
+    /** The user committed an edit, so validation errors may now be shown. */
+    protected markInteracted(): void;
+    private syncUserInvalid;
+}

package/dist/core/form-control.js

@@ -0,0 +1,128 @@
+import { NeuElement } from './neu-element.js';
+/** Forms the user is trying to submit during the current task (click on a submitter, or Enter). */
+const submitAttempts = new WeakSet();
+let watching = false;
+/** Records that the user is trying to submit `form` in this task, so validation errors may show. */
+export function markSubmitAttempt(form) {
+    submitAttempts.add(form);
+    // Validation runs in the same task as the click/keydown/submit; forget the attempt afterwards.
+    setTimeout(() => submitAttempts.delete(form), 0);
+}
+/**
+ * A static brand on button-like classes whose type="submit" submits their form (NeuButton), so
+ * subclasses count under any tag. Symbol.for: two copies of the library on one page agree.
+ */
+export const SUBMITS = Symbol.for('neu-ui.submits');
+/** A button that submits its form when activated: native submit buttons and branded ones with type=submit. */
+export function isSubmitButton(el) {
+    if (el instanceof HTMLButtonElement)
+        return el.type === 'submit';
+    if (el instanceof HTMLInputElement)
+        return el.type === 'submit' || el.type === 'image';
+    return (el.constructor[SUBMITS] === true &&
+        el.type === 'submit');
+}
+/** The form owner of a control (its `form` property), which also covers form="id" association. */
+function formOf(node) {
+    const form = node.form;
+    return form instanceof HTMLFormElement ? form : null;
+}
+/**
+ * One capture listener pair on document sees every submit attempt: submitters outside their form
+ * (form="id") and forms inside open shadow roots included. The composed path is walked rather than
+ * the retargeted event.target, which would hide a control inside a shadow root from the document.
+ */
+function watchSubmitAttempts() {
+    if (watching || typeof document === 'undefined')
+        return;
+    watching = true;
+    document.addEventListener('click', (event) => {
+        for (const node of event.composedPath()) {
+            if (!(node instanceof Element) || !isSubmitButton(node))
+                continue;
+            const form = formOf(node);
+            if (form)
+                markSubmitAttempt(form);
+            return;
+        }
+    }, { capture: true });
+    document.addEventListener('keydown', (event) => {
+        if (event.key !== 'Enter')
+            return;
+        for (const node of event.composedPath()) {
+            // Not document or window: their named properties make `.form` a <form id|name="form">.
+            if (!(node instanceof Element))
+                continue;
+            const form = formOf(node);
+            if (form) {
+                markSubmitAttempt(form);
+                return;
+            }
+        }
+    }, { capture: true });
+}
+/** Base for every control that has a value (spec §6.6). */
+export class FormControlElement extends NeuElement {
+    static formAssociated = true;
+    interacted = false;
+    constructor() {
+        super();
+        watchSubmitAttempts();
+        // A failed submit attempt fires `invalid`; so does form.checkValidity(), which must stay silent.
+        this.addEventListener('invalid', () => {
+            const form = this.internals.form;
+            if (form && submitAttempts.has(form))
+                this.markInteracted();
+        });
+    }
+    get form() {
+        return this.internals.form;
+    }
+    get validity() {
+        return this.internals.validity;
+    }
+    get validationMessage() {
+        return this.internals.validationMessage;
+    }
+    get willValidate() {
+        return this.internals.willValidate;
+    }
+    checkValidity() {
+        return this.internals.checkValidity();
+    }
+    reportValidity() {
+        const valid = this.internals.reportValidity();
+        if (!valid)
+            this.markInteracted();
+        return valid;
+    }
+    formResetCallback() {
+        this.interacted = false;
+        this.resetToDefault();
+        this.commit();
+    }
+    formStateRestoreCallback(state) {
+        if (typeof state !== 'string')
+            return;
+        this.restoreState(state);
+        this.commit();
+    }
+    /** What the browser saves to restore the control after navigation; null saves nothing. */
+    formState() {
+        return this.formValue() ?? '';
+    }
+    /** Pushes the current value and validity to the form. Call after every value change. */
+    commit() {
+        this.internals.setFormValue(this.formValue(), this.formState());
+        this.validate();
+        this.syncUserInvalid();
+    }
+    /** The user committed an edit, so validation errors may now be shown. */
+    markInteracted() {
+        this.interacted = true;
+        this.syncUserInvalid();
+    }
+    syncUserInvalid() {
+        this.toggleState('user-invalid', this.interacted && !this.internals.validity.valid);
+    }
+}

package/dist/core/html.d.ts

@@ -0,0 +1,13 @@
+declare const RAW: unique symbol;
+/** A string that is already safe HTML. Only `html` and `unsafeHTML` create one. */
+export interface RawHtml {
+    readonly [RAW]: true;
+    readonly value: string;
+}
+export declare function escapeHtml(value: string): string;
+/** Marks markup as trusted. Only for library-owned markup such as built-in SVG icons. */
+export declare function unsafeHTML(value: string): RawHtml;
+export declare function isRawHtml(value: unknown): value is RawHtml;
+/** Tagged template that escapes every interpolated value unless it is RawHtml. */
+export declare function html(strings: TemplateStringsArray, ...values: unknown[]): RawHtml;
+export {};

package/dist/core/html.js

@@ -0,0 +1,35 @@
+const RAW = Symbol('neu.raw');
+const ESCAPES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+export function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
+}
+/** Marks markup as trusted. Only for library-owned markup such as built-in SVG icons. */
+export function unsafeHTML(value) {
+    return { [RAW]: true, value };
+}
+export function isRawHtml(value) {
+    return typeof value === 'object' && value !== null && RAW in value;
+}
+function render(value) {
+    if (value === null || value === undefined || value === false)
+        return '';
+    if (Array.isArray(value))
+        return value.map(render).join('');
+    if (isRawHtml(value))
+        return value.value;
+    return escapeHtml(String(value));
+}
+/** Tagged template that escapes every interpolated value unless it is RawHtml. */
+export function html(strings, ...values) {
+    let out = strings[0] ?? '';
+    values.forEach((value, index) => {
+        out += render(value) + (strings[index + 1] ?? '');
+    });
+    return unsafeHTML(out);
+}

package/dist/core/neu-element.d.ts

@@ -0,0 +1,87 @@
+import type { ComponentDef } from './define.js';
+import { type PropValue } from './props.js';
+/**
+ * HTMLElement does not exist in Node (SSR, React server rendering). Falling back to an empty
+ * class lets every module be imported there; nothing is ever constructed on the server.
+ */
+declare const ServerSafeHTMLElement: typeof HTMLElement;
+export declare abstract class NeuElement extends ServerSafeHTMLElement {
+    static def: ComponentDef;
+    /** Own properties to re-apply after upgrade besides def.props (spec §6.2 step 3). */
+    static extraProperties: readonly string[];
+    static get observedAttributes(): string[];
+    /** Installs accessors for def.props and registers the tag. Safe to call in Node. */
+    static define(): void;
+    /**
+     * True when this class defines `key`, or a class between it and NeuElement wrote its own
+     * accessor for it. Accessors that define() installed on a parent do not count: they coerce with
+     * the parent's declarations, and this class may declare the prop differently.
+     */
+    private static definesAccessor;
+    protected readonly internals: ElementInternals;
+    protected readonly props: Record<string, PropValue>;
+    private root;
+    private readonly refs;
+    private reflecting;
+    private hasConnected;
+    private formDisabled;
+    /** The author's tabindex (null when none is set), kept current by syncFocusable. */
+    private authorTabIndex;
+    /** The tabindex syncFocusable last left on the host (null: removed; undefined: never ran). */
+    private writtenTabIndex;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    /** Called by the browser for form-associated subclasses inside a disabled fieldset. */
+    formDisabledCallback(disabled: boolean): void;
+    protected get def(): ComponentDef;
+    protected get isDisabled(): boolean;
+    /** Element marked data-ref="name" in the shadow root, or null before the root exists. */
+    protected ref<T extends Element = HTMLElement>(name: string): T | null;
+    protected setProp(key: string, value: PropValue, fromAttribute?: boolean): void;
+    protected toggleState(name: string, on: boolean): void;
+    /**
+     * Focusable: the author's tabindex, or 0. Not focusable: no tabindex at all.
+     * A tabindex other than the one this method last left there was set (or removed) by the author
+     * since, as a roving-tabindex widget or a framework re-render does; it becomes the author's value.
+     */
+    protected syncFocusable(focusable: boolean): void;
+    /** For controls whose host is the control: aria-disabled and focusability follow isDisabled. */
+    protected syncDisabledState(): void;
+    /**
+     * Runs on every prop change, connected or not. ElementInternals work (form value, validity) is
+     * fine here; leave shadow-DOM and attribute writes to update().
+     */
+    protected willUpdate(_changed: ReadonlySet<string>): void;
+    /** Patches host state and shadow DOM for the changed props. Must be idempotent. */
+    protected update(_changed: ReadonlySet<string>): void;
+    /** Runs once, after the shadow root exists (rendered or adopted from SSR). */
+    protected rendered(): void;
+    protected connected(): void;
+    protected disconnected(): void;
+    private allKeys;
+    /** willUpdate, then update once connected, with the same one-key set. */
+    private propChanged;
+    private reflect;
+    private upgradeProperties;
+    /** `loaded`: DOMContentLoaded fired, so the parser is done and nothing is left to wait for. */
+    private ensureRoot;
+    /**
+     * While the document loads, the parser may still be writing this element's declarative shadow
+     * root (spec §8.1). Before the root exists, that is only possible while nothing has been parsed
+     * inside or after the element; one created by script in the middle of the page renders at once.
+     * Once it exists, its contents may still be streaming in: it is unfinished while it has fewer
+     * than `refs` data-ref nodes, and adopting it then would run rendered() without them.
+     */
+    private parsing;
+    /**
+     * Without a root, watches the document until a child or a following node shows the parser has
+     * moved past the element; with an unfinished root, watches that root until it is complete. Then
+     * ensureRoot() decides again. DOMContentLoaded is the fallback, after which a root that is still
+     * unfinished is rendered afresh.
+     */
+    private waitForParser;
+    private adoptRoot;
+}
+export {};

package/dist/core/neu-element.js

@@ -0,0 +1,285 @@
+import { attributeName, coerceProperty, parseAttribute, parseProps, serializeAttribute, } from './props.js';
+/**
+ * HTMLElement does not exist in Node (SSR, React server rendering). Falling back to an empty
+ * class lets every module be imported there; nothing is ever constructed on the server.
+ */
+const ServerSafeHTMLElement = globalThis.HTMLElement ??
+    class {
+    };
+const sheets = new WeakMap();
+/** Getters that define() installed, as opposed to accessors an author wrote. */
+const installedGetters = new WeakSet();
+function sheetFor(def) {
+    let sheet = sheets.get(def);
+    if (!sheet) {
+        sheet = new CSSStyleSheet();
+        sheet.replaceSync(def.styles);
+        sheets.set(def, sheet);
+    }
+    return sheet;
+}
+export class NeuElement extends ServerSafeHTMLElement {
+    /** Own properties to re-apply after upgrade besides def.props (spec §6.2 step 3). */
+    static extraProperties = [];
+    static get observedAttributes() {
+        return Object.entries(this.def.props).map(([key, decl]) => attributeName(key, decl));
+    }
+    /** Installs accessors for def.props and registers the tag. Safe to call in Node. */
+    static define() {
+        const def = this.def;
+        for (const [key, decl] of Object.entries(def.props)) {
+            if (this.definesAccessor(key))
+                continue;
+            const get = function () {
+                return this.props[key];
+            };
+            installedGetters.add(get);
+            Object.defineProperty(this.prototype, key, {
+                configurable: true,
+                enumerable: true,
+                get,
+                set(value) {
+                    this.setProp(key, coerceProperty(decl, value));
+                },
+            });
+        }
+        const registry = globalThis.customElements;
+        if (registry && !registry.get(def.tag)) {
+            registry.define(def.tag, this);
+        }
+    }
+    /**
+     * True when this class defines `key`, or a class between it and NeuElement wrote its own
+     * accessor for it. Accessors that define() installed on a parent do not count: they coerce with
+     * the parent's declarations, and this class may declare the prop differently.
+     */
+    static definesAccessor(key) {
+        if (Object.prototype.hasOwnProperty.call(this.prototype, key))
+            return true;
+        let proto = Object.getPrototypeOf(this.prototype);
+        for (; proto !== null && proto !== NeuElement.prototype; proto = Object.getPrototypeOf(proto)) {
+            const descriptor = Object.getOwnPropertyDescriptor(proto, key);
+            if (descriptor)
+                return !(descriptor.get && installedGetters.has(descriptor.get));
+        }
+        return false;
+    }
+    internals;
+    props;
+    root = null;
+    refs = new Map();
+    reflecting = false;
+    hasConnected = false;
+    formDisabled = false;
+    /** The author's tabindex (null when none is set), kept current by syncFocusable. */
+    authorTabIndex = null;
+    /** The tabindex syncFocusable last left on the host (null: removed; undefined: never ran). */
+    writtenTabIndex;
+    constructor() {
+        super();
+        this.internals = this.attachInternals();
+        this.props = parseProps(this.def.props, (name) => this.getAttribute(name));
+        // Disabled controls emit no events at all, including the native click (spec §6.4).
+        this.addEventListener('click', (event) => {
+            if (!this.isDisabled)
+                return;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+        }, { capture: true });
+    }
+    connectedCallback() {
+        if (!this.hasConnected) {
+            this.hasConnected = true;
+            this.upgradeProperties();
+            this.update(this.allKeys());
+            this.ensureRoot();
+        }
+        this.connected();
+    }
+    disconnectedCallback() {
+        this.disconnected();
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (this.reflecting)
+            return;
+        for (const [key, decl] of Object.entries(this.def.props)) {
+            if (attributeName(key, decl) === name) {
+                this.setProp(key, parseAttribute(decl, value), true);
+                return;
+            }
+        }
+    }
+    /** Called by the browser for form-associated subclasses inside a disabled fieldset. */
+    formDisabledCallback(disabled) {
+        this.formDisabled = disabled;
+        this.propChanged('disabled');
+    }
+    get def() {
+        return this.constructor.def;
+    }
+    get isDisabled() {
+        return this.props.disabled === true || this.formDisabled;
+    }
+    /** Element marked data-ref="name" in the shadow root, or null before the root exists. */
+    ref(name) {
+        if (!this.root)
+            return null;
+        let el = this.refs.get(name);
+        if (!el) {
+            const found = this.root.querySelector(`[data-ref="${name}"]`);
+            if (!found)
+                return null;
+            this.refs.set(name, found);
+            el = found;
+        }
+        return el;
+    }
+    setProp(key, value, fromAttribute = false) {
+        const decl = this.def.props[key];
+        if (!decl || Object.is(this.props[key], value))
+            return;
+        this.props[key] = value;
+        if (!fromAttribute && decl.reflect)
+            this.reflect(key, decl, value);
+        this.propChanged(key);
+    }
+    toggleState(name, on) {
+        if (on)
+            this.internals.states.add(name);
+        else
+            this.internals.states.delete(name);
+    }
+    /**
+     * Focusable: the author's tabindex, or 0. Not focusable: no tabindex at all.
+     * A tabindex other than the one this method last left there was set (or removed) by the author
+     * since, as a roving-tabindex widget or a framework re-render does; it becomes the author's value.
+     */
+    syncFocusable(focusable) {
+        const current = this.getAttribute('tabindex');
+        if (current !== this.writtenTabIndex)
+            this.authorTabIndex = current;
+        const wanted = focusable ? (this.authorTabIndex ?? '0') : null;
+        if (wanted === null)
+            this.removeAttribute('tabindex');
+        else if (current !== wanted)
+            this.setAttribute('tabindex', wanted);
+        this.writtenTabIndex = wanted;
+    }
+    /** For controls whose host is the control: aria-disabled and focusability follow isDisabled. */
+    syncDisabledState() {
+        this.internals.ariaDisabled = this.isDisabled ? 'true' : null;
+        this.syncFocusable(!this.isDisabled);
+    }
+    /**
+     * Runs on every prop change, connected or not. ElementInternals work (form value, validity) is
+     * fine here; leave shadow-DOM and attribute writes to update().
+     */
+    willUpdate(_changed) { }
+    /** Patches host state and shadow DOM for the changed props. Must be idempotent. */
+    update(_changed) { }
+    /** Runs once, after the shadow root exists (rendered or adopted from SSR). */
+    rendered() { }
+    connected() { }
+    disconnected() { }
+    allKeys() {
+        return new Set(Object.keys(this.def.props));
+    }
+    /** willUpdate, then update once connected, with the same one-key set. */
+    propChanged(key) {
+        const changed = new Set([key]);
+        this.willUpdate(changed);
+        if (this.hasConnected)
+            this.update(changed);
+    }
+    reflect(key, decl, value) {
+        const attribute = serializeAttribute(decl, value);
+        const name = attributeName(key, decl);
+        this.reflecting = true;
+        try {
+            if (attribute === null)
+                this.removeAttribute(name);
+            else
+                this.setAttribute(name, attribute);
+        }
+        finally {
+            this.reflecting = false;
+        }
+    }
+    upgradeProperties() {
+        const ctor = this.constructor;
+        const self = this;
+        for (const key of [...Object.keys(ctor.def.props), ...ctor.extraProperties]) {
+            if (!Object.prototype.hasOwnProperty.call(this, key))
+                continue;
+            const value = self[key];
+            delete self[key];
+            self[key] = value;
+        }
+    }
+    /** `loaded`: DOMContentLoaded fired, so the parser is done and nothing is left to wait for. */
+    ensureRoot(loaded) {
+        if (this.root)
+            return;
+        let root = this.internals.shadowRoot;
+        // A root is unfinished while it has fewer data-ref nodes than the template renders.
+        const refs = root ? this.def.template(this.props).value.split('data-ref="').length - 1 : 0;
+        if (!loaded && document.readyState === 'loading' && this.parsing(root, refs)) {
+            this.waitForParser(root, refs);
+            return;
+        }
+        // No root yet, or one still unfinished after the parser is done (a truncated response):
+        // render the template, so rendered() and every update() find their nodes.
+        if (!root || this.parsing(root, refs)) {
+            root ??= this.attachShadow({
+                mode: 'open',
+                delegatesFocus: this.def.delegatesFocus ?? false,
+            });
+            root.innerHTML = this.def.template(this.props).value;
+        }
+        this.adoptRoot(root);
+    }
+    /**
+     * While the document loads, the parser may still be writing this element's declarative shadow
+     * root (spec §8.1). Before the root exists, that is only possible while nothing has been parsed
+     * inside or after the element; one created by script in the middle of the page renders at once.
+     * Once it exists, its contents may still be streaming in: it is unfinished while it has fewer
+     * than `refs` data-ref nodes, and adopting it then would run rendered() without them.
+     */
+    parsing(root, refs) {
+        if (root)
+            return root.querySelectorAll('[data-ref]').length < refs;
+        if (this.firstChild !== null || this.nextSibling !== null)
+            return false;
+        for (let node = this.parentNode; node !== null; node = node.parentNode) {
+            if (node.nextSibling !== null)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Without a root, watches the document until a child or a following node shows the parser has
+     * moved past the element; with an unfinished root, watches that root until it is complete. Then
+     * ensureRoot() decides again. DOMContentLoaded is the fallback, after which a root that is still
+     * unfinished is rendered afresh.
+     */
+    waitForParser(root, refs) {
+        const resume = (loaded) => {
+            observer.disconnect();
+            document.removeEventListener('DOMContentLoaded', resume);
+            this.ensureRoot(loaded);
+        };
+        const observer = new MutationObserver(() => {
+            if (!this.parsing(root, refs))
+                resume();
+        });
+        observer.observe(root ?? document, { childList: true, subtree: true });
+        document.addEventListener('DOMContentLoaded', resume);
+    }
+    adoptRoot(root) {
+        this.root = root;
+        root.adoptedStyleSheets = [sheetFor(this.def)];
+        root.querySelector('style[data-neu-ssr]')?.remove();
+        this.rendered();
+        this.update(this.allKeys());
+    }
+}

package/dist/core/props.d.ts

@@ -0,0 +1,44 @@
+export type PropDecl = {
+    readonly type: 'boolean';
+    readonly reflect?: boolean;
+    readonly attribute?: string;
+} | {
+    readonly type: 'number';
+    readonly default: number;
+    readonly reflect?: boolean;
+    readonly attribute?: string;
+} | {
+    readonly type: 'string';
+    readonly default: string;
+    readonly values: readonly string[];
+    readonly reflect?: boolean;
+    readonly attribute?: string;
+} | {
+    readonly type: 'string';
+    readonly default?: string;
+    readonly values?: never;
+    readonly reflect?: boolean;
+    readonly attribute?: string;
+};
+export type PropsSchema = Readonly<Record<string, PropDecl>>;
+export type PropValue = string | number | boolean;
+type InferProp<D> = D extends {
+    type: 'boolean';
+} ? boolean : D extends {
+    type: 'number';
+} ? number : D extends {
+    values: readonly (infer V extends string)[];
+} ? V : string;
+export type InferProps<S extends PropsSchema> = {
+    -readonly [K in keyof S]: InferProp<S[K]>;
+};
+/** `helpText` → `help-text`, unless the declaration names the attribute explicitly. */
+export declare function attributeName(prop: string, decl: PropDecl): string;
+/** Attribute text (null when absent) → prop value. Invalid input silently becomes the default. */
+export declare function parseAttribute(decl: PropDecl, raw: string | null): PropValue;
+/** Value assigned through a JS property → prop value, with the same fallback rules. */
+export declare function coerceProperty(decl: PropDecl, value: unknown): PropValue;
+/** Prop value → attribute text for reflection and SSR; null means "remove the attribute". */
+export declare function serializeAttribute(decl: PropDecl, value: PropValue): string | null;
+export declare function parseProps<S extends PropsSchema>(schema: S, read: (attribute: string) => string | null): InferProps<S>;
+export {};