@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/notifications/root/notifications-root.js

@@ -7,127 +7,33 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, HelixReadEvent, hostAria, MixinCollection, slotFilled, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A feed a reader comes back to, made of notifications they may not have seen.
- *
- * @description
- * **Slotted children rather than a data property.** A notification is a small
- * piece of somebody's own markup, with an avatar and a link and a button in it,
- * and there are tens of them rather than thousands, so writing them out lets an
- * item hold anything.
- *
- * **This does not virtualize, and it cannot.** Windowing needs the list to own
- * the data, and here the consumer owns it: N notifications is N elements by
- * construction. A feed that really does hold thousands wants a data table with a
- * custom cell, and this component will not grow into one.
- *
- * **Read state is reported, never invented.** Marking read is usually a round
- * trip: this element asks its items and each item asks the consumer, so a
- * refused `helix-read` leaves everything alone and a consumer who owns `read`
- * sees nothing change until they say so. `unread` is derived from the items and
- * written to an attribute, so a stylesheet and a badge can both read it without
- * either of them counting.
- *
- * @since 0.1.0
- * @status experimental
- * @category feedback
- * @aliases Notification feed, Inbox, Activity
- * @documentation https://helix.fusion.dev/components/notifications
- *
- * @slot - The notifications, as `helix-notification` children.
- * @slot footer - Below the list, for a link to everything.
- * @slot header - Above the list, for a title and the mark-all control.
- *
- * @event {HelixReadEvent} helix-read - Fired by an item, and by this element when everything is marked read. Cancelable.
- *
- * @csspart empty - Shown when there is nothing in the feed.
- * @csspart footer - The region below the list.
- * @csspart header - The region above the list.
- * @csspart list - The list itself.
- * @csspart loading - Shown while the feed is still on its way.
- * @csspart mark-all - The control that marks everything read.
- */
 let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the feed.
-         */
         this.label = '';
-        /**
-         * Whether to draw a control that marks everything read.
-         */
         this.markAll = false;
-        /**
-         * Label for that control.
-         */
         this.markAllLabel = 'Mark all as read';
-        /** Items arrive from the light DOM, which changes no property here. */
         this.handleSlotChange = () => {
             this.assign();
             this.requestUpdate();
         };
-        /**
-         * An item's own read event, heard on the way past, so the count follows.
-         *
-         * `unread` is derived from the items and nothing about an item changing tells
-         * Lit to look again. Not stopped: the event is the consumer's to hear, and
-         * this element is a bystander that happens to need to redraw.
-         */
         this.handleRead = () => {
-            /* After the item has applied it, not before: read synchronously the count
-               would be the one from before the change and the badge would trail by one
-               every time. */
             queueMicrotask(() => this.requestUpdate());
         };
         this.handleMarkAll = () => {
             this.markEveryoneRead();
         };
     }
-    /**
-     * Nothing is assigned by name, so the items land in a list and the rest does not.
-     *
-     * `role="listitem"` under anything but a `list` is a list item belonging to
-     * nothing, and the items are ordinary children a consumer writes with no
-     * `slot`. Manual assignment is the only way to wrap them without editing the
-     * consumer's markup, which is a change a React consumer's hydration reports
-     * and does not patch up.
-     */
     static { this.shadowRootOptions = {
         ...HelixElement.shadowRootOptions,
         slotAssignment: 'manual',
     }; }
-    /**
-     * How many items are unread, counted from the items themselves.
-     *
-     * Read-only because it is derived: a count the consumer could set is a second
-     * source of truth for something the items already know.
-     *
-     * **The attribute is written in `updated`, never reflected.**
-     * `@property({ reflect: true })` on a getter with no setter reflects once: Lit
-     * reflects what is in `changedProperties`, and nothing puts a derived getter
-     * there after the first update. Measured with two items, one marked read: the
-     * property answered 1 and the attribute still said 2, so a badge reading the
-     * attribute showed a count for an item the reader had just opened.
-     */
     get unread() {
         return this.items.filter((item) => !item.read).length;
     }
-    /** The notifications declared as children, in the order they are written. */
     get items() {
-        /* `?? []` is the server. Lit's element shim carries attributes and not a
-           tree, so `children` is undefined there, and this getter is reached from
-           `unread` during the first update. */
         return [...(this.children ?? [])].filter((child) => 'isNotification' in child && child.isNotification === true);
     }
