@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/radio/root/radio-root.js

@@ -7,119 +7,34 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, HelixSelectEvent } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary One choice in a radio group.
- *
- * @description
- * Renders a `<button role="radio">`, not an `<input type="radio">`, and the
- * reason is the shadow boundary rather than preference: native radios group by
- * sharing a `name` within a form, and a radio inside a shadow root cannot join
- * a group on the other side of it. The group is the form control here, so the
- * option only has to say what it is and announce when it is chosen.
- *
- * **It carries no label of its own.** A radio is named by the words beside it,
- * which is its own content, and the label, hint and message of the *set* belong
- * to the group. This is the one control in the family that takes nothing from
- * `MixinField`, because a lone radio is not a control: it is an answer to one.
- *
- * Selection is announced rather than applied. The item dispatches, the group
- * decides, and the group writes `selected` back. An item that set itself would
- * be a second source of truth for which one is on.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Option, Choice
- * @documentation https://helix.fusion.dev/components/radio
- *
- * @slot - The words naming this choice.
- * @slot icon - A mark shown beside them, or instead of them under
- * `appearance="chip"`, where the words become the accessible name and the mark
- * is what a reader picks between. Separate from the default slot because the
- * chip has to hide one and show the other, and they are both in the same place
- * otherwise.
- *
- * @event {HelixSelectEvent} helix-select - Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart box - The circle.
- * @csspart item - The button, which is the whole row.
- * @csspart label - The words beside it.
- * @csspart mark - The dot inside it.
- */
 let HelixHeadlessRadio = class HelixHeadlessRadio extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether this choice can be made.
-         */
         this.disabled = false;
-        /** What the markup said, read once at construction for the reason above. */
         this.seeded = this.hasAttribute('selected');
-        /**
-         * Whether this is the current choice.
-         *
-         * Written by the group.
-         */
         this.selected = false;
-        /**
-         * Identifies this choice to the group, and is what the form submits.
-         */
         this.value = '';
     }
-    /**
-     * Whether the markup declared this one chosen, which is what a reset returns to.
-     *
-     * `<option selected>` reflects to `defaultSelected` and `option.selected` is
-     * live state that does not reflect, and those are two different facts. This
-     * element has one `selected` doing both jobs, so what is captured here is what
-     * the markup said at upgrade, before anything could overwrite it: read the
-     * attribute later and the listbox's own writes answer instead.
-     *
-     * **The deeper half is not this.** State reflecting under the declaration's
-     * name is the fault `TreeItem` avoids by mirroring to `data-selected`.
-     * Splitting them means moving what every stylesheet selects on, which is a
-     * change of its own rather than a property being added.
-     */
     get defaultSelected() {
         return this.seeded;
     }
     set defaultSelected(next) {
         this.seeded = next;
     }
-    /** Moves focus to this choice, for the group's arrow keys. */
     focusItem() {
         this.renderRoot.querySelector('[part="item"]')?.focus();
     }
