@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/tour/root/tour-root.js

@@ -7,99 +7,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixBeforeActivateEvent, HelixBeforeCloseEvent, HelixCompleteEvent, HelixElement, hostAria, requestChange, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, queryAssignedElements, state } from 'lit/decorators.js';
-/**
- * @summary A guided run through an interface, one stop at a time.
- *
- * @description
- * The root owns the order and nothing else. Which stop is current, what Next
- * and Back mean, when the run is finished; the stops own where they point, and
- * the consumer owns every word.
- *
- * **The spotlight is a shadow, not a hole.** The scrim is a box the size of the
- * current target with an enormous spread on its `box-shadow`, so the darkness
- * is what the shadow paints and the target is simply where the box is. A
- * `clip-path` on a full-screen scrim is the other way to do it and is worse
- * here: it needs the viewport in the same coordinate space as the cut, which
- * stops being true the moment anything between them is transformed.
- *
- * **It measures, and this is a case where measuring is the only option.** The
- * target is an element somewhere else on the page whose position nothing can
- * know statically. That is different from a trail folding by width, where the
- * design rule was expressible and the measurement was answering a question
- * nobody had asked. Here the question is "where is that button", and there is
- * no other way to ask it.
- *
- * **Nothing is measured on the server and nothing needs to be.** A tour starts
- * closed and a closed tour draws nothing, so the server renders the stops as
- * inert markup and the first frame is correct. This is also what makes it
- * acceptable for the root to write `current` onto stops it does not own: there
- * is no server state for the write to disagree with.
- *
- * **It cannot point inside a modal, and nothing can fix that here.**
- * `showModal()` makes everything outside the dialog's own subtree inert, so a
- * panel anywhere else is unpressable however the top layer is ordered: this is
- * what modal means rather than a stacking accident. Measured with a modal
- * `Drawer` open, `elementsFromPoint` over the tour's own Done button returned
- * the drawer, the press light-dismissed the drawer, and the tour heard nothing
- * at all. Anything a tour points into has to stay reachable, which for `Drawer`
- * and `Dialog` means not modal while the tour is running.
- *
- * **Focus is not trapped.** A reader has to be able to look at, and reach, the
- * thing being pointed at. `Escape` leaves, which is the one binding a tour
- * needs and the one every reader already tries.
- *
- * @since 0.1.0
- * @status experimental
- * @category overlays
- * @aliases Coachmark, Product tour, Walkthrough, Onboarding
- * @documentation https://helix.fusion.dev/components/tour
- *
- * @slot - The stops, in the order they should be visited.
- *
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current stop moves, carrying the new index. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the reader leaves early. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixCompleteEvent} helix-complete - Fired when the last stop is
- * finished.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart spotlight - The box over the current target, which paints the scrim.
- */
 let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Label for the control that goes back, handed to every stop.
-         */
         this.backLabel = '';
-        /**
-         * Stop to start on, where nothing declared one.
-         */
         this.defaultIndex = 0;
-        /** The stop being shown, whoever set it, and `undefined` until somebody has. */
         this.indexState = undefined;
-        /**
-         * Label for the control that goes on from the last stop.
-         */
         this.doneLabel = '';
-        /**
-         * Accessible name for the run, such as "Getting started".
-         */
         this.label = '';
-        /**
-         * Label for the control that goes on.
-         */
         this.nextLabel = '';
-        /**
-         * Whether the tour is running.
-         */
         this.open = false;
-        /**
-         * Label for the control that leaves the tour.
-         */
         this.skipLabel = '';
-        /**
-         * Space left around the target when it is lit, in pixels.
-         */
         this.spotlightPadding = 8;
         this.handleAsk = (event) => {
             const what = event.detail?.what;
@@ -119,24 +37,10 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
                 this.skip();
             }
         };
-        /* On the window, because the scrim is fixed and a scroll or a resize moves
-           the target out from under it. Passive: neither handler cancels anything. */
         this.handleViewport = () => {
             this.light();
         };
     }
