@fusion.dev/helix-core 0.182.2 → 0.184.0

package/custom-elements.json

@@ -5787,6 +5787,16 @@
               "default": "0",
               "description": "The estimate the sums were built against, so a change to it rebuilds."
             },
+            {
+              "kind": "field",
+              "name": "changes",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Counts each change to a height, for a placement built from them."
+            },
             {
               "kind": "method",
               "name": "at",
@@ -5853,6 +5863,16 @@
               ],
               "description": "The room items `[0, index)` take."
             },
+            {
+              "kind": "method",
+              "name": "stamp",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "description": "Says which heights these are: a placement built from a stamp it was\ngiven again holds, and one built from another stamp is out of date."
+            },
             {
               "kind": "method",
               "name": "total",
@@ -6476,6 +6496,75 @@
               },
               "description": "Whether this pass places by measurement: offered, and wanted or needed."
             },
+            {
+              "kind": "method",
+              "name": "laned",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Waterfall | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "total",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The waterfall the host lays its items out in, placed by the heights known now."
+            },
+            {
+              "kind": "method",
+              "name": "startOf",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "total",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Where item `index` starts down the set, before any drift: after the items\nbefore it, or in its column of a waterfall, where the starts never go back\nup either."
+            },
+            {
+              "kind": "method",
+              "name": "indexAt",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "offset",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "total",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The item at `offset`: the last to start at or before it, or in a\nwaterfall the first to reach past it."
+            },
             {
               "kind": "method",
               "name": "placed",
@@ -6701,6 +6790,291 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/controllers/virtualize-controller/waterfall.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Where each item of a waterfall stands: a set laid out down several columns\nof one width, each item under the shortest column so far, as a masonry wall\nof photos is.\n\n**Its own module, which a host hands to `VirtualizeController`**, so the\nhosts that window a single column carry none of it. The controller asks it\nwhich items reach the box and where each one starts, and the host draws each\nitem at its column and its start.\n\n**Placed in the order of the set, each item under the column that ends\nhighest**, the leftmost of a tie, as React Aria's `WaterfallLayout` and\nTanStack Virtual's lanes place them. So an item's start is never above the\nstart of the item before it, and the first item to reach any offset is found\nby a binary search, as one column finds it.\n\nSizes are the controller's: what was measured, or the estimate, each with\nthe gap below it.",
+          "name": "Waterfall",
+          "members": [
+            {
+              "kind": "field",
+              "name": "lanes",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "How many columns the items are laid out in, at least one."
+            },
+            {
+              "kind": "field",
+              "name": "starts",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "Where each item starts, in pixels from the top of the set."
+            },
+            {
+              "kind": "field",
+              "name": "columns",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "The column each item stands in."
+            },
+            {
+              "kind": "field",
+              "name": "sizes",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "How much room each item takes, with the gap below it."
+            },
+            {
+              "kind": "field",
+              "name": "reach",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "default": "[]",
+              "description": "How far down the set the items `[0, i]` reach, the furthest of their ends."
+            },
+            {
+              "kind": "field",
+              "name": "extent",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "How long the set is: where its longest column ends."
+            },
+            {
+              "kind": "field",
+              "name": "built",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "''",
+              "description": "What the placement was built from, so it is built again only when that changes."
+            },
+            {
+              "kind": "method",
+              "name": "place",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "size",
+                  "type": {
+                    "text": "(index: number) => number"
+                  }
+                },
+                {
+                  "name": "stamp",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Places `count` items whose sizes `size` gives, unless `stamp` says the\nsizes, the count and the columns are the ones already placed."
+            },
+            {
+              "kind": "method",
+              "name": "start",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Where item `index` starts, and where the set ends for an index past it."
+            },
+            {
+              "kind": "method",
+              "name": "lane",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The column item `index` stands in."
+            },
+            {
+              "kind": "method",
+              "name": "length",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "How long the set is, where its longest column ends."
+            },
+            {
+              "kind": "method",
+              "name": "from",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "offset",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The first item that reaches past `offset`, or the count where none does."
+            },
+            {
+              "kind": "method",
+              "name": "to",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "offset",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The first item that starts at or past `offset`, so every item before it starts above."
+            },
+            {
+              "kind": "method",
+              "name": "search",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "sorted",
+                  "type": {
+                    "text": "readonly number[]"
+                  }
+                },
+                {
+                  "name": "offset",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The first index whose number in `sorted` is past `offset`."
+            },
+            {
+              "kind": "method",
+              "name": "step",
+              "return": {
+                "type": {
+                  "text": "number | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "page",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Which item a key moves to from `at`, in a set of `count` items, or\n`undefined` for a key it does not take or where there is no item that way:\n\n- Down and Up move to the next or the previous item in the same column.\n- `next` and `previous` move to the column beside, to its item that sits\n  beside this one the most, or the nearest above where none does. Which\n  of Left and Right is `next` is the caller's, for a right-to-left page.\n- Page Down and Page Up move down or up the same column by `page` pixels,\n  to the item there, or the last item that way."
+            },
+            {
+              "kind": "method",
+              "name": "size",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "How much room item `index` takes down its column, with the gap below it."
+            }
+          ],
+          "helix": {}
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "Waterfall",
+          "declaration": {
+            "name": "Waterfall",
+            "module": "src/controllers/virtualize-controller/waterfall.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/events/action.ts",
@@ -13785,6 +14159,14 @@
             "package": "#audit-children"
           }
         },
+        {
+          "kind": "js",
+          "name": "auditEntry",
+          "declaration": {
+            "name": "auditEntry",
+            "package": "#audit-children"
+          }
+        },
         {
           "kind": "js",
           "name": "auditName",
@@ -14521,6 +14903,14 @@
             "module": "./controllers/virtualize-controller/virtualize-controller.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "Waterfall",
+          "declaration": {
+            "name": "Waterfall",
+            "module": "./controllers/virtualize-controller/waterfall.js"
+          }
+        },
         {
           "kind": "js",
           "name": "eventsForTag",
@@ -25571,6 +25961,14 @@
           "type": {
             "text": "typeof audit"
           }
+        },
+        {
+          "kind": "function",
+          "name": "auditEntry",
+          "description": "The missing-entry warning in a production build: nothing. See `auditEntry`.",
+          "type": {
+            "text": "typeof entry"
+          }
         }
       ],
       "exports": [
@@ -25581,6 +25979,14 @@
             "name": "auditChildren",
             "module": "src/utils/audit-children/audit-children-off.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "auditEntry",
+          "declaration": {
+            "name": "auditEntry",
+            "module": "src/utils/audit-children/audit-children-off.ts"
+          }
         }
       ]
     },
