@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/option/root/option-root.js

@@ -7,156 +7,24 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, HelixSelectEvent } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary One choice in a listbox.
- *
- * @description
- * **Its own family rather than a part of Select, and the reason is what it
- * belongs to.** `role="option"` requires an owning `role="listbox"`, which is
- * the ARIA contract: an option cannot stand alone. But a Select is *a listbox
- * with a trigger*, a Combobox is *a listbox with a text input*, and a command
- * palette is the same listbox again. The thing an option belongs to is the
- * listbox, not any one control that happens to contain one.
- *
- * That is the difference from `Radio`, which is a part of its group: a radio
- * has exactly one kind of owner, and an option has several.
- *
- * Selection is announced rather than applied, the way a radio's is. The option
- * says it was chosen, the listbox decides whether that stands, and the listbox
- * writes `selected` back. An option that selected itself would be a second
- * answer to which one is chosen.
- *
- * **Nothing here knows about filtering.** A hidden option is hidden by whatever
- * owns it, through `hidden`, because what counts as a match is the listbox's
- * question and differs between a select and a command palette.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Item, Choice
- * @documentation https://helix.fusion.dev/components/option
- *
- * @slot - The words naming this choice.
- * @slot end - After them, for a shortcut or a count.
- * @slot start - Before the words, for an icon or an avatar.
- *
- * @event {HelixSelectEvent} helix-select - Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart description - The caption under the words, when there is one.
- * @csspart item - The row.
- * @csspart label - The words.
- * @csspart text - The words and the caption under them, as one column.
- */
 let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether this is the option the keyboard is on.
-         *
-         * Written by the listbox.
-         */
         this.active = false;
-        /**
-         * A second destination for this row, taken with the modifier held.
-         *
-         * **An attribute rather than a second row, which is the whole point.** A
-         * palette of eighty-eight components that offered each of them a reference
-         * page and a sandbox as separate entries would be a palette of a hundred and
-         * seventy-six, and one earns its keep by getting a reader to one thing in
-         * three keystrokes. The row already carries the first destination, so the
-         * second belongs beside it.
-         *
-         * Declared here and acted on by whatever owns the list, the same division
-         * selection already uses: an option says what it is and the listbox decides
-         * what happens. `Command` is the only owner that reads it today, because a
-         * select has one destination by definition.
-         *
-         * Absent is a row with one destination, which is nearly every row.
-         */
         this.alternate = '';
-        /**
-         * What the second destination is, for a reader who cannot see the footer.
-         *
-         * A row with two destinations needs both said, or a screen reader is told
-         * about one of them and the other is a key nobody mentioned. It goes to
-         * `aria-description` rather than into the name: the name is the row's own
-         * words and stays what a reader searched for, and the second destination is a
-         * fact about what pressing a key would do, which is what a description is.
-         */
         this.alternateLabel = '';
-        /** What the markup said, read once at construction for the reason above. */
         this.seeded = this.hasAttribute('selected');
-        /**
-         * Whether this choice can be made.
-         */
         this.disabled = false;
-        /**
-         * A shorter name for this choice, for where the row does not fit.
-         *
-         * `<option label>`'s own meaning: the text a chooser shows when it has less
-         * room than the row does, which is what a select's closed trigger has. Empty
-         * means the row's own content, which is the common case and is why this is not
-         * simply the accessible name.
-         */
         this.label = '';
-        /**
-         * Whether this choice is currently chosen.
-         *
-         * Written by the listbox.
-         */
         this.selected = false;
-        /**
-         * Identifies this choice, and is what a form submits.
-         */
         this.value = '';
     }