-    /**
-     * Which stop the reader is on.
-     *
-     * **Moved through `requestChange`, never by assignment from `move`.** That
-     * announces first and applies only if nobody refused, and refusing is how a
-     * consumer takes the decision; writing the property and then announcing puts
-     * `preventDefault` after the move it is refusing.
-     *
-     * The shape is `Carousel`'s, which is the nearest thing in the library: a
-     * `default-index` for markup that only seeds and a held state that is
-     * `undefined` until somebody sets one.
-     */
     get index() {
         return this.indexState ?? this.defaultIndex;
     }
@@ -145,15 +49,12 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         this.indexState = next;
         this.requestUpdate('index', previous);
     }
-    /** The stops, in the order they were written. */
     get stops() {
         return (this.assigned ?? []).filter((one) => one.current !== undefined);
     }
-    /** How many stops there are. */
     get length() {
         return this.stops.length;
     }
-    /** Goes on, and finishes the run on the last stop. */
     next() {
         if (this.index >= this.length - 1) {
             this.finish();
@@ -161,20 +62,12 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         }
         this.move(this.index + 1);
     }
-    /** Goes back, and does nothing on the first stop. */
     back() {
         if (this.index <= 0) {
             return;
         }
         this.move(this.index - 1);
     }
-    /**
-     * Leaves the run early, which is a close rather than a completion.
-     *
-     * Announced before it is applied, and cancelable because of it: writing
-     * `open` first and dispatching after leaves a consumer calling
-     * `preventDefault` refusing something that has already happened.
-     */
     skip() {
         const event = new HelixBeforeCloseEvent();
         this.dispatchEvent(event);
@@ -183,17 +76,10 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         }
         this.open = false;
     }
-    /* Announced before it closes, and not cancelable, which is the difference
-       from `skip`. `HelixCompleteEvent` is `cancelable: false` by construction:
-       leaving early is a request a consumer may refuse, and having reached the
-       end is something that has already happened. What ordering still buys is a
-       listener that reads `open` and sees the tour as it was when it finished. */
     finish() {
         this.dispatchEvent(new HelixCompleteEvent({ value: String(this.index) }));
         this.open = false;
     }
-    /* The one path every stateful change in the library goes through: it
-       announces, then applies where nothing refused. */
     move(to) {
         requestChange({
             apply: (value) => {
@@ -206,13 +92,6 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
     }
     connectedCallback() {
         super.connectedCallback();
-        /* On the host, not on the slot the stops are assigned to.
-           The event is composed and bubbles, so in a browser it reaches either. It
-           does not reach the slot under `bun test`: happy-dom does not propagate
-           events through slot assignment, so a listener bound there hears nothing
-           and every spec about pressing Next passes for the wrong reason or fails
-           for a reason that is not the component's. `Megamenu` moved its own
-           listener to the host for exactly this. */
         this.addEventListener('helix-tour-ask', this.handleAsk);
         this.ownerDocument.addEventListener('keydown', this.handleKeydown);
         globalThis.addEventListener('resize', this.handleViewport, { passive: true });
@@ -234,14 +113,6 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         this.settle();
         this.light();
     }
-    /**
-     * Tells each stop where it is in the run.
-     *
-     * Written onto the stops, which is the one outward write in this family and
-     * is argued for on the class above. The labels go with it, and only where the
-     * root was given one, so a stop keeps its own default unless somebody has
-     * localised the tour.
-     */
     settle() {
         const stops = this.stops;
         const at = Math.max(0, Math.min(this.index, stops.length - 1));
@@ -263,7 +134,6 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
             }
         });
     }
