@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/toast/item/toast-item.js

@@ -9,89 +9,10 @@ import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary One message in the toast region.
- *
- * @description
- * An element rather than a slot, because it carries a timeout, a tone, a
- * dismiss control and a lifetime that pauses: behavior, state and API, which
- * is the test for whether a region becomes an element in this library.
- *
- * **The timer is the item's own.** Held by the region, one message arriving
- * would restart another's, so a stack of three would go from three seconds each
- * to nine for the last one. Each message is on its own clock from the moment it
- * is rendered.
- *
- * **A message is the opposite of the page it is over.** Inverted by default,
- * because a thing arriving in a corner has to be told apart from the page in
- * the moment before it is read, and inverting does that without spending a
- * color that means something. It is a flip of `color-scheme` rather than a
- * named inverse surface: every token in the subtree re-resolves, so a `Retry`
- * a consumer slots in comes out right without knowing where it is. `Tooltip`
- * can name the inverse surface directly because it holds no controls; this
- * cannot. Set `data-color-mode` on the region to take the page's mode instead.
- *
- * **No duration means it stays.** That is the safe default rather than the
- * common one: anything carrying an action has to still be there when the reader
- * decides to take it, and a component cannot tell from the outside whether the
- * message it was given is disposable.
- *
- * **The clock stops while it is being read.** Hover pauses it, and so does
- * focus landing anywhere inside, which is the case that matters more: a
- * keyboard reader tabbing towards the action in a toast is exactly the person a
- * timer must not race. Both resume where they left off rather than starting
- * again, so a message half-read does not get a full second life every time a
- * pointer crosses it.
- *
- * **Going away is a request, never an act.** It dispatches a cancelable
- * `helix-dismiss` and does nothing else: the consumer owns the list, so the
- * item removing itself would leave the two disagreeing. Auto-dismiss and the
- * dismiss control raise the same event, so a consumer handles one path and not
- * two.
- *
- * @since 0.1.0
- * @status experimental
- * @documentation https://helix.fusion.dev/components/toast
- *
- * @slot - The message.
- * @slot actions - What to do about it, usually a button or a link.
- * @slot dismiss-icon - Replaces the glyph inside the dismiss control.
- * @slot icon - Replaces the tone mark. Matches `Callout`, which is why the
- *   dismiss control's own glyph is `dismiss-icon` rather than this: two slots
- *   cannot share a name, assignment goes to whichever comes first in the tree,
- *   and the tone mark is the one a consumer reaches for.
- *
- * @event {HelixDismissEvent} helix-dismiss - Fired when it asks to go, whether by the control or by its timer. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart actions - The region holding what to do about it.
- * @csspart content - The message.
- * @csspart dismiss - The control that asks to close.
- * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
- * @csspart icon - The tone mark, where the message has one.
- * @csspart icon-mark - The tone glyph, where none is slotted.
- * @csspart item - The message's own surface.
- * @csspart timer - The bar showing how long is left, where a duration was given.
- *
- * @cssproperty --toast-duration - How long this message stays, in milliseconds, for a progress hint.
- */
 let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissible(HelixElement) {
     constructor() {
         super(...arguments);
-        /** Whether it is showing, whoever said so, and `undefined` until somebody has. */
         this.openState = undefined;
-        /* Arrows, so `this` is the item wherever the listener ends up. Lit does bind
-           a template listener to its host, and relying on that puts a load-bearing
-           fact about a library in a place nobody reading this file would look. */
-        /**
-         * How many reasons there are to hold the clock, rather than whether there is
-         * one.
-         *
-         * Hover and focus stop the same timer, and the two are genuinely independent:
-         * a pointer can leave while focus stays, and focus can leave while the
-         * pointer stays. Uncounted, a reader who tabs into a message and then moves
-         * the pointer off it has the clock restarted underneath them, which is the
-         * case the pause exists for. Only the last one out starts it again.
-         */
         this.holds = 0;
         this.handlePause = () => {
             this.holds += 1;
@@ -104,19 +25,6 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
             }
         };
     }