-    /**
-     * Marks every unread item read, and reports how many actually moved.
-     *
-     * **Through each item's own request rather than by writing its property**,
-     * which is what makes one refusal refuse one item: a consumer who owns some
-     * items and not others gets the right answer for each, and a server that
-     * rejects one does not silently mark the rest.
-     */
     markEveryoneRead() {
         if (!this.dispatchEvent(new HelixReadEvent({ read: true }))) {
             return 0;
@@ -166,56 +72,13 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label || 'Notifications', role: 'region' });
     }
-    /**
-     * Says whether anything in the feed has media, so every item can hold the
-     * column open whether or not it has one of its own.
-     *
-     * **A fact no item can answer for itself**, which is why it is here. An item
-     * knows about its own media slot and nothing about its neighbors, so a feed
-     * where some rows have an avatar and some do not draws two different left
-     * edges for its text: measured on a four item feed, the rows without media
-     * started their text 32 pixels to the left of the rows with it. The styled
-     * tier turns this into a width; this tier ships no stylesheet and is
-     * unaffected.
-     *
-     * Read off the light DOM rather than off the items, so it does not depend on
-     * which children have upgraded by the time this runs.
-     */
     markMedia() {
         this.toggleState('media', this.items.some((item) => item.querySelector(':scope > [slot="media"]') !== null));
     }
-    /**
-     * Says on each region whether anything is in it.
-     *
-     * **A stylesheet cannot ask this, and the obvious selector fails twice over.**
-     * `[part="header"]:not(:has(> slot:has(*)))`: `:has()` may not be nested
-     * inside `:has()`, so the selector fails to parse and the whole rule is
-     * discarded; and a slot's assigned nodes are not its DOM children, so
-     * `slot:has(*)` reports whether the slot has *fallback* rather than whether a
-     * consumer filled it, and would have been false either way. Both verified in a
-     * browser: `insertRule` throws a `SyntaxError` on the first, and an assigned
-     * element still leaves `slot.matches(':has(*)')` false.
-     *
-     * `slotFilled` is what the rest of the library already asks with. It is said
-     * on the region inside this shadow root rather than on the host, because an
-     * attribute written onto the host is a change to markup the consumer rendered,
-     * which React reports on hydration and does not patch up.
-     */
     markEmpty() {
-        /* The header is not empty while this element is drawing its own control into
-           it. */
         this.markRegion('header', ['header'], '[part="mark-all"]');
         this.markRegion('footer', ['footer']);
     }