-    /** Makes this choice and announces it. */
     select() {
         if (this.disabled) {
             return;
         }
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
-    /**
-     * Mirrors the chosen state where a stylesheet can select on it.
-     *
-     * **A custom state rather than the `selected` attribute.** The parent writes
-     * this: a listbox choosing a row, a tab strip moving the tab, a radio group
-     * answering for its set. Reflected, that puts the element's own bookkeeping
-     * onto markup a consumer wrote and a consumer's server never sent, which
-     * React reconciles and reports as a mismatch, and which a serialized element
-     * pasted back declares as a choice nobody made. `ElementInternals` holds it
-     * instead, where it is not in the DOM at all.
-     *
-     * Reading `selected` is unaffected and so is writing it: the attribute still
-     * seeds the property, which is what `<helix-radio selected>` in a consumer's
-     * markup means. There is no write back.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('selected', this.selected);
     }
     render() {
-        /* Roving `tabindex`: one stop for the whole set, which is what a radio
-           group is in the tab order, and the arrow keys move within it. The group
-           owns the keys, because moving between items is a fact about the set. */
         return html `<button
       part="item"
       type="button"

package/dist/rating/root/rating-root.js

@@ -7,188 +7,29 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { valueAsNumber as asNumber, customElement, numberAsValue as fromNumber, HelixFormElement, KeyboardNavigationController, MixinControllerValue, MixinField, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * @summary A score out of a few marks, given or shown.
- *
- * @description
- * **Half marks decide the shape.** Supporting them means the value is not an
- * integer and the targets are not the marks: five stars at a half step is ten
- * places to press, and a mark that is filled to the middle. The pointer handling
- * and `step` are both built around that rather than added over it.
- *
- * **A partial mark is the whole mark, clipped.** Not a second glyph filled to
- * the middle: that needs a matching pair drawn for every mark anybody uses, and
- * the moment a consumer wants a heart or a circle they need to draw one too. The
- * fill is the same marks over the same marks, cut off partway, so any mark works
- * and any fraction does.
- *
- * **Read-only is not this control grayed out, it is a different thing.** The
- * commoner use is showing a score nobody is being asked for, a product's
- * average, and that is not a control at all: it takes no focus, answers no keys,
- * has no options to choose between, and reads as one thing rather than as five.
- * So `readonly` is `role="img"` with the score in its name, where the control is
- * a radio group. A disabled control is still a control and still says so; this
- * is not one.
- *
- * **Moving is choosing here**, which is the radio group's reading and the
- * opposite of `Menu`'s: arriving at four stars *is* rating it four, because
- * nothing else follows and there is nothing to confirm. That is what
- * `KeyboardNavigationController` takes `selects` for, and why this can use it
- * where a menu cannot.
- *
- * **The mark is a stylesheet's, not a slot's.** A slot projects its content
- * once, and there are two layers of marks here: slotting a star would put it in
- * the track or the fill and leave the other empty. So the mark is a shape the
- * styled tier masks with, which is also what lets a partial one be a clip of the
- * whole rather than a second drawing of it.
- *
- * 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 Stars, Score, Review score
- * @documentation https://helix.fusion.dev/components/rating
- *
- * @event {Event} change - Announced with it, the choice being the commit.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the score changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
- *
- * @csspart feedback - What is wrong with it.
- * @csspart fill - The filled marks, clipped to the score.
- * @csspart hint - Help under the marks, while nothing is wrong.
- * @csspart label - The question, over the marks.
- * @csspart mark - One mark, in either layer.
- * @csspart marks - The row of marks.
- * @csspart option - One place a reader can press, which is one step.
- * @csspart track - The unfilled marks.
- * @csspart value - The score written out, under `show-value`.
- *
- * @cssproperty --rating-full - How many marks are wholly filled.
- * @cssproperty --rating-part - How much of the next mark is filled, 0 to 1.
- * @cssproperty --rating-step - The width of one step, as a fraction of a mark.
- * @cssproperty --rating-steps - How many steps one mark is divided into.
- */
 let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
-        /*
-         * Discrete. `Input`, `Slider`, `NumberInput`, `Textarea` and `PinInput` all
-         * announce input, and every one of them is edited continuously: a value passes
-         * through every keystroke or pixel on its way to the one meant. A rating does
-         * not. A press picks a score, an arrow picks the next one, and the drag
-         * deliberately asks for nothing until it is let go, so there is exactly one
-         * value and it is the chosen one. That is `helix-before-change`, the same as
-         * the radio group this announces itself as.
-         */
         this.announcesInput = false;
-        /**
-         * How many marks there are.
-         */
         this.max = 5;
-        /**
-         * The lowest score a reader can give, which is what clearing returns to.
-         *
-         * Zero rather than one, because "no rating" and "the worst rating" are
-         * different answers and a control that cannot express the first has to
-         * pretend the second. A survey that requires an answer says so with
-         * `required`, not by making one unreachable.
-         */
         this.min = 0;
-        /**
-         * Whether this shows a score rather than asks for one.
-         *
-         * A readout is not a control that has been switched off. It takes no focus,
-         * answers no keys, and reads as one thing: see the note on the class.
-         */
         this.readOnly = false;
-        /**
-         * Whether the score is written out beside the marks.
-         *
-         * Marks say roughly, and a number says exactly. Four and a bit stars is not a
-         * reading anyone can repeat, which is why a product's average is nearly always
-         * printed next to them. `Meter` spells its reading the same way and under the
-         * same attribute.
-         *
-         * It follows the pointer, because it labels what the marks are showing rather
-         * than what the form holds: a label that disagreed with the marks under the
-         * reader's own cursor would be worse than no label.
-         */
         this.showValue = false;
-        /**
-         * The smallest part of a mark that can be chosen.
-         *
-         * `0.5` is the half star, and it is the reason the value is a number rather
-         * than an index: with halves, five marks are ten answers.
-         */
         this.step = 1;
-        /**
-         * How the score is read out, where "3.5 out of 5" is not what it should say.
-         *
-         * A rating out of five is one of the few places a screen reader gets a worse
-         * answer from the value than from a sentence: "3.5" alone is a number without
-         * a subject. This names the readout, where a control is named by its `label`
-         * and each of its options by the score that option is.
-         */
         this.valueText = '';
-        /**
-         * The shape a consumer slotted, if they slotted one.
-         *
-         * Read rather than projected. A `<slot>` shows its content once and a rating
-         * needs the shape as many times as there are marks, twice over because there
-         * are two layers, so the slot here is a way of being handed the shape rather
-         * than a place the shape is drawn. What is handed over gets cloned into every
-         * position.
-         *
-         * **One shape, not one per position.** A rating is a quantity of identical
-         * marks and the fill is a clip across all of them, so a row whose third mark
-         * is a different drawing from its first is not a rating: it is a set of
-         * choices, which is `Radio.Group` and already carries a value and a name on
-         * each of its own options. Anything past the first slotted element is
-         * ignored.
-         */
         this.markSource = undefined;
-        /**
-         * What the pointer is over, which is shown instead of the score while it is.
-         */
         this.previewing = undefined;
-        /* The radio group's reading, and `selects` is what makes it one: arriving at
-           a mark rates it. `Menu` passes false to the same option for the opposite
-           reason, which is the whole of the difference between a set of choices and a
-           set of commands. */
         this.keys = new KeyboardNavigationController(this, {
             items: () => this.options,
             selects: () => true,
             wrap: false,
         });
-        /** The pointer drawing a score, while one is. */
         this.dragging = undefined;
-        /**
-         * One clone per place a mark goes, kept so a render does not remake them.
-         *
-         * A drag renders on every pointer move, and handing Lit a fresh node each
-         * time would swap every mark in the row on every frame of a gesture whose
-         * whole point is that only the fill moves.
-         */
         this.clones = new Map();
         this.handleMarkSlot = (event) => {
             this.clones.clear();
             this.markSource = event.target.assignedElements({ flatten: true })[0];
         };
-        /**
-         * Dragging across the marks draws a score, and letting go chooses it.
-         *
-         * One press and a slide is how a rating is given on a phone, and on a desktop
-         * it is how somebody who overshoots corrects without lifting. Pointer capture
-         * is what makes it one gesture: without it the events go to whichever target
-         * the pointer crossed into, and a drag that leaves the row stops reporting.
-         *
-         * Nothing is chosen until release, so a drag that ends back where it started,
-         * or off the element entirely, has asked for nothing.
-         */
         this.handleDragStart = (event) => {
             if (this.isDisabled || this.readOnly || event.button !== 0) {
                 return;
@@ -202,9 +43,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
                 event.currentTarget.setPointerCapture(event.pointerId);
             }
             catch {
-                /* A synthesized pointer has no capture to take, and the drag works
-                   without it right up until the pointer leaves the row. Worth having the
-                   gesture testable rather than making the specs drive a real device. */
             }
             this.dragging = event.pointerId;
             this.previewing = Number.parseFloat(score);
@@ -229,8 +67,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
                 this.requestValue(score);
             }
         };
-        /* A canceled pointer is the system taking the gesture away, which is not the
-           reader choosing. Put the marks back to the value they already held. */
         this.handleDragCancel = (event) => {
             if (this.dragging !== event.pointerId) {
                 return;
@@ -253,7 +89,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
             this.previewing = undefined;
         };
     }
-    /** The score, as a number, clamped to what the marks can show. */
     get score() {
         const parsed = Number.parseFloat(this.value);
         if (!Number.isFinite(parsed)) {
@@ -261,19 +96,10 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         }
         return Math.min(Math.max(parsed, 0), this.max);
     }
-    /** Every score a reader can choose, which is `max / step` of them. */
     get steps() {
         const count = Math.max(1, Math.round(this.max / this.step));
         return Array.from({ length: count }, (_, index) => Number(((index + 1) * this.step).toFixed(2)));
     }
-    /**
-     * The options, as the shared controller wants them.
-     *
-     * Adapters rather than elements, because these are buttons this element drew
-     * rather than a consumer's custom elements: the interface asks for five
-     * things and a `<button>` in a shadow root can answer all five without being
-     * dressed up as a component to do it.
-     */
     get options() {
         const found = [...(this.renderRoot?.querySelectorAll('[part="option"]') ?? [])];
         return found.map((element) => ({
@@ -286,7 +112,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
             selected: element.getAttribute('aria-checked') === 'true',
         }));
     }
-    /** The shape for one place, or nothing when the stylesheet is drawing it. */
     markFor(layer, index) {
         if (!this.markSource) {
             return undefined;
@@ -300,18 +125,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         this.clones.set(key, clone);
         return clone;
     }
-    /**
-     * The step under a point on the row, or the nearest one to it.
-     *
-     * Asked of the boxes rather than worked out from `max` and `step`, because
-     * where a step sits is the stylesheet's arithmetic and this would be a second
-     * copy of it that could disagree. The browser has already laid the targets
-     * out; this reads them back.
-     *
-     * Nearest rather than only a hit, so a drag that runs off the end of the row
-     * pins to the last mark instead of stopping at whatever it last touched, and
-     * a pointer in the half-gap outside the first mark still answers.
-     */
     scoreAt(clientX) {
         let nearest;
         let best = Number.POSITIVE_INFINITY;
@@ -328,23 +141,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         }
         return nearest;
     }
-    /**
-     * Reports the value, and whether the form may go without one.
-     *
-     * **`required` arrives from the mixin, so it prints on the reference page
-     * whether or not anything here enforces it.** Without a `setValidity` call a
-     * form holding an unrated required rating submits, `:valid` true and the
-     * entry present but empty. `reportRequired` is what makes the property real.
-     *
-     * **Empty is `value === ''` rather than a score of zero**, because zero is a
-     * rating a reader can deliberately give when `min` allows it, and refusing to
-     * submit it would be the control disagreeing with the property that permits
-     * it. What `required` asks is whether they answered at all.
-     *
-     * `Slider` is deliberately not given the same treatment: a native
-     * `<input type="range" required>` is always valid, because a range always
-     * holds a number, and matching the platform there is the point.
-     */
     sync() {
         this.internals.setFormValue(this.value);
         this.reportRequired(this.value === '', 'Choose a rating to continue.', 'marks');
@@ -359,8 +155,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
     }
     updated(changed) {
         super.updated?.(changed);
-        // Every update, not only the ones that name `value`: see the note on
-        // `ColorInput.updated`.
         this.sync();
     }
     firstUpdated(changed) {
@@ -373,13 +167,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         const count = Math.max(0, Math.round(this.max));
         const first = this.steps[0];
         const mark = (layer, index) => html `<span part="mark">${this.markFor(layer, index)}</span>`;
-        /* Both layers hold every mark, because the fill is a clip of the whole row
-           rather than a count of the filled ones.
-         
-           Written out twice rather than through one helper taking the part name:
-           a part is read from the source as a literal, and a `part=${name}`
-           binding is invisible. The stylesheet's `[part="track"]` and
-           `[part="fill"]` read as dead. */
         const marksIn = (layer) => Array.from({ length: count }, (_, index) => mark(layer, index));
         return html `<div
       part="marks"
@@ -433,13 +220,6 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         >`
             : nothing}`;
     }
