@fusion.dev/helix-core 0.160.0 → 0.161.0

package/custom-elements.json

@@ -5977,6 +5977,25 @@
               },
               "description": "Whether the reader is scrolling: a finger is on the box, the box moved\nwithin the last 150 milliseconds, or it has moved and its `scroll` event\nhas not arrived yet.\n\nFor a host that holds its own reader: a write to the scroll offset while\nthis is true ends a fling on iOS, and a reader position noted before the\nlast move is out of date."
             },
+            {
+              "kind": "method",
+              "name": "noteClamp",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "box",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ],
+              "description": "Takes the offset as the box's own where the box moved it up only because\nthe set below it got shorter, which the browser does to keep the offset\ninside the content, and answers where it was before.\n\n**Not a reader scrolling.** Rows at the end of the set measured shorter\nthan their estimates shrink the content, and the box pulls its offset back\nto the new bottom before any `scroll` event arrives. Read as a scroll, the\ndifference went into the spacer as drift and was then paid a second time:\nin Chromium, End on 2,000 rows of one to five lines left the window 292\npixels above the last item, which stayed drawn below the box as the row\nholding focus."
+            },
             {
               "kind": "field",
               "name": "rest",
@@ -6091,6 +6110,17 @@
               },
               "description": "How tall one item is on the straight line: the drawn rows' height once\nread, and `estimate` until then.\n\n**An estimate that is wrong on the straight line leaves the end of the\nset out of reach.** Rows of 21 pixels placed at 32 fill two thirds of the\nroom they are counted for, so the window stops short of the bottom of the\nbox and the spacer after it holds the rest: in Chromium, `scrollToIndex`\non the last of 5,000 such rows scrolled to the end and drew nothing there.\nReading the drawn rows once corrects the slope, and it is still a line."
             },
+            {
+              "kind": "method",
+              "name": "gap",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "description": "The space the host draws between two items, which each item counts."
+            },
             {
               "kind": "method",
               "name": "sampleRows",
@@ -18483,9 +18513,16 @@
                   "type": {
                     "text": "string"
                   }
+                },
+                {
+                  "name": "cause",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
                 }
               ],
-              "description": "Requests a new current item, and returns whether the change was applied."
+              "description": "Requests a new current item, and returns whether the change was applied.\n`cause` says why, where the family names its causes, and reaches\n`helix-before-activate` as `detail.cause`."
             },
             {
               "kind": "method",
@@ -18557,9 +18594,16 @@
                   "type": {
                     "text": "string"
                   }
+                },
+                {
+                  "name": "cause",
+                  "optional": true,
+                  "type": {
+                    "text": "string"
+                  }
                 }
               ],
-              "description": "Requests a new current item, and returns whether the change was applied.\n\nAnnounces before it acts, so `preventDefault()` on the `helix-before-activate` is\na refusal and nothing moves. Unlike a native control, nothing has moved\nby the time this runs, so refusing is simply not writing: there is\nnothing to put back. Nobody refusing means the set updates itself,\nwhether or not a consumer declared `active`, a declared property being a\nseed and a correction."
+              "description": "Requests a new current item, and returns whether the change was applied.\n\nAnnounces before it acts, so `preventDefault()` on the `helix-before-activate` is\na refusal and nothing moves. Unlike a native control, nothing has moved\nby the time this runs, so refusing is simply not writing: there is\nnothing to put back. Nobody refusing means the set updates itself,\nwhether or not a consumer declared `active`, a declared property being a\nseed and a correction. `cause` says why, where the family names its\ncauses, and reaches the event as `detail.cause`."
             },
             {
               "kind": "method",
@@ -32859,7 +32903,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.160.0'",
+          "default": "'0.161.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."
         }
       ],
@@ -33419,6 +33463,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.160.0"
+    "version": "0.161.0"
   }
 }

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

