@fusion.dev/helix-headless 0.0.0-dev

package/dist/slider/root/slider-root.js

@@ -0,0 +1,488 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { AriaForwardController, customElement, HelixFormElement, MixinControllerValue, MixinField, restoreValue, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+/**
+ * @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.
+ */
+let HelixHeadlessSlider = class HelixHeadlessSlider extends MixinControllerValue(MixinField(HelixFormElement)) {
+    constructor() {
+        super(...arguments);
+        /* A consumer's `aria-describedby` names ids in their own tree and the control
+           is in this shadow root, so the reference has to be carried down as an
+           element rather than copied as an id. See `AriaForwardController`: measured
+           in Chrome's own tree, the host held the description and the control the
+           reader is actually on was exposed without it. */
+        this.aria = new AriaForwardController(this, {
+            target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
+        });
+        /** Typed or dragged, so every edit is announced. See `announcesInput`. */
+        this.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.
+         */
+        this.range = false;
+        /**
+         * The largest value the reader can choose.
+         */
+        this.max = 100;
+        /**
+         * The smallest value the reader can choose.
+         */
+        this.min = 0;
+        /**
+         * Whether the chosen value is shown beside the track.
+         */
+        this.showValue = false;
+        /**
+         * 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.
+         */
+        this.markers = 0;
+        /**
+         * Whether each mark says which value it stands at.
+         */
+        this.markerLabels = false;
+        /** How far one press of an arrow key moves it. */
+        this.step = 1;
+        this.handleInput = (event) => {
+            // Stopped for the reason `Input.handleInput` gives: the inner control's own
+            // `input` is composed and would reach a consumer beside this element's.
+            event.stopPropagation();
+            const control = event.target;
+            if (this.range) {
+                const [start, end] = this.bounds;
+                const moved = Number(control.value);
+                /* Clamped against the other thumb rather than bounded by it, for the
+                   reason the class says: bounding shortens the input's own range and the
+                   two thumbs stop sharing a track. */
+                const pair = control.dataset.thumb === 'start'
+                    ? [Math.min(moved, end), end]
+                    : [start, Math.max(moved, start)];
+                this.requestValue(pair.join(','));
+                restoreValue(control, String(control.dataset.thumb === 'start' ? this.bounds[0] : this.bounds[1]));
+                return;
+            }
+            const next = control.value;
+            /* Through the mixin, like the other native-backed controls. The thumb has
+               already moved either way, so wherever the answer does not follow it has
+               to be put back: a refusal and a consumer who owns the value are the same
+               situation seen from here. */
+            this.requestValue(next);
+            restoreValue(control, this.value);
+        };
+        /** Relayed, because `change` does not cross a shadow boundary on its own. */
+        this.handleChange = (event) => {
+            event.stopPropagation();
+            this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
+        };
+    }
+    /**
+     * 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.
+     */
+    get reserve() {
+        const widest = Math.max(String(this.min).length, String(this.max).length);
+        return this.range ? widest * 2 + ' to '.length : widest;
+    }
+    /**
+     * 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.
+     */
+    get precision() {
+        return String(this.step).split('.')[1]?.length ?? 0;
+    }
+    /**
+     * How far one press of an arrow key moves it.
+     */
+    get markerValues() {
+        const span = this.max - this.min;
+        if (this.markers < 2 || span <= 0) {
+            return [];
+        }
+        const step = this.step > 0 ? this.step : 1;
+        const snapped = Array.from({ length: this.markers }, (_, at) => {
+            const raw = this.min + (at / (this.markers - 1)) * span;
+            const snappedAt = Math.min(this.max, Math.max(this.min, this.min + Math.round((raw - this.min) / step) * step));
+            // Back to the step's own precision, or a fractional step prints
+            // `0.30000000000000004` on a marker label.
+            return Number(snappedAt.toFixed(this.precision));
+        });
+        return [...new Set(snapped)];
+    }
+    /**
+     * 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() {
+        const parsed = Number.parseFloat(this.value);
+        return Number.isNaN(parsed) ? this.min : parsed;
+    }
+    /** Focus is delegated to the control, so the host is never the target. */
+    static { this.shadowRootOptions = {
+        ...HelixFormElement.shadowRootOptions,
+        delegatesFocus: true,
+    }; }
+    /**
+     * 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.
+     */
+    get bounds() {
+        /* A lone number is not a range, so it is not read as one.
+         *
+         * An untouched range slider does not hold an empty string: the native input
+         * reports its own midpoint and the mixin takes it, so `value` came back as
+         * "50" on a slider from 10 to 90 and reading that as the lower thumb put a
+         * filter half shut before anyone touched it. Only a pair is a pair, and
+         * anything else opens fully wide, which is what "nothing filtered out"
+         * looks like. */
+        const parts = this.value.split(',');
+        const from = Number.parseFloat(parts[0] ?? '');
+        const to = Number.parseFloat(parts[1] ?? '');
+        if (!Number.isFinite(from) || !Number.isFinite(to)) {
+            return [this.min, this.max];
+        }
+        return [Math.min(from, to), Math.max(from, to)];
+    }
+    /** Where one value sits along the track, as a fraction of it. */
+    along(at) {
+        const span = this.max - this.min;
+        if (span === 0) {
+            return 0;
+        }
+        return Math.min(1, Math.max(0, (at - this.min) / span));
+    }
+    /** Reports the value. */
+    sync() {
+        this.internals.setFormValue(this.value);
+        this.refreshFeedback();
+    }
+    /**
+     * 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.
+     */
+    get fraction() {
+        const span = this.max - this.min;
+        if (span === 0) {
+            return 0;
+        }
+        return this.along(this.snapped(this.valueAsNumber));
+    }
+    /**
+     * 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.
+     */
+    snapped(at) {
+        if (!(this.step > 0)) {
+            return at;
+        }
+        const steps = Math.round((at - this.min) / this.step);
+        return Number((this.min + steps * this.step).toFixed(this.precision));
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        /* A range with no value starts in the middle, which is the platform's own
+           rule and is what the control will show whether or not this agrees. Seeded
+           here so the value the form would submit matches the thumb from the first
+           render rather than from the first drag. */
+        if (!this.hasUpdated && this.value === '') {
+            /* Onto `defaultValue`, never onto `value`. Writing `value` is how a
+               consumer says they own it, so seeding through it would have made every
+               range with no value controlled on its first render and frozen the thumb
+               where it started. `defaultValue` is where the markup's intent lives,
+               and "no value given" is exactly a fact about the markup. */
+            this.defaultValue = String(this.min + (this.max - this.min) / 2);
+        }
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.sync();
+    }
+    render() {
+        /* The range's bounds are written before its value below, and that order is
+           the whole of this element's correctness on a wide scale. Lit commits
+           bindings in template order, and a range clamps whatever is assigned to the
+           bounds it holds at that moment: with the value first, a slider from 0 to
+           360 given 225 took the default max of 100, clamped to 100, and drew its
+           handle at 100/360.
+       *
+       * Found on Color Input's hue channel, where the handle sat at 28 per cent of a
+       * track whose fill said 62.5. The two disagreed because they are computed from
+       * different things: the fill is arithmetic on this element's property, and the
+       * handle is the platform's reading of the input's own clamped value. Every
+       * slider with a max above 100 had it, and the fill being right is what made it
+       * read as a drawing bug rather than a value one. */
+        const [start, end] = this.bounds;
+        /* One input per thumb, each spanning the whole range so both read against
+           the same track. The lower one paints the fill and the upper one's track
+           is transparent, because two stacked tracks would paint the ramp twice. */
+        /* **The lower thumb answers to `control`, and it has to answer to
+           something.** `MixinField.renderLabel` writes `<label for="control">` for
+           every field in the library, and only the single-thumb branch below ever
+           rendered that id: a range slider therefore shipped a label pointing at
+           nothing, so pressing the words focused no thumb and the `<output for>`
+           beside it named a missing element too. It was the only unresolved IDREF
+           in the whole corpus, which is the shape this class of fault takes, valid
+           markup that reaches nothing and says nothing.
+    
+           The lower one, because a label forwards a press to the first control it
+           names and the reader expects the start of the range. The upper takes
+           `control-end`, which is what the readout lists alongside it. */
+        const thumb = (which, at) => html `<input
+        part="control"
+        id=${which === 'start' ? 'control' : 'control-end'}
+        data-thumb=${which}
+        type="range"
+        style="--slider-from: ${this.along(start)}; --slider-to: ${this.along(end)}"
+        min=${this.min}
+        max=${this.max}
+        step=${this.step}
+        .value=${String(at)}
+        aria-label=${`${this.label} ${which === 'start' ? 'minimum' : 'maximum'}`}
+        aria-describedby=${this.describedBy ?? nothing}
+        ?disabled=${this.isDisabled}
+        @input=${this.handleInput}
+        @change=${this.handleChange}
+      />`;
+        /* `data-markers` mirrors "there are marks" for the stylesheet.
+         *
+         * The whole marker layout hung off `:host([markers])` and `markers` does
+         * not reflect, so `slider.markers = 5` drew nothing at all: only the
+         * attribute written in the markup ever worked, and the property that is the
+         * documented API silently did not.
+         *
+         * Reflecting the count instead would put `markers="0"` on every slider, an
+         * attribute the server's markup does not have and one that selector would
+         * match, drawing the layout for no marks. So the boolean fact is mirrored
+         * to a `data-` name, which is the rule this library already follows for
+         * state: the stylesheet wants to know whether there are marks, not how
+         * many. How many is what `markerValues` answers, and `< 2` is where it
+         * already draws the line.
+         *
+         * A `/*` and written here, because it describes this binding and not a
+         * member. As a `/**` above `markerLabels` it never closed, so it swallowed
+         * that property's one-line description and the manifest shipped this whole
+         * argument as the text for "whether each mark says which value it stands
+         * at". `check:orphans` cannot see an unclosed block, only one sitting on
+         * another. */
+        return html `${this.renderLabel()}
+    <div
+      part="field"
+      data-markers=${this.markerValues.length > 0 ? '' : nothing}
+      data-range=${this.range ? '' : nothing}
+      style="--slider-fraction: ${this.fraction}; --slider-from: ${this.along(start)}; --slider-to: ${this.along(end)}"
+    >
+      ${this.range ? thumb('start', start) : nothing}
+      ${this.range ? thumb('end', end) : nothing}
+      ${this.range
+            ? nothing
+            : html `<input
+              part="control"
+              id="control"
+              type="range"
+              style="--slider-fraction: ${this.fraction}"
+              min=${this.min}
+              max=${this.max}
+              step=${this.step}
+              .value=${this.value}
+              name=${this.name || nothing}
+              aria-describedby=${this.describedBy ?? nothing}
+              ?disabled=${this.isDisabled}
+              @input=${this.handleInput}
+              @change=${this.handleChange}
+            />`}
+      ${this.markers > 1
+            ? html `<div part="markers" aria-hidden="true">
+              ${this.markerValues.map((at) => html `<span
+                    part="marker"
+                    style="--slider-marker-at: ${((at - this.min) / (this.max - this.min)) * 100}%"
+                    >${this.markerLabels ? html `<span part="marker-label">${at}</span>` : nothing}</span
+                  >`)}
+            </div>`
+            : nothing}
+      ${
+        /* Hidden from the accessibility tree, like the markers above it.
+         *
+         * A bare `<output>` maps to `role="status"` with an implicit polite
+         * live region, so every intermediate value during a drag was announced
+         * on top of the range's own value announcement: a reader dragging from
+         * 10 to 60 heard both twice, fifty times. It repeats what the control
+         * already reports, which is the definition of decoration. */
+        this.showValue
+            ? html `<output
+              part="output"
+              for=${this.range ? 'control control-end' : 'control'}
+              aria-hidden="true"
+              style=${`--_slider-output-reserve: ${this.reserve}ch`}
+              >${this.range ? `${start} to ${end}` : this.value}</output
+            >`
+            : nothing}
+    </div>
+    ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessSlider.prototype, "range", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessSlider.prototype, "max", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessSlider.prototype, "min", void 0);
+__decorate([
+    property({ attribute: 'show-value', reflect: true, type: Boolean })
+], HelixHeadlessSlider.prototype, "showValue", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessSlider.prototype, "markers", void 0);
+__decorate([
+    property({ attribute: 'marker-labels', reflect: true, type: Boolean })
+], HelixHeadlessSlider.prototype, "markerLabels", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessSlider.prototype, "step", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessSlider.prototype, "orientation", void 0);
+HelixHeadlessSlider = __decorate([
+    customElement('helix-headless-slider')
+], HelixHeadlessSlider);
+export { HelixHeadlessSlider };

package/dist/sparkline/index.d.ts

@@ -0,0 +1 @@
+export * from './root/sparkline-root.js';

package/dist/sparkline/index.js

@@ -0,0 +1 @@
+export * from './root/sparkline-root.js';

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

@@ -0,0 +1,147 @@
+import { type Curve, HelixElement, SourceController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A line with no axes, for the shape of a series beside the number it belongs to.
+ *
+ * @description
+ * The one chart here that takes its numbers from an attribute, and the reversal
+ * is deliberate. Every other chart reads a table because a reader might want to
+ * interrogate it; nobody interrogates the squiggle next to a figure. A
+ * fourteen-row table behind a bare trend line is fourteen dates read aloud in
+ * place of the one sentence that carries the meaning, so `values` is the list
+ * and `label` is the sentence.
+ *
+ * That is the library's own rule rather than a second data channel: a content
+ * property is its slot's fallback, which is why `Tooltip` takes `content` and
+ * `Avatar` takes `name`. `for` stays for the sparkline that genuinely has a
+ * table behind it, and it wins where both are given.
+ *
+ * **No label means decorative, and that is a choice rather than an oversight.**
+ * A sparkline beside a stat that already says "Sessions, 1,102" has nothing of
+ * its own to announce, and an unnamed `role="img"` announces "graphic" and
+ * stops. So an unlabelled sparkline is `aria-hidden`, and a labeled one is an
+ * image named by its sentence.
+ *
+ * It goes *beside* a `Stat` rather than inside one. The plan this was built
+ * from called for a `trend` slot on `Stat`; the spec already on `Stat` says the
+ * opposite, that a change beside a figure is a second fact, and the spec is
+ * right. `Trend` composes the same way.
+ *
+ * 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 charts
+ * @aliases Micro Chart, Trend Line, Inline Chart
+ * @documentation https://helix.fusion.dev/components/sparkline
+ *
+ * @csspart area - The region between the line and the bottom of its range.
+ * @csspart bar - One column, under `plot="bar"`.
+ * @csspart line - The path itself.
+ * @csspart svg - The drawing.
+ * @csspart terminus - The mark on the last value.
+ * @csspart wash-end - The far stop of the area's gradient.
+ * @csspart wash-start - The stop of the area's gradient that meets the line.
+ *
+ * @cssproperty --chart-terminus-x - Where the last point sits horizontally, as a percentage.
+ * @cssproperty --chart-terminus-y - Where the last point sits vertically, as a percentage.
+ */
+export declare class HelixHeadlessSparkline extends HelixElement {
+    #private;
+    /**
+     * What the readings are drawn as.
+     *
+     * Absent is a line, `area` is a line with the region beneath it washed, and
+     * `bar` is a column per reading.
+     *
+     * **A bar plot measures from zero and the other two measure from the data's
+     * own range**, which is the one way the plots are not interchangeable. A line
+     * says where the readings sit relative to each other, so a scale over their
+     * extent uses the whole box and claims nothing about absolute size. A bar's
+     * length *is* the value, so any baseline but zero makes the lengths
+     * proportional to nothing.
+     *
+     * **Which is a reason to prefer a line for readings in a narrow band far from
+     * zero.** Seven values between 1,102 and 1,408 drawn as columns from zero are
+     * seven columns of nearly the same height, and that is the true picture: they
+     * *are* nearly the same. The same readings as a line fill the box and show
+     * the movement, because a line is only ever claiming a shape.
+     *
+     * **Absent is `area`**, which is the departure from the rule that a resting
+     * arrangement is the plainest thing. At the size a sparkline is actually
+     * drawn, a hairline in a wide box is mostly box: the wash under it is what
+     * gives the shape a body and lets a reader see it at a glance rather than
+     * hunting for it, which is the entire job. `line` is the bare stroke for
+     * anywhere the fill would be noise, several of them in one box for instance.
+     *
+     * This tier rather than the one above: a plot type is geometry and geometry
+     * is markup, the same reason `curve` lives here.
+     */
+    plot?: 'area' | 'bar' | 'line';
+    /**
+     * How the line gets from one reading to the next.
+     *
+     * **`smooth` is the resting curve.** *Changed 21 Aug 2026, reversing the
+     * argument this comment used to make.* It read that joining the readings
+     * claims nothing in between and is the default for that reason, which is true
+     * and is why `straight` still exists: a straight segment asserts nothing about
+     * the values between two readings, and a curve invents them.
+     *
+     * What settles it the other way is that the invention is bounded. The
+     * interpolation is monotone cubic, so it never leaves the band the data sets
+     * and never introduces a peak or a trough the series does not have. Within
+     * that bound the smoothed line is the easier one to follow across a long
+     * series, which is what the drawing is for. `straight` becomes the claim a
+     * consumer makes deliberately rather than the one they get by saying nothing.
+     *
+     * **The property stays optional and the default lives in the render.** A
+     * reflecting property with a default writes its attribute onto every host
+     * anybody renders, including the ones nobody configured, which the SSR specs
+     * assert against. So the resting state is still the attribute's absence, and
+     * `curve ?? 'smooth'` is what reads it.
+     *
+     * `step` claims the opposite of both, that a reading holds until the next.
+     * Bars ignore it, having no between to interpolate.
+     */
+    curve?: Curve;
+    /**
+     * The id of a table to read instead, when there is one behind the line.
+     *
+     * The first column of numbers is the series drawn. This wins over `values`,
+     * because a table is the readable representation and a list of numbers in an
+     * attribute is not.
+     *
+     * **In React this arrives as a property and not as an attribute**, the way
+     * `Tooltip.for` does, so it does not reflect and nothing styles on it.
+     */
+    for: string;
+    /**
+     * What the line says, in a sentence.
+     *
+     * "Sessions rose from 1,240 to 1,318 and fell to 1,102 over fourteen days" is
+     * the accessible representation of a sparkline, and a list of the fourteen
+     * numbers is not. Absent, the drawing is hidden from a screen reader rather
+     * than announced without a name.
+     */
+    label: string;
+    /**
+     * The numbers, separated by whitespace or by commas.
+     *
+     * Both separators, so `values="1240 1318"` and an array assigned to the
+     * property both work: assigning `[1240, 1318]` stringifies to `1240,1318`,
+     * and a string is what survives React's hydration where an array property
+     * does not.
+     */
+    values: string;
+    protected readonly source: SourceController;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-sparkline': HelixHeadlessSparkline;
+    }
+}