@neumorphism-ui/elements 1.0.0-next.2 → 1.0.0-next.3

package/dist/components/textarea/textarea.d.ts

@@ -6,7 +6,6 @@ export declare class NeuTextarea extends TextControlElement {
         };
         readonly name: {
             readonly type: "string";
-            readonly reflect: true;
         };
         readonly label: {
             readonly type: "string";
@@ -22,15 +21,12 @@ export declare class NeuTextarea extends TextControlElement {
         };
         readonly required: {
             readonly type: "boolean";
-            readonly reflect: true;
         };
         readonly disabled: {
             readonly type: "boolean";
-            readonly reflect: true;
         };
         readonly readOnly: {
             readonly type: "boolean";
-            readonly reflect: true;
             readonly attribute: "readonly";
         };
         readonly minLength: {
@@ -58,13 +54,11 @@ export declare class NeuTextarea extends TextControlElement {
             readonly type: "string";
             readonly default: "vertical";
             readonly values: readonly ["none", "vertical", "auto"];
-            readonly reflect: true;
         };
         readonly size: {
             readonly type: "string";
             readonly default: "md";
             readonly values: readonly ["sm", "md", "lg"];
-            readonly reflect: true;
         };
     }>;
     static extraProperties: string[];

package/dist/components/textarea/textarea.def.d.ts

@@ -5,7 +5,6 @@ declare const props: {
     };
     readonly name: {
         readonly type: "string";
-        readonly reflect: true;
     };
     readonly label: {
         readonly type: "string";
@@ -21,15 +20,12 @@ declare const props: {
     };
     readonly required: {
         readonly type: "boolean";
-        readonly reflect: true;
     };
     readonly disabled: {
         readonly type: "boolean";
-        readonly reflect: true;
     };
     readonly readOnly: {
         readonly type: "boolean";
-        readonly reflect: true;
         readonly attribute: "readonly";
     };
     readonly minLength: {
@@ -57,13 +53,11 @@ declare const props: {
         readonly type: "string";
         readonly default: "vertical";
         readonly values: readonly ["none", "vertical", "auto"];
-        readonly reflect: true;
     };
     readonly size: {
         readonly type: "string";
         readonly default: "md";
         readonly values: readonly ["sm", "md", "lg"];
-        readonly reflect: true;
     };
 };
 export type TextareaProps = InferProps<typeof props>;
@@ -75,7 +69,6 @@ export declare const textareaDef: import("../../core/define.js").ComponentDef<{
     };
     readonly name: {
         readonly type: "string";
-        readonly reflect: true;
     };
     readonly label: {
         readonly type: "string";
@@ -91,15 +84,12 @@ export declare const textareaDef: import("../../core/define.js").ComponentDef<{
     };
     readonly required: {
         readonly type: "boolean";
-        readonly reflect: true;
     };
     readonly disabled: {
         readonly type: "boolean";
-        readonly reflect: true;
     };
     readonly readOnly: {
         readonly type: "boolean";
-        readonly reflect: true;
         readonly attribute: "readonly";
     };
     readonly minLength: {
@@ -127,13 +117,11 @@ export declare const textareaDef: import("../../core/define.js").ComponentDef<{
         readonly type: "string";
         readonly default: "vertical";
         readonly values: readonly ["none", "vertical", "auto"];
-        readonly reflect: true;
     };
     readonly size: {
         readonly type: "string";
         readonly default: "md";
         readonly values: readonly ["sm", "md", "lg"];
-        readonly reflect: true;
     };
 }>;
 export {};

package/dist/components/textarea/textarea.def.js

@@ -1,17 +1,16 @@
 import { defineComponent } from '../../core/define.js';
 import { html } from '../../core/html.js';
-import { themeCssProperties } from '../../core/styles.js';
 import { textareaStyles } from './textarea.styles.js';
 const props = {
     value: { type: 'string' },
-    name: { type: 'string', reflect: true },
+    name: { type: 'string' },
     label: { type: 'string' },
     placeholder: { type: 'string' },
     helpText: { type: 'string' },
     errorText: { type: 'string' },
-    required: { type: 'boolean', reflect: true },
-    disabled: { type: 'boolean', reflect: true },
-    readOnly: { type: 'boolean', reflect: true, attribute: 'readonly' },
+    required: { type: 'boolean' },
+    disabled: { type: 'boolean' },
+    readOnly: { type: 'boolean', attribute: 'readonly' },
     minLength: { type: 'number', default: -1, attribute: 'minlength' },
     maxLength: { type: 'number', default: -1, attribute: 'maxlength' },
     autocomplete: { type: 'string' },
@@ -21,9 +20,8 @@ const props = {
         type: 'string',
         default: 'vertical',
         values: ['none', 'vertical', 'auto'],
-        reflect: true,
     },
-    size: { type: 'string', default: 'md', values: ['sm', 'md', 'lg'], reflect: true },
+    size: { type: 'string', default: 'md', values: ['sm', 'md', 'lg'] },
 };
 /** A row count the native textarea would also accept; anything else means the default of 3. */
 export function rowsOf(rows) {
@@ -43,23 +41,4 @@ export const textareaDef = defineComponent({
     // with a newline keeps it.
     template: (p) => html `<div part="base" class="base"><label part="label" class="label" for="input"><slot name="label"><span class="label-text" data-ref="label-text">${p.label}</span></slot></label><div part="control" class="control"><textarea part="textarea" class="input" id="input" data-ref="input" rows="${rowsOf(p.rows)}" aria-describedby="help"${areaAttributes(p)}>
 ${p.value}</textarea></div><div part="help-text" class="help" id="help"><slot name="help-text"><span class="help-text" data-ref="help-text">${p.helpText}</span></slot><span class="error-text" data-ref="error-text">${p.errorText}</span></div></div>`,
-    docs: {
-        summary: 'A multi-line text input with an inset field. The value attribute is the default value; resize="auto" grows the field with its content.',
-        events: [
-            { name: 'input', description: 'Fired on every edit (the native input event, composed).' },
-            { name: 'change', description: 'Fired when an edit is committed, usually on blur.' },
-        ],
-        slots: [
-            { name: 'label', description: 'Rich label; replaces the label attribute.' },
-            { name: 'help-text', description: 'Rich help text; replaces the help-text attribute.' },
-        ],
-        parts: [
-            { name: 'base', description: 'Outer wrapper.' },
-            { name: 'label', description: 'The <label> element.' },
-            { name: 'control', description: 'The inset field around the textarea.' },
-            { name: 'textarea', description: 'The native <textarea>.' },
-            { name: 'help-text', description: 'Help or error text area.' },
-        ],
-        cssProperties: themeCssProperties,
-    },
 });

package/dist/components/textarea/textarea.docs.d.ts

@@ -0,0 +1,2 @@
+import type { ComponentDocs } from '../../core/define.js';
+export declare const textareaDocs: ComponentDocs;

package/dist/components/textarea/textarea.docs.js

@@ -0,0 +1,40 @@
+import { themeCssProperties } from '../theme-docs.js';
+export const textareaDocs = {
+    summary: 'A multi-line text input with an inset field. The value attribute is the default value; resize="auto" grows the field with its content.',
+    descriptions: {
+        value: 'The current text as typed or set by script.',
+        name: 'The name under which the text is submitted with a form.',
+        label: 'Visible label text; the label slot replaces it.',
+        placeholder: 'Hint shown while the field is empty.',
+        helpText: 'Guidance shown below the field; the help-text slot replaces it.',
+        errorText: "Shown in place of the browser's validation message once the field is invalid after user interaction; does not itself make the field invalid.",
+        required: 'Makes the form invalid while the field is empty.',
+        disabled: 'Prevents interaction and leaves the field out of form submission.',
+        readOnly: 'Keeps the text visible and submitted but not editable.',
+        minLength: 'The fewest characters the text must have; checked after user edits, like native, not on script-set values.',
+        maxLength: 'The most characters the text may have; checked after user edits, like native, not a hard limit on script-set values.',
+        autocomplete: "Hint for the browser's autofill, as for the native attribute.",
+        enterKeyHint: "Hint for the label of the virtual keyboard's Enter key.",
+        rows: 'The number of visible text lines; falls back to 3 for anything but a positive integer.',
+        resize: "How the user or the content can change the field's height.",
+        size: 'The field size.',
+        defaultValue: 'The text the field starts with, which a form reset restores; set by the value attribute.',
+    },
+    events: [
+        { name: 'input', description: 'Fired on every edit (the native input event, composed).' },
+        { name: 'change', description: 'Fired when an edit is committed, usually on blur.' },
+    ],
+    slots: [
+        { name: 'label', description: 'Rich label; replaces the label attribute.' },
+        { name: 'help-text', description: 'Rich help text; replaces the help-text attribute.' },
+    ],
+    parts: [
+        { name: 'base', description: 'Outer wrapper.' },
+        { name: 'label', description: 'The <label> element.' },
+        { name: 'control', description: 'The inset field around the textarea.' },
+        { name: 'textarea', description: 'The native <textarea>.' },
+        { name: 'help-text', description: 'Help or error text area.' },
+    ],
+    cssProperties: themeCssProperties,
+    keyboard: [],
+};

package/dist/components/textarea/textarea.styles.d.ts

@@ -1 +1 @@
-export declare const textareaStyles = "\n:host {\n  --_neu-bg: var(--neu-bg, #e0e5ec);\n  --_neu-accent-c: var(--neu-accent, #6d5dfc);\n  --_neu-d: var(--neu-distance, 6px);\n  --_neu-k: var(--neu-intensity, 1);\n  --_neu-r: var(--neu-radius, 12px);\n  --_neu-danger: var(--neu-danger, #e5484d);\n  --_neu-dur: var(--neu-duration, 150ms);\n  --_neu-sd: var(--neu-shadow-dark, color-mix(in oklab, var(--_neu-bg), black min(100%, calc(var(--_neu-shade, 18%) * var(--_neu-k)))));\n  --_neu-sl: var(--neu-shadow-light, color-mix(in oklab, var(--_neu-bg), white min(100%, calc(var(--_neu-light, 100%) * var(--_neu-k)))));\n  --_neu-fg: var(--neu-fg, color-mix(in oklab, var(--_neu-bg), var(--_neu-ink, black) var(--_neu-fg-mix, 32%)));\n  --_neu-fg-muted: var(--neu-fg-muted, color-mix(in oklab, var(--_neu-bg), var(--_neu-ink, black) var(--_neu-fg-muted-mix, 18%)));\n  --_neu-accent-soft: color-mix(in oklab, var(--_neu-accent-c) 25%, var(--_neu-bg));\n  --_neu-focus: 0 0 0 3px color-mix(in oklab, var(--_neu-accent-c) 45%, transparent);\n  --_neu-raised: var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) var(--_neu-sd), calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n  --_neu-raised-sm: calc(var(--_neu-d) * 0.5) calc(var(--_neu-d) * 0.5) var(--_neu-d) var(--_neu-sd), calc(var(--_neu-d) * -0.5) calc(var(--_neu-d) * -0.5) var(--_neu-d) var(--_neu-sl);\n  --_neu-inset: inset var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) var(--_neu-sd), inset calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n  --_neu-inset-sm: inset calc(var(--_neu-d) * 0.5) calc(var(--_neu-d) * 0.5) var(--_neu-d) var(--_neu-sd), inset calc(var(--_neu-d) * -0.5) calc(var(--_neu-d) * -0.5) var(--_neu-d) var(--_neu-sl);\n  font-family: var(--neu-font);\n  color: var(--_neu-fg);\n  -webkit-tap-highlight-color: transparent;\n}\n:host(:not(:defined)) { visibility: inherit !important; min-block-size: auto !important; }\n:host([hidden]) { display: none !important; }\n:host(:focus) { outline: none; }\n*, *::before, *::after { box-sizing: border-box; }\n\n:host { display: block; }\n:host(:disabled), :host([disabled]) { cursor: not-allowed; }\n.base { display: flex; flex-direction: column; }\n.label-text, ::slotted([slot='label']) {\n  display: block; margin-block-end: 0.375rem;\n  font-size: 0.8125rem; font-weight: 600; line-height: 1rem; color: var(--_neu-fg-muted);\n}\n.label-text:empty { display: none; }\n.control {\n  display: flex; align-items: center; min-block-size: 2.75rem; padding-inline: 0.875rem;\n  border-radius: var(--_neu-r); background: var(--_neu-bg); box-shadow: var(--_neu-inset);\n  transition: box-shadow var(--_neu-dur) ease;\n}\n:host([size='sm']) .control { min-block-size: 2.25rem; padding-inline: 0.75rem; box-shadow: var(--_neu-inset-sm); }\n:host([size='lg']) .control { min-block-size: 3.25rem; padding-inline: 1rem; }\n:host(:focus-within) .control { box-shadow: var(--_neu-inset), var(--_neu-focus); }\n:host(:state(user-invalid)) .control {\n  box-shadow:\n    inset var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) color-mix(in oklab, var(--_neu-danger) 35%, var(--_neu-sd)),\n    inset calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n}\n:host(:disabled) .control, :host([disabled]) .control { box-shadow: var(--_neu-inset-sm); opacity: 0.6; }\n.input {\n  flex: 1; min-inline-size: 0; align-self: stretch; padding: 0; border: none; outline: none;\n  background: transparent; color: inherit; font: inherit; font-size: 0.9375rem;\n}\n.input::placeholder { color: var(--_neu-fg-muted); opacity: 1; }\n.help { font-size: 0.75rem; color: var(--_neu-fg-muted); }\n.help-text, ::slotted([slot='help-text']) { display: block; margin-block-start: 0.375rem; }\n.help-text:empty { display: none; }\n.error-text { display: none; margin-block-start: 0.375rem; color: var(--_neu-danger); }\n:host(:state(user-invalid)) slot[name='help-text'] { display: none; }\n:host(:state(user-invalid)) .error-text:not(:empty) { display: block; }\n\n.control { align-items: stretch; }\n.input {\n  display: block; box-sizing: border-box; padding-block: 0.625rem; line-height: 1.4; resize: vertical;\n}\n:host([resize='none']) .input { resize: none; }\n:host([resize='auto']) .input { resize: none; overflow: hidden; }\n";
+export declare const textareaStyles = "\n:host {\n  --_neu-bg: var(--neu-bg, #e0e5ec);\n  --_neu-accent-c: var(--neu-accent, #6d5dfc);\n  --_neu-d: var(--neu-distance, 6px);\n  --_neu-k: var(--neu-intensity, 1);\n  --_neu-r: var(--neu-radius, 12px);\n  --_neu-danger: var(--neu-danger, #e5484d);\n  --_neu-dur: var(--neu-duration, 150ms);\n  --_neu-sd: var(--neu-shadow-dark, color-mix(in oklab, var(--_neu-bg), black min(100%, calc(var(--_neu-shade, 18%) * var(--_neu-k)))));\n  --_neu-sl: var(--neu-shadow-light, color-mix(in oklab, var(--_neu-bg), white min(100%, calc(var(--_neu-light, 100%) * var(--_neu-k)))));\n  --_neu-fg: var(--neu-fg, color-mix(in oklab, var(--_neu-bg), var(--_neu-ink, black) var(--_neu-fg-mix, 32%)));\n  --_neu-fg-muted: var(--neu-fg-muted, color-mix(in oklab, var(--_neu-bg), var(--_neu-ink, black) var(--_neu-fg-muted-mix, 18%)));\n  --_neu-accent-soft: color-mix(in oklab, var(--_neu-accent-c) 25%, var(--_neu-bg));\n  --_neu-focus: 0 0 0 3px color-mix(in oklab, var(--_neu-accent-c) 45%, transparent);\n  --_neu-raised: var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) var(--_neu-sd), calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n  --_neu-raised-sm: calc(var(--_neu-d) * 0.5) calc(var(--_neu-d) * 0.5) var(--_neu-d) var(--_neu-sd), calc(var(--_neu-d) * -0.5) calc(var(--_neu-d) * -0.5) var(--_neu-d) var(--_neu-sl);\n  --_neu-inset: inset var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) var(--_neu-sd), inset calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n  --_neu-inset-sm: inset calc(var(--_neu-d) * 0.5) calc(var(--_neu-d) * 0.5) var(--_neu-d) var(--_neu-sd), inset calc(var(--_neu-d) * -0.5) calc(var(--_neu-d) * -0.5) var(--_neu-d) var(--_neu-sl);\n  font-family: var(--neu-font);\n  color: var(--_neu-fg);\n  -webkit-tap-highlight-color: transparent;\n}\n:host(:not(:defined)) { visibility: inherit !important; min-block-size: auto !important; }\n:host([hidden]) { display: none !important; }\n:host(:focus) { outline: none; }\n*, *::before, *::after { box-sizing: border-box; }\n\n:host { display: block; }\n:host(:disabled), :host([disabled]) { cursor: not-allowed; }\n.base { display: flex; flex-direction: column; }\n.label { font-size: 0.8125rem; font-weight: 600; line-height: 1rem; color: var(--_neu-fg-muted); }\n.label-text, ::slotted([slot='label']) { display: block; margin-block-end: 0.375rem; }\n.label-text:empty { display: none; }\n.control {\n  display: flex; align-items: center; min-block-size: 2.75rem; padding-inline: 0.875rem;\n  border-radius: var(--_neu-r); background: var(--_neu-bg); box-shadow: var(--_neu-inset);\n  transition: box-shadow var(--_neu-dur) ease;\n}\n:host([size='sm']) .control { min-block-size: 2.25rem; padding-inline: 0.75rem; box-shadow: var(--_neu-inset-sm); }\n:host([size='lg']) .control { min-block-size: 3.25rem; padding-inline: 1rem; }\n:host(:focus-within) .control { box-shadow: var(--_neu-inset), var(--_neu-focus); }\n:host(:state(user-invalid)) .control {\n  box-shadow:\n    inset var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) color-mix(in oklab, var(--_neu-danger) 35%, var(--_neu-sd)),\n    inset calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n}\n:host(:disabled) .control, :host([disabled]) .control { box-shadow: var(--_neu-inset-sm); opacity: 0.6; }\n.input {\n  flex: 1; min-inline-size: 0; align-self: stretch; padding: 0; border: none; outline: none;\n  background: transparent; color: inherit; font: inherit; font-size: 0.9375rem;\n}\n.input::placeholder { color: var(--_neu-fg-muted); opacity: 1; }\n.help { font-size: 0.75rem; color: var(--_neu-fg-muted); }\n.help-text, ::slotted([slot='help-text']) { display: block; margin-block-start: 0.375rem; }\n.help-text:empty { display: none; }\n.error-text { display: none; margin-block-start: 0.375rem; color: var(--_neu-danger); }\n:host(:state(user-invalid)) slot[name='help-text'] { display: none; }\n:host(:state(user-invalid)) .error-text:not(:empty) { display: block; }\n\n.control { align-items: stretch; }\n.input {\n  display: block; box-sizing: border-box; padding-block: 0.625rem; line-height: 1.4; resize: vertical;\n}\n:host([resize='none']) .input { resize: none; }\n:host([resize='auto']) .input { resize: none; overflow: hidden; }\n";

package/dist/components/theme-docs.d.ts

@@ -0,0 +1,3 @@
+import type { DocEntry } from '../core/define.js';
+/** The theme tokens every component documents; docs only, so it stays out of the core bundle. */
+export declare const themeCssProperties: readonly DocEntry[];

package/dist/components/theme-docs.js

@@ -0,0 +1,8 @@
+/** The theme tokens every component documents; docs only, so it stays out of the core bundle. */
+export const themeCssProperties = [
+    { name: '--neu-bg', description: 'Surface colour; shadows and text are derived from it.' },
+    { name: '--neu-accent', description: 'Accent colour.' },
+    { name: '--neu-distance', description: 'Shadow distance for the md size.' },
+    { name: '--neu-intensity', description: 'Shadow strength multiplier.' },
+    { name: '--neu-radius', description: 'Corner radius for the md size.' },
+];

package/dist/core/define.d.ts

@@ -6,10 +6,14 @@ export interface DocEntry {
 }
 export interface ComponentDocs {
     readonly summary: string;
+    /** One line per prop of the def, per key of def.properties, and per defaultValue/defaultChecked. */
+    readonly descriptions: Readonly<Record<string, string>>;
     readonly events: readonly DocEntry[];
     readonly slots: readonly DocEntry[];
     readonly parts: readonly DocEntry[];
     readonly cssProperties: readonly DocEntry[];
+    /** name: the keys as spec §7 writes them; description: what they do. */
+    readonly keyboard: readonly DocEntry[];
 }
 export interface FormDef {
     /** The prop whose attribute holds the default value (spec §6.1). */
@@ -38,7 +42,6 @@ export interface ComponentDef<S extends PropsSchema = PropsSchema> {
     readonly properties?: Readonly<Record<string, string>>;
     /** Tag of the children a server renderer reads into `TemplateContext.options`. */
     readonly optionsFrom?: string;
-    readonly docs: ComponentDocs;
 }
 export declare function defineComponent<const S extends PropsSchema>(def: ComponentDef<S>): ComponentDef<S>;
 /**

package/dist/core/dom.d.ts

@@ -7,6 +7,10 @@ export declare function setOptionalAttribute(el: Element | null, name: string, v
  * loses focus, which also fires blur on the element; it is false once focus moved elsewhere.
  */
 export declare function isActiveInRoot(el: Element): boolean;
+/** True when `node` sits in a child of `host` assigned to a named slot (a rich label, help text). */
+export declare function inSlotted(host: Element, node: Node): boolean;
+/** An IME keystroke: WebKit ends the composition first, so the Enter that commits has keyCode 229. */
+export declare const composing: (event: KeyboardEvent) => boolean;
 /** Dispatches a bubbling, composed event from a host (spec §6.4). */
 export declare function dispatch(target: EventTarget, type: string): void;
 /**

package/dist/core/dom.js

@@ -19,6 +19,13 @@ export function setOptionalAttribute(el, name, value) {
 export function isActiveInRoot(el) {
     return el.getRootNode().activeElement === el;
 }
+/** True when `node` sits in a child of `host` assigned to a named slot (a rich label, help text). */
+export function inSlotted(host, node) {
+    const slotted = (node instanceof Element ? node : node.parentElement)?.closest('[slot]');
+    return !!slotted && slotted !== host && host.contains(slotted);
+}
+/** An IME keystroke: WebKit ends the composition first, so the Enter that commits has keyCode 229. */
+export const composing = (event) => event.isComposing || event.keyCode === 229;
 /** 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 }));

package/dist/core/form-control.js

@@ -1,3 +1,4 @@
+import { composing } from './dom.js';
 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();
@@ -49,7 +50,9 @@ function watchSubmitAttempts() {
     document.addEventListener('keydown', (event) => {
         // Only a native input submits on Enter (neu text/number fields use their inner input); Enter
         // in a textarea, select or switch is no attempt and must not reveal untouched fields.
-        if (event.key !== 'Enter' || !(event.composedPath()[0] instanceof HTMLInputElement))
+        if (event.key !== 'Enter' ||
+            composing(event) ||
+            !(event.composedPath()[0] instanceof HTMLInputElement))
             return;
         for (const node of event.composedPath()) {
             // Not document or window: their named properties make `.form` a <form id|name="form">.

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

@@ -71,8 +71,8 @@ export declare abstract class NeuElement extends ServerSafeHTMLElement {
      * 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.
+     * Once it exists, its contents may still be streaming in: it is unfinished while one of the
+     * `refs` data-ref nodes is missing, and adopting it then would run rendered() without them.
      */
     private parsing;
     /**

package/dist/core/neu-element.js

@@ -1,4 +1,4 @@
-import { attributeName, coerceProperty, parseAttribute, parseProps, serializeAttribute, } from './props.js';
+import { attributeName, coerceProperty, parseAttribute, parseProps, reflects, 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.
@@ -139,7 +139,7 @@ export class NeuElement extends ServerSafeHTMLElement {
         if (!decl || Object.is(this.props[key], value))
             return;
         this.props[key] = value;
-        if (!fromAttribute && decl.reflect)
+        if (!fromAttribute && reflects(key, decl, this.def))
             this.reflect(key, decl, value);
         this.propChanged(key);
     }
@@ -221,8 +221,11 @@ export class NeuElement extends ServerSafeHTMLElement {
         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;
+        // The data-ref names the template renders. A root that lacks one is unfinished, or was rendered
+        // by another version of this component (a page cached before an upgrade).
+        const refs = root
+            ? [...this.def.template(this.props).value.matchAll(/data-ref="([^"]+)"/g)].map((m) => m[1])
+            : [];
         if (!loaded && document.readyState === 'loading' && this.parsing(root, refs)) {
             this.waitForParser(root, refs);
             return;
@@ -242,12 +245,12 @@ export class NeuElement extends ServerSafeHTMLElement {
      * 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.
+     * Once it exists, its contents may still be streaming in: it is unfinished while one of the
+     * `refs` data-ref nodes is missing, and adopting it then would run rendered() without them.
      */
     parsing(root, refs) {
         if (root)
-            return root.querySelectorAll('[data-ref]').length < refs;
+            return refs.some((name) => !root.querySelector(`[data-ref="${name}"]`));
         if (this.firstChild !== null || this.nextSibling !== null)
             return false;
         for (let node = this.parentNode; node !== null; node = node.parentNode) {

package/dist/core/props.d.ts

@@ -34,11 +34,23 @@ export type InferProps<S extends PropsSchema> = {
 };
 /** `helpText` → `help-text`, unless the declaration names the attribute explicitly. */
 export declare function attributeName(prop: string, decl: PropDecl): string;
+/**
+ * Every prop reflects to its attribute, except the live value of a form control (the def's
+ * form.valueProp, whose attribute is only the default) and props that declare `reflect: false`.
+ */
+export declare function reflects(key: string, decl: PropDecl, def: {
+    readonly form?: {
+        readonly valueProp: string;
+    };
+}): boolean;
 /** 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". */
+/**
+ * Prop value → attribute text for reflection and SSR; null means "remove the attribute". The empty
+ * string is removed only when that parses back to it, i.e. when the default is empty too.
+ */
 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 {};

package/dist/core/props.js

@@ -2,6 +2,13 @@
 export function attributeName(prop, decl) {
     return decl.attribute ?? prop.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
 }
+/**
+ * Every prop reflects to its attribute, except the live value of a form control (the def's
+ * form.valueProp, whose attribute is only the default) and props that declare `reflect: false`.
+ */
+export function reflects(key, decl, def) {
+    return decl.reflect ?? key !== def.form?.valueProp;
+}
 /** Attribute text (null when absent) → prop value. Invalid input silently becomes the default. */
 export function parseAttribute(decl, raw) {
     switch (decl.type) {
@@ -32,15 +39,18 @@ export function coerceProperty(decl, value) {
     }
     return parseAttribute(decl, value === null || value === undefined ? null : String(value));
 }
-/** Prop value → attribute text for reflection and SSR; null means "remove the attribute". */
+/**
+ * Prop value → attribute text for reflection and SSR; null means "remove the attribute". The empty
+ * string is removed only when that parses back to it, i.e. when the default is empty too.
+ */
 export function serializeAttribute(decl, value) {
     switch (decl.type) {
         case 'boolean':
             return value ? '' : null;
         case 'number':
-            return String(value);
+            return Number.isFinite(value) ? String(value) : null;
         case 'string':
-            return value === '' ? null : String(value);
+            return value === '' && !decl.default ? null : String(value);
     }
 }
 export function parseProps(schema, read) {

package/dist/core/styles.d.ts

@@ -1,8 +1,6 @@
-import type { DocEntry } from './define.js';
 /**
  * Re-declares the derived theme values on every host (spec §5.3). Fallbacks are the light
  * defaults from @neumorphism-ui/tokens so components still look right without the tokens stylesheet;
  * styles.test.ts keeps the two in sync.
  */
 export declare const hostTheme = "\n:host {\n  --_neu-bg: var(--neu-bg, #e0e5ec);\n  --_neu-accent-c: var(--neu-accent, #6d5dfc);\n  --_neu-d: var(--neu-distance, 6px);\n  --_neu-k: var(--neu-intensity, 1);\n  --_neu-r: var(--neu-radius, 12px);\n  --_neu-danger: var(--neu-danger, #e5484d);\n  --_neu-dur: var(--neu-duration, 150ms);\n  --_neu-sd: var(--neu-shadow-dark, color-mix(in oklab, var(--_neu-bg), black min(100%, calc(var(--_neu-shade, 18%) * var(--_neu-k)))));\n  --_neu-sl: var(--neu-shadow-light, color-mix(in oklab, var(--_neu-bg), white min(100%, calc(var(--_neu-light, 100%) * var(--_neu-k)))));\n  --_neu-fg: var(--neu-fg, color-mix(in oklab, var(--_neu-bg), var(--_neu-ink, black) var(--_neu-fg-mix, 32%)));\n  --_neu-fg-muted: var(--neu-fg-muted, color-mix(in oklab, var(--_neu-bg), var(--_neu-ink, black) var(--_neu-fg-muted-mix, 18%)));\n  --_neu-accent-soft: color-mix(in oklab, var(--_neu-accent-c) 25%, var(--_neu-bg));\n  --_neu-focus: 0 0 0 3px color-mix(in oklab, var(--_neu-accent-c) 45%, transparent);\n  --_neu-raised: var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) var(--_neu-sd), calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n  --_neu-raised-sm: calc(var(--_neu-d) * 0.5) calc(var(--_neu-d) * 0.5) var(--_neu-d) var(--_neu-sd), calc(var(--_neu-d) * -0.5) calc(var(--_neu-d) * -0.5) var(--_neu-d) var(--_neu-sl);\n  --_neu-inset: inset var(--_neu-d) var(--_neu-d) calc(var(--_neu-d) * 2) var(--_neu-sd), inset calc(var(--_neu-d) * -1) calc(var(--_neu-d) * -1) calc(var(--_neu-d) * 2) var(--_neu-sl);\n  --_neu-inset-sm: inset calc(var(--_neu-d) * 0.5) calc(var(--_neu-d) * 0.5) var(--_neu-d) var(--_neu-sd), inset calc(var(--_neu-d) * -0.5) calc(var(--_neu-d) * -0.5) var(--_neu-d) var(--_neu-sl);\n  font-family: var(--neu-font);\n  color: var(--_neu-fg);\n  -webkit-tap-highlight-color: transparent;\n}\n:host(:not(:defined)) { visibility: inherit !important; min-block-size: auto !important; }\n:host([hidden]) { display: none !important; }\n:host(:focus) { outline: none; }\n*, *::before, *::after { box-sizing: border-box; }\n";
-export declare const themeCssProperties: readonly DocEntry[];

package/dist/core/styles.js

@@ -31,10 +31,3 @@ export const hostTheme = `
 :host(:focus) { outline: none; }
 *, *::before, *::after { box-sizing: border-box; }
 `;
-export const themeCssProperties = [
-    { name: '--neu-bg', description: 'Surface colour; shadows and text are derived from it.' },
-    { name: '--neu-accent', description: 'Accent colour.' },
-    { name: '--neu-distance', description: 'Shadow distance for the md size.' },
-    { name: '--neu-intensity', description: 'Shadow strength multiplier.' },
-    { name: '--neu-radius', description: 'Corner radius for the md size.' },
-];

package/dist/docs.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentDocs } from './core/define.js';
+/** The documentation of every component by tag, for tools. DOM-free; never part of the runtime bundles. */
+export declare const componentDocs: ReadonlyMap<string, ComponentDocs>;

package/dist/docs.js

@@ -0,0 +1,41 @@
+import { avatarDocs } from './components/avatar/avatar.docs.js';
+import { badgeDocs } from './components/badge/badge.docs.js';
+import { buttonDocs } from './components/button/button.docs.js';
+import { buttonGroupDocs } from './components/button-group/button-group.docs.js';
+import { checkboxDocs } from './components/checkbox/checkbox.docs.js';
+import { dividerDocs } from './components/divider/divider.docs.js';
+import { iconDocs } from './components/icon/icon.docs.js';
+import { iconButtonDocs } from './components/icon-button/icon-button.docs.js';
+import { numberFieldDocs } from './components/number-field/number-field.docs.js';
+import { optionDocs } from './components/option/option.docs.js';
+import { radioDocs } from './components/radio/radio.docs.js';
+import { radioGroupDocs } from './components/radio-group/radio-group.docs.js';
+import { selectDocs } from './components/select/select.docs.js';
+import { sliderDocs } from './components/slider/slider.docs.js';
+import { spinnerDocs } from './components/spinner/spinner.docs.js';
+import { surfaceDocs } from './components/surface/surface.docs.js';
+import { switchDocs } from './components/switch/switch.docs.js';
+import { textFieldDocs } from './components/text-field/text-field.docs.js';
+import { textareaDocs } from './components/textarea/textarea.docs.js';
+/** The documentation of every component by tag, for tools. DOM-free; never part of the runtime bundles. */
+export const componentDocs = new Map([
+    ['neu-avatar', avatarDocs],
+    ['neu-badge', badgeDocs],
+    ['neu-button', buttonDocs],
+    ['neu-button-group', buttonGroupDocs],
+    ['neu-checkbox', checkboxDocs],
+    ['neu-divider', dividerDocs],
+    ['neu-icon', iconDocs],
+    ['neu-icon-button', iconButtonDocs],
+    ['neu-number-field', numberFieldDocs],
+    ['neu-option', optionDocs],
+    ['neu-radio', radioDocs],
+    ['neu-radio-group', radioGroupDocs],
+    ['neu-select', selectDocs],
+    ['neu-slider', sliderDocs],
+    ['neu-spinner', spinnerDocs],
+    ['neu-surface', surfaceDocs],
+    ['neu-switch', switchDocs],
+    ['neu-text-field', textFieldDocs],
+    ['neu-textarea', textareaDocs],
+]);

package/dist/ssr.d.ts

@@ -3,7 +3,7 @@ export type { ComponentDef, ComponentDocs, DocEntry, FormDef, OptionData, Templa
 export { formDefaultProp } from './core/define.js';
 export { optionLabel } from './components/option/option-data.js';
 export type { InferProps, PropDecl, PropsSchema, PropValue } from './core/props.js';
-export { attributeName, coerceProperty, parseAttribute, parseProps, serializeAttribute, } from './core/props.js';
+export { attributeName, coerceProperty, parseAttribute, parseProps, reflects, serializeAttribute, } from './core/props.js';
 /** Every component definition by tag. DOM-free: safe to import in Node. */
 export declare const definitions: ReadonlyMap<string, ComponentDef>;
 /** Inner HTML of a declarative shadow root: inline styles, then the template. */

package/dist/ssr.js

@@ -20,7 +20,7 @@ import { textareaDef } from './components/textarea/textarea.def.js';
 import { parseProps } from './core/props.js';
 export { formDefaultProp } from './core/define.js';
 export { optionLabel } from './components/option/option-data.js';
-export { attributeName, coerceProperty, parseAttribute, parseProps, serializeAttribute, } from './core/props.js';
+export { attributeName, coerceProperty, parseAttribute, parseProps, reflects, serializeAttribute, } from './core/props.js';
 /** Every component definition by tag. DOM-free: safe to import in Node. */
 export const definitions = /* @__PURE__ */ new Map([
     [avatarDef.tag, avatarDef],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neumorphism-ui/elements",
-  "version": "1.0.0-next.2",
+  "version": "1.0.0-next.3",
   "description": "Neumorphism UI web components",
   "license": "MIT",
   "type": "module",
@@ -100,6 +100,10 @@
       "types": "./dist/all.d.ts",
       "default": "./dist/all.js"
     },
+    "./docs.js": {
+      "types": "./dist/docs.d.ts",
+      "default": "./dist/docs.js"
+    },
     "./ssr.js": {
       "types": "./dist/ssr.d.ts",
       "default": "./dist/ssr.js"