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

package/dist/components/shared/press.js

@@ -0,0 +1,42 @@
+import { afterDispatch, isActiveInRoot } from '../../core/dom.js';
+/**
+ * Native-like keyboard activation shared by button, switch and checkbox: Space arms on keydown and
+ * clicks on keyup, Enter clicks on keydown. `inactive` blocks both arming and clicking.
+ */
+export function pressable(host, states, enter, inactive) {
+    const press = (on) => (on ? states.add('pressed') : states.delete('pressed'));
+    // Not cancelled at the keydown/keyup itself, so a handler further up can still cancel the click.
+    const clickUnlessCancelled = (event) => afterDispatch(event, () => {
+        if (!event.defaultPrevented && !inactive())
+            host.click();
+    });
+    host.addEventListener('keydown', (event) => {
+        if (inactive())
+            return;
+        if (event.key === ' ') {
+            if (event.defaultPrevented)
+                return;
+            // Cancelled at once: deferred, an ancestor that stops propagation would let the page scroll.
+            // An ancestor claims Space in the capture phase, or by cancelling the keyup.
+            event.preventDefault();
+            press(true);
+        }
+        else if (event.key === 'Enter' &&
+            (enter === 'repeat' || (enter === 'once' && !event.repeat))) {
+            clickUnlessCancelled(event);
+        }
+    });
+    host.addEventListener('keyup', (event) => {
+        if (event.key !== ' ' || !states.has('pressed'))
+            return;
+        press(false);
+        clickUnlessCancelled(event);
+    });
+    // Disarm when focus moves away, not when only the window loses focus.
+    host.addEventListener('blur', () => {
+        if (!isActiveInRoot(host))
+            press(false);
+    });
+    // Focus coming back means Space may have been released while it was away.
+    host.addEventListener('focus', () => press(false));
+}

package/dist/components/shared/step.d.ts

@@ -0,0 +1,2 @@
+/** A step a native input would accept; anything at or below zero means the default of 1. */
+export declare const stepUnit: (step: number) => number;

package/dist/components/shared/step.js

@@ -0,0 +1,2 @@
+/** A step a native input would accept; anything at or below zero means the default of 1. */
+export const stepUnit = (step) => (step > 0 ? step : 1);

package/dist/components/shared/text-control.d.ts

@@ -0,0 +1,72 @@
+import { FormControlElement } from '../../core/form-control.js';
+type TextControl = HTMLInputElement | HTMLTextAreaElement;
+/** The props every text control shares; a subclass's def may leave some out. */
+interface TextControlProps {
+    value: string;
+    placeholder: string;
+    required: boolean;
+    readOnly: boolean;
+    minLength: number;
+    maxLength: number;
+    autocomplete: string;
+    errorText: string;
+    label: string;
+    helpText: string;
+    enterKeyHint: string;
+}
+/** The props that can change the form value, its restore state or its validity in every text control. */
+export declare const baseCommitProps: readonly ["value", "required", "disabled", "readOnly", "minLength", "maxLength", "errorText", "autocomplete"];
+/**
+ * The behaviour text-field, textarea and number-field share: a native control in the shadow root
+ * (`data-ref="input"`) holds the value, and the host mirrors its form value, restore state and
+ * validity. update() touches a prop only when it is in `changed`, so props a def does not declare
+ * never reach it.
+ */
+export declare abstract class TextControlElement extends FormControlElement {
+    name: string;
+    label: string;
+    placeholder: string;
+    helpText: string;
+    errorText: string;
+    required: boolean;
+    disabled: boolean;
+    readOnly: boolean;
+    autocomplete: string;
+    /** True once the value was edited or set as a property; the default then stops applying. */
+    protected dirty: boolean;
+    /** A value set before the shadow root exists. */
+    protected pendingValue: string | null;
+    /** Props that can change the form value, its restore state or its validity. */
+    protected abstract readonly commitProps: readonly string[];
+    /** A detached control holding `value`, sanitized and constrained the way the real one is. */
+    protected abstract probe(value: string): TextControl;
+    get value(): string;
+    set value(next: string);
+    get defaultValue(): string;
+    set defaultValue(next: string);
+    /** Focuses the inner control directly, so the caret stays where it was (no select-all). */
+    focus(options?: FocusOptions): void;
+    select(): void;
+    setSelectionRange(start: number, end: number, direction?: 'forward' | 'backward' | 'none'): void;
+    protected get p(): TextControlProps;
+    protected get input(): TextControl | null;
+    /** Hook for keys pressed in the inner control. */
+    protected controlKeyDown(_event: KeyboardEvent): void;
+    private needsCommit;
+    /** Stands in for the inner control until it exists, so validity is right from the start. */
+    private validityProbe;
+    protected rendered(): void;
+    protected update(changed: ReadonlySet<string>): void;
+    /** update() only runs once connected; before that, keep the value and validity current here. */
+    protected willUpdate(changed: ReadonlySet<string>): void;
+    protected formValue(): string;
+    /**
+     * Like a native control, one with autocomplete=off is never saved for restore, nor is one
+     * that sets none of its own inside a form with autocomplete=off.
+     */
+    protected formState(): string | null;
+    protected validate(): void;
+    protected resetToDefault(): void;
+    protected restoreState(state: string): void;
+}
+export {};

