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

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

@@ -0,0 +1,92 @@
+import { TextControlElement } from '../shared/text-control.js';
+export declare class NeuTextarea extends TextControlElement {
+    static def: import("../../ssr.js").ComponentDef<{
+        readonly value: {
+            readonly type: "string";
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly label: {
+            readonly type: "string";
+        };
+        readonly placeholder: {
+            readonly type: "string";
+        };
+        readonly helpText: {
+            readonly type: "string";
+        };
+        readonly errorText: {
+            readonly type: "string";
+        };
+        readonly required: {
+            readonly type: "boolean";
+        };
+        readonly disabled: {
+            readonly type: "boolean";
+        };
+        readonly readOnly: {
+            readonly type: "boolean";
+            readonly attribute: "readonly";
+        };
+        readonly minLength: {
+            readonly type: "number";
+            readonly default: -1;
+            readonly attribute: "minlength";
+        };
+        readonly maxLength: {
+            readonly type: "number";
+            readonly default: -1;
+            readonly attribute: "maxlength";
+        };
+        readonly autocomplete: {
+            readonly type: "string";
+        };
+        readonly enterKeyHint: {
+            readonly type: "string";
+            readonly attribute: "enterkeyhint";
+        };
+        readonly rows: {
+            readonly type: "number";
+            readonly default: 3;
+        };
+        readonly resize: {
+            readonly type: "string";
+            readonly default: "vertical";
+            readonly values: readonly ["none", "vertical", "auto"];
+        };
+        readonly size: {
+            readonly type: "string";
+            readonly default: "md";
+            readonly values: readonly ["sm", "md", "lg"];
+        };
+    }>;
+    static extraProperties: string[];
+    minLength: number;
+    maxLength: number;
+    rows: number;
+    resize: 'none' | 'vertical' | 'auto';
+    size: 'sm' | 'md' | 'lg';
+    protected readonly commitProps: readonly ["value", "required", "disabled", "readOnly", "minLength", "maxLength", "errorText", "autocomplete"];
+    private get tp();
+    get value(): string;
+    set value(next: string);
+    protected probe(value: string): HTMLTextAreaElement;
+    private sizeWatch;
+    private sizeFrame;
+    private lastWidth;
+    /**
+     * Re-fits when the width changes or the box first gets a layout (it was hidden, or server
+     * rendered); its own height changes keep the width, so they do not loop.
+     */
+    private watchSize;
+    private stopWatch;
+    /** resize="auto": fit the height to the content, never below the rows height. */
+    private grow;
+    protected connected(): void;
+    protected disconnected(): void;
+    protected rendered(): void;
+    protected update(changed: ReadonlySet<string>): void;
+    protected resetToDefault(): void;
+    protected restoreState(state: string): void;
+}

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

@@ -0,0 +1,127 @@
+import type { InferProps } from '../../core/props.js';
+declare const props: {
+    readonly value: {
+        readonly type: "string";
+    };
+    readonly name: {
+        readonly type: "string";
+    };
+    readonly label: {
+        readonly type: "string";
+    };
+    readonly placeholder: {
+        readonly type: "string";
+    };
+    readonly helpText: {
+        readonly type: "string";
+    };
+    readonly errorText: {
+        readonly type: "string";
+    };
+    readonly required: {
+        readonly type: "boolean";
+    };
+    readonly disabled: {
+        readonly type: "boolean";
+    };
+    readonly readOnly: {
+        readonly type: "boolean";
+        readonly attribute: "readonly";
+    };
+    readonly minLength: {
+        readonly type: "number";
+        readonly default: -1;
+        readonly attribute: "minlength";
+    };
+    readonly maxLength: {
+        readonly type: "number";
+        readonly default: -1;
+        readonly attribute: "maxlength";
+    };
+    readonly autocomplete: {
+        readonly type: "string";
+    };
+    readonly enterKeyHint: {
+        readonly type: "string";
+        readonly attribute: "enterkeyhint";
+    };
+    readonly rows: {
+        readonly type: "number";
+        readonly default: 3;
+    };
+    readonly resize: {
+        readonly type: "string";
+        readonly default: "vertical";
+        readonly values: readonly ["none", "vertical", "auto"];
+    };
+    readonly size: {
+        readonly type: "string";
+        readonly default: "md";
+        readonly values: readonly ["sm", "md", "lg"];
+    };
+};
+export type TextareaProps = InferProps<typeof props>;
+/** A row count the native textarea would also accept; anything else means the default of 3. */
+export declare function rowsOf(rows: number): number;
+export declare const textareaDef: import("../../core/define.js").ComponentDef<{
+    readonly value: {
+        readonly type: "string";
+    };
+    readonly name: {
+        readonly type: "string";
+    };
+    readonly label: {
+        readonly type: "string";
+    };
+    readonly placeholder: {
+        readonly type: "string";
+    };
+    readonly helpText: {
+        readonly type: "string";
+    };
+    readonly errorText: {
+        readonly type: "string";
+    };
+    readonly required: {
+        readonly type: "boolean";
+    };
+    readonly disabled: {
+        readonly type: "boolean";
+    };
+    readonly readOnly: {
+        readonly type: "boolean";
+        readonly attribute: "readonly";
+    };
+    readonly minLength: {
+        readonly type: "number";
+        readonly default: -1;
+        readonly attribute: "minlength";
+    };
+    readonly maxLength: {
+        readonly type: "number";
+        readonly default: -1;
+        readonly attribute: "maxlength";
+    };
+    readonly autocomplete: {
+        readonly type: "string";
+    };
+    readonly enterKeyHint: {
+        readonly type: "string";
+        readonly attribute: "enterkeyhint";
+    };
+    readonly rows: {
+        readonly type: "number";
+        readonly default: 3;
+    };
+    readonly resize: {
+        readonly type: "string";
+        readonly default: "vertical";
+        readonly values: readonly ["none", "vertical", "auto"];
+    };
+    readonly size: {
+        readonly type: "string";
+        readonly default: "md";
+        readonly values: readonly ["sm", "md", "lg"];
+    };
+}>;
+export {};

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

@@ -0,0 +1,44 @@
+import { defineComponent } from '../../core/define.js';
+import { html } from '../../core/html.js';
+import { textareaStyles } from './textarea.styles.js';
+const props = {
+    value: { type: 'string' },
+    name: { type: 'string' },
+    label: { type: 'string' },
+    placeholder: { type: 'string' },
+    helpText: { type: 'string' },
+    errorText: { type: 'string' },
+    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' },
+    enterKeyHint: { type: 'string', attribute: 'enterkeyhint' },
+    rows: { type: 'number', default: 3 },
+    resize: {
+        type: 'string',
+        default: 'vertical',
+        values: ['none', 'vertical', 'auto'],
+    },
+    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) {
+    return Number.isInteger(rows) && rows >= 1 ? rows : 3;
+}
+/** Attributes of the inner <textarea> that only appear when set. */
+function areaAttributes(p) {
+    return html `${p.placeholder ? html ` placeholder="${p.placeholder}"` : ''}${p.required ? html ` required` : ''}${p.disabled ? html ` disabled` : ''}${p.readOnly ? html ` readonly` : ''}${p.minLength >= 0 ? html ` minlength="${p.minLength}"` : ''}${p.maxLength >= 0 ? html ` maxlength="${p.maxLength}"` : ''}${p.autocomplete ? html ` autocomplete="${p.autocomplete}"` : ''}${p.enterKeyHint ? html ` enterkeyhint="${p.enterKeyHint}"` : ''}`;
+}
+export const textareaDef = defineComponent({
+    tag: 'neu-textarea',
+    props,
+    delegatesFocus: true,
+    form: { valueProp: 'value' },
+    styles: textareaStyles,
+    // The newline after the opening tag is dropped by the HTML parser, so a value that itself starts
+    // 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>`,
+});

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.js

@@ -0,0 +1,101 @@
+import { baseCommitProps, TextControlElement } from '../shared/text-control.js';
+import { rowsOf, textareaDef } from './textarea.def.js';
+export class NeuTextarea extends TextControlElement {
+    static def = textareaDef;
+    static extraProperties = ['defaultValue'];
+    // enterKeyHint is inherited from HTMLElement with the right type.
+    commitProps = baseCommitProps;
+    get tp() {
+        return this.props;
+    }
+    // An accessor override must redefine both halves; a script-set value needs a fresh height.
+    get value() {
+        return super.value;
+    }
+    set value(next) {
+        super.value = next;
+        this.grow();
+    }
+    probe(value) {
+        const probe = document.createElement('textarea');
+        probe.value = value;
+        return probe;
+    }
+    sizeWatch;
+    sizeFrame = 0;
+    lastWidth = -1;
+    /**
+     * Re-fits when the width changes or the box first gets a layout (it was hidden, or server
+     * rendered); its own height changes keep the width, so they do not loop.
+     */
+    watchSize(area, on) {
+        if (!on) {
+            this.stopWatch();
+            return;
+        }
+        if (this.sizeWatch)
+            return;
+        this.lastWidth = -1;
+        this.sizeWatch = new ResizeObserver(([entry]) => {
+            const width = entry?.contentRect.width ?? 0;
+            if (width === this.lastWidth)
+                return;
+            this.lastWidth = width;
+            // Next frame: resizing an observed box inside its own callback reports a
+            // "ResizeObserver loop" error on window.
+            cancelAnimationFrame(this.sizeFrame);
+            this.sizeFrame = requestAnimationFrame(() => this.grow());
+        });
+        this.sizeWatch.observe(area);
+    }
+    stopWatch() {
+        cancelAnimationFrame(this.sizeFrame);
+        this.sizeWatch?.disconnect();
+        this.sizeWatch = undefined;
+    }
+    /** resize="auto": fit the height to the content, never below the rows height. */
+    grow() {
+        const area = this.input;
+        if (!area)
+            return;
+        this.watchSize(area, this.isConnected && this.tp.resize === 'auto');
+        if (this.tp.resize !== 'auto') {
+            area.style.blockSize = '';
+            return;
+        }
+        // Back to the rows height first: scrollHeight is never smaller than the box it sits in.
+        area.style.blockSize = 'auto';
+        const fit = area.scrollHeight;
+        // Not laid out (disconnected or hidden): keep the rows height.
+        if (fit)
+            area.style.blockSize = `${fit}px`;
+    }
+    connected() {
+        super.connected();
+        this.grow();
+    }
+    disconnected() {
+        super.disconnected();
+        this.stopWatch();
+    }
+    rendered() {
+        super.rendered();
+        this.input?.addEventListener('input', () => this.grow());
+    }
+    update(changed) {
+        const area = this.input;
+        if (area && changed.has('rows'))
+            area.rows = rowsOf(this.tp.rows);
+        super.update(changed);
+        if (['value', 'rows', 'resize', 'size'].some((key) => changed.has(key)))
+            this.grow();
+    }
+    resetToDefault() {
+        super.resetToDefault();
+        this.grow();
+    }
+    restoreState(state) {
+        super.restoreState(state);
+        this.grow();
+    }
+}

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

@@ -0,0 +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 { 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/textarea/textarea.styles.js

@@ -0,0 +1,9 @@
+import { fieldStyles } from '../shared/field.styles.js';
+export const textareaStyles = `${fieldStyles}
+.control { align-items: stretch; }
+.input {
+  display: block; box-sizing: border-box; padding-block: 0.625rem; line-height: 1.4; resize: vertical;
+}
+:host([resize='none']) .input { resize: none; }
+:host([resize='auto']) .input { resize: none; overflow: hidden; }
+`;

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,24 +6,42 @@ 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). */
     readonly valueProp: 'value' | 'checked';
 }