-    /**
-     * 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() {
         return asNumber(this.value);
     }

package/dist/scroll-area/root/scroll-area-root.js

@@ -7,69 +7,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/** Which edges have something past them, as a set of tokens. */
 const EDGES = ['block-start', 'block-end', 'inline-start', 'inline-end'];
-/**
- * @summary A scrolling box that says there is more.
- *
- * @description
- * **The whole component is one fact a stylesheet cannot work out for itself:
- * which edges have content past them.** A fade at the bottom of a list is easy
- * to draw and impossible to decide, because CSS has no reading of scroll
- * position. So this measures and says, in a custom state per edge, and the
- * styled tier draws whatever it likes on the edges named.
- *
- * **States rather than attributes**, so an element that upgrades after a
- * framework rendered its markup does not hand that framework markup it did not
- * write. A stylesheet asks `:host(:state(more-block-end))`.
- *
- * **A scrolling region takes the keyboard when it scrolls, and not before.**
- * A box a reader can only reach with a pointer is a box some readers cannot
- * read at all, which is what `tabindex` answers here. Only while it overflows:
- * a tab stop on a box with nothing to scroll is a stop that does nothing, and a
- * form full of them is worse than the problem.
- *
- * `role="region"` only with a `label`, because an unnamed region is an
- * announcement with no content: a screen reader says "region" and the reader
- * has learned nothing they did not already know.
- *
- * @since 0.1.0
- * @status stable
- * @category layout
- * @aliases Scroller, Overflow, Scroll container
- * @documentation https://helix.fusion.dev/components/scroll-area
- *
- * @slot - What scrolls.
- *
- * @csspart edges - Where the sideways edge cues are drawn.
- * @csspart viewport - The scrolling box.
- */
 let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Names the region, for a reader arriving at it out of context.
