@fusion.dev/helix-headless 0.182.2 → 0.184.0

package/dist/menu/root/menu-root.js

@@ -1,5 +1,5 @@
 import { __decorate } from "tslib";
-import { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, filterKeeps, focusTarget, formatWords, HelixElement, HelixFilterEvent, inlineStep, KeyboardNavigationController, linkDescription, MIRROR_RULE, MixinCollection, MixinControllerOpen, markMatches, OpenPhaseController, onUnlessFalse, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, auditEntry, customElement, DrilldownController, deepActiveElement, deepContains, focusTarget, HelixElement, inlineStep, KeyboardNavigationController, linkDescription, MIRROR_RULE, MixinCollection, MixinControllerOpen, OpenPhaseController, onUnlessFalse, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -98,18 +98,13 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             surface: () => this.partNamed('surface'),
         });
         this.settledOnce = false;
-        this.filterPage = null;
-        this.handleFilterInput = (event) => {
-            event.stopPropagation();
-            this.filterBy(event.target.value);
-        };
         this.followRemoved = (records) => {
             if (!this.open) {
                 return;
             }
             const active = deepActiveElement();
             const lost = active === null || active === document.body || !active.isConnected;
-            const record = records.find((one) => [...one.removedNodes].some((node) => isItem(node) && (this.filterable ? node === this.highlighted : lost)));
+            const record = records.find((one) => [...one.removedNodes].some((node) => isItem(node) && (this.filters ? node === this.filters.highlighted : lost)));
             if (!record) {
                 return;
             }
@@ -125,7 +120,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             const next = after(record.nextSibling, 'nextSibling') ??
                 after(record.previousSibling, 'previousSibling') ??
                 items.at(-1);
-            if (this.filterable || next) {
+            if (this.filters || next) {
                 this.reach(next);
                 return;
             }
@@ -188,23 +183,13 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             const items = this.items;
             const at = items.findIndex((item) => item.active);
             const along = inlineStep(this, event.key);
-            const typing = this.filterable && event.composedPath()[0] === this.field;
-            const step = event.key === 'ArrowDown' ? 1 : event.key === 'ArrowUp' ? -1 : 0;
+            if (this.filters?.keydown(event, items, at)) {
+                event.preventDefault();
+                return;
+            }
             if (event.key === 'Escape') {
                 event.stopPropagation();
-                if (!this.filterable || this.filter === '') {
-                    this.leave();
-                }
-                else {
-                    this.filterBy('');
-                }
-            }
-            else if (typing && step !== 0) {
-                const count = items.length;
-                this.reach(items[at < 0 ? (step > 0 ? 0 : count - 1) : (at + step + count) % count]);
-            }
-            else if (typing && event.key === 'Enter') {
-                items[at]?.renderRoot.querySelector('[part="item"]')?.click();
+                this.leave();
             }
             else if (along === 1 && items[at]?.hasSubmenu) {
                 this.enter(items[at]);
@@ -244,14 +229,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 this.longPress.down(event);
             }
         };
-        this.handleMouseDown = (event) => {
-            if (this.filterable &&
-                this.open &&
-                event.composedPath()[0] !== this.field &&
-                !this.fromTrigger(event)) {
-                event.preventDefault();
-            }
-        };
         this.handlePointerMove = (event) => {
             this.longPress.move(event);
         };
@@ -406,48 +383,27 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         return rows.filter((row) => !row.disabled && this.kept(row));
     }
     get menuBox() {
-        return this.filterable
+        return this.filters
             ? (this.renderRoot?.querySelector('#items') ?? null)
             : this.partNamed('surface');
     }
-    get field() {
-        return this.partNamed('search-field');
-    }
-    get filtering() {
-        return this.filterable && this.filter.trim() !== '' && this.filter !== this.refused;
+    get filters() {
+        return this.filterable ? this.filterer : undefined;
     }
     kept(row) {
-        return (!this.filtering ||
-            this.holderOf(row) !== this.filterPage ||
-            filterKeeps(slottedWords(row, ['']), this.filter.trim(), this.filterMatch));
+        return this.filters?.kept(row) ?? true;
     }
     requestFilter(value) {
-        if (value === this.filter) {
-            return;
-        }
-        this.filterPage = this.flies ? this.keyPage : this.drilldown.page;
-        this.refused = this.dispatchEvent(new HelixFilterEvent({ value })) ? undefined : value;
-        this.filter = value;
-    }
-    filterBy(value) {
-        this.requestFilter(value);
-        void this.updateComplete.then(() => this.reach(this.items[0]));
+        this.filterer?.request(value);
     }
     reach(row) {
-        if (!this.filterable) {
+        const filters = this.filters;
+        if (!filters) {
             row?.focus();
             return;
         }
-        if (this.highlighted && this.highlighted !== row) {
-            this.highlighted.highlighted = false;
-        }
-        this.highlighted = row;
-        const field = this.field;
-        if (field && 'ariaActiveDescendantElement' in field) {
-            field.ariaActiveDescendantElement = row ?? null;
-        }
+        filters.highlight(row);
         if (row) {
-            row.highlighted = true;
             this.revealRow(row);
         }
     }
@@ -460,7 +416,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         }
         this.updateComplete.then(() => {
             const items = this.items;
-            this.field?.focus();
+            this.filters?.field?.focus();
             this.reach(end === 'first' ? items[0] : items[items.length - 1]);
         });
     }