-    /** Reads the current target's box, which is where the light falls. */
     light() {
         const stops = this.stops;
         const target = this.open

package/dist/tour/stop/tour-stop.js

@@ -8,139 +8,36 @@ import { customElement, HelixElement, HelixTourAskEvent, hostAria, PopoverContro
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../button/index.js';
-/**
- * @summary One stop on a tour: what it points at, and a panel to say it in.
- *
- * @description
- * A stop names a target with `for` and holds whatever the consumer puts in it.
- * It owns no content of its own, which is the whole shape of this family: the
- * tour abstracts the three things that are genuinely hard, and the words are
- * the consumer's.
- *
- * What it does own:
- *
- * - **Where the panel goes.** Anchored to the target through the same floating
- *   pass every other overlay here uses.
- * - **That it is on top.** A popover, so it is in the top layer. A tour points
- *   at things inside dialogs, inside scrollers, inside anything with a stacking
- *   context, and a panel in the ordinary flow loses to all three.
- * - **When it shows.** Which is `current`, and which the root decides.
- *
- * What it does not own is the heading, the paragraph, the picture and the
- * layout. Slot a `helix-card`, or a heading and a line of prose, or anything
- * else. Fixed `title` and `body` parts would be a component deciding what a
- * tour is allowed to say.
- *
- * **The buttons are slot fallback, so the common case costs nothing and the
- * uncommon one is possible.** Write nothing and get Back, Next and Skip already
- * wired. Slot `actions` and they are yours, driven by `next()`, `back()` and
- * `skip()` on the root, which are public for exactly that.
- *
- * **`for` is an id, the same as `Tooltip`'s.** The target is elsewhere on the
- * page, and an id is the one reference a consumer can write in markup without
- * holding an element. Resolved against the root node, so a stop inside a shadow
- * tree points at a target in that tree.
- *
- * @since 0.1.0
- * @status experimental
- * @category overlays
- * @documentation https://helix.fusion.dev/components/tour
- *
- * @slot - What this stop says. A card, a heading and a line, anything.
- * @slot actions - Replaces the controls, which are Back, Next and Skip.
- *
- * @event {HelixTourAskEvent} helix-tour-ask - A stop asking the tour to move, from its own controls.
- *
- * @csspart actions - The row the controls sit in.
- * @csspart arrow - The point, which the floating pass places against the target.
- * @csspart back - The control that goes to the previous stop.
- * @csspart back-button - The inner control.
- * @csspart bubble - The panel that points at the target.
- * @csspart content - The region holding the slotted content.
- * @csspart next - The control that goes on, and finishes on the last stop.
- * @csspart next-button - The inner control.
- * @csspart skip - The control that leaves the tour.
- * @csspart skip-button - The inner control.
- */
 let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Label for the control that goes back.
-         */
         this.backLabel = 'Back';
-        /**
-         * Whether this is the stop the reader is on.
-         *
-         * Written by the root rather than by a consumer, which is the one place this
-         * family writes onto markup it does not own. It is acceptable here for a
-         * reason that did not hold for the trail or the avatar group: a tour starts
-         * closed, so there is no server state to get wrong. The server renders a
-         * closed tour, a closed tour shows nothing, and nothing can disagree.
-         */
         this.current = false;
-        /**
-         * Label for the control that goes on from the last stop.
-         */
         this.doneLabel = 'Done';
-        /**
-         * Whether this is the first stop, so there is nowhere back to.
-         */
         this.first = false;
-        /**
-         * The id of the element this stop is about.
-         */
         this.for = '';
-        /**
-         * Whether this is the last stop, so the control says Done.
-         */
         this.last = false;
-        /**
-         * Label for the control that goes on.
-         */
         this.nextLabel = 'Next';
-        /**
-         * Which side of the target the panel prefers.
-         */
         this.placement = 'bottom';
-        /**
-         * Label for the control that leaves the tour.
-         */
         this.skipLabel = 'Skip';
         this.floating = new PopoverController(this, {
             anchor: () => this.target,
             arrow: () => this.renderRoot?.querySelector('[part="arrow"]'),
-            /* A press outside does not end a tour, and this is the decision rather than
-               a stub. Everywhere else a surface closes on an outside press because
-               pressing elsewhere means the reader is finished with it. Here elsewhere
-               is the thing being pointed at: the scrim lets the pointer through on
-               purpose, so the first press a reader makes on the button the tour is
-               describing would be the press that ends the tour. Leaving is the skip
-               control and `Escape`, both of which say so. */
             onDismiss: () => { },
             placement: () => this.placement,
             surface: () => this.renderRoot?.querySelector('[part="bubble"]'),
         });
     }
-    /** The element this stop is about, or null where the id resolves to nothing. */
     get target() {
         const scope = this.getRootNode();
         return this.for === '' ? null : (scope.getElementById?.(this.for) ?? null);
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* `group`, not `dialog`, and this is a decision rather than a shortcut. A
-           tour must not trap focus: the reader has to be able to look at the thing
-           being pointed at, and an overlay that will not let them has hidden its
-           own subject. */
         hostAria(this.internals, { role: 'group' });
     }
     updated(changed) {
         super.updated(changed);
-        /* Shown and hidden from here rather than by a controller reading a
-           property, because `current` is written onto this element by the root and
-           is not a property this element decides. The controller does the top layer
-           and the placement; when is ours. */
         if (this.current) {
             this.floating.show();
         }
@@ -148,15 +45,6 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
             this.floating.hide();
         }
     }