-    /**
-     * Whether the markup declared this one chosen, which is what a reset returns to.
-     *
-     * `<option selected>` reflects to `defaultSelected` and `option.selected` is
-     * live state that does not reflect, and those are two different facts. This
-     * element has one `selected` doing both jobs, so what is captured here is what
-     * the markup said at upgrade, before anything could overwrite it: read the
-     * attribute later and the listbox's own writes answer instead.
-     *
-     * **The deeper half is 302 and is not this.** State reflecting under the
-     * declaration's name is the fault `TreeItem` already avoids by mirroring to
-     * `data-selected`, and four families here still write `selected` back into a
-     * consumer's markup. 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;
     }
-    /**
-     * The words, for a listbox that has to match text against them.
-     *
-     * Read from the rendered content rather than required as a property, because
-     * the content is where a consumer naturally puts it and asking for both is
-     * asking for two things to disagree.
-     *
-     * **The default slot's content, never `this.textContent`.** An option holds
-     * three slots: the words, plus `start` for an icon and `end` for a shortcut
-     * or a count. Neither of the latter two is what a reader searched for, and
-     * `textContent` runs both onto the end of it. Measured on a font picker whose
-     * options carry a two-letter specimen in `end`: the field read
-     * `Noto Sans Linear BAg`, and typing `ag` matched 1,892 of 1,893 options,
-     * every row containing the sample. An option with a keyboard shortcut in its
-     * end slot has the same fault and a worse one, every row carrying one matching
-     * every letter of it.
-     *
-     * Six things read this: the collapsed field of Select and of Combobox, the
-     * listbox's filter, Combobox's match against typed text, its inline
-     * completion, and the label on a chosen tag.
-     *
-     * A node goes to the default slot when it names no other, which is the rule
-     * the platform applies at assignment. Asking the same question here rather
-     * than a second one is what stops the two disagreeing. Text nodes are
-     * always the default slot's and cannot say otherwise.
-     */
     get text() {
         return [...this.childNodes]
             .filter((node) => !(node instanceof Element) || node.slot === '')
@@ -164,47 +32,22 @@ let HelixHeadlessOption = class HelixHeadlessOption extends HelixElement {
             .join('')
             .trim();
     }
-    /** Makes this choice and announces it. */
     select() {
         if (this.disabled) {
             return;
         }
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
-    /**
-     * Mirrors the chosen state where a stylesheet can select on it.
-     *
-     * **A custom state, and never 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-option selected>` in a consumer's
-     * markup means. What stops is the write back.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('selected', this.selected);
     }
     render() {
-        /* `role` and `aria-selected` on the host through internals, because an
-           option's semantics have to be visible to the listbox that owns it and a
-           wrapper in here would put a box between them. */
         this.internals.role = 'option';
         this.internals.ariaSelected = String(this.selected);
         this.internals.ariaDisabled = this.disabled ? 'true' : null;
         this.internals.ariaDescription =
             this.alternate !== '' && this.alternateLabel !== '' ? this.alternateLabel : null;
-        /* A pointer reaches `select()` the way every other choosable row in this
-           library does, from a `@click` in its own template: `Tabs.Tab`,
-           `Tree.Item` and `Menu.Item` all bind one. Nothing else listens for a click
-           on an option, so removing this leaves a select the keyboard can use and a
-           pointer cannot. A spec that chooses by calling `select()` or by pressing a
-           key cannot tell the difference. */
         return html `<div part="item" @click=${() => this.select()}>
       <slot name="start"></slot>
       <span part="text">

package/dist/outline/root/outline-root.js

@@ -7,129 +7,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixBeforeActivateEvent, HelixElement, IndicatorController, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * @summary Links to the headings on this page, marking the one being read.
- *
- * @description
- * A table of contents, named for the job. It sits beside `Navigation`, which is
- * the same job at the other scale: one navigates a site, the other navigates a
- * document. `Contents` and `TableOfContents` are both taken by something else,
- * `display: contents` and the `content` part in one case and the `Table` family
- * in the other.
- *
- * **The links are the consumer's own anchors**, the same as `Navigation`. A router
- * renders its own `<a>` and cannot render one inside this shadow root, and the
- * hrefs are fragments the page already knows.
- *
- * **What is current is decided by position, not by intersection.** The obvious
- * build is an `IntersectionObserver` with a thin band near the top of the
- * window, and it fails in both directions: with headings far apart nothing is
- * in the band and the marker goes out entirely, and with headings close
- * together several are and it flickers between them. So the observer is only
- * the *trigger*, and the answer is computed from where the headings actually
- * are: the current section is the last one whose top has passed the reading
- * line, or the first heading before any of them has.
- *
- * That rule is what a reader means. Two headings on screen at once are not
- * ambiguous to a person: they are reading under the upper one.
- *
- * **`aria-current="location"`, and it is written onto the consumer's anchor.**
- * This library does not normally write to light-DOM children, because an
- * attribute added after upgrade is one a server's markup never had. It is right
- * here for the reason `Carousel` names its slides: what is current is derived
- * from scroll position, so no server could have rendered it and there is
- * nothing for hydration to disagree with. `location` rather than `page`, which
- * is what `Navigation` uses: `page` means this is the page, and every one of these
- * is the same page.
- *
- * @since 0.1.0
- * @status experimental
- * @category navigation
- * @aliases Table of contents, On this page, Outline
- * @documentation https://helix.fusion.dev/components/outline
- *
- * @slot - The links, as anchors with fragment hrefs.
- *
- * @event {HelixBeforeActivateEvent} helix-before-activate - The section being read has changed, carrying its id as the value. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart indicator - The mark that travels to the section being read.
- * @csspart nav - The navigation landmark.
- */
 let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     constructor() {
         super(...arguments);
-        /* The mark. Vertical, which the controller needs no telling about: it writes
-           all four values and the stylesheet uses the two it cares about. */
         this.indicator = new IndicatorController(this, {
             active: () => this.links.find((link) => link.hasAttribute('aria-current')),
             indicator: () => this.renderRoot?.querySelector('[part="indicator"]'),
             surface: () => this.renderRoot?.querySelector('[part="nav"]'),
         });
-        /**
-         * How a click on one of these links travels to its section.
-         *
-         * The platform's own vocabulary, because this is the platform's own option:
-         * `auto` defers to whatever `scroll-behavior` the page has set on its scroll
-         * container, which is the honest default and means an outline changes nothing
-         * a consumer did not ask it to. `smooth` slides, `instant` jumps.
-         *
-         * **`auto` is also the only value that leaves the navigation to the browser.**
-         * A fragment link does four things: it scrolls, it writes the hash, it pushes
-         * a history entry, and it moves the sequential focus point so the next Tab
-         * continues from the heading rather than from the link. Choosing a behavior
-         * means intercepting the click, and an interception that does only the first
-         * of those is a keyboard reader stranded in the contents list. So the other
-         * three are done by hand here, and only when there is a reason to take over.
-         *
-         * `smooth` becomes `instant` under `prefers-reduced-motion: reduce`. That is
-         * read at the click rather than cached, because a reader can change it while
-         * the page is open and this is the only motion in the component that
-         * JavaScript rather than CSS decides.
-         */
         this.behavior = 'auto';
-        /**
-         * Accessible name for the navigation.
-         */
         this.label = 'On this page';
-        /**
-         * How far below the top of the window a heading counts as reached, in pixels.
-         *
-         * The reading line. A page with a sticky masthead sets this to its height, or
-         * a little more: without it the current section changes as a heading slides
-         * under the chrome rather than as it reaches the top of what can be seen.
-         */
         this.offset = 0;
-        /**
-         * What `current` reports, which only `mark` writes.
-         */
         this.reading = '';
-        /** The frame a mark is already scheduled for, so a scroll asks for one. */
         this.frame = 0;
-        /**
-         * The two things an `IntersectionObserver` cannot see, and one listener for
-         * both.
-         *
-         * *At the bottom*, arriving at the end of a page changes no intersection: a
-         * short last section is fully visible long before the final pixel, so its
-         * ratio reached 1 and stopped moving. Nothing fires for the scroll that ends
-         * the page.
-         *
-         * *And at the end of a smooth scroll*, which is the one that showed up in
-         * use. Clicking a link in the contents list scrolled to the section and left
-         * the mark where it was. Measured on the shipped example: after clicking
-         * `#usage` the heading sat at 72px, exactly the reading line, and `current`
-         * was still `install`. The observer fires several times during the travel and
-         * the last of them lands a frame or two before the final position, where the
-         * heading has not crossed yet, and no callback follows for the rest of the
-         * way.
-         *
-         * Marking once per animation frame while a scroll is happening covers both,
-         * where a listener that marks only when its own comparison changes fixes the
-         * bottom and cannot fix the settle. The cost is what `mark()` costs, a
-         * `getBoundingClientRect` per section on frames a reader is already scrolling
-         * through. Passive, and coalesced to one call per frame however many events
-         * arrive.
-         */
         this.handleScroll = () => {
             if (this.frame !== 0) {
                 return;
@@ -139,13 +29,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
                 this.mark();
             });
         };
-        /**
-         * Takes a link's click, but only where `auto` would not have done the job.
-         *
-         * Left the platform's wherever it can be: a modified click is a new tab or a
-         * download and none of this applies, a click something else has already
-         * handled is not ours, and `auto` is the whole point of `auto`.
-         */
         this.handleClick = (event) => {
             if (event.defaultPrevented || event.button !== 0) {
                 return;
@@ -158,23 +41,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             if (!section) {
                 return;
             }
-            /* The destination is marked now, and everything between here and there is
-             * not.
-             *
-             * The marker follows the scroll, which is right when a reader is scrolling
-             * and wrong when they have said where they are going: traveling to the
-             * fifth section passes the second, third and fourth, each became current
-             * for a frame or two on the way, and the mark stepped down the list one
-             * item at a time instead of making the journey.
-             *
-             * Suppressed for any click on one of these links, not only the ones this
-             * component scrolls itself: a consumer with `scroll-behavior: smooth` on
-             * their own scroll container gets the same travel and the same stepping,
-             * and `behavior="auto"` does not mean "nobody is animating".
-             *
-             * `landing` is cleared when the page stops moving, by the same `scrollend`
-             * and timeout pair the mark uses elsewhere, because a scroll that is
-             * interrupted by a reader grabbing the page has to hand the marker back. */
             this.landing = section;
             this.markTo(section);
             clearTimeout(this.landed);
@@ -195,11 +61,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
                 behavior: reduced && this.behavior === 'smooth' ? 'instant' : this.behavior,
                 block: 'start',
             });
-            /* The three things the anchor would have done and the scroll does not. The
-               history entry keeps Back working and the address bar copyable; the focus
-               move is what stops Tab continuing from the contents list. `preventScroll`
-               because the scroll above is already under way and focusing would fight it,
-               instantly, wherever `smooth` was asked for. */
             globalThis.history?.pushState(null, '', link?.getAttribute('href') ?? '');
             const target = section.target;
             if (!target.hasAttribute('tabindex')) {
@@ -207,70 +68,28 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             }
             target.focus({ preventScroll: true });
         };