-    /**
-     * Whether the message is still showing.
-     *
-     * The item always applies: it goes when it is asked to, having announced
-     * `helix-dismiss` first, and a consumer who owns the list refuses that event
-     * to take the decision instead.
-     *
-     * **No `default-open`, unlike the four mixins.** A `default-` seed exists so
-     * markup can choose a starting state without claiming ownership, and there is
-     * only one starting state that makes sense: a message that has been rendered
-     * is showing. An attribute whose only legal value is the default is an
-     * attribute nobody can use.
-     */
     get open() {
         return this.openState ?? true;
     }
@@ -125,21 +33,10 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         this.openState = next;
         this.requestUpdate('open', previous);
     }
-    /**
-     * Asks to be taken away, and reports whether the request stood.
-     *
-     * Announced before anything happens, so `preventDefault()` is a refusal and
-     * the message stays. The event still carries the label, because a consumer
-     * removing this from their own state has to know which one went, and that is
-     * true whether or not the item hid itself first.
-     */
     dismiss() {
         if (!this.open) {
             return true;
         }
-        /* The clock stops either way. A timer left running on a message that has
-           gone would fire into nothing, and would hold the item alive until it
-           did. */
         clearTimeout(this.timer);
         this.timer = undefined;
         return requestChange({
@@ -148,18 +45,11 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
                 this.openState = false;
                 this.requestUpdate('open', previous);
             },
-            /* `helix-dismiss` answers a controlled `open`, which reads oddly and is
-               exact. A toast is not an overlay that opens and closes: `next` below is
-               `false` and nothing here ever calls `requestOpen(true)`, so it only
-               ever asks in one direction, and the verb for that direction is
-               `dismiss`. A consumer controlling `open` therefore answers
-               `onhelix-dismiss`, and the generated types ask for exactly that. */
             event: () => this.dismissEvent(),
             host: this,
             next: false,
         });
     }