-         *
-         * Without one there is no region: see the note on the class.
-         */
         this.label = '';
-        /**
-         * Which edges have content past them, measured rather than guessed.
-         */
         this.more = [];
-        /**
-         * Whether there is anything to scroll at all, which decides the tab stop.
-         */
         this.scrolls = false;
-        /**
-         * Reads the four edges off the box.
-         *
-         * A pixel of slack on each, because a scroller at its end is routinely a
-         * fraction short of it: browsers round scroll positions differently under
-         * zoom and on a display that is not at one to one, and a fade that never
-         * quite goes out at the bottom of a fully scrolled list is the bug that
-         * costs.
-         */
         this.measure = () => {
             const box = this.scroller;
             if (!box) {
@@ -100,35 +44,12 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
             this.measure();
         };
     }
-    /**
-     * The box that actually scrolls, for anything that needs to move it.
-     *
-     * **Public because the alternative is silence.** The scrolling box is inside
-     * this shadow root: a consumer holding a reference to this element holds the
-     * host, which does not scroll, and `scrollBy` on it is a no-op that reports
-     * nothing. That is how `scrollItemIntoView`'s `offsetParent` default fails
-     * here.
-     *
-     * The element rather than a method of our own, because the utilities that
-     * want it already take one.
-     */
     get scroller() {
         return this.renderRoot?.querySelector('[part="viewport"]') ?? null;
     }
     connectedCallback() {
         super.connectedCallback();
-        /* Both the box and what is in it. The box changing size is a layout change
-           and the content changing size is a data change, and a fade that only
-           answered one of them was wrong every time a list was filtered. */
         this.watcher = new ResizeObserver(this.measure);
-        /* And what it watches, which rebuilding the observer does not restore. A
-         * fresh observer watches nothing until something calls `observe`, so a
-         * scroll area moved in the DOM comes back registered on no targets: the
-         * fades stop answering a resize or a filtered list, and the component goes
-         * on rendering.
-         *
-         * Guarded on `hasUpdated`, because the first connection happens before the
-         * first render and there is no scroller to find yet. */
         if (this.hasUpdated) {
             this.watchContent();
         }
@@ -143,7 +64,6 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
         this.watchContent();
         this.measure();
     }