package/dist/components/shared/text-control.js

@@ -0,0 +1,191 @@
+import { dispatch, setOptionalAttribute, setText } from '../../core/dom.js';
+import { FormControlElement } from '../../core/form-control.js';
+import { copyValidity } from '../../core/validation.js';
+/** The props that can change the form value, its restore state or its validity in every text control. */
+export const baseCommitProps = [
+    'value',
+    'required',
+    'disabled',
+    'readOnly',
+    'minLength',
+    'maxLength',
+    'errorText',
+    'autocomplete',
+];
+function autocompleteOff(value) {
+    return (value ?? '').trim().toLowerCase() === 'off';
+}
+/**
+ * The behaviour text-field, textarea and number-field share: a native control in the shadow root
+ * (`data-ref="input"`) holds the value, and the host mirrors its form value, restore state and
+ * validity. update() touches a prop only when it is in `changed`, so props a def does not declare
+ * never reach it.
+ */
+export class TextControlElement extends FormControlElement {
+    /** True once the value was edited or set as a property; the default then stops applying. */
+    dirty = false;
+    /** A value set before the shadow root exists. */
+    pendingValue = null;
+    get value() {
+        return this.input?.value ?? this.pendingValue ?? this.p.value;
+    }
+    set value(next) {
+        const text = next === null || next === undefined ? '' : String(next);
+        this.dirty = true;
+        const input = this.input;
+        if (input)
+            input.value = text;
+        else
+            this.pendingValue = text;
+        this.commit();
+    }
+    get defaultValue() {
+        return this.p.value;
+    }
+    set defaultValue(next) {
+        this.setAttribute('value', String(next));
+    }
+    /** Focuses the inner control directly, so the caret stays where it was (no select-all). */
+    focus(options) {
+        const input = this.input;
+        if (input)
+            input.focus(options);
+        else
+            super.focus(options);
+    }
+    select() {
+        this.input?.select();
+    }
+    setSelectionRange(start, end, direction) {
+        this.input?.setSelectionRange(start, end, direction);
+    }
+    get p() {
+        return this.props;
+    }
+    get input() {
+        return this.ref('input');
+    }
+    /** Hook for keys pressed in the inner control. */
+    controlKeyDown(_event) { }
+    needsCommit(changed) {
+        return this.commitProps.some((key) => changed.has(key));
+    }
+    /** Stands in for the inner control until it exists, so validity is right from the start. */
+    validityProbe() {
+        const p = this.p;
+        const probe = this.probe(this.value);
+        probe.required = p.required;
+        probe.readOnly = p.readOnly;
+        probe.disabled = this.isDisabled;
+        if (p.minLength >= 0)
+            probe.setAttribute('minlength', String(p.minLength));
+        if (p.maxLength >= 0)
+            probe.setAttribute('maxlength', String(p.maxLength));
+        return probe;
+    }
+    rendered() {
+        const input = this.input;
+        // A declarative root adopted without its control (cut short by the parser): nothing to wire up.
+        if (!input)
+            return;
+        // An SSR'd control works before JS loads; keep whatever was typed or autofilled meanwhile.
+        // Compare with the sanitized default: the browser trims or strips some values by itself.
+        if (input.value !== this.probe(this.p.value).value)
+            this.dirty = true;
+        if (this.pendingValue !== null) {
+            input.value = this.pendingValue;
+            this.pendingValue = null;
+        }
+        input.addEventListener('input', () => {
+            this.dirty = true;
+            this.commit();
+        });
+        input.addEventListener('change', () => {
+            this.markInteracted();
+            dispatch(this, 'change');
+        });
+        input.addEventListener('keydown', (event) => this.controlKeyDown(event));
+    }
+    update(changed) {
+        const p = this.p;
+        const input = this.input;
+        if (input) {
+            if (changed.has('value')) {
+                if (input.defaultValue !== p.value)
+                    input.defaultValue = p.value;
+                if (!this.dirty)
+                    input.value = p.value;
+            }
+            if (changed.has('placeholder'))
+                setOptionalAttribute(input, 'placeholder', p.placeholder);
+            if (changed.has('required'))
+                input.required = p.required;
+            if (changed.has('disabled'))
+                input.disabled = this.isDisabled;
+            if (changed.has('readOnly'))
+                input.readOnly = p.readOnly;
+            if (changed.has('minLength')) {
+                setOptionalAttribute(input, 'minlength', p.minLength >= 0 ? String(p.minLength) : '');
+            }
+            if (changed.has('maxLength')) {
+                setOptionalAttribute(input, 'maxlength', p.maxLength >= 0 ? String(p.maxLength) : '');
+            }
+            if (changed.has('autocomplete'))
+                setOptionalAttribute(input, 'autocomplete', p.autocomplete);
+            if (changed.has('enterKeyHint'))
+                setOptionalAttribute(input, 'enterkeyhint', p.enterKeyHint);
+        }
+        if (changed.has('label'))
+            setText(this.ref('label-text'), p.label);
+        if (changed.has('helpText'))
+            setText(this.ref('help-text'), p.helpText);
+        if (this.needsCommit(changed))
+            this.commit();
+    }
+    /** update() only runs once connected; before that, keep the value and validity current here. */
+    willUpdate(changed) {
+        if (!this.isConnected && !this.input && this.needsCommit(changed))
+            this.commit();
+    }
+    formValue() {
+        return this.value;
+    }
+    /**
+     * Like a native control, one with autocomplete=off is never saved for restore, nor is one
+     * that sets none of its own inside a form with autocomplete=off.
+     */
+    formState() {
+        const own = this.p.autocomplete?.trim();
+        const off = own
+            ? autocompleteOff(own)
+            : autocompleteOff(this.internals.form?.getAttribute('autocomplete'));
+        return off ? null : this.value;
+    }
+    validate() {
+        const input = this.input;
+        const source = input ?? this.validityProbe();
+        // A disabled or readonly control still sets flags such as typeMismatch, but is barred from
+        // validation and has no message; setValidity() would throw on flags without a message.
+        if (!source.willValidate || source.validity.valid)
+            this.internals.setValidity({});
+        else {
+            this.internals.setValidity(copyValidity(source.validity), source.validationMessage, input ?? undefined);
+        }
+        setText(this.ref('error-text'), this.p.errorText || input?.validationMessage || '');
+    }
+    resetToDefault() {
+        this.dirty = false;
+        this.pendingValue = null;
+        const input = this.input;
+        if (input)
+            input.value = this.p.value;
+    }
+    restoreState(state) {
+        this.dirty = true;
+        const input = this.input;
+        if (input)
+            input.value = state;
+        else
+            this.pendingValue = state;
+    }
+}

