@fusion.dev/helix-core 0.5.0 → 0.7.0

package/custom-elements.json

@@ -2033,7 +2033,18 @@
             },
             {
               "kind": "method",
-              "name": "measured",
+              "name": "measuring",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "description": "Whether this pass places by measurement: offered, and wanted."
+            },
+            {
+              "kind": "method",
+              "name": "placed",
               "privacy": "private",
               "return": {
                 "type": {
@@ -3902,6 +3913,14 @@
             "module": "./controllers/token-color-controller/token-color-controller.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "Rendered",
+          "declaration": {
+            "name": "Rendered",
+            "module": "./controllers/virtualize-controller/virtualize-controller.js"
+          }
+        },
         {
           "kind": "js",
           "name": "VirtualizeController",

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

@@ -22,11 +22,35 @@ export interface VirtualizeOptions {
      * 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.
+     * **Each row carries its own index rather than being counted off from
+     * `window.first`.** A host is free to place its rows whenever it likes, and
+     * `hostUpdated` runs *before* `updated`, so a host that appends there has the
+     * previous window's rows in the tree when this is asked. Counting positionally
+     * would then record the heights of the right elements against the wrong
+     * items, and be silently wrong exactly when the window moved.
      */
-    rows?: () => Iterable<HTMLElement>;
+    rows?: () => Iterable<Rendered>;
+    /**
+     * Whether to place by measurement on this pass, for a host that can be told.
+     *
+     * **Separate from `rows` because the two answer different questions**: `rows`
+     * says a host is able to report what it drew, and this says it wants the
+     * measured placement today. A host with a `measured` attribute needs to
+     * change its mind at runtime, and a controller is constructed once.
+     *
+     * True by default, so a host that supplies `rows` and nothing else measures.
+     * The uniform path is kept for the case it is better at: it converts offset
+     * to index by division, where the measured one builds prefix sums across the
+     * whole set the first time it is asked.
+     */
+    measured?: () => boolean;
+}
+/** A row that has been drawn, and which item of the set it drew. */
+export interface Rendered {
+    /** The element, measured along the scroll axis. */
+    element: HTMLElement;
+    /** Which item it is, in the whole set rather than in the window. */
+    index: number;
 }
 /** Which slice is rendered, and how much empty space stands in for the rest. */
 export interface Window {
@@ -130,6 +154,8 @@ export declare class VirtualizeController implements ReactiveController {
     measure(): void;
     /** The straight line: one estimate, so offset and index convert by division. */
     private uniform;
+    /** Whether this pass places by measurement: offered, and wanted. */
+    private measuring;
     /**
      * The measured version, which asks where each item starts rather than dividing.
      *
@@ -137,7 +163,7 @@ export declare class VirtualizeController implements ReactiveController {
      * 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;
+    private placed;
     /**
      * Measures what was just drawn, and holds the reader still if it moved.
      *

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

@@ -47,8 +47,8 @@ export class VirtualizeController {
             return;
         }
         const overscan = this.options.overscan ?? 4;
-        const next = this.options.rows
-            ? this.measured(box, total, overscan)
+        const next = this.measuring()
+            ? this.placed(box, total, overscan)
             : this.uniform(box, total, size, overscan);
         if (this.last?.count !== total || this.last.estimate !== size) {
             this.last = { count: total, estimate: size };
@@ -76,7 +76,10 @@ export class VirtualizeController {
         const last = Math.min(total, first + fits);
         return { after: Math.max(0, (total - last) * size), before: first * size, first, last };
     }
-    measured(box, total, overscan) {
+    measuring() {
+        return this.options.rows !== undefined && (this.options.measured?.() ?? true);
+    }
+    placed(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);
@@ -92,6 +95,9 @@ export class VirtualizeController {
         };
     }
     hostUpdated() {
+        if (!this.measuring()) {
+            return;
+        }
         const rows = this.options.rows?.();
         if (!rows) {
             return;
@@ -99,12 +105,10 @@ export class VirtualizeController {
         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)) {
+        for (const { element, index } of rows) {
+            if (this.heights.record(index, element.getBoundingClientRect().height)) {
                 news = true;
             }
-            index += 1;
         }
         if (!news) {
             return;

package/dist/index.d.ts

@@ -12,7 +12,7 @@ export { KeyboardNavigationController, type KeyboardNavigationOptions, type Navi
 export { PopoverController, type PopoverOptions, } from './controllers/popover-controller/popover-controller.js';
 export { SourceController, type SourceHost, } from './controllers/source-controller/source-controller.js';
 export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
-export { VirtualizeController, type VirtualizeOptions, type Window as VirtualizeWindow, } from './controllers/virtualize-controller/virtualize-controller.js';
+export { type Rendered, VirtualizeController, type VirtualizeOptions, type Window as VirtualizeWindow, } from './controllers/virtualize-controller/virtualize-controller.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
 export { type CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFilterEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, type NavigateDetail, type OpenDetail, type ReadDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type ToggleDetail, } from './events/events.js';
 export { HelixElement } from './helix-element/helix-element.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.5.0",
+  "version": "0.7.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.5.0"
+    "@fusion.dev/helix-icons": "0.7.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.5.0",
-    "@fusion.dev/helix-testing": "0.5.0",
+    "@fusion.dev/helix-cem": "0.7.0",
+    "@fusion.dev/helix-testing": "0.7.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",