@@ -610,7 +566,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.addEventListener('focusin', this.handleFocusIn);
         this.addEventListener('contextmenu', this.handleContextMenu);
         this.addEventListener('pointerdown', this.handlePointerDown);
-        this.addEventListener('mousedown', this.handleMouseDown);
         this.addEventListener('pointermove', this.handlePointerMove);
         this.addEventListener('pointerup', this.handlePointerUp);
         this.addEventListener('pointercancel', this.handlePointerCancel);
@@ -635,10 +590,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.removeEventListener('focusin', this.handleFocusIn);
         this.removeEventListener('contextmenu', this.handleContextMenu);
         this.removeEventListener('pointerdown', this.handlePointerDown);
-        this.removeEventListener('mousedown', this.handleMouseDown);
-        if (this.filterable) {
-            markMatches(this, [], '');
-        }
         this.removeEventListener('pointermove', this.handlePointerMove);
         this.removeEventListener('pointerup', this.handlePointerUp);
         this.removeEventListener('pointercancel', this.handlePointerCancel);
@@ -667,7 +618,8 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             if (isSection(child)) {
                 child.onPage =
                     top &&
-                        (!this.filtering || [...child.children].some((row) => isItem(row) && this.kept(row)));
+                        (!this.filters?.filtering ||
+                            [...child.children].some((row) => isItem(row) && this.kept(row)));
                 for (const row of child.children) {
                     if (row.isMenuItem === true) {
                         this.mark(row, top);
@@ -684,14 +636,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.toggleState('drilled', !this.flies && !this.drilldown.atRoot);
         this.markColumns();
         this.nameSurface();
-        if (this.filterable) {
-            markMatches(this, this.rowsOf(this.filterPage).filter((row) => this.kept(row)), this.filtering ? this.filter.trim() : '');
-            const items = this.items;
-            if (changed.has('filter') &&
-                this.open &&
-                !items.includes(this.highlighted)) {
-                this.reach(items[0]);
-            }
+        this.filterer?.updated();
+        if (this.filterable && !this.filterer) {
+            auditEntry(this, 'filterable', 'menu/filter', 'it shows no filter field', () => this.filterable && !this.filterer);
         }
     }
     nameSurface() {
@@ -729,7 +676,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     mark(item, onPage) {
         const page = this.drilldown.page;
         item.onPage = onPage && this.kept(item);
-        item.virtual = this.filterable;
+        item.virtual = this.filters !== undefined;
         const holds = page !== null && item.contains(page);
         item.flyout = this.flies;
         item.expanded = this.flies && holds;
@@ -753,16 +700,9 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     }
     render() {
         const point = this.context && this.point;
-        const filtering = this.filtering;
-        const count = filtering
-            ? this.rowsOf(this.filterPage).filter((row) => this.kept(row)).length
-            : 0;
-        const none = filtering && count === 0;
-        this.announced = none
-            ? this.noResultsText
-            : filtering
-                ? formatWords(this, 'resultsLabel', { count })
-                : '';
+        const filters = this.filters;
+        this.announced = '';
+        const none = filters?.status();
         const rows = html `${this.flies || this.drilldown.atRoot
             ? nothing
             : html `<div part="header">
@@ -781,9 +721,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             <span part="title" id="title">${this.drilldown.label}</span>
           </div>`}
       <slot @slotchange=${(event) => this.countRows(event)}></slot>
-      ${none
-            ? html `<p part="empty"><slot name="no-results">${this.noResultsText}</slot></p>`
-            : this.renderStatus(this.hasRows)}`;
+      ${none ?? this.renderStatus(this.hasRows)}`;
         const busy = this.loading ? 'true' : nothing;
         const label = this.label || nothing;
         return html `<slot name="trigger" @click=${this.handleTriggerClick}></slot>${point
@@ -796,27 +734,14 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
       <div
         part="surface"
         popover="manual"
-        role=${this.filterable ? nothing : 'menu'}
-        aria-busy=${this.filterable ? nothing : busy}
-        aria-label=${this.filterable ? nothing : label}
+        role=${filters ? nothing : 'menu'}
+        aria-busy=${filters ? nothing : busy}
+        aria-label=${filters ? nothing : label}
         data-drilled=${this.flies || this.drilldown.atRoot ? nothing : ''}
-        data-filtered=${filtering ? '' : nothing}
+        data-filtered=${filters?.filtering ? '' : nothing}
         ?hidden=${!this.open}
       >
-        ${this.filterable
-            ? html `<input
-                  part="search-field"
-                  type="text"
-                  autocomplete="off"
-                  spellcheck="false"
-                  .value=${this.filter}
-                  placeholder=${this.filterLabel}
-                  aria-label=${this.filterLabel}
-                  aria-autocomplete="list"
-                  aria-controls="items"
-                  @input=${this.handleFilterInput}
-                /><div id="items" role="menu" aria-busy=${busy} aria-label=${label}>${rows}</div>`
-            : rows}
+        ${filters ? filters.drawFilter(rows, busy) : rows}
       </div>${this.renderLive(this.hasRows)}`;
     }
 };

package/dist/time-input/root/time-input-root.d.ts

@@ -217,6 +217,11 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      * on why a wheel cannot do either.
      */
     mode?: 'multiple' | 'range';
+    /**
+     * The words on the list's button that chooses the current time, drawn with
+     * `show-now`.
+     */
+    nowLabel: string;
     /**
      * Placeholder text shown before a time is entered.
      */
@@ -252,6 +257,12 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      * See Time Picker's `seconds`.
      */
     seconds: boolean;
+    /**
+     * Draws a button under the times in the list that chooses the current time,
+     * moved to the nearest time on offer. See Time Picker's `show-now`. Its words
+     * are `now-label`.
+     */
+    showNow: boolean;
     /**
      * How far apart the offered times are, in minutes, or in seconds with
      * `seconds`.

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

@@ -21,12 +21,14 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
         this.locale = '';
         this.max = '23:59';
         this.min = '00:00';
+        this.nowLabel = 'Now';
         this.placeholder = 'HH:mm';
         this.rangeLengthMessage = 'A range is two times.';
         this.rangeOverflowMessage = 'Choose a time at or before {max}.';
         this.rangeUnderflowMessage = 'Choose a time at or after {min}.';
         this.removeLabel = 'Remove {name}';
         this.seconds = false;
+        this.showNow = false;
         this.step = 15;
         this.timeStyle = 'local';
         this.triggerLabel = 'Choose a time';
@@ -246,7 +248,9 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
       locale=${handedLocale(this) || nothing}
       max=${this.max}
       min=${this.min}
+      now-label=${this.nowLabel}
       ?seconds=${this.seconds}
+      ?show-now=${this.showNow}
       step=${this.step}
       .value=${this.picked}
       @helix-before-change=${this.handlePicked}
@@ -400,6 +404,10 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessTimeInput.prototype, "mode", void 0);
+__decorate([
+    words,
+    property({ attribute: 'now-label' })
+], HelixHeadlessTimeInput.prototype, "nowLabel", void 0);
 __decorate([
     words,
     property()
@@ -423,6 +431,9 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessTimeInput.prototype, "seconds", void 0);
+__decorate([
+    property({ attribute: 'show-now', type: Boolean })
+], HelixHeadlessTimeInput.prototype, "showNow", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessTimeInput.prototype, "step", void 0);

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

@@ -57,7 +57,11 @@ export class VirtualListReorderController {
     }
     get enabled() {
         const host = this.host;
-        return (host.reorderable && host.columns <= 1 && host.minColumnWidth <= 0 && host.sectionField === '');
+        return (host.reorderable &&
+            host.columns <= 1 &&
+            host.minColumnWidth <= 0 &&
+            host.sectionField === '' &&
+            host.layout !== 'waterfall');
     }
     hostUpdated() {
         queueMicrotask(() => this.mark());

package/dist/virtual-list/root/virtual-list-root.d.ts

@@ -61,6 +61,32 @@ export interface VirtualListRange {
  * smallest item size, and follows the box as it resizes. `gap` spaces the rows, and the columns
  * of a grid, by a number of pixels the list counts in each row's place.
  *
+ * A grid without `selection-mode` is a grid to a reader, as the APG's grid
+ * and React Aria's grid list are: the box is a `grid` with `aria-rowcount`
+ * and `aria-colcount`, each line drawn is a `row` with `aria-rowindex`, and
+ * each item a `gridcell` with `aria-colindex`. Each line is a slot of the
+ * list's own, so your rows stay its children: give an item one element. With
+ * `selection-mode` it stays a list box of options, as React Aria's list box
+ * in a grid layout does.
+ *
+ * **A waterfall.** `layout="waterfall"` puts each item, in the order of the
+ * set, under the column that ends highest so far, the leftmost of a tie, as a
+ * wall of photos of different heights is, and as React Aria's waterfall
+ * layout and TanStack Virtual's lanes do. `columns`, or `min-column-width`,
+ * says how many columns. Every item is measured, at the width of its column,
+ * and placed at its column and its height, so items of any height leave no
+ * holes. The list draws the items that reach into the box, and the item
+ * holding focus. A reader hears a list, or a list box, in the order of the
+ * set, which is also the order Tab and a screen reader's own keys take.
+ *
+ * In a waterfall, Down and Up move along the column to the next or the
+ * previous item in it, Right and Left move to the next or the previous
+ * column, to the item there that sits beside this one the most, or the
+ * nearest above where none does, and Page Down and Page Up move a box down
+ * or up the column. Home and End go to the first and the last item of the
+ * set, and Shift with a key takes in the items between in the order of the
+ * set.
+ *
  * **Across.** `orientation="horizontal"` lays the items out along a line and
  * scrolls it sideways, as a strip of cards does, windowed the same way:
  * `estimate` is then an item's width, and the box needs an inline size.
@@ -79,10 +105,11 @@ export interface VirtualListRange {
  *
  * | Key | What it does |
  * |---|---|
- * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line. |
- * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |
- * | Home, End | Moves to the first or the last item. |
- * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen. |
+ * | Down, Up | Moves to the next or the previous item, or in a grid to the item in the same column on the next or the previous line, or in a waterfall to the next or the previous item down the same column. |
+ * | Right, Left | In a grid, moves to the next or the previous item along the line, the other way round on a right-to-left page. In a waterfall, moves to the item beside in the next or the previous column. In a list that runs across, moves to the next or the previous item the same way, and Down and Up are left to the row. |
+ * | Home, End | Moves to the first or the last item. In a grid without `selection-mode`, to the first or the last item of the line. |
+ * | Control or Command with Home or End | In a grid without `selection-mode`, moves to the first or the last item. |
+ * | Page Down, Page Up | Moves by the number of items, or of lines in a grid, on screen, or in a waterfall a box down or up the column. |
  * | A letter or a word | Moves to the next item whose text starts with what you typed. |
  * | Escape | Lets go of every chosen item, in a list with `selection-mode`. |
  * | Alt with Up or Down | In a `reorderable` list, moves the item a place. Alt with Home or End moves it to either end. |
@@ -97,8 +124,9 @@ export interface VirtualListRange {
  * or the item itself when it is a string or a number.
  *
  * Each row says its place in the whole set with `aria-posinset` and
- * `aria-setsize`, so a screen reader says "4,000 of 10,000". The row holding
- * focus stays drawn when it scrolls out.
+ * `aria-setsize`, so a screen reader says "4,000 of 10,000", and each cell of
+ * a grid its line and its column. The row holding focus stays drawn when it
+ * scrolls out.
  *
  * **Selecting.** `selection-mode` makes the list a list box a reader chooses
  * from: `single` selects one item and `multiple` any number. Space or a press
@@ -267,6 +295,15 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * wins over this.
      */
     label: string;
+    /**
+     * How items of more than one column are laid out. `grid`, the default, puts
+     * them in lines of equal columns. `waterfall` puts each item, in the order
+     * of the set, under the column that ends highest, as a wall of photos of
+     * different heights is: `columns`, or `min-column-width`, says how many
+     * columns. Rows of a waterfall are measured, and Up and Down move along a
+     * column.
+     */
+    layout: 'grid' | 'waterfall';
     /**
      * Marks the list as busy fetching more items, and draws a row after the last
      * item that says so.
@@ -300,7 +337,7 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * Which way the list runs. `horizontal` lays the items out along a line
      * and scrolls it sideways: Left and Right move between items, the other
      * way round on a right-to-left page, and `estimate` is an item's width. A
-     * grid always runs down.
+     * grid and a waterfall always run down.
      */
     orientation: 'horizontal' | 'vertical';
     /**
@@ -324,7 +361,8 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * with an arrow moves the row the keys are on, and a pointer drags a row.
      * The list moves no item itself: you move your `items` on `helix-reorder`.
      * Without that import it does nothing, so a list that never moves items
-     * carries none of the code. A list of one column, without sections.
+     * carries none of the code. A list of one column, without sections or a
+     * waterfall.
      */
     reorderable: boolean;
     /**
@@ -422,24 +460,42 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     get range(): VirtualListRange;
     /** The gap in pixels, none where it is not a positive number. */
     private get space();
+    /** Where each item of a waterfall stands, which the controller places. */
+    private readonly lanes;
+    /** Whether the items are laid out as a waterfall, each down a column. */
+    private get waterfall();
     /**
-     * How many items a line holds: as many as fit at `min-column-width` where
-     * it is set and the box has a width, and `columns` otherwise, at least one.
+     * Whether the list is a grid a reader reads, and not a list box: lines of
+     * columns with no `selection-mode`, which are `grid`, `row` and `gridcell`
+     * to a reader, as the APG's grid and React Aria's grid list are.
+     */
+    private get lined();
+    /**
+     * How many items a line holds, which a waterfall draws one at a time: its
+     * columns are not lines.
      */
     private get across();
+    /**
+     * How many columns there are: as many as fit at `min-column-width` where
+     * it is set and the box has a width, and `columns` otherwise, at least one.
+     */
+    private get columnCount();
     /** How wide the box is, read for `min-column-width`. */
     private boxWidth;
     /** Watches the box's width, for `min-column-width`. */
     private widthWatch;
-    /** The items to a line the measurements were taken at. */
+    /** The items to a line the measurements were taken at, or a waterfall's columns and width. */
     private measuredAcross;
-    /** Watches the box for its width while `min-column-width` asks for it. */
+    /**
+     * Watches the box for its width while `min-column-width` asks for it, or a
+     * waterfall, whose items are as tall as their width makes them.
+     */
     private watchWidth;
     /** The items a span of lines holds. */
     private itemsOn;
     /** The line item `at` is on: its entry in a list with sections. */
     private lineOf;
-    /** Whether the list runs across, which a grid never does. */
+    /** Whether the list runs across, which a grid and a waterfall never do. */
     private get horizontal();
     /** The sections and the items they were read from, kept until either changes. */
     private sectionsRead;
@@ -541,6 +597,14 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * is that control's, so a field in a row keeps its arrows.
      */
     private readonly handleKeydown;
+    /**
+     * Where a key goes in a waterfall, through the columns `Waterfall.step`
+     * reads: along the column for Down, Up, Page Down and Page Up, and to the
+     * item beside in the next column or the one before for the keys along the
+     * line, the other way round on a right-to-left page. Past a disabled item,
+     * on the same way.
+     */
+    private inWaterfall;
     /** The key of item `at` in `value`. See `keyField`. */
     private keyAt;
     /** @internal Every item's key, in the order of the set, which the reorder entry moves. */
@@ -600,15 +664,25 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     private keptIndex;
     /**
      * Writes a row's role, and whether it is chosen in a list that selects:
-     * `option` with `aria-selected` there, and `listitem` otherwise, and
-     * `aria-disabled` on an item `disabled-keys` names. Every pass,
-     * since a choice changes no row's content.
+     * `option` with `aria-selected` there, `gridcell` in a grid, and `listitem`
+     * otherwise, and `aria-disabled` on an item `disabled-keys` names. Every
+     * pass, since a choice changes no row's content.
+     *
+     * Its place too: `aria-posinset` and `aria-setsize` in a list, and in a
+     * grid its column, with the line's `row` given by the slot it is drawn in.
      *
      * `data-selected` and `data-disabled` say the same to a stylesheet, as
      * React Aria's rows do, so one rule reads the same in either kind of list.
      */
     private mark;
-    /** Writes a row's place in the set. */
+    /**
+     * Writes which item a row drew, for the controller to measure it against:
+     * the real index, the same one `aria-posinset` carries one higher.
+     *
+     * `mark` writes the place a reader hears from it, 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.
+     */
     private stamp;
     /** Fills a drawn row from its item, by `renderItem` or by the template's holes. */
     private fill;
@@ -642,6 +716,10 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
     private place;
     /** The sections the rows were last placed in. */
     private placedSections;
+    /** Whether the rows were last placed in a waterfall. */
+    private placedWaterfall;
+    /** The lines of a grid drawn on the last pass, each a `row` the render draws a slot in. */
+    private drawnLines;
     /** The function the drawn headers were drawn by, so a new one draws them again. */
     private headedBy;
     /** Ties each header's id to this list. */