@fusion.dev/helix-headless 0.0.0-dev

package/dist/number-input/root/number-input-root.d.ts

@@ -0,0 +1,282 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A number a reader types or steps to.
+ *
+ * @description
+ * **A family rather than `Input`'s `type="number"`, and rather than a part of
+ * it.** `Input` already takes that type and will keep it: a bare numeric field
+ * in a form is a text field with a different keyboard, and that is all it needs
+ * to be. This is a different control. It renders two buttons, binds four keys
+ * that `Input` does not, and owns clamping and stepping, so it is an alternative
+ * and not a variant. Namespacing it under `Input` would say it is contained by
+ * one, which is what `IconButton` is top-level for.
+ *
+ * **The field is `type="text"` with `inputmode="decimal"`, and that is a
+ * measurement rather than a preference.** Asked of a real browser, `type=number`
+ * fails three ways this control cannot live with:
+ *
+ * ```
+ * typed "12e" into type=number  → .value === ""
+ * focused, wheeled over it      → 5 became 4
+ * selectionStart on type=number → null
+ * same keystrokes into type=text → .value === "12e"
+ * ```
+ *
+ * The first is fatal on its own: the element cannot see what the reader typed,
+ * so a controlled value is destroyed by a keystroke and there is nothing left to
+ * correct or to report. The second changes a value because a page scrolled past.
+ * The third means the caret cannot be managed at all, which any correcting or
+ * formatting field needs. `inputmode` is what keeps the phone keypad, which is
+ * the one thing `type=number` was giving.
+ *
+ * Validity is still the platform's, through `min`, `max` and `step` mirrored
+ * onto the host's own `setValidity`. What is not mirrored is the field's
+ * `type`, because a text field has no opinion about numbers.
+ *
+ * **Stepping is separate from typing.** A reader mid-way through "1" of "12"
+ * has not asked for anything to be clamped, so the value is only pulled into
+ * range when they step, blur, or the form asks. Clamping on every keystroke is
+ * what makes a field that cannot be typed backwards into.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases NumberField, Stepper, InputNumber
+ * @documentation https://helix.fusion.dev/components/number-input
+ *
+ * @slot end - After it.
+ * @slot start - Before the number, for a unit or an icon.
+ *
+ * @event {Event} change - Relayed from the field once the reader has finished.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the value changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart control - The field itself.
+ * @csspart decrement - The control that steps down.
+ * @csspart decrement-mark - The glyph on the step down control.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The box holding everything.
+ * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart increment - The control that steps up.
+ * @csspart increment-mark - The glyph on the step up control.
+ * @csspart label - The name over the field, which is also the scrub grip.
+ */
+export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_base {
+    protected readonly aria: AriaForwardController;
+    /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+    protected readonly announcesInput = true;
+    /**
+     * What the browser may autofill here, as one of the platform's own tokens.
+     *
+     * Empty leaves the attribute off, which is the browser's default and is what
+     * lets autofill work at all. This used to be hardcoded `off`, so a reader
+     * could never have a birthday or a postal code filled in for them and a
+     * consumer had no way to ask for it. See 295.
+     */
+    autocomplete: string;
+    /**
+     * Smallest value the reader may reach.
+     *
+     * Absent has no floor.
+     */
+    min?: number;
+    /**
+     * Largest value the reader may reach.
+     *
+     * Absent has no ceiling.
+     */
+    max?: number;
+    /**
+     * How far one step moves.
+     */
+    step: number;
+    /**
+     * How far `PageUp` and `PageDown` move.
+     *
+     * Ten steps, which is the convention every spinner on the platform follows,
+     * and a property because ten of a step of `0.01` is a hundredth and rarely
+     * what a reader wants from a whole key.
+     */
+    largeStep?: number;
+    /**
+     * Shown while the field is empty.
+     *
+     * Not a label: it goes when typing starts.
+     */
+    placeholder: string;
+    /**
+     * Whether the field refuses input while still submitting its value.
+     */
+    readOnly: boolean;
+    /**
+     * Whether a grip is shown that changes the value when it is dragged.
+     *
+     * The label is what is dragged, so this adds no chrome at all. Still opt-in,
+     * because it changes what a press on the label does and a reader who drags
+     * across a word expecting to select it should get that everywhere it has not
+     * been asked for. Where it earns its place is a value a reader tunes rather
+     * than states: a duration, a weight, a count they are looking for rather than
+     * one they already know.
+     */
+    scrub: boolean;
+    /**
+     * Accessible name for the control that steps down.
+     */
+    decrementLabel: string;
+    /**
+     * Accessible name for the control that steps up.
+     */
+    incrementLabel: string;
+    /** Focus is delegated to the field, so the host is never the focus target. */
+    static shadowRootOptions: ShadowRootInit;
+    private get control();
+    /** The value as a number, or `null` where the field holds nothing usable. */
+    private get numeric();
+    /**
+     * A value pulled into range and onto the step grid.
+     *
+     * The grid is anchored at `min` where there is one, so `min="1" step="2"`
+     * gives 1, 3, 5 rather than 0, 2, 4. Rounded to the step's own precision,
+     * because stepping 0.1 in binary floating point otherwise produces
+     * `0.30000000000000004` and puts it in the field.
+     */
+    private clamp;
+    /**
+     * Moves by whole steps, from where the reader is.
+     *
+     * From `min` when the field is empty, so the first press of an arrow lands
+     * somewhere meaningful rather than on zero: an empty field with `min="1"`
+     * stepping to 0 would be out of range before the reader had typed anything.
+     */
+    private nudge;
+    /** One step up, or `PageUp`'s larger one. */
+    stepUp(large?: boolean): void;
+    /**
+     * Steps the value down, by `largeStep` when `large` is set.
+     *
+     * The same path a press of the down arrow takes, so a consumer driving this
+     * from their own control gets the clamping and the announcement rather than
+     * having to repeat both.
+     */
+    stepDown(large?: boolean): void;
+    /**
+     * The label is the surface, which is where the convention already is.
+     *
+     * A grip was drawn first, an icon of its own at the leading edge, and it was
+     * a second control in a field that already has three. Every tool that does
+     * this well drags the *name* of the value: the label is present on every
+     * field, costs no chrome, and a reader who wants to know what they are
+     * dragging is already looking at it.
+     *
+     * Overridden rather than handled on the host, because the handlers have to
+     * sit on the element that takes the capture. The markup is the mixin's, said
+     * again here, which is the duplication #76 exists to remove: when base
+     * renders break into methods a styled tier can extend, this becomes a call to
+     * `super` with three listeners added.
+     *
+     * A label with nothing in it is still nothing. `scrub` on a field whose label
+     * is empty leaves no surface, which is honest: there is nowhere to put the
+     * gesture and inventing somewhere is how the grip happened.
+     */
+    protected renderLabel(): TemplateResult | typeof nothing;
+    /** Where the pointer went down, and what the value was there. */
+    private scrubFrom;
+    private scrubValue;
+    /**
+     * Press, and the value follows the pointer.
+     *
+     * Captured, so a drag that leaves the grip keeps going: a reader tuning a
+     * number moves further than a 20 pixel handle and the gesture ending because
+     * they overshot it would be the control refusing the very thing it offered.
+     * `preventDefault` because a press inside a field otherwise starts a text
+     * selection, which drags a blue wash across the label at the same time.
+     */
+    private readonly handleScrubDown;
+    /**
+     * Read from where the press began, never from the last frame.
+     *
+     * Accumulating a delta per move drifts: every rounding to a step throws away
+     * the remainder, and a slow drag across a hundred events throws it away a
+     * hundred times, so the value and the pointer disagree by more the longer
+     * anyone holds. From the origin the arithmetic is the same on every frame and
+     * the value can only be where the pointer says it is.
+     */
+    private readonly handleScrubMove;
+    /** Let go, and the capture goes with it. */
+    private readonly handleScrubEnd;
+    /**
+     * Every keystroke, cancelable, and put back where it is refused.
+     *
+     * Not clamped here. A reader typing "12" is at "1" for one keystroke, and a
+     * field with `min="10"` that corrected them at that moment could never be
+     * typed into at all. Range is settled on blur, on a step, and at submit.
+     */
+    private readonly handleInput;
+    /**
+     * Leaving the field is where a half-typed number becomes a number.
+     *
+     * Blank is left blank, because an empty optional field is a legitimate answer
+     * and filling it with `min` would put a number in a form the reader never
+     * gave.
+     *
+     * **And text that is not a number is left alone, which this cleared at
+     * first.** Typing `2.7e` and tabbing away emptied the field: the reader looks
+     * back and their entry is gone with nothing saying why, and the likeliest
+     * cause is a fat finger on a number they had almost finished. Nothing is lost
+     * by keeping it, because `sync` has already marked it `badInput`, so the field
+     * shows as wrong and the form refuses to submit. Destroying the evidence of a
+     * mistake is not the same as preventing one.
+     */
+    private readonly handleBlur;
+    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    private readonly handleChange;
+    /**
+     * The four keys a spinner answers, which `Input` does not bind.
+     *
+     * `Home` and `End` only where there is a bound to go to: without one they are
+     * the text field's own keys and moving the caret to the start of the number is
+     * what a reader pressing them meant.
+     */
+    private readonly handleKeydown;
+    /**
+     * Reports the value and a verdict on it.
+     *
+     * Computed here rather than copied off the field, which is the one place this
+     * differs from `Input`: the field is text, so the browser has no opinion about
+     * whether it is a number in range. The flags are the platform's own names, so
+     * a consumer reading `validity.rangeOverflow` finds what they expect and the
+     * message is what a native spinner would have said.
+     */
+    private sync;
+    /** Puts the caret in the field, the way a label pointing at one would. */
+    focus(options?: FocusOptions): void;
+    /** Selects the number, so typing replaces it. */
+    select(): void;
+    /**
+     * The caret, held across a value the consumer wrote rather than the reader.
+     *
+     * Set in `willUpdate` and spent in `updated`, because Lit's `.value` binding
+     * lands between the two and takes the selection with it. See `holdCaret`.
+     */
+    private releaseCaret;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+    /**
+     * The value as a number, or `NaN` while the control is empty.
+     *
+     * `NaN` and not zero, which is the trap the platform already avoids: `Number('')`
+     * is zero, so an empty control would report a number it does not hold and a
+     * form would submit it.
+     */
+    get valueAsNumber(): number;
+    set valueAsNumber(count: number);
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-number-input': HelixHeadlessNumberInput;
+    }
+}
+export {};