+/** One option child as the server reads it (spec §8.2): its value, label text and disabled state. */
+export interface OptionData {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+}
+/** What a server renderer knows beyond the attributes: the option children of a select (§8.3). */
+export interface TemplateContext {
+    readonly options?: readonly OptionData[];
+}
 /** The DOM-free half of a component, shared by the element, SSR, React wrappers and docs. */
 export interface ComponentDef<S extends PropsSchema = PropsSchema> {
     readonly tag: string;
     readonly props: S;
     readonly styles: string;
-    template(props: InferProps<S>): RawHtml;
+    /** The client always renders without `ctx`; only a server renderer passes one. */
+    template(props: InferProps<S>, ctx?: TemplateContext): RawHtml;
     readonly delegatesFocus?: boolean;
     readonly form?: FormDef;
-    readonly docs: ComponentDocs;
+    /** Properties set only from JS (no attribute), name to TypeScript type, for wrappers and the manifest. Type-only. */
+    readonly properties?: Readonly<Record<string, string>>;
+    /** Tag of the children a server renderer reads into `TemplateContext.options`. */
+    readonly optionsFrom?: string;
 }
 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();
@@ -47,7 +48,11 @@ function watchSubmitAttempts() {
         }
     }, { capture: true });
     document.addEventListener('keydown', (event) => {
-        if (event.key !== 'Enter')
+        // 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' ||
+            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) {