@fusion.dev/helix-headless 0.4.7 → 0.6.0

package/custom-elements.json

@@ -74918,7 +74918,7 @@
                 "text": "number"
               },
               "default": "32",
-              "description": "How tall one row is, in pixels, used to map scroll offset to an index.",
+              "description": "How tall one row is, in pixels, used to map scroll offset to an index.\n\nAn estimate rather than a measurement while `measured` is off, which is\nright whenever the rows really are one height and is the cheaper of the two.",
               "attribute": "estimate"
             },
             {
@@ -74941,6 +74941,16 @@
               "description": "What the list is called, since the rendered rows are only a window on it.",
               "attribute": "label"
             },
+            {
+              "kind": "field",
+              "name": "measured",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Places rows by what they came to rather than by `estimate`.\n\n**Off by default, because the straight line is better when it holds.** One\nestimate makes offset and index convert by division, which can never\ndisagree with itself; measuring is what a set of genuinely different\nheights needs and costs a read of each row as it renders. A list of\none-line rows should leave this alone.",
+              "attribute": "measured"
+            },
             {
               "kind": "field",
               "name": "rows",
@@ -74956,7 +74966,18 @@
               "name": "virtualize",
               "privacy": "private",
               "readonly": true,
-              "default": "new VirtualizeController(this, { container: () => this.renderRoot.querySelector<HTMLElement>('[part=\"viewport\"]'), count: () => this.rows.length, estimate: () => this.estimate, })"
+              "default": "new VirtualizeController(this, { container: () => this.renderRoot.querySelector<HTMLElement>('[part=\"viewport\"]'), count: () => this.rows.length, estimate: () => this.estimate, measured: () => this.measured, rows: () => this.drawn(), })"
+            },
+            {
+              "kind": "method",
+              "name": "drawn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ element: HTMLElement; index: number }[]"
+                }
+              },
+              "description": "The rows in the tree, each with the item it drew.\n\n**Read off `data-index` rather than counted**, because what is in the tree\nwhen the controller asks is what `place` appended on the *previous* pass:\n`hostUpdated` runs before `updated`, so counting from the current window\nwould record the right heights against the wrong items every time the\nwindow moved."
             },
             {
               "kind": "method",
@@ -75160,7 +75181,7 @@
                 "text": "number"
               },
               "default": "32",