-    /** Registers the box and everything slotted into it, which is what resizes. */
     watchContent() {
         const box = this.scroller;
         if (!box || !this.watcher) {
@@ -158,26 +78,6 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     }
     updated(changed) {
         super.updated?.(changed);
-        /* On the host rather than the viewport, so a consumer can style from the
-           outside without reaching through a part.
-    
-           **Custom states and never attributes, which is what keeps hydration
-           clean.** These are a reading of a laid-out box, so they are written on
-           upgrade, and upgrade happens before a framework hydrates the subtree
-           around it. Written as attributes they are markup on the host that the
-           framework did not render: React reported a hydration mismatch naming
-           `data-scrolls` and `data-more` on every load of a page holding one.
-           `states` is not in the DOM at all, so this element may upgrade whenever it
-           likes and a framework finds the markup it rendered. That is the rule the
-           rest of the library already keeps, `app-header`'s `scrolled` being the
-           clearest statement of it.
-    
-           One state per edge rather than one holding tokens, because a custom state
-           is a name and not a value: there is no `~=` to ask with. The four
-           selectors are what the styled tier writes either way. */
-        /* Through `toggleState` for the feature test it carries. This is `updated`
-           rather than `willUpdate`, so the server never reaches it, but Safari
-           below 17.4 and Firefox below 126 do and have no `CustomStateSet`. */
         this.toggleState('scrolls', this.scrolls);
         for (const edge of EDGES) {
             this.toggleState(`more-${edge}`, this.more.includes(edge));