-    /**
-     * Skip, back and next, behind a seam the styled tier can move.
-     *
-     * They are slot fallback rather than markup a consumer has to write, so a
-     * tour with nothing slotted still has the three controls a tour needs; and
-     * they are a method as well, so a tier above can render its own three without
-     * reimplementing the panel around them. Both are needed: the slot is for the
-     * consumer and the method is for the tier.
-     */
     renderActions() {
         return html `<slot name="actions">
       <${this.tag('button')}
@@ -187,14 +75,7 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
     }
     render() {
         return html `<div part="bubble" popover="manual" ?hidden=${!this.current}>
-      ${
-        /* The one surface in this library that draws an arrow, and every other
-           one deliberately does not. A menu or a select hangs off its trigger
-           and adjacency says what it belongs to; a tour panel is anchored to
-           something it did not open, on a page full of other things, and
-           collision may flip it to the far side of its target. Leaving arrows
-           off elsewhere is house style rather than a fact about the system. */
-        ''}
+      ${''}
       <div part="arrow" aria-hidden="true"></div>
       <div part="content"><slot></slot></div>
       <div part="actions">
@@ -202,13 +83,6 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
       </div>
     </div>`;
     }
-    /**
-     * Says what the reader pressed and lets the root decide.
-     *
-     * A stop cannot move a tour: it does not know what is after it, and a stop
-     * that reached up to its parent to find out would be a stop that only works
-     * inside one. Composed, so the root hears it through its own slot.
-     */
     ask(what) {
         this.dispatchEvent(new HelixTourAskEvent({ what }));
     }

package/dist/tree/item/tree-item.js

@@ -9,141 +9,23 @@ import { caretDown } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary One node in a tree.
- *
- * @description
- * **`open`, on `MixinControllerOpen`, rather than a bare boolean of its own.** A
- * branch showing its children is the same state a disclosure holds, and
- * `AccordionItem` is on that mixin too. A hand-written toggle announces nothing,
- * so a consumer can neither know a branch opened nor own the state.
- * `aria-expanded` is still what the row renders, because that is the attribute a
- * tree uses; the property is what differs, not the semantics.
- *
- * An element rather than a slot because it owns state: whether it is open,
- * whether it is selected, and whether it is the one holding focus.
- *
- * A branch is any item with something slotted into `children`, detected in
- * `firstUpdated` rather than declared by the consumer. That is a client-side
- * enhancement by necessity, since the server cannot inspect children, so the
- * server renders the node as a leaf and the twisty appears on hydration. It
- * appears rather than disappearing, which is the harmless direction.
- *
- * **`href` makes the row itself the link.** A tree used as navigation is a list
- * of links, and the row is what a reader presses: with the anchor slotted into
- * the name instead, everything outside the words is dead, Enter does nothing,
- * and there is no middle-click, no status bar and no open-in-new-tab. Given an
- * `href` the row *is* an `<a>`, so the platform provides all of that and the
- * keyboard needs no handler at all.
- *
- * It changes the shape of the ARIA, which is why it is a property and not the
- * default. An anchor cannot contain the group, since the group holds more
- * anchors and nesting them is invalid, so the row carries `treeitem` and the
- * group becomes its sibling under a presentational wrapper. That is exactly the
- * navigation flavor of the tree pattern, and the arrangement without an `href`
- * stays as it was: `treeitem` containing `group`, which is what an `<li>`
- * holding a `<ul>` is.
- *
- * A consumer whose framework owns routing slots its own link instead and leaves
- * `href` unset. The row follows that one too, so the whole row works either
- * way; what the anchor adds is what only a real anchor can give.
- *
- * 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
- * @aliases TreeNode, Branch, Leaf
- * @documentation https://helix.fusion.dev/components/tree
- *
- * @slot - The item's label.
- * @slot children - Nested items, which make this a branch.
- * @slot end - After the label, at the row's far side. A count, or a state.
- * @slot start - Before the label, after the chevron. A mark about the item.
- *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before a branch closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before a branch opens, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart group - The container for nested items.
- * @csspart item - The node, and the focus target unless `href` moves it to the row.
- * @csspart label - The label text.
- * @csspart row - The clickable label row, which is an `<a>` where `href` is set.
- * @csspart toggle - The expand and collapse control.
- *
- * @cssproperty --tree-level - How deep this row sits, counting from zero, for the indent.
- */
 let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Where this node goes, which makes its row a real link.
-         *
-         * Unset by default, and unreflected: a tree of choosable nodes is not a tree
-         * of links, and an empty `href` written onto every row would be a link to the
-         * current page on every item a consumer never asked to be one.
-         */
         this.href = '';
-        /**
-         * What the link declares about where it goes.
-         *
-         * Set by the consumer rather than derived from `target`: `noreferrer` is a
-         * decision about their own analytics and a component should not make it for
-         * them. `noopener` is not needed as a default either, since every browser
-         * this library supports implies it for `target="_blank"` already.
-         */
         this.rel = '';
-        /**
-         * Whether this item is the current one.
-         *
-         * Not reflected, for the reason `level` below gives in full: the tree assigns
-         * this after it upgrades, so the attribute would be a change to markup the
-         * consumer rendered and hydration would report it. Mirroring to
-         * `data-selected` on the host instead is the same fault under another name.
-         *
-         * The stylesheet reads it from the row inside this shadow root, because the
-         * row is not part of the tree React hydrates.
-         */
         this.selected = false;
-        /**
-         * Where the link opens, for the rare row that leaves the site.
-         */
         this.target = '';
-        /**
-         * Identifies the item to the consumer, carried in `helix-select`.
-         */
         this.value = '';
-        /**
-         * Whether this item holds the tree's single tab stop.
-         */
         this.focusable = false;
-        /**
-         * Whether anything is slotted into `children`.
-         *
-         * Read after first render.
-         */
         this.branch = false;
         this.handleToggleClick = (event) => {
-            /* Only where the row is a link, and then it has to stop: the row would
-               navigate away from the branch the reader was trying to open. Without an
-               `href` the whole row toggles, which is what a tree of folders wants, so
-               there is nothing here to intercept. */
             event.preventDefault();
             event.stopPropagation();
             this.toggleOpen();
         };
         this.handleRowClick = (event) => {
-            /* A press that landed on a link is that link's, whichever branch of this
-               runs, and the test has to be made on both sides. A row can hold a link in
-               its `end` slot, and asked on one side only, pressing that link collapses
-               the branch on the way out: one press, `open` false and the route
-               changed. */
             const onLink = event.composedPath().some((node) => node instanceof HTMLAnchorElement);
-            /* A branch that is also a link goes where it points, and its chevron is
-               what opens it. A branch that is not toggles from anywhere in the row. */
             if (this.branch && this.href === '') {
                 if (!onLink) {
                     this.toggleOpen();
@@ -151,8 +33,6 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
                 return;
             }
             this.select();
-            /* Following it here as well would follow it twice and, where a consumer's
-               router is listening, route twice. */
             if (!onLink) {
                 this.follow();
             }
@@ -166,74 +46,22 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
             this.branch = slot.assignedElements().length > 0;
         });
     }
-    /**
-     * @internal Read by the tree to identify a branch across the light DOM,
-     * which is cheaper than `instanceof` and is why this is public rather than
-     * protected. A consumer asks `branch`, which is the property they set.
-     */
     get isBranch() {
         return this.branch;
     }
-    /**
-     * Moves focus to this node.
-     *
-     * Which element that is moves with `href`: the thing carrying `treeitem` is
-     * the thing the tree's roving tab stop lives on, and with a link that is the
-     * row rather than the wrapper around it.
-     */
     focusItem() {
-        /* `preventScroll`, because the browser's own answer to a focus is to walk
-           every scrollable ancestor and reveal the element, which is
-           `scrollIntoView` by another route and takes the page with it. The root
-           calls `scrollItemIntoView` on the next line precisely to avoid that, and
-           without this the careful call arrives after the thing it exists to
-           prevent has already happened. */
         this.renderRoot
             .querySelector(this.href === '' ? '[part="item"]' : '[part="row"]')
             ?.focus({ preventScroll: true });
     }
-    /** Selects this node and announces it. */
     select() {
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
-    /**
-     * Chooses this node the way a reader does, from a press or from Enter.
-     *
-     * Selecting and following are two things and this is where they meet, so the
-     * pointer and the keyboard take one path to the same end. The tree calls this
-     * rather than `select` for the keyboard, or a nav tree whose rows are links
-     * could be walked with the arrows and never entered: choosing announces a
-     * value and nothing listens for it.
-     */
     activate() {
         this.select();
         this.follow();
     }
-    /**
-     * Follows a link slotted into the name, if there is one.
-     *
-     * A row is wider than the words in it: the indent, the padding, and with the
-     * chevron at the far end most of the row's width are all outside the anchor,
-     * so a reader who pressed the row anywhere but on the text got nothing. The
-     * words are the consumer's own content and this does not rewrite them, so
-     * what it does instead is press the link they put there.
-     *
-     * The consumer's anchor rather than an `href` of this element's own,
-     * deliberately: a framework's link component is what carries prefetching and
-     * client-side routing, and a plain `<a href>` rendered in here would be a
-     * full page load on a site that had neither. A synthetic click is what those
-     * components listen for, so both keep working.
-     *
-     * `querySelector` on the light DOM, not the render root: the link is the
-     * consumer's, and it is scoped to this item's own name rather than to the
-     * whole subtree, or a branch would follow the first link belonging to one of
-     * its children.
-     */
     follow() {
-        /* Its own row first, where `href` made one. Pressed with a pointer the
-           anchor has already navigated and this never runs; from the keyboard it
-           has not, because the tree calls `preventDefault` on every key it handles
-           and that is what would otherwise swallow Enter on a link. */
         const own = this.renderRoot?.querySelector('a[part="row"]');
         if (own) {
             own.click();
@@ -250,7 +78,6 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
             }
         }
     }
-    /** Everything inside the row, which is the same whichever element it is. */
     renderRow() {
         return html `${this.branch
             ? html `<svg
@@ -267,36 +94,11 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
       <span part="label"><slot></slot></span>
       <slot name="end"></slot>`;
     }
-    /**
-     * Mirrors the chosen state where a stylesheet can select on it.
-     *
-     * **A custom state, never a reflected `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-tree-item selected>` in a consumer's
-     * markup means. What stops is the write back.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('selected', this.selected);
     }
     render() {
-        /* Where the semantics sit, which `href` decides.
-         *
-         * A link row carries them itself and the wrapper drops to `none`, because
-         * an anchor cannot contain the group: the group holds more anchors and
-         * nesting them is invalid markup that no assistive technology reads the way
-         * it looks. So the row becomes the `treeitem` and the group becomes its
-         * sibling, which is the navigation flavor of the pattern.
-         *
-         * Without one, nothing changes: the wrapper is the `treeitem` and holds the
-         * group, which is what an `<li>` holding a `<ul>` is. */
         const linked = this.href !== '';
         const level = this.level ?? 1;
         const expanded = this.branch ? (this.open ? 'true' : 'false') : nothing;