@fusion.dev/helix-headless 0.0.0-dev

package/dist/slider/root/slider-root.d.ts

@@ -0,0 +1,235 @@
+import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A value chosen from a range by dragging.
+ *
+ * @description
+ * A real `<input type="range">`, so the drag, the arrow keys, Home and End, the
+ * page keys and the touch target are all the platform's. Every one of those is
+ * a thing a hand-built slider gets wrong, and the last is the one nobody
+ * notices: a native range has a hit area larger than its thumb, sized by the
+ * platform for a finger.
+ *
+ * **The value is a string, like every other form control's.** A range submits
+ * text and `MixinControllerValue` holds text, so the number is a reading of the
+ * value rather than the value itself. `valueAsNumber` is there for anything
+ * doing arithmetic on it.
+ *
+ * **Marks are drawn rather than left to `<datalist>`**, which was the first
+ * answer and is the wrong one. A datalist's ticks cannot be styled at all, and
+ * Firefox does not render them for a range at all, so the platform's version is
+ * a mark that looks like someone else's design where it appears and no mark
+ * where it does not. Drawing them costs the semantics nothing, because a mark
+ * is decoration: what a reader can actually land on is `step`, which the input
+ * enforces whether or not anything is drawn.
+ *
+ * `markers` is a count rather than a flag tied to `step`. A flag reads well
+ * until a slider from zero to a hundred stepping by one asks for a hundred and
+ * one ticks, and then it is either noise or a silent refusal to draw. A number
+ * is what the reader sees, so it cannot surprise anyone.
+ *
+ * **A range is two of them, not a hand-built one.** There is no native
+ * two-thumb range, and the answer is not to stop using the platform's: it is to
+ * stack two of them on one track, so each thumb keeps its own drag, its own
+ * arrow keys, its own Home and End and its own finger-sized hit area. Rebuilding
+ * would throw away every argument this component is made of, to gain a second
+ * handle.
+ *
+ * Crossing is stopped in the handler rather than by the bounds, and that is not
+ * the obvious way round. Giving the lower input `max` of the upper reads well
+ * and breaks the drawing: an input's thumb sits at a fraction of *its own*
+ * range, so a lower thumb bounded at the upper one paints against a shorter
+ * track and the two stop lining up. Both inputs span the whole range and the
+ * values are clamped against each other on the way in.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Range, Range input
+ * @documentation https://helix.fusion.dev/components/slider
+ *
+ * @event {Event} change - Relayed once the reader has let go.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the value changes, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart control - The range input.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The row: the control and its readout.
+ * @csspart hint - Help under the track, while nothing is wrong.
+ * @csspart label - The question, over the track.
+ * @csspart marker - One mark.
+ * @csspart marker-label - The value a mark stands at, when `marker-labels` is set.
+ * @csspart markers - The row of marks along the track.
+ * @csspart output - The current value, shown beside it.
+ *
+ * @cssproperty --slider-fraction - The value as a fraction of the range, 0 to 1.
+ * @cssproperty --slider-from - Where the filled span starts, as a percentage of the track.
+ * @cssproperty --slider-marker-at - Where one marker sits, as a percentage of the track.
+ * @cssproperty --slider-to - Where the filled span ends, as a percentage of the track.
+ */
+export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
+    protected readonly aria: AriaForwardController;
+    /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+    protected readonly announcesInput = true;
+    /**
+     * Whether there are two thumbs and the value is a pair.
+     *
+     * The pair is one string, `"10,50"`, which is what a form submits and what
+     * `MixinControllerValue` already holds. `valueAsNumber` reads the lower of
+     * the two, since a range has no single number.
+     */
+    range: boolean;
+    /**
+     * The largest value the reader can choose.
+     */
+    max: number;
+    /**
+     * The smallest value the reader can choose.
+     */
+    min: number;
+    /**
+     * Whether the chosen value is shown beside the track.
+     */
+    showValue: boolean;
+    /**
+     * How many marks to draw along the track, evenly spaced, ends included.
+     *
+     * `0` or `1` draws none: one mark on a track says nothing about a range.
+     * They are decoration, so they are `aria-hidden`; what a reader can land on
+     * is `step`, which the input enforces regardless.
+     *
+     * **Each one is snapped to a step before it is placed.** Evenly spaced and
+     * on a step are two different things, and asking for four marks across a
+     * hundred in twenty-fives wants them at 0, 33.3, 66.7 and 100: two of those
+     * are places the thumb cannot go. A mark the thumb can never sit on is the
+     * one thing a mark must not be, so the spacing gives way rather than the
+     * step, and marks may come out unevenly spaced when the two disagree. That
+     * is the honest picture of the range being offered.
+     */
+    markers: number;
+    /**
+     * Whether each mark says which value it stands at.
+     */
+    markerLabels: boolean;
+    /** How far one press of an arrow key moves it. */
+    step: number;
+    /**
+     * How many characters the readout has to be able to hold, widest case.
+     *
+     * **A number that grows a digit makes the track jump.** The output sizes to
+     * its text, so a range crossing 99 to 100 widens by a character and the row
+     * gives that width back out of the track: the handle moves while the value
+     * has not, which reads as the control drifting under the pointer. `3ch` was
+     * the floor and covers a plain value up to three digits, and a range says
+     * "35 to 100", which is ten.
+     *
+     * Widest rather than current, so the box never changes size at all. Measured
+     * off the bounds because that is what the readout can ever say: the longer of
+     * the two ends, twice, plus the four of " to " when both are shown. Negative
+     * bounds are covered by measuring the rendered string rather than the digits,
+     * since the sign is a character like any other.
+     *
+     * `tabular-nums` is on the part already and is the other half of this: equal
+     * digit widths keep a same-length number from shifting inside the box the
+     * same way a different-length one shifted the box.
+     */
+    private get reserve();
+    /**
+     * How many decimals the step is written to, so a label is not float noise.
+     *
+     * `min + index * step` on a fractional step prints `0.30000000000000004`,
+     * which is arithmetic being honest and a label being wrong. Rounding back to
+     * the step's own precision is what the reader asked for when they wrote it.
+     */
+    private get precision();
+    /**
+     * How far one press of an arrow key moves it.
+     */
+    private get markerValues();
+    /**
+     * The chosen value as a number, for anything doing arithmetic on it.
+     *
+     * @reference https://html.spec.whatwg.org/multipage/input.html#dom-input-valueasnumber HTMLInputElement.valueAsNumber
+     */
+    get valueAsNumber(): number;
+    /** Focus is delegated to the control, so the host is never the target. */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * The pair, as numbers, in order.
+     *
+     * Falls back to the whole range rather than to zero, so a range slider given
+     * no value opens fully wide instead of pinned shut at its own minimum, which
+     * is what a filter with nothing filtered out looks like.
+     */
+    private get bounds();
+    /** Where one value sits along the track, as a fraction of it. */
+    private along;
+    private readonly handleInput;
+    /** Relayed, because `change` does not cross a shadow boundary on its own. */
+    private readonly handleChange;
+    /** Reports the value. */
+    private sync;
+    /**
+     * How far along the track the thumb sits, as a fraction.
+     *
+     * Arithmetic rather than a measurement, because the browser already knows
+     * where it drew the handle and measuring it would be a guess at that.
+     *
+     * **Sanitized here, not read back off the control.** This asked the input for
+     * its value, on the reasoning that a range clamps and snaps whatever it is
+     * given, so the control is the truth about where the thumb is. The reasoning
+     * is right and the timing is not: `fraction` is evaluated inside `render()`,
+     * and the `style` binding carrying it is committed *before* the `.value`
+     * binding below it, so it read the value this very render was about to
+     * replace. The fill was a render behind the thumb, and on the first pass it
+     * read the seeded midpoint and stayed there.
+     *
+     * Measured on a slider from 0 to 1: after dragging to either end, the host's
+     * `value` was `1`, the control's was `1`, and `--slider-fraction` was still
+     * `0.5`. Off by half a track, and stable, which is what made it look like a
+     * drawing bug rather than a timing one.
+     *
+     * So the same two operations a range performs are done here: snap to the step
+     * from `min`, then clamp to the bounds. Nothing is read from the tree, so
+     * there is no order for this to be on the wrong side of.
+     */
+    private get fraction();
+    /**
+     * A value snapped to the step, counted from `min` the way a range counts it.
+     *
+     * `min` rather than zero is the whole of it: a slider from `0.2` with a step
+     * of `0.05` can land on `0.2`, `0.25` and so on, and snapping against zero
+     * would offer `0.2` and `0.25` too but round the ones between to the wrong
+     * side. `precision` is what keeps `0.30000000000000004` off the track, the
+     * same guard the marker labels already use.
+     */
+    private snapped;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Which way the track runs, `vertical` standing it on end.
+     *
+     * For a level rather than a quantity: a fader, a channel, anything a reader
+     * pictures as high and low rather than as less and more. Absent is
+     * horizontal, which is what almost every slider in a form wants.
+     *
+     * **A vertical track has no length of its own**, the way a horizontal one
+     * takes the width of the row it is in. `--slider-length` is that number and
+     * defaults to nine rem, so one dropped into a layout is a usable height
+     * rather than a thumb sitting on nothing.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-slider': HelixHeadlessSlider;
+    }
+}
+export {};