-        /**
-         * The set changed: watch it, and measure it.
-         *
-         * Both, for the reason the tab strip records: the host renders before its
-         * links have anything to point at, so the first measurement finds nothing,
-         * and without a second one at `slotchange` the mark stays unplaced for the
-         * life of the page.
-         */
         this.handleSlotChange = () => {
             this.watch();
             this.indicator.place();
         };
     }
-    /**
-     * The id of the section being read, or empty before anything is measured.
-     *
-     * Read-only, and a getter rather than a property for that reason: it is
-     * derived from where the page is scrolled to, so a consumer setting it would
-     * be overwritten by the next thing that crossed the reading line. Every other
-     * writable property in this library that a component also writes is state a
-     * consumer can own; this one cannot be, and saying so with the type is better
-     * than saying it in a sentence nobody reads.
-     */
     get current() {
         return this.reading;
     }
-    /** The links, in document order. Empty on the server, which has no tree. */
     get links() {
         const slot = this.renderRoot?.querySelector('slot');
         return (slot?.assignedElements({ flatten: true }) ?? []).filter((element) => element instanceof HTMLAnchorElement &&
             element.getAttribute('href')?.startsWith('#') === true);
     }
-    /** What each link points at, paired with the link, skipping anything missing. */
     get sections() {
         const root = this.getRootNode();
         return this.links.flatMap((link) => {
             const id = decodeURIComponent(link.getAttribute('href')?.slice(1) ?? '');
             const target = id ? root.getElementById?.(id) : null;
-            /* A section that is not rendered is not one that can be read.
-             *
-             * `display: none` reports a zero rect, and zero is above the reading line,
-             * so an unrendered section counts as passed on every measurement and the
-             * marker lands on the last one of them. Found on a reference page that
-             * shows one API tier at a time and hides the other: the rail marked a
-             * heading the reader could not see, and no scrolling could move it,
-             * because the hidden sections always won the comparison.
-             *
-             * `getClientRects()` rather than a size check, because it is empty for
-             * exactly the case in question and non-empty for a section that is merely
-             * scrolled out of view, which is very much readable. */
             return target && target.getClientRects().length > 0 ? [{ link, target }] : [];
         });
     }