-    /**
-     * One region, hidden when its slot holds nothing and nothing of ours fills it.
-     *
-     * `hidden` beside the `data-empty` mirror: `data-empty` is the hook the styled
-     * sheet reads, and this tier ships no sheet, so an empty region left in the box
-     * tree would be a gap a headless consumer cannot close without knowing to look
-     * for it. The styled rule stays too, because that sheet sets `display` on these
-     * parts and therefore outranks the UA's `[hidden]` one.
-     */
     markRegion(part, slots, occupied) {
         const region = this.renderRoot?.querySelector(`[part="${part}"]`);
         const empty = !slots.some((name) => slotFilled(this.renderRoot?.querySelector(`slot[name="${name}"]`))) && !(occupied && this.renderRoot?.querySelector(occupied));
@@ -224,20 +87,9 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
     }
     updated(changed) {
         super.updated(changed);
-        /* Before `markEmpty`, which reads what is assigned: on a feed with no items
-           nothing else ever schedules a second update, so a header asked about
-           before its slot was filled stays hidden for the life of the element. The
-           empty feed is the one state where the header is the only thing on screen. */
         this.assign();
         this.markEmpty();
         this.markMedia();
-        /* Written after the render rather than reflected during it, so it follows
-           every change rather than only the first.
-    
-           **Zero is the absence of the attribute, not `unread="0"`.** Writing it at
-           rest puts an attribute on the host that a consumer's server never sent,
-           and `updated` is no later than hydration: it is the same microtask
-           checkpoint `firstUpdated` runs in. Only a departure from resting writes. */
         const unread = this.unread > 0 ? String(this.unread) : null;
         if (this.getAttribute('unread') !== unread) {
             if (unread === null) {

package/dist/number-input/root/number-input-root.js

@@ -9,154 +9,24 @@ import { minus, plus } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * How far a pointer travels for one step of the value, in pixels.
- *
- * Four, measured against the alternatives rather than picked: at one the value
- * runs away from the pointer and a field with `step="1"` crosses a hundred in
- * the width of a word, and at ten a reader has to cross the viewport to reach
- * a useful number. Four is roughly a character's width at the sizes this is set
- * in, so a step reads as "about one glyph of travel".
- */
 const SCRUB_PITCH = 4;
-/**
- * And the same step over four times the travel, which is what fine means here.
- *
- * Fine lengthens the distance rather than shrinking the increment. A drag that
- * produced values between the steps would be the one input in the library that
- * can reach a number its own arrow keys cannot, and `step` would stop being the
- * grid the control is on.
- */
 const SCRUB_FINE = 16;
-/**
- * @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.
- */
 let HelixHeadlessNumberInput = class HelixHeadlessNumberInput 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;
-        /**
-         * 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. Hardcoding `off` here is what stops a reader
-         * having a birthday or a postal code filled in for them, with no way for a
-         * consumer to ask for it.
-         */
         this.autocomplete = '';
-        /**
-         * Accessible name for the control that steps down.
-         */
         this.decrementLabel = 'Decrease';
-        /**
-         * Accessible name for the control that steps up.
-         */
         this.incrementLabel = 'Increase';
-        /**
-         * Shown while the field is empty.
-         *
-         * Not a label: it goes when typing starts.
-         */
         this.placeholder = '';
-        /**
-         * Whether the field refuses input while still submitting its value.
-         */
         this.readOnly = false;
-        /**
-         * 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.
-         */
         this.scrub = false;
-        /**
-         * How far one step moves.
-         */
         this.step = 1;
-        /** Where the pointer went down, and what the value was there. */
         this.scrubFrom = 0;
         this.scrubValue = 0;
-        /**
-         * 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.
-         */
         this.handleScrubDown = (event) => {
             if (this.isDisabled || this.readOnly) {
                 return;
@@ -167,15 +37,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             this.scrubValue = this.numeric ?? this.min ?? 0;
             event.preventDefault();
         };
-        /**
-         * 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.
-         */
         this.handleScrubMove = (event) => {
             const grip = event.currentTarget;
             if (!grip.hasPointerCapture(event.pointerId)) {
@@ -186,10 +47,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             const pitch = event.altKey ? SCRUB_FINE : SCRUB_PITCH;
             const steps = Math.round((event.clientX - this.scrubFrom) / pitch);
             const next = String(this.clamp(this.scrubValue + steps * unit));
-            /* Compared before it is sent. A drag produces a move event per frame and
-               most of them land on the step the value is already on, and announcing
-               those would be `helix-input` firing sixty times a second saying nothing
-               changed. */
             if (next === this.value) {
                 return;
             }
@@ -199,43 +56,18 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
                 restoreValue(control, this.value);
             }
         };
-        /** Let go, and the capture goes with it. */
         this.handleScrubEnd = (event) => {
             const grip = event.currentTarget;
             if (grip.hasPointerCapture(event.pointerId)) {
                 grip.releasePointerCapture(event.pointerId);
             }
         };
-        /**
-         * 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.
-         */
         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;
             this.requestValue(control.value);
             restoreValue(control, this.value);
         };
-        /**
-         * 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.** Clearing it means typing
-         * `2.7e` and tabbing away empties 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.
-         */
         this.handleBlur = () => {
             const control = this.control;
             const parsed = this.numeric;
@@ -245,18 +77,10 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             this.requestValue(String(this.clamp(parsed)));
             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 }));
         };
-        /**
-         * 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.
-         */
         this.handleKeydown = (event) => {
             if (event.key === 'ArrowUp') {
                 this.stepUp();
@@ -269,9 +93,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             }
             else if (event.key === 'PageDown') {
                 this.stepDown(true);
-                /* Guarded the way `nudge` is. A read-only field still receives keydown,
-                   so an unguarded Home on one with a `min` silently rewrites the value
-                   that the arrows beside it correctly refuse to touch. */
             }
             else if (event.key === 'Home' &&
                 this.min !== undefined &&
@@ -288,11 +109,9 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             else {
                 return;
             }
-            // Or the arrows scroll the page and Home jumps to the top of it.
             event.preventDefault();
         };
     }
-    /** Focus is delegated to the field, so the host is never the focus target. */
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
@@ -300,7 +119,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
     get control() {
         return this.renderRoot.querySelector('[part="control"]');
     }
