@fusion.dev/helix-core 0.4.6 → 0.5.0

package/custom-elements.json

@@ -1645,6 +1645,215 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/controllers/virtualize-controller/heights.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Where each item starts, when the items are not all the same height.\n\n**The fixed-estimate window is a straight line and this is the other case\nthe controller's own note defers.** With one estimate, offset and index\nconvert by division, which can never disagree with itself. A transcript whose\nlast message grows every token, or a table row that wraps, has no such line:\nthe only way to place item 900 is to know what the 899 above it came to.\n\n**Measured where it has been seen, estimated everywhere else.** An item is\nmeasured once it has been rendered, and until then it stands at the estimate,\nso a set of ten thousand costs ten thousand numbers rather than ten thousand\nlayouts. The estimate is read per call rather than captured, because a host\nmay change it and the sums have to move with it.\n\n**The prefix sums are rebuilt from the first index that changed**, not from\nzero and not on every read. Recording a height marks that index dirty;\nnothing is recomputed until somebody asks a question that needs it. A scroll\nthat records twelve rows therefore pays one rebuild rather than twelve, and a\nscroll that records none pays nothing.",
+          "name": "Heights",
+          "members": [
+            {
+              "kind": "field",
+              "name": "estimate",
+              "type": {
+                "text": "() => number"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "default": "estimate"
+            },
+            {
+              "kind": "field",
+              "name": "seen",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Map<number, number>()",
+              "description": "Heights that have been seen, by index. Sparse on purpose."
+            },
+            {
+              "kind": "field",
+              "name": "sums",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "default": "[0]",
+              "description": "`sums[i]` is the room items `[0, i)` take. One longer than the count."
+            },
+            {
+              "kind": "field",
+              "name": "dirty",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "The first index whose sum is no longer trustworthy."
+            },
+            {
+              "kind": "field",
+              "name": "built",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "The estimate the sums were built against, so a change to it rebuilds."
+            },
+            {
+              "kind": "method",
+              "name": "at",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "How tall one item is: what was measured, or what is assumed."
+            },
+            {
+              "kind": "method",
+              "name": "record",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "size",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Records a height, and says whether it was news.\n\nThe answer matters to the caller rather than here: a height that differs\nfrom what was assumed moves the window, and the controller has to know that\nthe move came from outside rather than from itself."
+            },
+            {
+              "kind": "method",
+              "name": "before",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The room items `[0, index)` take."
+            },
+            {
+              "kind": "method",
+              "name": "total",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The room the whole set takes."
+            },
+            {
+              "kind": "method",
+              "name": "indexAt",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "offset",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The last item that starts at or before `offset`.\n\nA binary search rather than a walk, so a reader dragging the thumb to the\nend of ten thousand rows costs fourteen comparisons rather than ten\nthousand."
+            },
+            {
+              "kind": "method",
+              "name": "forget",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Drops everything, for a set that is no longer the same set.\n\nA host that swaps its data has heights recorded against indices that now\nname different items, and keeping them is worse than having none: the\nestimate is honest about not knowing where a stale measurement is not."
+            },
+            {
+              "kind": "method",
+              "name": "build",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "count",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Brings the sums up to date, from the first index that changed."
+            }
+          ],
+          "helix": {}
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "Heights",
+          "declaration": {
+            "name": "Heights",
+            "module": "src/controllers/virtualize-controller/heights.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/controllers/virtualize-controller/virtualize-controller.ts",
@@ -1729,6 +1938,17 @@
               "default": "{ after: 0, before: 0, first: 0, last: 0 }",
               "description": "The slice to render, recomputed on scroll and on resize."
             },
+            {
+              "kind": "field",
+              "name": "heights",
+              "type": {
+                "text": "Heights"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "Where each item starts, once any of them has been seen.",
+              "default": "new Heights(() => this.options.estimate())"
+            },
             {
               "kind": "method",
               "name": "hostConnected",
@@ -1774,6 +1994,94 @@
               },
               "description": "Reads the scroll offset and settles the window.\n\nAsks for an update only when the slice actually moved. A scroll fires many\nevents per frame and most of them land inside the row already at the top,\nso requesting one per event would re-render the list for every pixel."
             },
+            {
+              "kind": "method",
+              "name": "uniform",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Window"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                },
+                {
+                  "name": "total",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "size",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "overscan",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The straight line: one estimate, so offset and index convert by division."
+            },
+            {
+              "kind": "method",
+              "name": "measured",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Window"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                },
+                {
+                  "name": "total",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "overscan",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "The measured version, which asks where each item starts rather than dividing.\n\nThe scan for `last` walks forward from `first` rather than searching,\nbecause it stops at the bottom of the viewport: it is bounded by what fits\non screen plus the overscan, whatever the set's length."
+            },
+            {
+              "kind": "method",
+              "name": "hostUpdated",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Measures what was just drawn, and holds the reader still if it moved.\n\n**This is the pass the fixed-estimate note warns about, made to terminate.**\nMeasuring after a render, and re-windowing on what was measured, is a loop\nthat feeds itself. What bounds it is that a height is news exactly once:\n`record` answers false for a size it already holds, so an item can move the\nwindow on the render that first shows it and never again. A set of ten\nthousand can therefore surprise this ten thousand times over its life and\nnot twice for the same row.\n\n**The scroll offset is corrected before anything is drawn again.** An item\nabove the window turning out taller than its estimate moves everything\nbelow it, including what the reader is looking at. Adding the same\ndifference to `scrollTop` puts the content back under them, which is why a\nlist of variable rows can be scrolled through without it walking away.\nSkipped at the very top, where there is nothing above to have moved."
+            },
+            {
+              "kind": "method",
+              "name": "forget",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Drops every measurement, for a host that swapped its data.\n\nNot called on a count change, which would be the obvious place and is\nwrong: appending to a transcript leaves every existing index naming the\nsame item, and forgetting there would re-measure the whole set on every\nmessage. A host that replaces its set calls this, because only it knows\nthat index 900 is now a different row."
+            },
             {
               "kind": "method",
               "name": "report",
@@ -1787,14 +2095,6 @@
             }
           ],
           "helix": {}
-        },
-        {
-          "kind": "variable",
-          "name": "first"
-        },
-        {
-          "kind": "variable",
-          "name": "last"
         }
       ],
       "exports": [

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

@@ -0,0 +1,65 @@
+/**
+ * Where each item starts, when the items are not all the same height.
+ *
+ * **The fixed-estimate window is a straight line and this is the other case
+ * the controller's own note defers.** With one estimate, offset and index
+ * convert by division, which can never disagree with itself. A transcript whose
+ * last message grows every token, or a table row that wraps, has no such line:
+ * the only way to place item 900 is to know what the 899 above it came to.
+ *
+ * **Measured where it has been seen, estimated everywhere else.** An item is
+ * measured once it has been rendered, and until then it stands at the estimate,
+ * so a set of ten thousand costs ten thousand numbers rather than ten thousand
+ * layouts. The estimate is read per call rather than captured, because a host
+ * may change it and the sums have to move with it.
+ *
+ * **The prefix sums are rebuilt from the first index that changed**, not from
+ * zero and not on every read. Recording a height marks that index dirty;
+ * nothing is recomputed until somebody asks a question that needs it. A scroll
+ * that records twelve rows therefore pays one rebuild rather than twelve, and a
+ * scroll that records none pays nothing.
+ */
+export declare class Heights {
+    private readonly estimate;
+    /** Heights that have been seen, by index. Sparse on purpose. */
+    private readonly seen;
+    /** `sums[i]` is the room items `[0, i)` take. One longer than the count. */
+    private sums;
+    /** The first index whose sum is no longer trustworthy. */
+    private dirty;
+    /** The estimate the sums were built against, so a change to it rebuilds. */
+    private built;
+    constructor(estimate: () => number);
+    /** How tall one item is: what was measured, or what is assumed. */
+    at(index: number): number;
+    /**
+     * Records a height, and says whether it was news.
+     *
+     * The answer matters to the caller rather than here: a height that differs
+     * from what was assumed moves the window, and the controller has to know that
+     * the move came from outside rather than from itself.
+     */
+    record(index: number, size: number): boolean;
+    /** The room items `[0, index)` take. */
+    before(index: number, count: number): number;
+    /** The room the whole set takes. */
+    total(count: number): number;
+    /**
+     * The last item that starts at or before `offset`.
+     *
+     * A binary search rather than a walk, so a reader dragging the thumb to the
+     * end of ten thousand rows costs fourteen comparisons rather than ten
+     * thousand.
+     */
+    indexAt(offset: number, count: number): number;
+    /**
+     * Drops everything, for a set that is no longer the same set.
+     *
+     * A host that swaps its data has heights recorded against indices that now
+     * name different items, and keeping them is worse than having none: the
+     * estimate is honest about not knowing where a stale measurement is not.
+     */
+    forget(): void;
+    /** Brings the sums up to date, from the first index that changed. */
+    private build;
+}

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

@@ -0,0 +1,80 @@
+export class Heights {
+    constructor(estimate) {
+        this.seen = new Map();
+        this.sums = [0];
+        this.dirty = 0;
+        this.built = 0;
+        this.estimate = estimate;
+    }
+    at(index) {
+        return this.seen.get(index) ?? Math.max(1, this.estimate());
+    }
+    record(index, size) {
+        if (index < 0 || !Number.isFinite(size) || size <= 0) {
+            return false;
+        }
+        const rounded = Math.round(size);
+        if (this.seen.get(index) === rounded) {
+            return false;
+        }
+        const was = this.at(index);
+        this.seen.set(index, rounded);
+        if (rounded === was) {
+            return false;
+        }
+        this.dirty = Math.min(this.dirty, index);
+        return true;
+    }
+    before(index, count) {
+        this.build(count);
+        return this.sums[Math.max(0, Math.min(index, count))] ?? 0;
+    }
+    total(count) {
+        return this.before(count, count);
+    }
+    indexAt(offset, count) {
+        if (count <= 0) {
+            return 0;
+        }
+        this.build(count);
+        const target = Math.max(0, offset);
+        let low = 0;
+        let high = count;
+        while (low < high) {
+            const mid = (low + high) >> 1;
+            if ((this.sums[mid + 1] ?? 0) <= target) {
+                low = mid + 1;
+            }
+            else {
+                high = mid;
+            }
+        }
+        return Math.min(low, count - 1);
+    }
+    forget() {
+        this.seen.clear();
+        this.dirty = 0;
+        this.sums = [0];
+    }
+    build(count) {
+        const size = Math.max(1, this.estimate());
+        if (size !== this.built) {
+            this.built = size;
+            this.dirty = 0;
+        }
+        if (this.dirty > count && this.sums.length === count + 1) {
+            return;
+        }
+        const from = Math.min(this.dirty, count);
+        if (this.sums.length !== count + 1) {
+            this.sums.length = count + 1;
+        }
+        let running = this.sums[from] ?? 0;
+        for (let index = from; index < count; index++) {
+            this.sums[index] = running;
+            running += this.at(index);
+        }
+        this.sums[count] = running;
+        this.dirty = count + 1;
+    }
+}

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

@@ -13,6 +13,20 @@ export interface VirtualizeOptions {
      * fast scrolling at a 32 pixel row.
      */
     overscan?: number;
+    /**
+     * The rendered rows, in window order, for a set whose items differ in height.
+     *
+     * **Supplying this is what turns measurement on**, and leaving it off keeps
+     * the straight line the note below defends. A host that returns its row
+     * elements gets each one measured after it renders and placed by what it
+     * came to; a host that returns nothing gets every item at `estimate`, which
+     * is right whenever the rows really are uniform and is cheaper.
+     *
+     * The first element returned is `window.first`. Order is the only thing
+     * connecting an element to an index, since the controller cannot ask a row
+     * which item it drew.
+     */
+    rows?: () => Iterable<HTMLElement>;
 }
 /** Which slice is rendered, and how much empty space stands in for the rest. */
 export interface Window {
@@ -98,6 +112,8 @@ export declare class VirtualizeController implements ReactiveController {
     private last;
     /** The slice to render, recomputed on scroll and on resize. */
     window: Window;
+    /** Where each item starts, once any of them has been seen. */
+    private readonly heights;
     constructor(host: ReactiveControllerHost, options: VirtualizeOptions);
     hostConnected(): void;
     hostDisconnected(): void;
@@ -112,6 +128,45 @@ export declare class VirtualizeController implements ReactiveController {
      * so requesting one per event would re-render the list for every pixel.
      */
     measure(): void;
+    /** The straight line: one estimate, so offset and index convert by division. */
+    private uniform;
+    /**
+     * The measured version, which asks where each item starts rather than dividing.
+     *
+     * The scan for `last` walks forward from `first` rather than searching,
+     * because it stops at the bottom of the viewport: it is bounded by what fits
+     * on screen plus the overscan, whatever the set's length.
+     */
+    private measured;
+    /**
+     * Measures what was just drawn, and holds the reader still if it moved.
+     *
+     * **This is the pass the fixed-estimate note warns about, made to terminate.**
+     * Measuring after a render, and re-windowing on what was measured, is a loop
+     * that feeds itself. What bounds it is that a height is news exactly once:
+     * `record` answers false for a size it already holds, so an item can move the
+     * window on the render that first shows it and never again. A set of ten
+     * thousand can therefore surprise this ten thousand times over its life and
+     * not twice for the same row.
+     *
+     * **The scroll offset is corrected before anything is drawn again.** An item
+     * above the window turning out taller than its estimate moves everything
+     * below it, including what the reader is looking at. Adding the same
+     * difference to `scrollTop` puts the content back under them, which is why a
+     * list of variable rows can be scrolled through without it walking away.
+     * Skipped at the very top, where there is nothing above to have moved.
+     */
+    hostUpdated(): void;
+    /**
+     * Drops every measurement, for a host that swapped its data.
+     *
+     * Not called on a count change, which would be the obvious place and is
+     * wrong: appending to a transcript leaves every existing index naming the
+     * same item, and forgetting there would re-measure the whole set on every
+     * message. A host that replaces its set calls this, because only it knows
+     * that index 900 is now a different row.
+     */
+    forget(): void;
     /**
      * Says once that the box cannot be measured, and why.
      *

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

@@ -1,3 +1,4 @@
+import { Heights } from './heights.js';
 const UNSTABLE = 10;
 export class VirtualizeController {
     constructor(host, options) {
@@ -11,6 +12,7 @@ export class VirtualizeController {
         };
         this.host = host;
         this.options = options;
+        this.heights = new Heights(() => this.options.estimate());
         host.addController(this);
     }
     hostConnected() {
@@ -45,15 +47,9 @@ export class VirtualizeController {
             return;
         }
         const overscan = this.options.overscan ?? 4;
-        const first = Math.max(0, Math.floor(box.scrollTop / size) - overscan);
-        const fits = Math.ceil(box.clientHeight / size) + overscan * 2;
-        const last = Math.min(total, first + fits);
-        const next = {
-            after: Math.max(0, (total - last) * size),
-            before: first * size,
-            first,
-            last,
-        };
+        const next = this.options.rows
+            ? this.measured(box, total, overscan)
+            : this.uniform(box, total, size, overscan);
         if (this.last?.count !== total || this.last.estimate !== size) {
             this.last = { count: total, estimate: size };
             this.settling = 0;
@@ -74,6 +70,56 @@ export class VirtualizeController {
         this.window = next;
         this.host.requestUpdate();
     }
+    uniform(box, total, size, overscan) {
+        const first = Math.max(0, Math.floor(box.scrollTop / size) - overscan);
+        const fits = Math.ceil(box.clientHeight / size) + overscan * 2;
+        const last = Math.min(total, first + fits);
+        return { after: Math.max(0, (total - last) * size), before: first * size, first, last };
+    }
+    measured(box, total, overscan) {
+        const first = Math.max(0, this.heights.indexAt(box.scrollTop, total) - overscan);
+        const bottom = box.scrollTop + box.clientHeight;
+        let last = this.heights.indexAt(box.scrollTop, total);
+        while (last < total && this.heights.before(last, total) < bottom) {
+            last += 1;
+        }
+        last = Math.min(total, last + overscan);
+        return {
+            after: Math.max(0, this.heights.total(total) - this.heights.before(last, total)),
+            before: this.heights.before(first, total),
+            first,
+            last,
+        };
+    }
+    hostUpdated() {
+        const rows = this.options.rows?.();
+        if (!rows) {
+            return;
+        }
+        const total = Math.max(0, this.options.count());
+        const was = this.heights.before(this.window.first, total);
+        let news = false;
+        let index = this.window.first;
+        for (const row of rows) {
+            if (this.heights.record(index, row.getBoundingClientRect().height)) {
+                news = true;
+            }
+            index += 1;
+        }
+        if (!news) {
+            return;
+        }
+        this.settling = 0;
+        const box = this.options.container();
+        const now = this.heights.before(this.window.first, total);
+        if (box && box.scrollTop > 0 && now !== was) {
+            box.scrollTop += now - was;
+        }
+        this.measure();
+    }
+    forget() {
+        this.heights.forget();
+    }
     report() {
         if (this.warned) {
             return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,12 +34,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.4.6"
+    "@fusion.dev/helix-icons": "0.5.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.4.6",
-    "@fusion.dev/helix-testing": "0.4.6",
+    "@fusion.dev/helix-cem": "0.5.0",
+    "@fusion.dev/helix-testing": "0.5.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",