-    /**
-     * Works out which section is being read, and marks its link.
-     *
-     * Positional rather than a reading of what intersects, for the reason above.
-     * The comparison is against `offset` and not zero, so the reading line is
-     * wherever the page says the top of the readable area is.
-     */
     mark() {
-        /* A destination beats a measurement. See `handleClick`: while the page is
-           traveling to somewhere a reader asked for, what it passes on the way is
-           not what they are reading. */
         if (this.landing) {
             return;
         }
@@ -279,31 +98,9 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             return;
         }
         const passed = sections.filter(({ target }) => target.getBoundingClientRect().top - this.offset <= 1);
-        /* At the end of the page the last section is what is being read, whether or
-           not its top ever reached the reading line.
-         *
-         * The positional rule has one blind spot and it is at the bottom: a section
-         * is current once its top passes the line, and a section near the end of the
-         * document may not have enough page beneath it to get there. Measured on
-         * three sections with a short last one, scrolled fully to the end, 910 of
-         * 910: the third heading sat at 530px, plainly on screen and plainly the
-         * thing being read, and the marker stayed on the second. The last item in a
-         * contents list was unreachable by scrolling.
-         *
-         * There is no mirror of it at the top: `passed` is empty there and the first
-         * section is already the fallback, and the first heading's top starts *at*
-         * the line rather than below it, so there is nothing for it to fail to
-         * reach.
-         *
-         * What this cannot do is tell trailing sections apart. If the last three
-         * share the final screenful, none of them can reach the line and the page
-         * has no scroll left to distinguish them, so all three collapse into "you
-         * are at the end". That is a fact about the page rather than a choice made
-         * here: the component cannot invent room to scroll. */
         const active = this.atEnd ? sections.at(-1) : (passed.at(-1) ?? sections[0]);
         this.markTo(active);
     }