@@ -7,6 +7,12 @@ export interface VirtualizeOptions {
     count: () => number;
     /** How tall one item is along the scroll axis, in pixels. */
     estimate: () => number;
+    /**
+     * The space between two items along the scroll axis, in pixels, which the
+     * host draws, such as a flex or grid `gap`. Each item counts it as part of
+     * its own size. Zero by default.
+     */
+    gap?: () => number;
     /**
      * Rows kept either side of what fits, so a scroll reveals something drawn
      * rather than something blank. Four by default.
@@ -213,6 +219,20 @@ export declare class VirtualizeController implements ReactiveController {
      * last move is out of date.
      */
     scrolling(): boolean;
+    /**
+     * Takes the offset as the box's own where the box moved it up only because
+     * the set below it got shorter, which the browser does to keep the offset
+     * inside the content, and answers where it was before.
+     *
+     * **Not a reader scrolling.** Rows at the end of the set measured shorter
+     * than their estimates shrink the content, and the box pulls its offset back
+     * to the new bottom before any `scroll` event arrives. Read as a scroll, the
+     * difference went into the spacer as drift and was then paid a second time:
+     * in Chromium, End on 2,000 rows of one to five lines left the window 292
+     * pixels above the last item, which stayed drawn below the box as the row
+     * holding focus.
+     */
+    private noteClamp;
     /** Squares the spacer and the scroll offset once the box is still. */
     private readonly rest;
     /**
@@ -264,6 +284,8 @@ export declare class VirtualizeController implements ReactiveController {
      * Reading the drawn rows once corrects the slope, and it is still a line.
      */
     private line;
+    /** The space the host draws between two items, which each item counts. */
+    private gap;
     /**
      * Reads the drawn rows' height once for the straight line, for a host that
      * offers `rows` and does not measure.

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

@@ -17,7 +17,11 @@ export class VirtualizeController {
         this.touching = false;
         this.uneven = false;
         this.handleScroll = () => {
-            const top = this.options.container()?.scrollTop ?? 0;
+            const box = this.options.container();
+            if (box) {
+                this.noteClamp(box);
+            }
+            const top = box?.scrollTop ?? 0;
             if (top !== this.lastTop) {
                 this.heading = top > this.lastTop ? 1 : -1;
                 this.lastTop = top;
@@ -95,6 +99,15 @@ export class VirtualizeController {
             this.resting !== undefined ||
             (this.options.container()?.scrollTop ?? this.lastTop) !== this.lastTop);
     }
+    noteClamp(box) {
+        const was = this.lastTop;
+        if (!this.touching &&
+            box.scrollTop < was &&
+            box.scrollTop >= box.scrollHeight - box.clientHeight - 1) {
+            this.lastTop = box.scrollTop;
+        }
+        return was;
+    }
     square() {
         const box = this.options.container();
         if (this.drift > 0 && box) {
@@ -161,7 +174,10 @@ export class VirtualizeController {
     }
     line() {
         const estimate = Math.max(1, this.options.estimate());
-        return this.sample?.estimate === estimate ? this.sample.size : estimate;
+        return this.sample?.estimate === estimate ? this.sample.size : estimate + this.gap();
+    }
+    gap() {
+        return Math.max(0, this.options.gap?.() ?? 0);
     }
     sampleRows() {
         const estimate = Math.max(1, this.options.estimate());
@@ -176,7 +192,7 @@ export class VirtualizeController {
         const uneven = Math.max(...seen) - Math.min(...seen) > 1;
         if (this.sample?.estimate !== estimate) {
             const was = this.line();
-            const size = Math.max(1, seen.reduce((sum, height) => sum + height, 0) / seen.length);
+            const size = Math.max(1, seen.reduce((sum, height) => sum + height, 0) / seen.length) + this.gap();
             this.sample = { estimate, size };
             if (Math.abs(size - was) >= 0.5) {
                 const box = this.options.container();
@@ -291,12 +307,13 @@ export class VirtualizeController {
         }
         const total = Math.max(0, this.options.count());
         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);
         let news = false;
         for (const { element, index } of rows) {
-            if (this.heights.record(index, element.getBoundingClientRect().height)) {
+            if (this.heights.record(index, element.getBoundingClientRect().height + this.gap())) {
                 news = true;
             }
         }
@@ -310,7 +327,7 @@ export class VirtualizeController {
                 this.drift -= moved;
             }
             else {
-                box.scrollTop += moved;
+                box.scrollTop = from + moved;
                 this.lastTop = box.scrollTop;
             }
         }

package/dist/events/details.d.ts

@@ -258,6 +258,12 @@ export interface TourAskDetail {
  * that `event.target` does not.
  */
 export interface ChangeDetail {
+    /**
+     * Why the change was asked for, where a family names its causes. Video
+     * Playlist sends `ended`, `next`, `press`, `previous`, and `removed` on
+     * `helix-before-activate`.
+     */
+    cause?: string;
     /** The value after the change. */
     value: string;
 }

package/dist/mixins/mixin-controller-active/mixin-controller-active.d.ts

@@ -21,8 +21,12 @@ export declare class MixinControllerActiveInterface {
      * is written.
      */
     defaultActive: string;
-    /** Requests a new current item, and returns whether the change was applied. */
-    requestActive(next: string): boolean;
+    /**
+     * Requests a new current item, and returns whether the change was applied.
+     * `cause` says why, where the family names its causes, and reaches
+     * `helix-before-activate` as `detail.cause`.
+     */
+    requestActive(next: string, cause?: string): boolean;
     /**
      * Which item is current, given what there is to choose from.
      *

package/dist/mixins/mixin-controller-active/mixin-controller-active.js

@@ -23,7 +23,7 @@ export const MixinControllerActive = (Base) => {
             this.activeState = next;
             this.requestUpdate('active', previous);
         }
-        requestActive(next) {
+        requestActive(next, cause) {
             if (next === this.active) {
                 return true;
             }
@@ -34,7 +34,7 @@ export const MixinControllerActive = (Base) => {
                     this.activeState = value;
                     this.requestUpdate('active', previous);
                 },
-                event: (value) => new HelixBeforeActivateEvent({ value }),
+                event: (value) => new HelixBeforeActivateEvent(cause === undefined ? { value } : { cause, value }),
                 host: this,
                 next,
             });

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.160.0";
+export declare const VERSION = "0.161.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.160.0';
+export const VERSION = '0.161.0';

package/package.json

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