-    /** Stops the clock, leaving whatever is left of it. */
     pause() {
         if (this.timer === undefined || this.startedAt === undefined) {
             return;
@@ -168,13 +58,8 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         this.timer = undefined;
         this.remaining = Math.max((this.remaining ?? 0) - (Date.now() - this.startedAt), 0);
         this.startedAt = undefined;
-        /* Said on the host so the indicator can freeze with the clock. A `data-`
-           attribute rather than a property, because it is written after upgrade
-           from a pointer moving: nothing declares it and no server rendered it,
-           which is the same reason `Carousel` names its slides from here. */
         this.toggleAttribute('data-paused', true);
     }
-    /** Starts it again from where it stopped. */
     resume() {
         if (this.timer !== undefined || this.remaining === undefined || this.remaining <= 0) {
             return;
@@ -188,56 +73,21 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        // A message removed while its timer is running would otherwise fire into
-        // nothing, and hold the item alive until it did.
         clearTimeout(this.timer);
         this.timer = undefined;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* Mirrored for CSS rather than reflected onto `open` itself, which is the
-           library's rule about state: a reflected `open` is indistinguishable from
-           one the consumer declared, and that attribute is what ownership is read
-           from. `data-closed` can never be mistaken for a declaration. */
-        /* **`data-closed`, because open is the resting state.** A toast opens by
-           default, so a `data-open` would appear on a consumer's server-rendered
-           `<helix-toast-item>` without React having sent it. Inverting keeps the
-           `data-` hook for the headless consumer this publishes it for, and moves
-           the write to the side that only happens after somebody dismisses the
-           message, which is long past hydration. */
         this.toggleAttribute('data-closed', !this.open);
-        /* And `hidden` beside it, because `data-closed` is a hook and not a
-           mechanism. With the hiding living only in the styled sheet's
-           `opacity: 0` and `visibility: hidden`, a consumer on this tier has a
-           dismissed message that never goes away: measured, a closed base toast
-           printed its text on the page.
-           It costs the styled tier nothing, the same as the accordion: `:host` sets
-           `display: grid` unconditionally so the author rule beats the UA sheet,
-           and the exit still animates its row down from `1fr`. */
         this.toggleAttribute('hidden', !this.open);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        /* Here rather than in `connectedCallback`, which the server never calls, and
-           started only once: the clock belongs to this message's life on screen. */
         if (this.duration !== undefined && this.duration > 0) {
             this.remaining = this.duration;
             this.resume();
         }
     }
-    /**
-     * The mark for the message's tone, behind a seam.
-     *
-     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
-     * tier above replaces it by overriding. Those answer different people: the
-     * slot is for the page and the method is for whoever is building the styled
-     * layer, and a fallback with only the first is one a tier can restyle and
-     * cannot change.
-     *
-     * The mark is passed in rather than looked up again, since `render` has
-     * already resolved the tone and a second lookup is a second place for the
-     * fallback to disagree with the tone around it.
-     */
     renderIcon(mark) {
         return html `<slot name="icon">
       <svg part="icon-mark"
@@ -250,15 +100,6 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
       </svg>
     </slot>`;
     }
-    /**
-     * The mark on the dismiss control, behind a seam.
-     *
-     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
-     * tier above replaces it by overriding. Those answer different people: the
-     * slot is for the page and the method is for whoever is building the styled
-     * layer, and a fallback with only the first is one a tier can restyle and
-     * cannot change.
-     */
     renderDismissIcon() {
         return html `<slot name="dismiss-icon">
       <svg part="dismiss-mark" viewBox=${x.viewBox} fill="currentColor" aria-hidden="true">
@@ -267,12 +108,6 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
     </slot>`;
     }
     render() {
-        /* Nothing when no tone was given, which is the common message: "Project
-           saved" is not an error, a warning or an announcement, and an icon there
-           would be decoration standing where meaning is supposed to be. `Callout`
-           falls back to `info` because a callout exists to set a passage apart and
-           is always *about* something; a toast is just the next thing that
-           happened. */
         const mark = toneMark(this.tone);
         return html `<div
       part="item"

package/dist/toast/root/toast-root.js

@@ -7,67 +7,16 @@ 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 The region messages arrive in, and the only thing that announces them.
- *
- * @description
- * **The region is why this is one family rather than two.** A live region has
- * to be in the document *before* a message is put into it: assistive technology
- * subscribes to the region, and a region that arrives already holding its
- * message is frequently not announced at all. So the container is a part of the
- * family and not an arranger of complete things, which is the same reasoning
- * that puts `Radio.Group` inside its own family.
- *
- * **Polite, never assertive.** `role="alert"` interrupts whatever a reader is
- * being told, and almost nothing that arrives in a corner of the screen has
- * earned that. Something that genuinely cannot wait is a `Dialog`, which stops
- * the page for everyone rather than only for the people who cannot see it.
- *
- * **It never creates or destroys anything.** The consumer renders items and
- * removes them; asking to go is a cancelable `helix-dismiss` from the item. An
- * item that has gone hides itself and stays in the tree, so a consumer whose
- * state still lists it does not have their framework fighting a node this
- * component took away. It hides without waiting to be told, unless the consumer
- * declared `open` and said the state is theirs.
- * There is no `toast.show()`, because an imperative queue inside a component is
- * a second copy of the application's state that nothing can render from: an app
- * that wants a `toast()` function writes a thin one over the state it already
- * has, and keeps the ability to render the same messages on the server, in a
- * test, or twice.
- *
- * @since 0.1.0
- * @status experimental
- * @category overlays
- * @aliases Toaster, Snackbar, Notifications
- * @documentation https://helix.fusion.dev/components/toast
- *
- * @slot - The messages, as `helix-toast-item` elements.
- *
- * @csspart region - The stack the messages are in.
- */
 let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the region, such as "Notifications".
-         */
         this.label = 'Notifications';
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* On the host through internals, so the region is a landmark to anything
-           walking the light DOM as well as to a screen reader, and so nothing is
-           written onto the host as an attribute a server's markup never had. */
         hostAria(this.internals, { label: this.label, role: 'status' });
         this.internals.ariaLive = 'polite';
-        /* Additions are what a reader needs; a message going away is not news, and
-           announcing removals means every dismissal is read out. */
         this.internals.ariaRelevant = 'additions';
-        /* `role="status"` carries an implicit `aria-atomic="true"`, which means the
-           whole region is re-read whenever any part of it changes. With a stack of
-           four, the fifth arrival announces all five. `additions` alone does not
-           help: it says which mutations count, not how much is read out when one
-           does. Both are needed, and only one was here. */
         this.internals.ariaAtomic = 'false';
     }
     render() {

package/dist/toggle/group/toggle-group.js

@@ -8,80 +8,15 @@ import { customElement, DisabledCascadeController, HelixFormElement, hostAria, I
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessToggle } from '../root/toggle-root.js';
-/**
- * @summary A row of options with the selection marked by a moving indicator.
- *
- * @description
- * The indicator is one element that travels, not a background that appears on
- * whichever item is current. That difference is the whole point: a fill that
- * swaps is two things changing at once and reads as a flicker, while one that
- * moves is a single object the eye follows, and it says where the selection
- * came from as well as where it went.
- *
- * Its whole box is measured from the selected item and written onto
- * the indicator as custom properties, because labels are different lengths and
- * no proportion of the group is the right answer. Measurement is client-side by
- * necessity, so the server renders the indicator hidden and it fades in once it
- * has somewhere to be, which is the harmless direction: it appears rather than
- * jumping from a wrong place.
- *
- * A radio group, and only that. Navigation is links marked with `aria-current`
- * and styled by the `data-navigation-item` recipe: radio semantics would announce a
- * set of destinations as a set of choices. A tab controls a panel.
- *
- * Being a radio group, it is a form control, and it says so through
- * `HelixFormElement`: it reports its value under a `name`, comes back to the
- * markup's choice on reset, and restores the one a reader made when the browser
- * brings a form back.
- *
- * The semantics were already right: the host has carried `role="radiogroup"`
- * and the items `role="radio"` from the start. What none of it did was reach a
- * form. A button in a shadow root submits nothing whatever its role, so the
- * value has to be reported by the host, which is the only thing a form can
- * see.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases SegmentedControl, Segmented, Navigation, Switcher
- * @documentation https://helix.fusion.dev/components/toggle-group
- *
- * @slot - The group's items.
- *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the answer moves, and cancelable. The only way to refuse one.
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Dispatched by the item and listened for here. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- *
- * @csspart divider - The rule after an inline label, separating it from the items.
- * @csspart feedback - What is wrong with it.
- * @csspart hint - Help under the row, while nothing is wrong.
- * @csspart indicator - The moving marker behind the selected item.
- * @csspart label - The question, over the row.
- * @csspart row - The line the track sits on, with whatever flanks it.
- * @csspart track - The bar the items sit in.
- */
 let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinControllerValue(MixinField(HelixFormElement)) {
     constructor() {
         super(...arguments);
         this.indicator = new IndicatorController(this, {
-            // The same exact match `sync` makes: nothing chosen means nothing marked,
-            // and the controller takes the mark away rather than parking it on item one.
             active: () => this.items.find((item) => item.value === this.value),
             indicator: () => this.renderRoot?.querySelector('[part="indicator"]'),
             surface: () => this.renderRoot?.querySelector('[part="track"]'),
         });
-        /* Moving and choosing are one act, which is the radio group pattern this
-           control also follows, and is what the controller exists to stop being
-           written per component. */
-        /* Registered rather than held. A controller adds itself to the host, so there
-           is no reference to keep: nothing here talks to it after construction, which
-           is why it is `protected` and not `private`. A private field nothing reads
-           is an unused one, and the honest reading is that the subclass tier is where
-           a consumer would reach for it. */
         this.keys = new KeyboardNavigationController(this, { items: () => this.items });
-        /* Stated once, and the group never thinks about it again. The controller is
-           what stops the cascade being hand-called from whichever methods a component
-           happens to have. */
         this.cascade = new DisabledCascadeController(this, {
             items: () => this.items,
         });
@@ -89,22 +24,8 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
             this.requestValue(event.detail.value);
         };
     }
-    /** Marks the chosen item, separately from placing the indicator. */
     sync() {
-        /* An exact match and nothing else, never `resolveActiveItem`, which falls
-         * back to the first enabled item: a group with no value would mark one
-         * anyway, `aria-checked="true"` and the thumb under it and full selected
-         * styling, while the group reported nothing. A `required` group would then
-         * tell a reader a value is missing while they are looking at one.
-         *
-         * That fallback is right where it came from. A tab set always shows a panel,
-         * so something has to be current; a group that reports a form value has the
-         * honest option of reporting none. */
         const active = this.items.find((item) => item.value === this.value);
-        /* With nothing chosen there is no selection to carry the tab stop, so the
-           first item holds one until there is. Otherwise an unanswered group is a
-           control the keyboard cannot enter, which is what the fallback was quietly
-           also doing for it. */
         const entry = active ? undefined : this.items.find((item) => !item.disabled);
         for (const item of this.items) {
             item.selected = item === active;
@@ -114,15 +35,6 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
     get items() {
         return [...this.children].filter((child) => child instanceof HelixHeadlessToggle);
     }
-    /**
-     * Watches the group and every item it currently holds.
-     *
-     * Called again on `slotchange`, because the set was read once at first paint:
-     * an item added later was measured by nothing, so a group whose options
-     * arrive with the data had a thumb that stopped following the moment one of
-     * them changed width. Observing the same element twice is a no-op, so there
-     * is nothing to unwind first.
-     */
     watch() {
         this.observer?.observe(this);
         for (const item of this.items) {
@@ -132,14 +44,6 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
-        /* The observer is rebuilt here, because nothing else does it.
-         *
-         * `firstUpdated` runs once for the life of the element and
-         * `disconnectedCallback` runs every time it moves, so a framework
-         * reordering a list left this permanently dead: the observer gone, nothing
-         * to rebuild it, and the component still rendering as though it were
-         * watching. Guarded on `hasUpdated`, because the first connection happens
-         * before the first render and there is nothing to watch yet. */
         if (this.hasUpdated) {
             this.measure();
             this.watch();
@@ -154,85 +58,31 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
         super.firstUpdated(changed);
         this.sync();
         this.indicator.place();
-        /* Per item, not only the host, which is what the controller's own observer
-           covers. An item can change width inside a track that keeps its size, and
-           the host never fires for that. */
         this.measure();
         this.watch();
     }
-    /** The observer the items are registered on, rebuilt with them. */
     measure() {
         this.observer?.disconnect();
         this.observer = new ResizeObserver(() => this.indicator.place());
     }
     updated(changed) {
         super.updated(changed);
-        // Every update, not only the ones that name `value`: see the note on
-        // `ColorInput.updated`. The placement stays gated, because the indicator
-        // controller already places on every update of its own host.
         this.sync();
         if (changed.has('value')) {
             this.indicator.place();
         }
         this.validate();
-        /* Every update, because the label and the message come and go with the
-           properties behind them, and an element reference to a node that has been
-           re-rendered is a reference to nothing. */
         this.linkHost();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        // Through internals, so nothing lands on the host as an attribute. A nav
-        // renders a real `<nav>` in the shadow root and takes its semantics from
-        // that, so the host stays neutral.
-        /* The label goes on as a string as well as the element reference
-           `linkHost` sets, because this is the half a server can write. The
-           reference wins on the client, which is what lets a consumer slot a label
-           richer than a string. */
         hostAria(this.internals, { label: this.label, role: 'radiogroup' });
-        // `null` rather than an empty string when nothing is chosen, which is the
-        // difference between a control that submits nothing and one that submits a
-        // blank.
         this.internals.setFormValue(this.value === '' ? null : this.value);
     }
-    /**
-     * The verdict on the answer `required` asks for.
-     *
-     * `required` arrives with `MixinField` and enforces nothing on its own: the
-     * attribute reflects and the marker renders beside the label, and without this
-     * a form with an unanswered group submits anyway. The marker is a promise to
-     * the reader that something will stop them.
-     *
-     * The anchor is the track rather than the host, so the browser's own bubble
-     * points at the control rather than at a box with nothing in it.
-     */
     validate() {
         this.reportRequired(this.value === '', 'Choose one to continue.', 'track');
     }
-    /**
-     * The row the track sits in, so something can sit beside it.
-     *
-     * **Bare slots, and a wrapper only around the row itself.** An unassigned
-     * slot is `display: contents` in the UA stylesheet and generates no box at
-     * all, so a group with nothing slotted lays out exactly as it did before this
-     * existed: no grid track, no flex item, no gap. Wrapping each side in a div
-     * instead would paint an empty inset band on every group in the library that
-     * never asked for one, which is the measurement Card already paid for.
-     *
-     * The row does always generate a box, and is entitled to: the track is always
-     * in it.
-     */
     render() {
-        /* The track is an element rather than the host, and has to be: the label,
-           the hint and the message are the host's children too, so a track on the
-           host makes them flex items in the same row as the segments. The track also
-           owns the box the indicator is measured against, which is why `place` reads
-           it rather than `this`. */
-        /* **Inside the track when it is placed at the start, not beside it.** A
-           label sitting outside reads as a field's label that happens to be on one
-           line; inside, with a rule after it, the group reads as one control that
-           says what it is for. The divider is what makes that legible: without it
-           the word is a first segment that cannot be pressed. */
         const inside = this.labelPlacement === 'start';
         const label = this.renderGroupLabel();
         return html `${inside ? nothing : label}

package/dist/toggle/root/toggle-root.js

@@ -7,108 +7,30 @@ 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 option in a toggle group.
- *
- * @description
- * Renders a `<button role="radio">`. This is a form control and nothing else.
- *
- * Navigation is not this. It is links marked with `aria-current` and styled by
- * the `data-navigation-item` recipe in the base layer, which carries the same look
- * without radio semantics announcing destinations as choices.
- *
- * @since 0.1.0
- * @status experimental
- * @category actions
- * @aliases Segment, NavItem, Option
- * @documentation https://helix.fusion.dev/components/toggle
- *
- * @slot - The item's label.
- *
- * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart item - The radio button.
- */
 let HelixHeadlessToggle = class HelixHeadlessToggle extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the item can be chosen.
-         */
         this.disabled = false;
-        /** What the markup said, read once at construction for the reason above. */
         this.seeded = this.hasAttribute('selected');
-        /**
-         * Whether this item holds the group's tab stop while nothing is chosen.
-         *
-         * The stop normally rides on the selection, and an unanswered group has no
-         * selection, so without this the keyboard cannot reach it. Written by the
-         * group, with no attribute: it is coordination between elements, and
-         * `tabindex` on a host the consumer rendered is the change a React consumer's
-         * hydration reports and does not patch up.
-         */
         this.focusable = false;
-        /**
-         * Whether this item is the current one.
-         */
         this.selected = false;
-        /**
-         * Identifies the item to the group.
-         */
         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 item's own control.
-     *
-     * The group drives arrow-key navigation and cannot reach the control itself,
-     * which is inside this shadow root. Exposing the intent as a method keeps the
-     * group out of the child's internals.
-     */
     focusItem() {
         this.renderRoot.querySelector('[part="item"]')?.focus();
     }
-    /** Chooses this item 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-toggle selected>` in a consumer's
-     * markup means. There is no write back.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('selected', this.selected);