-    /** Where the destination is set, whether measured or asked for. */
     markTo(active) {
         for (const { link, target } of this.sections) {
             if (target === active?.target) {
@@ -313,41 +110,12 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
                 link.removeAttribute('aria-current');
             }
         }
-        /* And say so. `reading` is derived from scroll position, which is the one
-         * fact this component computes that nothing else on the page can, so a
-         * consumer syncing a URL hash to it has no other way in short of a
-         * `MutationObserver` on the anchors.
-         *
-         * Only on a change, because this runs from a scroll frame and an event per
-         * frame is not a signal, it is a firehose. */
         const next = active?.target.id ?? '';
         if (next !== this.reading) {
             this.reading = next;
             this.dispatchEvent(new HelixBeforeActivateEvent({ value: next }));
         }
     }
-    /**
-     * Whether the page has no more scroll left.
-     *
-     * `Math.ceil` and a pixel of slack, because a fractional device pixel ratio
-     * leaves the position a hair under the height at the very bottom and an exact
-     * comparison never fires.
-     *
-     * **All three numbers off the same element.** Adding the window's `scrollY`
-     * and `innerHeight` and comparing them against
-     * `documentElement.scrollHeight` mixes two coordinate systems, which agree
-     * only while the viewport is what scrolls, and the body takes that job the
-     * moment it becomes a scroll container. Measured on a page whose body is
-     * `overflow: clip visible`, which is a pair CSS resolves by making the
-     * `visible` axis `auto`: `documentElement.scrollTop` read 1126 at the bottom
-     * of the page and `window.scrollY` read 240, so a contents rail never learned
-     * it had reached the end and its last item stayed unreachable. This library's
-     * own base layer produces exactly that page.
-     *
-     * `clientHeight` rather than `innerHeight` for the same reason, and because it
-     * is the one that excludes a scrollbar, which is what `scrollHeight` is
-     * measured against.
-     */
     get atEnd() {
         const doc = globalThis.document?.scrollingElement ?? globalThis.document?.documentElement;
         if (!doc) {
@@ -355,49 +123,14 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         }
         return Math.ceil(doc.scrollTop + doc.clientHeight) >= doc.scrollHeight - 1;
     }