package/dist/components/slider/slider.d.ts

@@ -0,0 +1,67 @@
+import { FormControlElement } from '../../core/form-control.js';
+export declare class NeuSlider extends FormControlElement {
+    static def: import("../../ssr.js").ComponentDef<{
+        readonly value: {
+            readonly type: "number";
+            readonly default: number;
+        };
+        readonly min: {
+            readonly type: "number";
+            readonly default: 0;
+        };
+        readonly max: {
+            readonly type: "number";
+            readonly default: 100;
+        };
+        readonly step: {
+            readonly type: "number";
+            readonly default: 1;
+        };
+        readonly name: {
+            readonly type: "string";
+        };
+        readonly label: {
+            readonly type: "string";
+        };
+        readonly disabled: {
+            readonly type: "boolean";
+        };
+    }>;
+    static extraProperties: string[];
+    name: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+    disabled: boolean;
+    private current;
+    private dirty;
+    private dragging;
+    private startValue;
+    private formatter;
+    constructor();
+    protected disconnected(): void;
+    get value(): number;
+    set value(next: number);
+    get defaultValue(): number;
+    set defaultValue(next: number);
+    get valueFormatter(): ((value: number) => string) | undefined;
+    set valueFormatter(next: ((value: number) => string) | undefined);
+    private snap;
+    /** Pushes the value to ARIA and the thumb, without touching the form. */
+    private sync;
+    private setCurrent;
+    /** The value as a user change: marks the form interaction and fires input. Returns false if nothing changed. */
+    private userSet;
+    private onKey;
+    private onDown;
+    private onMove;
+    private moveTo;
+    private endDrag;
+    protected willUpdate(changed: ReadonlySet<string>): void;
+    protected update(changed: ReadonlySet<string>): void;
+    protected formValue(): string;
+    protected validate(): void;
+    protected resetToDefault(): void;
+    protected restoreState(state: string): void;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * The value `raw` becomes on a slider: the nearest step counted from min, inside [min, max]
+ * (plan decision 9). max < min counts as max = min, a step of 0 or less as 1, NaN as the midpoint.
+ * Rounded to the decimals of step and min, so 0.1 + 0.2 on a 0.1 step is 0.3.
+ */
+export declare function sliderValue(raw: number, min: number, max: number, step: number): number;
+/** What PageUp and PageDown move by: a tenth of the range in whole steps, at least one step. */
+export declare function sliderBigStep(min: number, max: number, step: number): number;
+/** The `style` of `.base`: where the thumb sits, 0 to 1. Template and update() write the same bytes. */
+export declare function sliderStyle(value: number, min: number, max: number): string;
+export declare const sliderDef: import("../../core/define.js").ComponentDef<{
+    readonly value: {
+        readonly type: "number";
+        readonly default: number;
+    };
+    readonly min: {
+        readonly type: "number";
+        readonly default: 0;
+    };
+    readonly max: {
+        readonly type: "number";
+        readonly default: 100;
+    };
+    readonly step: {
+        readonly type: "number";
+        readonly default: 1;
+    };
+    readonly name: {
+        readonly type: "string";
+    };
+    readonly label: {
+        readonly type: "string";
+    };
+    readonly disabled: {
+        readonly type: "boolean";
+    };
+}>;

package/dist/components/slider/slider.def.js

@@ -0,0 +1,54 @@
+import { defineComponent } from '../../core/define.js';
+import { html } from '../../core/html.js';
+import { stepUnit } from '../shared/step.js';
+import { sliderStyles } from './slider.styles.js';
+/** Decimal places of a number as written, exponent notation included. */
+function decimals(n) {
+    const [, fraction = '', exponent = '0'] = /(?:\.(\d+))?(?:e([+-]\d+))?$/.exec(String(n)) ?? [];
+    return Math.min(100, Math.max(0, fraction.length - Number(exponent)));
+}
+/**
+ * The value `raw` becomes on a slider: the nearest step counted from min, inside [min, max]
+ * (plan decision 9). max < min counts as max = min, a step of 0 or less as 1, NaN as the midpoint.
+ * Rounded to the decimals of step and min, so 0.1 + 0.2 on a 0.1 step is 0.3.
+ */
+export function sliderValue(raw, min, max, step) {
+    const hi = Math.max(min, max);
+    const unit = stepUnit(step);
+    const wanted = Number.isNaN(raw) ? min + (hi - min) / 2 : raw;
+    let steps = Math.round((wanted - min) / unit);
+    // Rounding up may pass max: the largest step that fits is the answer. The epsilon absorbs
+    // float noise such as (0.3 - 0) / 0.1 = 2.9999999999999996.
+    if (min + steps * unit > hi)
+        steps = Math.floor((hi - min) / unit + 1e-9);
+    const value = min + Math.max(0, steps) * unit;
+    return Number(Math.min(value, hi).toFixed(Math.max(decimals(unit), decimals(min))));
+}
+/** What PageUp and PageDown move by: a tenth of the range in whole steps, at least one step. */
+export function sliderBigStep(min, max, step) {
+    const unit = stepUnit(step);
+    const tenth = Math.round((Math.max(min, max) - min) / 10 / unit) * unit;
+    return Number(Math.max(unit, tenth).toFixed(decimals(unit)));
+}
+/** The `style` of `.base`: where the thumb sits, 0 to 1. Template and update() write the same bytes. */
+export function sliderStyle(value, min, max) {
+    const range = Math.max(min, max) - min;
+    const pos = range > 0 ? Math.round(((value - min) / range) * 1e4) / 1e4 : 0;
+    return `--_neu-pos:${pos}`;
+}
+export const sliderDef = defineComponent({
+    tag: 'neu-slider',
+    props: {
+        value: { type: 'number', default: Number.NaN },
+        min: { type: 'number', default: 0 },
+        max: { type: 'number', default: 100 },
+        step: { type: 'number', default: 1 },
+        name: { type: 'string' },
+        label: { type: 'string' },
+        disabled: { type: 'boolean' },
+    },
+    form: { valueProp: 'value' },
+    properties: { valueFormatter: '(value: number) => string' },
+    styles: sliderStyles,
+    template: (p) => html `<span part="base" class="base" data-ref="base" style="${sliderStyle(sliderValue(p.value, p.min, p.max, p.step), p.min, p.max)}"><span part="track" class="track" data-ref="track"><span part="fill" class="fill"></span><span part="thumb" class="thumb"></span></span></span>`,
+});

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

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

package/dist/components/slider/slider.docs.js

@@ -0,0 +1,45 @@
+import { themeCssProperties } from '../theme-docs.js';
+export const sliderDocs = {
+    summary: 'A horizontal slider for a number. The value attribute is the default; the value property is the current value. The valueFormatter property turns the value into the text a screen reader announces.',
+    descriptions: {
+        value: 'The current number, snapped to the nearest step within the range.',
+        min: 'The lowest value of the range.',
+        max: 'The highest value of the range.',
+        step: 'The distance between allowed values.',
+        name: 'The name under which the value is submitted with a form.',
+        label: 'Accessible name of the slider.',
+        disabled: 'Prevents interaction and leaves the slider out of form submission.',
+        defaultValue: 'The value the slider starts with, which a form reset restores; set by the value attribute.',
+        valueFormatter: 'Function that turns the value into the text a screen reader announces.',
+    },
+    events: [
+        {
+            name: 'input',
+            description: 'Fired on every change while the user drags or presses a key.',
+        },
+        {
+            name: 'change',
+            description: 'Fired after the user commits a change: on release, or per key.',
+        },
+    ],
+    slots: [],
+    parts: [
+        { name: 'base', description: 'Wrapper around the track.' },
+        { name: 'track', description: 'The inset groove.' },
+        { name: 'fill', description: 'The part of the track up to the thumb.' },
+        { name: 'thumb', description: 'The raised handle.' },
+    ],
+    cssProperties: themeCssProperties,
+    keyboard: [
+        {
+            name: 'ArrowRight / ArrowUp',
+            description: 'Increases the value by step; left and right swap in right-to-left text.',
+        },
+        { name: 'ArrowLeft / ArrowDown', description: 'Decreases the value by step.' },
+        {
+            name: 'PageUp / PageDown',
+            description: 'Changes the value by a large step: the larger of step and a tenth of the range.',
+        },
+        { name: 'Home / End', description: 'Sets the value to min or max.' },
+    ],
+};