@@ -25627,6 +26033,48 @@
             }
           ],
           "description": "Reports a child from another family that a container holds and nobody\nregistered, naming the entry to import.\n\n**A container does not register another family's children.** An option\nbelongs to the Option family, and a page writing one inside a Select imports\n`@fusion.dev/helix/option` itself, as it imports the Select. Left out, the\noption is an unknown element: the list reads no choices and nothing throws.\nThis says so, once for each container tag and child tag on the page, with\nthe line to add.\n\nAsked once the page has loaded and painted, so an entry a later module\nimports is not taken for a missing one.\n\n**In a development build only**, as `missing-name` is: every container would\npay for a sentence meant for the person writing the page. Core imports it as\n`#audit-children`, which `package.json` resolves here under the\n`development` condition and to `audit-children-off.ts`, which does nothing,\neverywhere else.\n\n`part` is the child's tag after the tier, such as `option`, and `entry` its\nfamily's entry, such as `option`; the host's `tier` gives the rest of both.\n`consequence` says what the missing child costs, after \"so\". `drawn` is for\nchildren the host draws from data, such as the options of Listbox's `items`:\nthe page wrote none, so an undefined tag is reported without one in the\nhost's light DOM."
+        },
+        {
+          "kind": "function",
+          "name": "auditEntry",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "host",
+              "type": {
+                "text": "HTMLElement"
+              }
+            },
+            {
+              "name": "attribute",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "entry",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "consequence",
+              "type": {
+                "text": "string"
+              }
+            },
+            {
+              "name": "missing",
+              "type": {
+                "text": "() => boolean"
+              }
+            }
+          ],
+          "description": "Reports a property set on a host whose behavior is in an entry of its own\nthat nobody imported, naming the entry.\n\n**The second shape of the same mistake.** Menu's filter is\n`menu/filter`, so a menu that never filters carries none of its code, and a\npage that sets `filterable` and imports only the menu gets a menu with no\nfield and nothing thrown. This says so, once for each host tag and entry on\nthe page, with the line to add.\n\n`attribute` is the one the page set, `entry` the entry after the tier's\npackage, such as `menu/filter`, and `consequence` what the missing entry\ncosts, after \"so\". `missing` is asked once the page has loaded and painted,\nso an entry a later module imports is not taken for a missing one."
         }
       ],
       "exports": [
@@ -25637,6 +26085,14 @@
             "name": "auditChildren",
             "module": "src/utils/audit-children/audit-children.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "auditEntry",
+          "declaration": {
+            "name": "auditEntry",
+            "module": "src/utils/audit-children/audit-children.ts"
+          }
         }
       ]
     },