-    /**
-     * Gives every section the same reading line the marker uses.
-     *
-     * `offset` says where the top of the readable area is, so it has to govern
-     * where a click lands as much as what the marker calls current. Read by the
-     * marker alone, a click puts the heading against the very top of the window
-     * and underneath the sticky masthead the consumer measured the offset from,
-     * which is the same number meaning two things.
-     *
-     * `scroll-margin-block-start` rather than an interception, because it is the
-     * property the platform provides for exactly this and the UA honors it on
-     * ordinary fragment navigation, on `scrollIntoView`, and on a browser
-     * restoring a position. Nothing has to be taken over to get it.
-     *
-     * Written onto the consumer's element, like `aria-current` above and for the
-     * same reason: it is derived from a property describing the page's chrome,
-     * so no server rendered it and there is nothing to disagree with. Cleared
-     * rather than set to `0px` when there is no offset, so the common case leaves
-     * no attribute at all.
-     */
     reach() {
         for (const { target } of this.sections) {
             const element = target;
             element.style.scrollMarginBlockStart = this.offset > 0 ? `${this.offset}px` : '';
         }
     }
-    /**
-     * Watches every section, and re-marks whenever any of them crosses anything.
-     *
-     * The thresholds are what make the trigger frequent enough: an observer fires
-     * on entering and leaving, and a long section scrolled slowly crosses neither
-     * for a long time. Asking for a callback at each quarter of visibility is
-     * cheap. It is still only a trigger: see `handleScroll` for the two cases no
-     * intersection can see.
-     */
     watch() {
         this.observer?.disconnect();
-        /* Nothing to watch yet is not nothing to watch ever. A page whose sections
-         * arrive after the nav does, which is every page rendering its content
-         * asynchronously, resolves no href at first update, and returning here
-         * without leaving a way back kills the component for the life of the page.
-         * `updated` re-runs this while `observer` is undefined, which is why the
-         * field is cleared rather than left holding a disconnected observer. */
         if (this.sections.length === 0) {
             this.observer = undefined;
             return;
@@ -423,9 +156,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         this.observer = undefined;
         this.resize?.disconnect();
         this.resize = undefined;
-        /* The landing timer holds a closure over this element for 1.2 seconds after
-           it leaves the document and then touches it, which on a route change is a
-           write to a tree nobody is looking at. */
         clearTimeout(this.landed);
         this.landed = undefined;
     }
@@ -433,13 +163,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         super.connectedCallback();
         this.addEventListener('click', this.handleClick);
         globalThis.addEventListener?.('scroll', this.handleScroll, { passive: true });
-        /* Both observers are rebuilt on reconnection. `firstUpdated` runs once for
-         * the life of the element and `disconnectedCallback` runs every time it
-         * moves, so without this an outline moved in the DOM, which a framework does
-         * on any reorder, comes back permanently frozen: `aria-current`, `current`
-         * and the traveling mark all stop for the rest of the page's life with
-         * nothing to say why. Guarded on `hasUpdated`, because the first connection
-         * happens before the first render and there is nothing to watch yet. */
         if (this.hasUpdated) {
             this.watch();
             this.resize = new ResizeObserver(() => this.indicator.place());
@@ -449,33 +172,18 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.watch();
-        /* The links are text in a column, so anything that changes the column's
-           width rewraps them and moves every one below. Nothing else would notice:
-           the intersection observer watches the sections, and a resize moves the
-           links without moving the page. */
         this.resize = new ResizeObserver(() => this.indicator.place());
         this.resize.observe(this);
     }
     updated(changed) {
         super.updated(changed);
-        /* The reading line moved, so where the reader is may have changed without
-           the page having moved at all. Nothing else would notice: the observer
-           fires on sections crossing the viewport, and this changes what crossing
-           means rather than whether anything did. */
         if (changed.has('offset')) {
             this.reach();
             this.mark();
         }
-        /* Try again while there is nothing being watched. Cheap: `watch` returns on
-           the first line once it has something, and this is the only path back for
-           a nav whose sections had not rendered when it first looked. */
         if (!this.observer) {
             this.watch();
         }
-        /* After the render that applied the new `aria-current`, not inside `mark()`
-           beside the attribute write. The current link is styled differently, and
-           on a narrow column the extra weight is enough to rewrap it, so measuring
-           before the style lands measures the wrong height. */
         this.indicator.place();
     }
     render() {