@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/video-playlist/item/video-playlist-item.js

@@ -7,77 +7,13 @@ 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 entry in a video playlist.
- *
- * @description
- * **It holds what the player needs and nothing about playing.** A source, a
- * poster and a name: the entry knows which file it stands for, and the playlist
- * is what hands that to a player. Nothing here touches a `<video>`, which is
- * what keeps a playlist usable with a player the consumer configured
- * themselves.
- *
- * **A real `<button>`, in a `listitem`.** A playlist is a list of things to
- * choose, and the list roles are the honest ones: `list` and `listitem` say how
- * many there are and where you are in them, which `listbox` would too, at the
- * cost of the pattern a listbox obliges. `Option` records that trap in full,
- * that a listbox has to keep focus elsewhere and say which item is current with
- * `aria-activedescendant`. Nothing here needs that, because focus really moves
- * to the button.
- *
- * `aria-current` rather than `aria-selected`, which belongs to the roles that
- * have a selection. What is true of the entry playing now is that it is the one
- * the player is on.
- *
- * @since 0.1.0
- * @status experimental
- * @category media
- * @documentation https://helix.fusion.dev/components/video-playlist
- *
- * @slot - The entry's name.
- * @slot media - A thumbnail. Falls back to an image of `poster`.
- * @slot meta - After the name. A duration, or a date.
- *
- * @event {HelixSelectEvent} helix-select - Fired when the entry is chosen. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart container - The `listitem`, which the button sits in.
- * @csspart item - The row, which is a button.
- * @csspart label - The name and whatever follows it.
- * @csspart media - The leading column.
- * @csspart thumbnail - The image `poster` falls back to.
- */
 let HelixHeadlessVideoPlaylistItem = class HelixHeadlessVideoPlaylistItem extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the player is on this entry.
-         *
-         * Written by the playlist rather than by the entry, the way an option's
-         * selection is: an entry that made itself current would be a second answer to
-         * which one is playing.
-         */
         this.current = false;
-        /**
-         * Whether the entry can be chosen.
-         */
         this.disabled = false;
-        /**
-         * What covers the picture before this entry plays, and the row's thumbnail.
-         *
-         * One property doing both, because they are the same picture: the frame that
-         * stands for the clip stands for it in the list too. It is the `media` slot's
-         * fallback rather than something drawn beside it, which is this library's rule
-         * for a content property, so a consumer with something better to show slots it
-         * and the two can never both appear.
-         */
         this.poster = '';
-        /**
-         * The file this entry plays.
-         */
         this.src = '';
-        /**
-         * What identifies the entry, and what `active` is compared against.
-         */
         this.value = '';
         this.choose = () => {
             if (this.disabled) {
@@ -86,17 +22,6 @@ let HelixHeadlessVideoPlaylistItem = class HelixHeadlessVideoPlaylistItem extend
             this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
         };
     }
-    /**
-     * The entry's name, which is the words and not everything in it.
-     *
-     * `textContent` takes the whole subtree: a row with a duration in `meta`
-     * reads as "His Girl Friday0:06", and that string reaches the player and the
-     * lock screen. Only the nodes the consumer left unslotted are the name;
-     * anything named is a column beside it.
-     *
-     * Light DOM rather than `assignedNodes`, so it answers on the server too,
-     * where there is no slot to ask. `Option.text` reads its own the same way.
-     */
     get text() {
         return [...this.childNodes]
             .filter((node) => !(node instanceof Element) || !node.hasAttribute('slot'))
@@ -104,26 +29,12 @@ let HelixHeadlessVideoPlaylistItem = class HelixHeadlessVideoPlaylistItem extend
             .join('')
             .trim();
     }