-    /** The value as a number, or `null` where the field holds nothing usable. */
     get numeric() {
         if (this.value.trim() === '') {
             return null;
@@ -308,33 +126,15 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         const parsed = Number(this.value);
         return Number.isFinite(parsed) ? parsed : null;
     }
-    /**
-     * 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.
-     */
     clamp(value) {
         const step = Math.abs(this.step) || 1;
         const anchor = this.min ?? 0;
         const stepped = anchor + Math.round((value - anchor) / step) * step;
         const floored = this.min === undefined ? stepped : Math.max(this.min, stepped);
         const capped = this.max === undefined ? floored : Math.min(this.max, floored);
-        /* Decimal places from the step and the anchor together: a step of 0.5 from
-           an anchor of 0.25 lands on 0.75, which needs two rather than the one the
-           step alone would give. */
         const places = Math.max(decimals(step), decimals(anchor));
         return Number(capped.toFixed(places));
     }
-    /**
-     * 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.
-     */
     nudge(steps) {
         if (this.isDisabled || this.readOnly) {
             return;
@@ -348,37 +148,12 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
             restoreValue(control, this.value);
         }
     }
-    /** One step up, or `PageUp`'s larger one. */
     stepUp(large = false) {
         this.nudge(large ? (this.largeStep ?? 10) : 1);
     }
-    /**
-     * 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 = false) {
         this.nudge(large ? -(this.largeStep ?? 10) : -1);
     }
-    /**
-     * The label is the surface, which is where the convention already is.
-     *
-     * Not a grip of its own at the leading edge, which is the obvious answer and
-     * is 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.
-     *
-     * 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.
-     */
     renderLabel() {
         if (!this.scrub) {
             return super.renderLabel();
@@ -398,15 +173,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
       ><slot name="label">${this.label || hidden}</slot></label
     >`;
     }
-    /**
-     * 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.
-     */
     sync() {
         const control = this.control;
         this.internals.setFormValue(this.value);
@@ -429,23 +195,16 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         else {
             this.internals.setValidity({}, '', control);
         }
-        // Straight after, because validity moved without any property moving.
         this.refreshFeedback();
     }
-    /** Puts the caret in the field, the way a label pointing at one would. */
     focus(options) {
         this.control?.focus(options);
     }
-    /** Selects the number, so typing replaces it. */
     select() {
         this.control?.select();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* Never before the first update, which is the one the server does: there is
-           no render root to query there, and `querySelector` is not merely empty on
-           Lit's element shim, it is undefined. There is also no caret to keep before
-           anything has rendered. */
         if (!this.hasUpdated) {
             return;
         }
@@ -479,13 +238,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
           </svg>
         </button>
         <slot name="start"></slot>
-        ${
-        /* `role="spinbutton"` with the range on it, which is what tells a
-           screen reader this is a number in a range rather than a line of
-           text. The three `aria-value*` attributes are what the native
-           `type=number` would have carried, and they have to be written here
-           because the field is text. */
-        ''}
+        ${''}
         <input
           part="control"
           id="control"
@@ -524,13 +277,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
       </div>
       ${this.renderHint()}${this.renderFeedback()}`;
     }
-    /**
-     * 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);
     }
@@ -572,14 +318,6 @@ HelixHeadlessNumberInput = __decorate([
     customElement('helix-headless-number-input')
 ], HelixHeadlessNumberInput);
 export { HelixHeadlessNumberInput };
-/**
- * How many decimal places a number is written with.
- *
- * Read off the string rather than computed, because the question is about how
- * the consumer wrote the step and not about what the binary can represent.
- * `1e-7` is handled separately: its string form has no dot at all, so counting
- * after one would say zero and round every result to a whole number.
- */
 const decimals = (value) => {
     const text = String(value);
     const exponent = /e-(\d+)$/.exec(text);

package/dist/option/group/option-group.js

@@ -7,35 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A named run of options inside a listbox.
- *
- * @description
- * A heading over a set, and nothing else: it holds no selection and no value,
- * because grouping is presentation over a list whose owner is the listbox. Its
- * options are still the listbox's options, which is what keeps the keyboard
- * moving through a grouped list exactly as it moves through a flat one.
- *
- * `role="group"` named by the heading, so a screen reader announces which run
- * an option is in without the heading becoming something to land on.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases OptGroup, Section
- * @documentation https://helix.fusion.dev/components/option-group
- *
- * @slot - The options in this run.
- * @slot label - Richer than a string.
- *
- * @csspart items - The run itself.
- * @csspart label - The heading.
- */
 let HelixHeadlessOptionGroup = class HelixHeadlessOptionGroup extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * The heading over the run.
-         */
         this.label = '';
     }
     willUpdate(changed) {