-              "description": "How tall one row is, in pixels, used to map scroll offset to an index.",
+              "description": "How tall one row is, in pixels, used to map scroll offset to an index.\n\nAn estimate rather than a measurement while `measured` is off, which is\nright whenever the rows really are one height and is the cheaper of the two.",
               "fieldName": "estimate"
             },
             {
@@ -75180,6 +75201,15 @@
               "default": "''",
               "description": "What the list is called, since the rendered rows are only a window on it.",
               "fieldName": "label"
+            },
+            {
+              "name": "measured",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Places rows by what they came to rather than by `estimate`.\n\n**Off by default, because the straight line is better when it holds.** One\nestimate makes offset and index convert by division, which can never\ndisagree with itself; measuring is what a set of genuinely different\nheights needs and costs a read of each row as it renders. A list of\none-line rows should leave this alone.",
+              "fieldName": "measured"
             }
           ],
           "superclass": {

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

@@ -32,6 +32,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 export declare class HelixHeadlessVirtualList extends HelixElement {
     /**
      * How tall one row is, in pixels, used to map scroll offset to an index.
+     *
+     * An estimate rather than a measurement while `measured` is off, which is
+     * right whenever the rows really are one height and is the cheaper of the two.
      */
     estimate: number;
     /**
@@ -42,6 +45,16 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      * What the list is called, since the rendered rows are only a window on it.
      */
     label: string;
+    /**
+     * Places rows by what they came to rather than by `estimate`.
+     *
+     * **Off by default, because the straight line is better when it holds.** One
+     * estimate makes offset and index convert by division, which can never
+     * disagree with itself; measuring is what a set of genuinely different
+     * heights needs and costs a read of each row as it renders. A list of
+     * one-line rows should leave this alone.
+     */
+    measured: boolean;
     /**
      * The parsed source.
      *
@@ -49,6 +62,16 @@ export declare class HelixHeadlessVirtualList extends HelixElement {
      */
     private rows;
     private readonly virtualize;
+    /**
+     * The rows in the tree, each with the item it drew.
+     *
+     * **Read off `data-index` rather than counted**, because what is in the tree
+     * when the controller asks is what `place` appended on the *previous* pass:
+     * `hostUpdated` runs before `updated`, so counting from the current window
+     * would record the right heights against the wrong items every time the
+     * window moved.
+     */
+    private drawn;
     /**
      * Reads the source named by `for`, once the document exists to read.
      *

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

@@ -13,13 +13,22 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
         this.estimate = 32;
         this.for = '';
         this.label = '';
+        this.measured = false;
         this.rows = [];
         this.virtualize = new VirtualizeController(this, {
             container: () => this.renderRoot.querySelector('[part="viewport"]'),
             count: () => this.rows.length,
             estimate: () => this.estimate,
+            measured: () => this.measured,
+            rows: () => this.drawn(),
         });
     }
+    drawn() {
+        return [...this.querySelectorAll('[data-index]')].map((element) => ({
+            element,
+            index: Number(element.dataset.index),
+        }));
+    }
     firstUpdated(changed) {
         super.firstUpdated?.(changed);
         this.read();
@@ -73,6 +82,7 @@ let HelixHeadlessVirtualList = class HelixHeadlessVirtualList extends HelixEleme
                 element.setAttribute('role', 'listitem');
                 element.setAttribute('aria-posinset', String(at + 1));
                 element.setAttribute('aria-setsize', String(total));
+                element.setAttribute('data-index', String(at));
             }
             fragment.append(clone);
         }
@@ -102,6 +112,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessVirtualList.prototype, "label", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessVirtualList.prototype, "measured", void 0);
 __decorate([
     state()
 ], HelixHeadlessVirtualList.prototype, "rows", void 0);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.4.7",
+  "version": "0.6.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -45,14 +45,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.4.7",
-    "@fusion.dev/helix-icons": "0.4.7",
+    "@fusion.dev/helix-core": "0.6.0",
+    "@fusion.dev/helix-icons": "0.6.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.4.7",
-    "@fusion.dev/helix-testing": "0.4.7",
+    "@fusion.dev/helix-cem": "0.6.0",
+    "@fusion.dev/helix-testing": "0.6.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^3.3.0",

package/types/jsx.d.ts

@@ -15296,21 +15296,43 @@ past the end is the one write the platform answers with an exception. */
 };
 
 export type HelixHeadlessVirtualListProps = {
-  /** How tall one row is, in pixels, used to map scroll offset to an index. */
+  /** How tall one row is, in pixels, used to map scroll offset to an index.
+
+An estimate rather than a measurement while `measured` is off, which is
+right whenever the rows really are one height and is the cheaper of the two. */
   estimate?: (HelixHeadlessVirtualList["estimate"]) | undefined;
   /** Id of the element holding the rows, as JSON in a script. */
   for?: (HelixHeadlessVirtualList["for"]) | undefined;
   /** What the list is called, since the rendered rows are only a window on it. */
   label?: (HelixHeadlessVirtualList["label"]) | undefined;
+  /** Places rows by what they came to rather than by `estimate`.
+
+**Off by default, because the straight line is better when it holds.** One
+estimate makes offset and index convert by division, which can never
+disagree with itself; measuring is what a set of genuinely different
+heights needs and costs a read of each row as it renders. A list of
+one-line rows should leave this alone. */
+  measured?: (HelixHeadlessVirtualList["measured"]) | undefined;
 };
 
 export type HelixHeadlessVirtualListSolidJsProps = {
-  /** How tall one row is, in pixels, used to map scroll offset to an index. */
+  /** How tall one row is, in pixels, used to map scroll offset to an index.
+
+An estimate rather than a measurement while `measured` is off, which is
+right whenever the rows really are one height and is the cheaper of the two. */
   "prop:estimate"?: (HelixHeadlessVirtualList["estimate"]) | undefined;
   /** Id of the element holding the rows, as JSON in a script. */
   "prop:for"?: (HelixHeadlessVirtualList["for"]) | undefined;
   /** What the list is called, since the rendered rows are only a window on it. */
   "prop:label"?: (HelixHeadlessVirtualList["label"]) | undefined;
+  /** Places rows by what they came to rather than by `estimate`.
+
+**Off by default, because the straight line is better when it holds.** One
+estimate makes offset and index convert by division, which can never
+disagree with itself; measuring is what a set of genuinely different
+heights needs and costs a read of each row as it renders. A list of
+one-line rows should leave this alone. */
+  "prop:measured"?: (HelixHeadlessVirtualList["measured"]) | undefined;
 
   /** Set the innerHTML of the element */
   innerHTML?: (string) | undefined;
@@ -29423,8 +29445,18 @@ export type CustomElements = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `estimate`: How tall one row is, in pixels, used to map scroll offset to an index.
+   *
+   * An estimate rather than a measurement while `measured` is off, which is
+   * right whenever the rows really are one height and is the cheaper of the two.
    * - `for`: Id of the element holding the rows, as JSON in a script.
    * - `label`: What the list is called, since the rendered rows are only a window on it.
+   * - `measured`: Places rows by what they came to rather than by `estimate`.
+   *
+   * **Off by default, because the straight line is better when it holds.** One
+   * estimate makes offset and index convert by division, which can never
+   * disagree with itself; measuring is what a set of genuinely different
+   * heights needs and costs a read of each row as it renders. A list of
+   * one-line rows should leave this alone.
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by
@@ -43837,8 +43869,18 @@ export type CustomElementsSolidJs = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `estimate`: How tall one row is, in pixels, used to map scroll offset to an index.
+   *
+   * An estimate rather than a measurement while `measured` is off, which is
+   * right whenever the rows really are one height and is the cheaper of the two.
    * - `for`: Id of the element holding the rows, as JSON in a script.
    * - `label`: What the list is called, since the rendered rows are only a window on it.
+   * - `measured`: Places rows by what they came to rather than by `estimate`.
+   *
+   * **Off by default, because the straight line is better when it holds.** One
+   * estimate makes offset and index convert by division, which can never
+   * disagree with itself; measuring is what a set of genuinely different
+   * heights needs and costs a read of each row as it renders. A list of
+   * one-line rows should leave this alone.
    * - `whenSettled`: Resolves a frame after the first update, when transitions are switched on.
    *
    * **Named `whenSettled` because `settled` is taken four times over**, by

package/types/vue.d.ts

@@ -7846,12 +7846,23 @@ export type HelixHeadlessVideoVueEvents = {
 };
 
 export type HelixHeadlessVirtualListVueProps = {
-  /** How tall one row is, in pixels, used to map scroll offset to an index. */
+  /** How tall one row is, in pixels, used to map scroll offset to an index.
+
+An estimate rather than a measurement while `measured` is off, which is
+right whenever the rows really are one height and is the cheaper of the two. */
   estimate?: (HelixHeadlessVirtualList["estimate"]) | undefined;
   /** Id of the element holding the rows, as JSON in a script. */
   for?: (HelixHeadlessVirtualList["for"]) | undefined;
   /** What the list is called, since the rendered rows are only a window on it. */
   label?: (HelixHeadlessVirtualList["label"]) | undefined;
+  /** Places rows by what they came to rather than by `estimate`.
+
+**Off by default, because the straight line is better when it holds.** One
+estimate makes offset and index convert by division, which can never
+disagree with itself; measuring is what a set of genuinely different
+heights needs and costs a read of each row as it renders. A list of
+one-line rows should leave this alone. */
+  measured?: (HelixHeadlessVirtualList["measured"]) | undefined;
 };
 
 export type HelixHeadlessVirtualListVueEvents = {};