-    /**
-     * What stands for the row: a thumbnail where there is one, and nothing where
-     * there is not.
-     *
-     * A seam rather than inline, so a tier can draw a duration badge over it or
-     * a placeholder in its place without reimplementing the row. A consumer
-     * slots `media` for the same reasons and neither has to know about the other.
-     */
     renderMedia() {
         return html `<slot name="media">
-      ${
-        // `alt=""`, because the row's own words already name it and a
-        // thumbnail repeating them is the same thing said twice.
-        this.poster === '' ? nothing : html `<img part="thumbnail" alt="" src=${this.poster} />`}
+      ${this.poster === '' ? nothing : html `<img part="thumbnail" alt="" src=${this.poster} />`}
     </slot>`;
     }
     render() {
-        /* `aria-current="true"`, and absent rather than `"false"` otherwise. A
-           reader is told which one is playing; being told about each of the others
-           that it is not playing is the same fact eleven times. */
         return html `<div part="container" role="listitem">
       <button
         part="item"

package/dist/video-playlist/menu/video-playlist-menu.js

@@ -12,91 +12,11 @@ import { html } from 'lit/static-html.js';
 import { HelixHeadlessVideoPlaylist } from '../root/video-playlist-root.js';
 import '../../menu/index.js';
 const ITEMS = 'helix-video-playlist-item, helix-headless-video-playlist-item';
-/**
- * @summary The playlist's entries, as a menu inside the player's control bar.
- *
- * @description
- * The entries again, reachable without leaving the picture. A playlist beside
- * the player is a list a reader scrolls to; the same list in the control bar is
- * one they open over the video, which is what a full-screen player has and what
- * a phone has room for.
- *
- * **It is placed by the consumer, not rendered by the playlist**, and that is
- * forced rather than chosen. A shadow root cannot project into a sibling's
- * light DOM, so nothing the playlist renders can land inside the player's
- * control bar. What can is an element the consumer writes there, which is what
- * `Video`'s `controls` slot is for:
- *
- * ```html
- * <helix-video-playlist>
- *   <helix-video slot="player" controls>
- *     <helix-video-playlist-menu slot="controls"></helix-video-playlist-menu>
- *   </helix-video>
- *   <helix-video-playlist-item value="one" src="/one.mp4">One</helix-video-playlist-item>
- * </helix-video-playlist>
- * ```
- *
- * So it finds its playlist upward rather than being handed one, and that chain
- * crosses a shadow boundary in the ordinary arrangement, which is why it is
- * `closestInstance` and not `closest`.
- *
- * **Choosing dispatches `helix-select`, the same event an entry dispatches.**
- * It never writes `active` on the playlist, which looks like the shorter path
- * and skips the cancelable request: an assignment applies the change with no
- * `helix-before-activate` for anyone to refuse. Announcing is what an entry
- * does, the playlist already listens for it, and a consumer refusing a
- * selection gets `preventDefault()` on one event rather than two paths that
- * behave differently.
- *
- * @since 0.1.0
- * @status experimental
- * @category media
- * @aliases Episode Menu, Queue Menu, Up Next
- * @documentation https://helix.fusion.dev/components/video-playlist
- *
- * @slot trigger - Replaces the button that opens the menu.
- *
- * @event {HelixSelectEvent} helix-select - Fired with the chosen entry's value. The playlist listens for it. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart entry - One entry in the menu.
- * @csspart entry-item - The row, which is an `<a>` where `href` is set.
- * @csspart entry-mark - The trailing mark: a tick when checked, a caret when it opens
- * @csspart entry-start - The leading column, which is a slot and is always there.
- * @csspart menu - The menu that holds the entries.
- * @csspart menu-back - The control that returns from a submenu.
- * @csspart menu-back-mark - The glyph on the back control of a submenu.
- * @csspart menu-empty - Shown when there are no items to show.
- * @csspart menu-header - The bar above a submenu, holding the way back and its name.
- * @csspart menu-loading - Shown while the items are still on their way.
- * @csspart menu-surface - The floating panel the menu is drawn on.
- * @csspart menu-title - The name of the submenu that is showing.
- * @csspart poster - An entry's still, where it has one.
- * @csspart trigger - The button that opens it.
- */
 let HelixHeadlessVideoPlaylistMenu = class HelixHeadlessVideoPlaylistMenu extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * The menu's accessible name, and its trigger's.
-         *
-         * "Episodes" suits a series and is wrong for a set of camera angles, and the
-         * component cannot know which one it is in.
-         */
         this.label = 'Episodes';
-        /**
-         * Where the menu opens relative to its trigger.
-         *
-         * `top-end` because a control bar sits at the foot of the picture, and a menu
-         * opening downward from there opens off the player.
-         */
         this.placement = 'top-end';
-        /* `requestUpdate` rather than a counter held in `@state`.
-         *
-         * The entries are the playlist's light DOM rather than this element's, so
-         * nothing about them schedules an update here: an entry added, removed, or
-         * made current changes a tree this element only looks at. A bumped `@state`
-         * field is the usual way to say "render again", and here it would be a field
-         * nothing reads, which the linter is right to call out. */
         this.reread = () => {
             this.requestUpdate();
         };
@@ -107,8 +27,6 @@ let HelixHeadlessVideoPlaylistMenu = class HelixHeadlessVideoPlaylistMenu extend
     #observer;
     connectedCallback() {
         super.connectedCallback();
-        /* After the first update, because the playlist is found by walking the tree
-           and the server has no tree to walk. */
         this.updateComplete.then(() => this.watch());
     }
     disconnectedCallback() {
@@ -117,46 +35,14 @@ let HelixHeadlessVideoPlaylistMenu = class HelixHeadlessVideoPlaylistMenu extend
         this.#observer?.disconnect();
         this.#observer = undefined;
     }
-    /* Resolved once, on the client, and never during a render.
-     *
-     * `closestInstance` walks `parentNode` and steps across a `ShadowRoot` by
-     * following its `host`, and the server has no `ShadowRoot` global, so
-     * reaching for it inside `render` throws
-     * `ReferenceError: Can't find variable: ShadowRoot` from inside Lit's own
-     * result collector. A component that walks the tree to render cannot render
-     * on a server, and the server has no tree to walk anyway. Set after the first
-     * update, and `undefined` on the server, where an empty menu is the honest
-     * output. */
     #playlist;
-    /** The playlist this menu belongs to, found upward through the slots. */
     get playlist() {
         return this.#playlist;
     }
-    /** The playlist's entries, in the order it holds them. */
     get entries() {
         const playlist = this.playlist;
         return playlist ? [...playlist.querySelectorAll(ITEMS)] : [];
     }
-    /**
-     * Watches the playlist for entries arriving, and re-reads it on every open.
-     *
-     * Two signals rather than one, because the two facts change on different
-     * clocks and only one of them is observable.
-     *
-     * **Which entries exist** is the playlist's light DOM, and a `MutationObserver`
-     * sees it directly.
-     *
-     * **Which entry is current** is `active`, a property with no attribute, so
-     * there is nothing to observe: events travel up from the playlist and this
-     * element is below it, and mirroring `active` to a `data-` name is ruled out
-     * on its own merits, `active` being a payload rather than a boolean fact. A
-     * `data-active` on every host is what `tree-root.ssr.spec.ts` fails on.
-     *
-     * So it is re-read at the moment it is looked at. `helix-before-open` comes from the
-     * menu in this element's own shadow root, which is the one direction events
-     * do arrive from, and a closed menu showing a stale mark is a thing nobody
-     * can see.
-     */
     watch() {
         this.#playlist ??= closestInstance(this, HelixHeadlessVideoPlaylist) ?? undefined;
         const playlist = this.#playlist;
@@ -171,7 +57,6 @@ let HelixHeadlessVideoPlaylistMenu = class HelixHeadlessVideoPlaylistMenu extend
     render() {
         return this.renderMenu();
     }
-    /** The menu itself, behind a method so a styled tier can render another one. */
     renderMenu() {
         const active = this.playlist?.active;
         return html `<${this.tag('menu')} part="menu"
@@ -188,27 +73,11 @@ let HelixHeadlessVideoPlaylistMenu = class HelixHeadlessVideoPlaylistMenu extend
           ?disabled=${entry.disabled}
           role="menuitemradio"
           @helix-select=${(event) => {
-            /* Stopped and re-announced from the host rather than let through.
-               What travels up is then this element's own event, so a consumer
-               listening on the menu sees what the playlist sees, and
-               `preventDefault()` refuses the selection in one place. */
             event.stopPropagation();
             this.choose(entry.value);
         }}
         >
-          ${
-        /* The still, where there is one: a reader picks an episode by
-           recognizing it faster than by reading its title, and this menu
-           opens over the picture where reading is hardest.
-         *
-         * In `start`, which is free: `Menu.Item` renders its tick *after*
-         * the label as `part="mark"`, so the leading column has nothing to
-         * collide with. `alt=""`, because the name is in the same row and a
-         * still repeating it is the same thing said twice.
-         *
-         * Omitted rather than empty where there is no poster, an `<img>`
-         * with no `src` being a broken-image glyph in every engine. */
-        entry.poster === ''
+          ${entry.poster === ''
             ? nothing
             : html `<img alt="" part="poster" slot="start" src=${entry.poster} />`}
           ${entry.text}

package/dist/video-playlist/root/video-playlist-root.js

@@ -7,79 +7,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, MixinControllerActive } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A set of clips and the one player they take turns in.
- *
- * @description
- * **The player is slotted, never rendered here.** A consumer's player carries
- * their appearance, their extra controls, their captions and their poster
- * treatment, and a playlist that rendered its own would either lose all of that
- * or grow a property for each of them. `Sandbox` takes its preview and `Menu`
- * its trigger the same way.
- *
- * **The entries are markup rather than an array property.** A list of objects
- * would be the shorter API and it does not survive the trip: React skips every
- * property it would have to apply imperatively while hydrating, so an array
- * handed to a custom element is missing on the first paint of every
- * server-rendered page. `using-the-elements.mdx` carries the measurement. Markup
- * is also what makes each entry a real button with a real name in it.
- *
- * **Nothing here plays anything.** It sets `src` on the player and lets the
- * player be a player. What the playlist owns is which entry is current, and it
- * moves that on three signals: an entry pressed, `helix-next` or
- * `helix-previous` from the player, and the player reaching the end.
- *
- * `ended` advances without asking, because a set of clips that stopped between
- * each one is a set the reader has to nurse. The clip that follows starts where
- * the last one left off, which is `autoplay` in the only sense that matters
- * here: the reader already pressed play once.
- *
- * @since 0.1.0
- * @status experimental
- * @category media
- * @aliases Playlist, Queue, Up next
- * @documentation https://helix.fusion.dev/components/video-playlist
- *
- * @slot - The entries.
- * @slot player - The `helix-video` they play in.
- *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current entry changes, and cancelable.
- *
- * @csspart items - The list of entries.
- * @csspart player - The region holding the player.
- */
 let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the list, which usually has no visible heading.
-         */
         this.label = 'Playlist';
-        /**
-         * Whether the entry changed because somebody moved through the playlist.
-         *
-         * All three ways it moves are the reader going somewhere: pressing an entry,
-         * pressing next or previous, or a clip ending and the next one following it.
-         * Every one of those means play, and the one case that does not is the first
-         * render, where the playlist is simply pointing the player at its opening
-         * entry and nobody has asked for anything yet.
-         *
-         * A press is also what makes the play legal. Autoplay is refused when nothing
-         * the reader did asked for it, so starting here works because this is inside
-         * the gesture that chose the entry, and where it is refused anyway the player
-         * shows its start control and waits.
-         */
         this.chased = false;
         this.handleSelect = (event) => {
-            /* Stopped and not relayed. The entry says it was chosen, this element says
-               what is playing, and a consumer hearing both would hear one press twice
-               under two names.
-        
-               `stopImmediatePropagation`, not `stopPropagation`. The consumer's listener
-               is on this same element, and stopping propagation only keeps an event off
-               the *next* node: every listener already bound here still runs, so the
-               entry's selection reaches them anyway. Command carries the longer note. */
             event.stopImmediatePropagation();
             this.chased = true;
             this.requestActive(event.detail.value);
@@ -97,38 +30,16 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
             this.step(1);
         };
     }
-    /**
-     * The entries, in the order the consumer wrote them.
-     *
-     * **Found by tag and filtered on the property, never on `[value]`.** React
-     * assigns a matching property rather than an attribute, so a playlist written
-     * in JSX carries no `value` attribute anywhere and `querySelectorAll('[value]')`
-     * returns nothing: every entry vanishes from the list, the active one
-     * included, and nothing throws, an empty playlist being a legal playlist.
-     *
-     * Reading `one.value` answers the same question the same way whether the
-     * consumer wrote markup or set a property, which is the only form that works
-     * for both.
-     */
     get items() {
         return [
             ...this.querySelectorAll('helix-video-playlist-item, helix-headless-video-playlist-item'),
         ].filter((one) => one.value !== '');
     }
-    /**
-     * The player, whichever tag the consumer slotted.
-     *
-     * Asked of the slot rather than matched by tag name: the headless tier's
-     * player is `helix-headless-video` and the styled tier's is `helix-video`, and
-     * a consumer bringing a third under either name should still be driven. What
-     * is needed of it is `src`, which is the whole of the contract.
-     */
     get player() {
         const slot = this.renderRoot?.querySelector('slot[name="player"]');
         const first = slot?.assignedElements()[0];
         return (first ?? null);
     }
-    /** Moves by one, and does nothing at either end. */
     step(by) {
         const items = this.items.filter((one) => !one.disabled);
         const at = items.findIndex((one) => one.value === this.resolveActive(items)?.value);
@@ -142,10 +53,6 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         this.addEventListener('helix-select', this.handleSelect);
         this.addEventListener('helix-next', this.handleNext);
         this.addEventListener('helix-previous', this.handlePrevious);
-        /* `ended` is a media event and does not compose out of the player's shadow
-           root on its own. The player relays it, which is why listening here works
-           at all, and why this listens on the element rather than on a `<video>` it
-           has no reference to. */
         this.addEventListener('ended', this.handleEnded);
     }
     disconnectedCallback() {
@@ -155,14 +62,6 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         this.removeEventListener('helix-previous', this.handlePrevious);
         this.removeEventListener('ended', this.handleEnded);
     }
-    /**
-     * Points the player at the current entry, and tells the entries which is on.
-     *
-     * In `updated` rather than in the handlers, so the three signals that move the
-     * current entry all arrive at one place that applies it. The server never runs
-     * this, which is correct: the entries are light DOM it cannot see, and what it
-     * renders is the player with whatever `src` the consumer wrote.
-     */
     updated(changed) {
         super.updated?.(changed);
         const items = this.items;
@@ -174,23 +73,11 @@ let HelixHeadlessVideoPlaylist = class HelixHeadlessVideoPlaylist extends MixinC
         if (!player || !current) {
             return;
         }
-        /* Only on a change. Writing `src` with the value it already holds reloads
-           the resource in every engine, so a playlist that assigned on each update
-           would restart the clip whenever anything else about it rendered. */
         if (player.src !== current.src) {
             player.src = current.src;
             player.poster = current.poster;
             player.label = current.text;
             if (this.chased) {
-                /* After the player has rendered, not now. `src` here is the element's
-                   property, and the `<video>` inside it only takes the new source on
-                   its next render: playing at this point plays the outgoing clip for an
-                   instant and the load that follows stops it again. Measured, and the
-                   reading was a player left paused on the entry that had just been
-                   chosen.
-        
-                   A microtask later is still inside the press that got us here, so the
-                   platform still counts it as asked for. */
                 void player.updateComplete?.then(() => {
                     player.play();
                 });

package/dist/virtual-list/root/virtual-list-root.js

@@ -7,113 +7,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, VirtualizeController } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * @summary Renders the rows of a long set that are on screen, and no others.
- *
- * @description
- * **The set arrives as data, which is what makes this a virtual list rather
- * than a box that hides children.** `for` names a
- * `<script type="application/json">` holding an array of objects, and a
- * `<template>` child says what one row looks like: elements carrying
- * `data-field="name"` are filled with that field of the item.
- *
- * Both halves are markup, and that is the whole reason for the shape.
- * `VirtualizeController` says why the obvious alternatives are shut: an `items`
- * property cannot survive React hydration, which skips every property it would
- * have to apply imperatively, and light-DOM children exist by the time anything
- * could decide not to create them. Text in the document is neither. A server
- * emits it, React re-emits it as a child rather than applying it, and it is one
- * node whatever the row count.
- *
- * **The accessible version is not a `<table>`**, the way it is for the charts
- * that share this `for="<id>"` shape: ten thousand rows in one is the cost this
- * exists to avoid. It is the rendered window plus `aria-setsize` and
- * `aria-posinset`, which is what says "four thousand of ten thousand" rather
- * than "four of twenty".
- *
- * **Rows are light DOM, deliberately.** They are cloned from the consumer's
- * template and appended to the host, so a document rule reaches them, the base
- * layer applies, and a class in the template means what it says. Cloned into
- * the shadow root they would be markup the consumer wrote and could not style,
- * which is the one thing a row template must not be.
- *
- * **Reading the source is client-only**, because a server has no document to
- * query. The window renders empty from the server and fills on the first update,
- * which is the same client-side enhancement rule every tree-reading component
- * here follows.
- *
- * **On this tier the consumer gives the viewport its box**, and the component
- * cannot do it for them: `helix/headless` ships no stylesheet, and a height is a
- * decision rather than a fact this could publish. So a base list wants two rules
- * before it is a list at all:
- *
- * ```css
- * helix-headless-virtual-list::part(viewport) {
- *   block-size: 12rem;
- *   overflow-y: auto;
- * }
- * ```
- *
- * **Without them it is not a scroller**, and the failure is worse than it
- * sounds. `scrollTop` is always zero, so nothing ever windows; and the box has
- * no height of its own, so `clientHeight` is a function of the rows just drawn.
- * Measuring then moves what is being measured, and the two need not converge:
- * measured in Chromium at 500 rows, it settled into a two-cycle between 378 and
- * 379 rows and stayed there, at two and a half thousand passes in eight seconds.
- * `VirtualizeController` gives up after ten passes and says so, so this now
- * draws a bad window rather than stopping the page, but a bad window is still
- * the answer until the rules are written.
- *
- * The styled tier writes them for you, with `--virtual-list-block-size`.
- *
- * @category layout
- * @since 0.1.0
- * @status experimental
- * @documentation https://helix.fusion.dev/components/virtual-list
- *
- * @csspart after - The space standing in for rows below the window.
- * @csspart before - The space standing in for rows above the window.
- * @csspart viewport - The scrolling box. Needs a block size and an overflow on this tier.
- */
 let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * How tall one row is, in pixels, used to map scroll offset to an index.
-         */
         this.estimate = 32;
-        /**
-         * Id of the element holding the rows, as JSON in a script.
-         */
         this.for = '';
-        /**
-         * What the list is called, since the rendered rows are only a window on it.
-         */
         this.label = '';
-        /**
-         * The parsed source.
-         *
-         * Empty on a server, which has nothing to read.
-         */
         this.rows = [];
-        /* No `overscan` property. The controller's four is a frame of fast scrolling
-           at a 32 pixel row, which is a fact about the platform rather than a
-           preference. */
         this.virtualize = new VirtualizeController(this, {
             container: () => this.renderRoot.querySelector('[part="viewport"]'),
             count: () => this.rows.length,
             estimate: () => this.estimate,
         });
     }
-    /**
-     * Reads the source named by `for`, once the document exists to read.
-     *
-     * `firstUpdated` rather than `connectedCallback`, per the server rules: the
-     * shim has attributes and no tree, so `getElementById` is undefined there.
-     * A source that is missing or not an array leaves the list empty rather than
-     * throwing, because a consumer whose data has not arrived yet is the ordinary
-     * case and an empty list says so by itself.
-     */
     firstUpdated(changed) {
         super.firstUpdated?.(changed);
         this.read();
@@ -138,18 +44,9 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             this.rows = Array.isArray(parsed) ? parsed : [];
         }
         catch {
-            /* Left empty rather than thrown. The source is a consumer's markup, and a
-               component that throws on it takes the page down over a comma. */
             this.rows = [];
         }
     }
-    /**
-     * Puts the windowed rows into the light DOM, and takes the rest out.
-     *
-     * Cleared and re-cloned rather than reconciled: a window is twenty-odd rows
-     * and cloning that many is well under a frame. A reconciler here would carry
-     * keys and identity for a set nothing selects into.
-     */
     place() {
         const template = this.querySelector('template');
         if (!template) {
@@ -172,8 +69,6 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
             for (const hole of clone.querySelectorAll('[data-field]')) {
                 hole.textContent = row[hole.dataset.field ?? ''] ?? '';
             }
-            /* The real index and the real total, not the position in the window. A
-               reader arrowing through this should hear where they are in the set. */
             for (const element of clone.children) {
                 element.setAttribute('role', 'listitem');
                 element.setAttribute('aria-posinset', String(at + 1));