@@ -35040,7 +35496,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.182.2'",
+          "default": "'0.184.0'",
           "description": "The version of the package this file ships in.\n\n**Written by `fusion/scripts/version.mjs`** wherever it writes the package's\n`package.json`, and stamped back into the repository beside it after a\nrelease, so the two never disagree; a spec beside this holds them to it.\nNothing else in the running code knows which release it is."
         }
       ],
@@ -35676,6 +36132,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.182.2"
+    "version": "0.184.0"
   }
 }

package/dist/controllers/virtualize-controller/heights.d.ts

@@ -29,6 +29,8 @@ export declare class Heights {
     private dirty;
     /** The estimate the sums were built against, so a change to it rebuilds. */
     private built;
+    /** Counts each change to a height, for a placement built from them. */
+    private changes;
     constructor(estimate: () => number);
     /** How tall one item is: what was measured, or what is assumed. */
     at(index: number): number;
@@ -42,6 +44,11 @@ export declare class Heights {
     record(index: number, size: number): boolean;
     /** The room items `[0, index)` take. */
     before(index: number, count: number): number;
+    /**
+     * Says which heights these are: a placement built from a stamp it was
+     * given again holds, and one built from another stamp is out of date.
+     */
+    stamp(): string;
     /** The room the whole set takes. */
     total(count: number): number;
     /**

package/dist/controllers/virtualize-controller/heights.js

@@ -4,6 +4,7 @@ export class Heights {
         this.sums = [0];
         this.dirty = 0;
         this.built = 0;
+        this.changes = 0;
         this.estimate = estimate;
     }
     at(index) {
@@ -23,12 +24,16 @@ export class Heights {
             return false;
         }
         this.dirty = Math.min(this.dirty, index);
+        this.changes += 1;
         return true;
     }
     before(index, count) {
         this.build(count);
         return this.sums[Math.max(0, Math.min(index, count))] ?? 0;
     }
+    stamp() {
+        return `${this.changes}:${this.estimate()}`;
+    }
     total(count) {
         return this.before(count, count);
     }
@@ -63,11 +68,13 @@ export class Heights {
             }
         }
         this.dirty = 0;
+        this.changes += 1;
     }
     forget() {
         this.seen.clear();
         this.dirty = 0;
         this.sums = [0];
+        this.changes += 1;
     }
     build(count) {
         const size = Math.max(1, this.estimate());

package/dist/controllers/virtualize-controller/virtualize-controller.d.ts

@@ -1,4 +1,5 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { Waterfall } from './waterfall.js';
 /** What the controller needs of a set and the box it is shown in. */
 export interface VirtualizeOptions {
     /** The scrolling box, or null before it renders. */
@@ -75,6 +76,16 @@ export interface VirtualizeOptions {
      * scroll offset during a fling.
      */
     anchor?: () => boolean;
+    /**
+     * Lays the items out down several columns, each item under the column that
+     * ends highest, as a wall of photos is: a `Waterfall`, whose `lanes` says how
+     * many columns. The window is then every item that reaches into the box, in
+     * the order of the set, and a host draws each item at its column,
+     * `waterfall.lane(index)`, and at `offsetOf(index)` down the set, which
+     * `offsetOf(count)` is the length of. Items are placed by measurement, so a
+     * host supplies `rows`. None by default.
+     */
+    waterfall?: () => Waterfall | undefined;
 }
 /** A row that has been drawn, and which item of the set it drew. */
 export interface Rendered {
@@ -320,6 +331,19 @@ export declare class VirtualizeController implements ReactiveController {
     private sampleRows;
     /** Whether this pass places by measurement: offered, and wanted or needed. */
     private measuring;
+    /** The waterfall the host lays its items out in, placed by the heights known now. */
+    private laned;
+    /**
+     * Where item `index` starts down the set, before any drift: after the items
+     * before it, or in its column of a waterfall, where the starts never go back
+     * up either.
+     */
+    private startOf;
+    /**
+     * The item at `offset`: the last to start at or before it, or in a
+     * waterfall the first to reach past it.
+     */
+    private indexAt;
     /**
      * The measured version, which asks where each item starts rather than dividing.
      *

package/dist/controllers/virtualize-controller/virtualize-controller.js

@@ -159,14 +159,13 @@ export class VirtualizeController {
             return;
         }
         const overscan = this.options.overscan ?? 4;
-        let next = this.measuring()
+        const choose = () => this.measuring()
             ? this.placed(box, total, overscan)
             : this.uniform(box, total, size, overscan);
+        let next = choose();
         if (this.drift !== 0 && (next.before < 0 || next.first === 0)) {
             this.square();
-            next = this.measuring()
-                ? this.placed(box, total, overscan)
-                : this.uniform(box, total, size, overscan);
+            next = choose();
         }
         if (this.last?.count !== total || this.last.estimate !== size) {
             this.last = { count: total, estimate: size };
@@ -235,22 +234,40 @@ export class VirtualizeController {
         }
     }
     measuring() {
-        return this.options.rows !== undefined && (this.uneven || (this.options.measured?.() ?? true));
+        return (this.options.rows !== undefined &&
+            (this.uneven ||
+                this.options.waterfall?.() !== undefined ||
+                (this.options.measured?.() ?? true)));
+    }
+    laned(total) {
+        const lanes = this.options.rows ? this.options.waterfall?.() : undefined;
+        lanes?.place(total, (index) => this.heights.at(index), this.heights.stamp());
+        return lanes;
+    }
+    startOf(index, total) {
+        return this.laned(total)?.start(index) ?? this.heights.before(index, total);
+    }
+    indexAt(offset, total) {
+        const lanes = this.laned(total);
+        return lanes
+            ? Math.min(lanes.from(offset), Math.max(0, total - 1))
+            : this.heights.indexAt(offset, total);
     }
     placed(box, total, overscan) {
         const top = this.offset(box);
         const lead = this.lead(box);
         const from = this.heading < 0 ? top - lead : top;
-        const first = Math.max(0, this.heights.indexAt(from, total) - overscan);
+        const more = overscan * (this.laned(total)?.lanes ?? 1);
+        const first = Math.max(0, this.indexAt(from, total) - more);
         const bottom = top + this.span(box) + (this.heading > 0 ? lead : 0);
-        let last = this.heights.indexAt(top, total);
-        while (last < total && this.heights.before(last, total) < bottom) {
+        let last = this.indexAt(top, total);
+        while (last < total && this.startOf(last, total) < bottom) {
             last += 1;
         }
-        last = Math.min(total, last + overscan);
+        last = Math.min(total, last + more);
         return {
-            after: Math.max(0, this.heights.total(total) - this.heights.before(last, total)),
-            before: this.heights.before(first, total) + this.drift,
+            after: Math.max(0, this.startOf(total, total) - this.startOf(last, total)),
+            before: this.startOf(first, total) + this.drift,
             first,
             last,
         };
@@ -268,20 +285,20 @@ export class VirtualizeController {
             const first = Math.min(Math.floor(top / size), total);
             return { first, last: Math.max(first, Math.min(total, Math.ceil(bottom / size))) };
         }
-        const first = this.heights.indexAt(top, total);
+        const first = this.indexAt(top, total);
         let last = first;
-        while (last < total && this.heights.before(last, total) < bottom) {
+        while (last < total && this.startOf(last, total) < bottom) {
             last += 1;
         }
         return { first, last };
     }
     remaining() {
         const box = this.options.container();
-        const total = Math.max(0, this.options.count());
         if (!box) {
             return 0;
         }
-        const length = this.measuring() ? this.heights.total(total) : total * this.line();
+        const total = Math.max(0, this.options.count());
+        const length = this.measuring() ? this.startOf(total, total) : total * this.line();
         return Math.max(0, length - Math.max(0, this.offset(box)) - this.span(box));
     }
     endInSight(length = Math.max(0, this.options.count())) {
@@ -332,8 +349,8 @@ export class VirtualizeController {
         const box = this.options.container();
         const from = box ? this.noteClamp(box) : this.lastTop;
         const top = box ? this.offset(box) : 0;
-        const anchor = this.target ?? this.heights.indexAt(top, total);
-        const was = this.heights.before(anchor, total);
+        const anchor = this.target ?? this.indexAt(top, total);
+        const was = this.startOf(anchor, total);
         let news = false;
         for (const { element, index } of rows) {
             if (this.heights.record(index, this.length(element) + this.gap())) {
@@ -344,7 +361,7 @@ export class VirtualizeController {
             return;
         }
         this.settling = 0;
-        const moved = this.heights.before(anchor, total) - was;
+        const moved = this.startOf(anchor, total) - was;
         if (box && top > 0 && moved !== 0 && (this.options.anchor?.() ?? true)) {
             if (this.scrolling()) {
                 this.drift -= moved;
@@ -353,6 +370,9 @@ export class VirtualizeController {
                 this.scrollBox(box, from + moved);
             }
         }
+        if (this.laned(total)) {
+            this.host.requestUpdate();
+        }
         this.measure();
     }
     shift(by) {
@@ -361,7 +381,7 @@ export class VirtualizeController {
         }
         const count = Math.max(0, this.options.count());
         this.heights.shift(by);
-        const room = this.heights.before(by, count);
+        const room = this.startOf(by, count);
         this.window = {
             ...this.window,
             before: this.window.before + room,
@@ -416,7 +436,7 @@ export class VirtualizeController {
     offsetOf(index) {
         const total = Math.max(0, this.options.count());
         return this.measuring()
-            ? this.heights.before(index, total) + this.drift
+            ? this.startOf(index, total) + this.drift
             : Math.max(0, Math.min(index, total)) * this.line();
     }
     forget() {

package/dist/controllers/virtualize-controller/waterfall.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Where each item of a waterfall stands: a set laid out down several columns
+ * of one width, each item under the shortest column so far, as a masonry wall
+ * of photos is.
+ *
+ * **Its own module, which a host hands to `VirtualizeController`**, so the
+ * hosts that window a single column carry none of it. The controller asks it
+ * which items reach the box and where each one starts, and the host draws each
+ * item at its column and its start.
+ *
+ * **Placed in the order of the set, each item under the column that ends
+ * highest**, the leftmost of a tie, as React Aria's `WaterfallLayout` and
+ * TanStack Virtual's lanes place them. So an item's start is never above the
+ * start of the item before it, and the first item to reach any offset is found
+ * by a binary search, as one column finds it.
+ *
+ * Sizes are the controller's: what was measured, or the estimate, each with
+ * the gap below it.
+ */
+export declare class Waterfall {
+    /** How many columns the items are laid out in, at least one. */
+    lanes: number;
+    /** Where each item starts, in pixels from the top of the set. */
+    private starts;
+    /** The column each item stands in. */
+    private columns;
+    /** How much room each item takes, with the gap below it. */
+    private sizes;
+    /** How far down the set the items `[0, i]` reach, the furthest of their ends. */
+    private reach;
+    /** How long the set is: where its longest column ends. */
+    private extent;
+    /** What the placement was built from, so it is built again only when that changes. */
+    private built;
+    /**
+     * Places `count` items whose sizes `size` gives, unless `stamp` says the
+     * sizes, the count and the columns are the ones already placed.
+     */
+    place(count: number, size: (index: number) => number, stamp: string): void;
+    /** Where item `index` starts, and where the set ends for an index past it. */
+    start(index: number): number;
+    /** The column item `index` stands in. */
+    lane(index: number): number;
+    /** How long the set is, where its longest column ends. */
+    length(): number;
+    /** The first item that reaches past `offset`, or the count where none does. */
+    from(offset: number): number;
+    /** The first item that starts at or past `offset`, so every item before it starts above. */
+    to(offset: number): number;
+    /** The first index whose number in `sorted` is past `offset`. */
+    private search;
+    /**
+     * Which item a key moves to from `at`, in a set of `count` items, or
+     * `undefined` for a key it does not take or where there is no item that way:
+     *
+     * - Down and Up move to the next or the previous item in the same column.
+     * - `next` and `previous` move to the column beside, to its item that sits
+     *   beside this one the most, or the nearest above where none does. Which
+     *   of Left and Right is `next` is the caller's, for a right-to-left page.
+     * - Page Down and Page Up move down or up the same column by `page` pixels,
+     *   to the item there, or the last item that way.
+     */
+    step(key: string, at: number, count: number, page: number): number | undefined;
+    /** How much room item `index` takes down its column, with the gap below it. */
+    private size;
+}

package/dist/controllers/virtualize-controller/waterfall.js

@@ -0,0 +1,137 @@
+export class Waterfall {
+    constructor() {
+        this.lanes = 1;
+        this.starts = [];
+        this.columns = [];
+        this.sizes = [];
+        this.reach = [];
+        this.extent = 0;
+        this.built = '';
+    }
+    place(count, size, stamp) {
+        const lanes = Math.max(1, Math.trunc(this.lanes) || 1);
+        const key = `${count}:${lanes}:${stamp}`;
+        if (key === this.built) {
+            return;
+        }
+        this.built = key;
+        const ends = new Array(lanes).fill(0);
+        this.starts = new Array(count);
+        this.columns = new Array(count);
+        this.sizes = new Array(count);
+        this.reach = new Array(count);
+        let furthest = 0;
+        for (let index = 0; index < count; index++) {
+            let lane = 0;
+            for (let other = 1; other < lanes; other++) {
+                if ((ends[other] ?? 0) < (ends[lane] ?? 0)) {
+                    lane = other;
+                }
+            }
+            const start = ends[lane] ?? 0;
+            const room = size(index);
+            const end = start + room;
+            ends[lane] = end;
+            furthest = Math.max(furthest, end);
+            this.starts[index] = start;
+            this.columns[index] = lane;
+            this.sizes[index] = room;
+            this.reach[index] = furthest;
+        }
+        this.extent = furthest;
+    }
+    start(index) {
+        return this.starts[index] ?? this.extent;
+    }
+    lane(index) {
+        return this.columns[index] ?? 0;
+    }
+    length() {
+        return this.extent;
+    }
+    from(offset) {
+        return this.search(this.reach, offset);
+    }
+    to(offset) {
+        return this.search(this.starts, offset - 1e-6);
+    }
+    search(sorted, offset) {
+        let low = 0;
+        let high = sorted.length;
+        while (low < high) {
+            const mid = (low + high) >> 1;
+            if ((sorted[mid] ?? 0) <= offset) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return low;
+    }
+    step(key, at, count, page) {
+        const lane = this.lane(at);
+        const along = (way, from = at) => {
+            for (let other = from + way; other >= 0 && other < count; other += way) {
+                if (this.lane(other) === lane) {
+                    return other;
+                }
+            }
+            return undefined;
+        };
+        if (key === 'ArrowDown' || key === 'ArrowUp') {
+            return along(key === 'ArrowDown' ? 1 : -1);
+        }
+        if (key === 'PageDown' || key === 'PageUp') {
+            const way = key === 'PageDown' ? 1 : -1;
+            const goal = this.start(at) + way * Math.max(1, page);
+            let found = at;
+            for (let next = along(way); next !== undefined; next = along(way, next)) {
+                found = next;
+                if (way > 0 ? this.start(next) + this.size(next) > goal : this.start(next) <= goal) {
+                    break;
+                }
+            }
+            return found === at ? undefined : found;
+        }
+        if (key !== 'next' && key !== 'previous') {
+            return undefined;
+        }
+        const beside = lane + (key === 'next' ? 1 : -1);
+        if (beside < 0 || beside >= Math.max(1, Math.trunc(this.lanes) || 1)) {
+            return undefined;
+        }
+        const top = this.start(at);
+        const bottom = top + this.size(at);
+        let best;
+        let most = 0;
+        let above;
+        for (let other = Math.max(0, this.from(top) - this.lanes); other < count; other++) {
+            const start = this.start(other);
+            if (start >= bottom) {
+                break;
+            }
+            if (this.lane(other) !== beside) {
+                continue;
+            }
+            const overlap = Math.min(bottom, start + this.size(other)) - Math.max(top, start);
+            if (overlap > most) {
+                best = other;
+                most = overlap;
+            }
+            above = other;
+        }
+        if (best !== undefined || above !== undefined) {
+            return best ?? above;
+        }
+        for (let other = at - 1; other >= 0; other--) {
+            if (this.lane(other) === beside) {
+                return other;
+            }
+        }
+        return undefined;
+    }
+    size(index) {
+        return this.sizes[index] ?? 0;
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { auditChildren } from '@fusion.dev/helix-core/audits/children';
+export { auditChildren, auditEntry } from '@fusion.dev/helix-core/audits/children';
 export { auditName } from '@fusion.dev/helix-core/audits/name';
 export { auditNesting } from '@fusion.dev/helix-core/audits/nesting';
 export { auditServed } from '@fusion.dev/helix-core/audits/served';
@@ -36,6 +36,7 @@ export { SwipeController, type SwipeOptions, } from './controllers/swipe-control
 export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { UpgradeController, type UpgradeOptions, } from './controllers/upgrade-controller/upgrade-controller.js';
 export { type Rendered, VirtualizeController, type VirtualizeOptions, type Window as VirtualizeWindow, } from './controllers/virtualize-controller/virtualize-controller.js';
+export { Waterfall } from './controllers/virtualize-controller/waterfall.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
 export { type ActivateDetail, type AuraFallbackDetail, type BandDetail, type CanvasView, type CaretDetail, type ChangeDetail, type CompleteDetail, type ConnectDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, type GraphFilterDetail, type GraphLayoutDetail, type GraphPartChangeDetail, type GraphSignalDetail, HelixActionEvent, HelixActivateEvent, HelixAuraFallbackEvent, HelixBandEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePasteEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeReorderEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixClearEvent, HelixCollapseEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyErrorEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixEditEvent, HelixEndEvent, HelixExpandEvent, HelixFacetEvent, HelixFilterEvent, HelixFilteredEvent, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, HelixHistoryEvent, HelixLoadEvent, HelixLoadMoreEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPanelResizeEvent, HelixPastedEvent, HelixPinEvent, HelixPressEvent, HelixPreviewEvent, HelixPreviousEvent, HelixRangeChangeEvent, HelixReadEvent, HelixReadingChangeEvent, HelixReadingPressEvent, HelixReconnectEvent, HelixRejectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixReorderedEvent, HelixResizedEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSelectedEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixSortedEvent, HelixSplitEvent, HelixStrandsFallbackEvent, HelixToggleEvent, HelixTourAskEvent, HelixTourStatusEvent, HelixTypingEvent, type MapClusterDetail, type MapPanDetail, type MapPartChangeDetail, type MapRotateDetail, type MapTiltDetail, type MapZoomDetail, type MoveDetail, type NavigateDetail, type OpenDetail, type PasteDetail, type PressDetail, type PressPointerType, type RangeDetail, type ReadDetail, type ReadingDetail, type ReconnectDetail, type Refusal, type RefusedFile, type RejectDetail, type RelabelDetail, type RemoveDetail, type ReorderDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type StrandsFallbackDetail, type ToggleDetail, type TourStatusDetail, type TypingDetail, type ViewportPanDetail, type ViewportZoomDetail, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { auditChildren } from '@fusion.dev/helix-core/audits/children';
+export { auditChildren, auditEntry } from '@fusion.dev/helix-core/audits/children';
 export { auditName } from '@fusion.dev/helix-core/audits/name';
 export { auditNesting } from '@fusion.dev/helix-core/audits/nesting';
 export { auditServed } from '@fusion.dev/helix-core/audits/served';
@@ -36,6 +36,7 @@ export { SwipeController, } from './controllers/swipe-controller/swipe-controlle
 export { TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { UpgradeController, } from './controllers/upgrade-controller/upgrade-controller.js';
 export { VirtualizeController, } from './controllers/virtualize-controller/virtualize-controller.js';
+export { Waterfall } from './controllers/virtualize-controller/waterfall.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
 export { HelixActionEvent, HelixActivateEvent, HelixAuraFallbackEvent, HelixBandEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePasteEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeReorderEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixClearEvent, HelixCollapseEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyErrorEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixEditEvent, HelixEndEvent, HelixExpandEvent, HelixFacetEvent, HelixFilterEvent, HelixFilteredEvent, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, HelixHistoryEvent, HelixLoadEvent, HelixLoadMoreEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPanelResizeEvent, HelixPastedEvent, HelixPinEvent, HelixPressEvent, HelixPreviewEvent, HelixPreviousEvent, HelixRangeChangeEvent, HelixReadEvent, HelixReadingChangeEvent, HelixReadingPressEvent, HelixReconnectEvent, HelixRejectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixReorderedEvent, HelixResizedEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSelectedEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixSortedEvent, HelixSplitEvent, HelixStrandsFallbackEvent, HelixToggleEvent, HelixTourAskEvent, HelixTourStatusEvent, HelixTypingEvent, } from './events/events.js';
 export { HelixElement, whenHydrated } from './helix-element/helix-element.js';

package/dist/utils/audit-children/audit-children-off.d.ts

@@ -1,4 +1,4 @@
-import type { auditChildren as audit } from './audit-children.js';
+import type { auditChildren as audit, auditEntry as entry } from './audit-children.js';
 /**
  * The unregistered-child warning in a production build: nothing.
  *
@@ -8,3 +8,5 @@ import type { auditChildren as audit } from './audit-children.js';
  * builds. See `audit-children.ts`.
  */
 export declare const auditChildren: typeof audit;
+/** The missing-entry warning in a production build: nothing. See `auditEntry`. */
+export declare const auditEntry: typeof entry;

package/dist/utils/audit-children/audit-children-off.js

@@ -1 +1,2 @@
 export const auditChildren = () => { };
+export const auditEntry = () => { };

package/dist/utils/audit-children/audit-children.d.ts

@@ -26,3 +26,19 @@
  * host's light DOM.
  */
 export declare const auditChildren: (host: HTMLElement, part: string, entry: string, consequence: string, drawn?: boolean) => void;
+/**
+ * Reports a property set on a host whose behavior is in an entry of its own
+ * that nobody imported, naming the entry.
+ *
+ * **The second shape of the same mistake.** Menu's filter is
+ * `menu/filter`, so a menu that never filters carries none of its code, and a
+ * page that sets `filterable` and imports only the menu gets a menu with no
+ * field and nothing thrown. This says so, once for each host tag and entry on
+ * the page, with the line to add.
+ *
+ * `attribute` is the one the page set, `entry` the entry after the tier's
+ * package, such as `menu/filter`, and `consequence` what the missing entry
+ * costs, after "so". `missing` is asked once the page has loaded and painted,
+ * so an entry a later module imports is not taken for a missing one.
+ */
+export declare const auditEntry: (host: HTMLElement, attribute: string, entry: string, consequence: string, missing: () => boolean) => void;

package/dist/utils/audit-children/audit-children.js

@@ -1,5 +1,16 @@
 import { reportRuntime } from '../report-runtime/report-runtime.js';
 const reported = new Set();
+const afterPaint = (check) => {
+    const frame = () => {
+        requestAnimationFrame(check);
+    };
+    if (document.readyState === 'complete') {
+        frame();
+    }
+    else {
+        window.addEventListener('load', frame, { once: true });
+    }
+};
 export const auditChildren = (host, part, entry, consequence, drawn = false) => {
     if (typeof window === 'undefined') {
         return;
@@ -25,13 +36,27 @@ export const auditChildren = (host, part, entry, consequence, drawn = false) =>
             tag: host.localName,
         });
     };
-    const frame = () => {
-        requestAnimationFrame(check);
-    };
-    if (document.readyState === 'complete') {
-        frame();
+    afterPaint(check);
+};
+export const auditEntry = (host, attribute, entry, consequence, missing) => {
+    if (typeof window === 'undefined') {
+        return;
     }
-    else {
-        window.addEventListener('load', frame, { once: true });
+    const key = `${host.localName}>${entry}`;
+    if (reported.has(key)) {
+        return;
     }
+    afterPaint(() => {
+        if (reported.has(key) || !host.isConnected || !missing()) {
+            return;
+        }
+        reported.add(key);
+        const tier = host.constructor.tier ?? 'helix-headless-';
+        const pkg = tier === 'helix-' ? '@fusion.dev/helix' : '@fusion.dev/helix-headless';
+        reportRuntime({
+            kind: 'unregistered-part',
+            message: `<${host.localName}> has \`${attribute}\` and its entry is not imported, so ${consequence}. Import '${pkg}/${entry}'.`,
+            tag: host.localName,
+        });
+    });
 };

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.182.2";
+export declare const VERSION = "0.184.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.182.2';
+export const VERSION = '0.184.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.182.2",
+  "version": "0.184.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -74,12 +74,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.182.2",
+    "@fusion.dev/helix-icons": "0.184.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.182.2",
-    "@fusion.dev/helix-testing": "0.182.2",
+    "@fusion.dev/helix-cem": "0.184.0",
+    "@fusion.dev/helix-testing": "0.184.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },