@fusion.dev/helix-core 0.22.0 → 0.24.0

package/custom-elements.json

@@ -1810,6 +1810,24 @@
               ],
               "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": "shift",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "by",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Moves every height along by `by` places, for a set that grew at its start.\n\nA transcript loading its history prepends, and every item already measured\nis now `by` further down the set. Moved rather than forgotten, because the\nmeasurements are still true of the same items: forgetting would put every\none of them back at the estimate at the moment the reader is looking at them."
+            },
             {
               "kind": "method",
               "name": "forget",
@@ -1949,6 +1967,16 @@
               "description": "Where each item starts, once any of them has been seen.",
               "default": "new Heights(() => this.options.estimate())"
             },
+            {
+              "kind": "field",
+              "name": "owed",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0",
+              "description": "Room `shift` added above the window, owed to the scroll offset once drawn."
+            },
             {
               "kind": "method",
               "name": "hostConnected",
@@ -2083,6 +2111,24 @@
               },
               "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": "shift",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "by",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Tells the controller the set grew by `by` items at its start.\n\nFor a host that prepends, which is what a transcript loading its history\ndoes. Every index the controller knew now names the item `by` places later,\nso the heights and the window move with them, and the scroll offset is moved\nby the room the new items take once they have been drawn. The reader stays\non the turn they were reading rather than on whatever now sits at their old\noffset, which is what loading history upward has to look like.\n\nCall it from `willUpdate`, before the render that draws the grown set."
+            },
             {
               "kind": "method",
               "name": "forget",
@@ -2821,6 +2867,28 @@
           },
           "helix": {}
         },
+        {
+          "kind": "class",
+          "description": "Fired when the reader changes which values a field is filtered by.\n\n**Not `helix-filter`, which is a different thing already taken.** That one\nsays a list narrowed itself to a string, and `Data Table` and `Listbox` both\ndispatch it with exactly that meaning. This one carries a structured filter:\na field, a comparison and a set of values, which is a shape neither of those\nhas and neither should grow.\n\nCancelable, and refusing it is how a consumer takes the decision for one\ninteraction, the way `requestChange` documents for every stateful change here.",
+          "name": "HelixFacetEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-facet'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
         {
           "kind": "class",
           "description": "Fired when a component narrows what it is showing.\n\nFiltering hides rather than removes, so nothing about the value changes and\n`helix-change` would be a lie. What a consumer wants to know is that the list\nin front of the reader is no longer the whole list.",
@@ -2887,6 +2955,50 @@
           },
           "helix": {}
         },
+        {
+          "kind": "class",
+          "description": "Fired when the reader asks for the columns in a different order.\n\nCancelable, and refusing it leaves the columns where they were, so a consumer\nwho stores the order, in a URL or a preference, can take the decision the way\na server-side sort takes `helix-sort`. The detail is the whole order as\nspace-separated fields rather than one move, because the order is the fact a\nconsumer stores, and a move is only meaningful against an order they would\nthen have to keep in step.\n\nNot `helix-sort`: that reorders the rows, this reorders the columns, and a\nconsumer listening for one should not hear the other.",
+          "name": "HelixReorderEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-reorder'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
+        {
+          "kind": "class",
+          "description": "Fired when a reader reaches the oldest turn a transcript holds, while there are\nolder ones to fetch.\n\n**A report of where the reader is, not a request to be granted**, so it is not\ncancelable: there is nothing for the transcript to do if nobody refuses, and\nnothing to stop if somebody does. The consumer answers by fetching, and says\nso through the transcript's `history` while the older turns are on their way.\n\nNo detail. The consumer holds the transcript and knows its oldest turn, which\nis the one thing a fetch needs.",
+          "name": "HelixHistoryEvent",
+          "members": [
+            {
+              "kind": "field",
+              "name": "eventName",
+              "type": {
+                "text": "string"
+              },
+              "static": true,
+              "readonly": true,
+              "default": "'helix-history'"
+            }
+          ],
+          "superclass": {
+            "name": "CustomEvent",
+            "module": "src/events/events.ts"
+          },
+          "helix": {}
+        },
         {
           "kind": "variable",
           "name": "helixEventNames",
@@ -3130,6 +3242,14 @@
             "module": "src/events/events.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixFacetEvent",
+          "declaration": {
+            "name": "HelixFacetEvent",
+            "module": "src/events/events.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixFilterEvent",
@@ -3154,6 +3274,22 @@
             "module": "src/events/events.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixReorderEvent",
+          "declaration": {
+            "name": "HelixReorderEvent",
+            "module": "src/events/events.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "HelixHistoryEvent",
+          "declaration": {
+            "name": "HelixHistoryEvent",
+            "module": "src/events/events.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "helixEventNames",
@@ -3256,6 +3392,92 @@
               "privacy": "private",
               "description": "Resolves `whenSettled`, once, from the frame that records the state."
             },
+            {
+              "kind": "field",
+              "name": "fromServer",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the shadow root was a server's, parsed from declarative shadow DOM."
+            },
+            {
+              "kind": "field",
+              "name": "hydrating",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this update is hydrating a server's markup, and so has to render\nexactly what the server rendered.\n\n**Lit hydrates by assuming the markup already shows the first render.** A\nvalue that differs is recorded and never written, so the page keeps the\nserver's, and a template that differs throws. The server has no children,\nso anything a component reads from its children waits for the update after\nhydration, which `finishHydration` asks for. Without a server's markup the\nfirst render reads them and there is one render.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "finishHydration",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Asks for the update a hydration put off, so the reads it skipped happen.\n\nCalled from `firstUpdated`, the end of the hydrating update. The render it\nschedules can only follow that one, which is the exception Lit's\nchange-in-update warning names, and it happens only on a page a server\nrendered."
+            },
+            {
+              "kind": "field",
+              "name": "childrenKnown",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this render can know the children.\n\nA server cannot: its element shim carries attributes and no tree, so\n`children` is undefined there. A render hydrating what a server sent must\nnot, because it has to be the server's render. Anywhere else it can. A\ncomponent whose render depends on its children reads them through\n`knownChildren`, and treats \"not known\" as its own answer rather than as\n\"none\": a list that renders its empty state because nobody has looked yet is\nthe one thing an empty state must never do.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "knownChildren",
+              "type": {
+                "text": "Element[]"
+              },
+              "privacy": "protected",
+              "description": "The children a render may read: all of them where they are known, and none otherwise.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "assignsByName",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this element's slots route by name although it asked to assign them\nby hand.\n\n**A declarative shadow root is always the by-name kind.** HTML has no way to\nask for manual assignment, so a component that assigns by hand and hydrates\na server's root gets one where `slot.assign()` does nothing, and its\nchildren land wherever their `slot` attribute sends them. The way through is\nto write that attribute, which is what `route` does. Only there: on a root\nthis element made, assignment stays manual and the consumer's markup is\nnever touched, which is what a React consumer's hydration requires.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "route",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "child",
+                  "type": {
+                    "text": "Element"
+                  }
+                },
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string | undefined"
+                  }
+                }
+              ],
+              "description": "Sends a child to a slot by name, on a root that routes by name.\n\n`undefined` is the default slot. Written only when it differs, so routing\nthe same child again on every update writes nothing."
+            },
             {
               "kind": "field",
               "name": "stopInner",
@@ -3548,6 +3770,120 @@
                 "module": "src/helix-element/helix-element.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "fromServer",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the shadow root was a server's, parsed from declarative shadow DOM.",
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "hydrating",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this update is hydrating a server's markup, and so has to render\nexactly what the server rendered.\n\n**Lit hydrates by assuming the markup already shows the first render.** A\nvalue that differs is recorded and never written, so the page keeps the\nserver's, and a template that differs throws. The server has no children,\nso anything a component reads from its children waits for the update after\nhydration, which `finishHydration` asks for. Without a server's markup the\nfirst render reads them and there is one render.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "finishHydration",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Asks for the update a hydration put off, so the reads it skipped happen.\n\nCalled from `firstUpdated`, the end of the hydrating update. The render it\nschedules can only follow that one, which is the exception Lit's\nchange-in-update warning names, and it happens only on a page a server\nrendered.",
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "childrenKnown",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this render can know the children.\n\nA server cannot: its element shim carries attributes and no tree, so\n`children` is undefined there. A render hydrating what a server sent must\nnot, because it has to be the server's render. Anywhere else it can. A\ncomponent whose render depends on its children reads them through\n`knownChildren`, and treats \"not known\" as its own answer rather than as\n\"none\": a list that renders its empty state because nobody has looked yet is\nthe one thing an empty state must never do.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "knownChildren",
+              "type": {
+                "text": "Element[]"
+              },
+              "privacy": "protected",
+              "description": "The children a render may read: all of them where they are known, and none otherwise.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "assignsByName",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this element's slots route by name although it asked to assign them\nby hand.\n\n**A declarative shadow root is always the by-name kind.** HTML has no way to\nask for manual assignment, so a component that assigns by hand and hydrates\na server's root gets one where `slot.assign()` does nothing, and its\nchildren land wherever their `slot` attribute sends them. The way through is\nto write that attribute, which is what `route` does. Only there: on a root\nthis element made, assignment stays manual and the consumer's markup is\nnever touched, which is what a React consumer's hydration requires.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "route",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "child",
+                  "type": {
+                    "text": "Element"
+                  }
+                },
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string | undefined"
+                  }
+                }
+              ],
+              "description": "Sends a child to a slot by name, on a root that routes by name.\n\n`undefined` is the default slot. Written only when it differs, so routing\nthe same child again on every update writes nothing.",
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "stopInner",
@@ -4017,6 +4353,14 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "FacetDetail",
+          "declaration": {
+            "name": "FacetDetail",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "FilterDetail",
@@ -4169,6 +4513,14 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixFacetEvent",
+          "declaration": {
+            "name": "HelixFacetEvent",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixFilterEvent",
@@ -4177,6 +4529,14 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixHistoryEvent",
+          "declaration": {
+            "name": "HelixHistoryEvent",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixNavigateEvent",
@@ -4209,6 +4569,14 @@
             "module": "./events/events.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "HelixReorderEvent",
+          "declaration": {
+            "name": "HelixReorderEvent",
+            "module": "./events/events.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixResizeEvent",
@@ -5448,6 +5816,16 @@
               ],
               "description": "Binds to a rows slot's `slotchange`, and answers `hasRows` from it."
             },
+            {
+              "kind": "field",
+              "name": "slotted",
+              "type": {
+                "text": "Element[]"
+              },
+              "privacy": "protected",
+              "description": "What the rows slot is given, read from the host so a first render has it.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "hasRows",
@@ -5515,7 +5893,7 @@
               },
               "privacy": "private",
               "default": "0",
-              "description": "How many there were, the last time anyone looked.\n\n**Never name this `rows`.** TypeScript's `private` is a compile-time\nclaim and the runtime field is whatever it is named, so a subclass\ndeclaring `@property() rows` for the data a consumer hands it would share\none field with this counter: the slot count would overwrite the\nconsumer's array on every `updated`, and `hasRows` would read the array's\nlength as a slot count. Nothing would throw. `helix-data-table` takes\nexactly that property."
+              "description": "How many there were, the last time anyone looked.\n\n**Never name this `rows`.** TypeScript's `private` is a compile-time\nclaim and the runtime field is whatever it is named, so a subclass\ndeclaring `@property() rows` for the data a consumer hands it would share\none field with this counter: the slot count would overwrite the\nconsumer's array on every update, and `hasRows` would read the array's\nlength as a slot count. Nothing would throw. `helix-data-table` takes\nexactly that property."
             },
             {
               "kind": "method",
@@ -5545,6 +5923,16 @@
               "privacy": "protected",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "slotted",
+              "type": {
+                "text": "Element[]"
+              },
+              "privacy": "protected",
+              "description": "What the rows slot is given: every child without a `slot`.\n\nThe default slot, because that is where every collection in this library\nputs its rows: Listbox its options, Tree its items, Table its rows, Menu\nand Drilldown their pages. A named slot is a header or a footer, and\nneither is content.\n\n**The host's children rather than the slot's assigned elements**, which\nare the same elements, because a slot exists only once a render has made\nit and the count is wanted by the first render. A collection that assigns\nits slots by hand says what it assigns.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "renderStatus",

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

@@ -52,6 +52,15 @@ export declare class Heights {
      * thousand.
      */
     indexAt(offset: number, count: number): number;
+    /**
+     * Moves every height along by `by` places, for a set that grew at its start.
+     *
+     * A transcript loading its history prepends, and every item already measured
+     * is now `by` further down the set. Moved rather than forgotten, because the
+     * measurements are still true of the same items: forgetting would put every
+     * one of them back at the estimate at the moment the reader is looking at them.
+     */
+    shift(by: number): void;
     /**
      * Drops everything, for a set that is no longer the same set.
      *

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

@@ -51,6 +51,19 @@ export class Heights {
         }
         return Math.min(low, count - 1);
     }
+    shift(by) {
+        if (by === 0) {
+            return;
+        }
+        const moved = [...this.seen].map(([index, size]) => [index + by, size]);
+        this.seen.clear();
+        for (const [index, size] of moved) {
+            if (index >= 0) {
+                this.seen.set(index, size);
+            }
+        }
+        this.dirty = 0;
+    }
     forget() {
         this.seen.clear();
         this.dirty = 0;

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

@@ -138,6 +138,8 @@ export declare class VirtualizeController implements ReactiveController {
     window: Window;
     /** Where each item starts, once any of them has been seen. */
     private readonly heights;
+    /** Room `shift` added above the window, owed to the scroll offset once drawn. */
+    private owed;
     constructor(host: ReactiveControllerHost, options: VirtualizeOptions);
     hostConnected(): void;
     hostDisconnected(): void;
@@ -183,6 +185,19 @@ export declare class VirtualizeController implements ReactiveController {
      * Skipped at the very top, where there is nothing above to have moved.
      */
     hostUpdated(): void;
+    /**
+     * Tells the controller the set grew by `by` items at its start.
+     *
+     * For a host that prepends, which is what a transcript loading its history
+     * does. Every index the controller knew now names the item `by` places later,
+     * so the heights and the window move with them, and the scroll offset is moved
+     * by the room the new items take once they have been drawn. The reader stays
+     * on the turn they were reading rather than on whatever now sits at their old
+     * offset, which is what loading history upward has to look like.
+     *
+     * Call it from `willUpdate`, before the render that draws the grown set.
+     */
+    shift(by: number): void;
     /**
      * Drops every measurement, for a host that swapped its data.
      *

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

@@ -6,6 +6,7 @@ export class VirtualizeController {
         this.settling = 0;
         this.warned = false;
         this.window = { after: 0, before: 0, first: 0, last: 0 };
+        this.owed = 0;
         this.handleScroll = () => {
             this.settling = 0;
             this.measure();
@@ -95,6 +96,13 @@ export class VirtualizeController {
         };
     }
     hostUpdated() {
+        if (this.owed !== 0) {
+            const box = this.options.container();
+            if (box) {
+                box.scrollTop += this.owed;
+            }
+            this.owed = 0;
+        }
         if (!this.measuring()) {
             return;
         }
@@ -121,6 +129,21 @@ export class VirtualizeController {
         }
         this.measure();
     }
+    shift(by) {
+        if (by <= 0) {
+            return;
+        }
+        const count = Math.max(0, this.options.count());
+        this.heights.shift(by);
+        const room = this.heights.before(by, count);
+        this.window = {
+            ...this.window,
+            before: this.window.before + room,
+            first: this.window.first + by,
+            last: this.window.last + by,
+        };
+        this.owed += room;
+    }
     forget() {
         this.heights.forget();
     }

package/dist/events/events.d.ts

@@ -80,6 +80,43 @@ export interface FilterDetail {
     /** What the list is being narrowed to. */
     value: string;
 }
+/**
+ * Detail carried by `helix-facet`.
+ *
+ * **Everything needed to draw the chip, so nothing has to be looked up again.**
+ * A consumer hearing this renders a `FilterChip` from it and stops: the labels
+ * are the reader's words and the names are their own model's, and both are here
+ * because only the thing that read the declarations knows both.
+ */
+export interface FacetDetail {
+    /**
+     * How many values the comparison in force takes.
+     *
+     * **What tells an empty filter from no filter.** `values` empty usually means
+     * the field is not being filtered any more, and a consumer drops the chip; a
+     * comparison of arity `none`, `is empty` or `is set`, is a filter that has no
+     * values to carry and never will. Without this the two arrive identical, and
+     * the thing that read the declaration is the only thing that could say which.
+     */
+    arity: 'many' | 'none' | 'one';
+    /** What the consumer's model calls the field. */
+    field: string;
+    /** What a reader is shown for the field. */
+    label: string;
+    /** What the consumer's model calls the comparison in force. */
+    operator: string;
+    /**
+     * The comparison as a reader sees it, and **empty for the field's usual one**.
+     *
+     * Passed straight to a chip's `operator-label`, which draws the segment only
+     * where there is one. Deciding it here is the point: the thing that read the
+     * field knows which of its operators is the default, and the chip never has
+     * to.
+     */
+    operatorLabel: string;
+    /** What the field is compared to, as the consumer's own values. */
+    values: readonly string[];
+}
 /** Detail carried by `helix-read`. */
 export interface ReadDetail {
     /**
@@ -589,6 +626,22 @@ export declare class HelixSortEvent extends CustomEvent<SortDetail> {
     static readonly eventName = "helix-sort";
     constructor(detail: SortDetail);
 }
+/**
+ * Fired when the reader changes which values a field is filtered by.
+ *
+ * **Not `helix-filter`, which is a different thing already taken.** That one
+ * says a list narrowed itself to a string, and `Data Table` and `Listbox` both
+ * dispatch it with exactly that meaning. This one carries a structured filter:
+ * a field, a comparison and a set of values, which is a shape neither of those
+ * has and neither should grow.
+ *
+ * Cancelable, and refusing it is how a consumer takes the decision for one
+ * interaction, the way `requestChange` documents for every stateful change here.
+ */
+export declare class HelixFacetEvent extends CustomEvent<FacetDetail> {
+    static readonly eventName = "helix-facet";
+    constructor(detail: FacetDetail);
+}
 /**
  * Fired when a component narrows what it is showing.
  *
@@ -633,6 +686,39 @@ export declare class HelixSelectEvent extends CustomEvent<SelectDetail> {
     static readonly eventName = "helix-select";
     constructor(detail: SelectDetail);
 }
+/**
+ * Fired when the reader asks for the columns in a different order.
+ *
+ * Cancelable, and refusing it leaves the columns where they were, so a consumer
+ * who stores the order, in a URL or a preference, can take the decision the way
+ * a server-side sort takes `helix-sort`. The detail is the whole order as
+ * space-separated fields rather than one move, because the order is the fact a
+ * consumer stores, and a move is only meaningful against an order they would
+ * then have to keep in step.
+ *
+ * Not `helix-sort`: that reorders the rows, this reorders the columns, and a
+ * consumer listening for one should not hear the other.
+ */
+export declare class HelixReorderEvent extends CustomEvent<ChangeDetail> {
+    static readonly eventName = "helix-reorder";
+    constructor(detail: ChangeDetail);
+}
+/**
+ * Fired when a reader reaches the oldest turn a transcript holds, while there are
+ * older ones to fetch.
+ *
+ * **A report of where the reader is, not a request to be granted**, so it is not
+ * cancelable: there is nothing for the transcript to do if nobody refuses, and
+ * nothing to stop if somebody does. The consumer answers by fetching, and says
+ * so through the transcript's `history` while the older turns are on their way.
+ *
+ * No detail. The consumer holds the transcript and knows its oldest turn, which
+ * is the one thing a fetch needs.
+ */
+export declare class HelixHistoryEvent extends CustomEvent<Record<string, never>> {
+    static readonly eventName = "helix-history";
+    constructor();
+}
 /**
  * Every event this file publishes, and the one place a new one is added.
  *
@@ -663,11 +749,14 @@ declare const registry: {
     readonly HelixCopyEvent: typeof HelixCopyEvent;
     readonly HelixCreateEvent: typeof HelixCreateEvent;
     readonly HelixDismissEvent: typeof HelixDismissEvent;
+    readonly HelixFacetEvent: typeof HelixFacetEvent;
     readonly HelixFilterEvent: typeof HelixFilterEvent;
+    readonly HelixHistoryEvent: typeof HelixHistoryEvent;
     readonly HelixNavigateEvent: typeof HelixNavigateEvent;
     readonly HelixNextEvent: typeof HelixNextEvent;
     readonly HelixPreviousEvent: typeof HelixPreviousEvent;
     readonly HelixReadEvent: typeof HelixReadEvent;
+    readonly HelixReorderEvent: typeof HelixReorderEvent;
     readonly HelixResizeEvent: typeof HelixResizeEvent;
     readonly HelixSampleEndEvent: typeof HelixSampleEndEvent;
     readonly HelixSampleStartEvent: typeof HelixSampleStartEvent;

package/dist/events/events.js

@@ -306,6 +306,17 @@ export class HelixSortEvent extends CustomEvent {
         });
     }
 }
+export class HelixFacetEvent extends CustomEvent {
+    static { this.eventName = 'helix-facet'; }
+    constructor(detail) {
+        super(HelixFacetEvent.eventName, {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            detail,
+        });
+    }
+}
 export class HelixFilterEvent extends CustomEvent {
     static { this.eventName = 'helix-filter'; }
     constructor(detail) {
@@ -339,6 +350,28 @@ export class HelixSelectEvent extends CustomEvent {
         });
     }
 }
+export class HelixReorderEvent extends CustomEvent {
+    static { this.eventName = 'helix-reorder'; }
+    constructor(detail) {
+        super(HelixReorderEvent.eventName, {
+            bubbles: true,
+            cancelable: true,
+            composed: true,
+            detail,
+        });
+    }
+}
+export class HelixHistoryEvent extends CustomEvent {
+    static { this.eventName = 'helix-history'; }
+    constructor() {
+        super(HelixHistoryEvent.eventName, {
+            bubbles: true,
+            cancelable: false,
+            composed: true,
+            detail: {},
+        });
+    }
+}
 const registry = {
     HelixActivateEvent,
     HelixBeforeActivateEvent,
@@ -358,11 +391,14 @@ const registry = {
     HelixCopyEvent,
     HelixCreateEvent,
     HelixDismissEvent,
+    HelixFacetEvent,
     HelixFilterEvent,
+    HelixHistoryEvent,
     HelixNavigateEvent,
     HelixNextEvent,
     HelixPreviousEvent,
     HelixReadEvent,
+    HelixReorderEvent,
     HelixResizeEvent,
     HelixSampleEndEvent,
     HelixSampleStartEvent,

package/dist/helix-element/helix-element.d.ts

@@ -119,6 +119,64 @@ export declare class HelixElement extends LitElement {
     /** Resolves `whenSettled`, once, from the frame that records the state. */
     private resolveSettled;
     constructor();
+    /** Whether the shadow root was a server's, parsed from declarative shadow DOM. */
+    private fromServer;
+    protected createRenderRoot(): HTMLElement | DocumentFragment;
+    /**
+     * Whether this update is hydrating a server's markup, and so has to render
+     * exactly what the server rendered.
+     *
+     * **Lit hydrates by assuming the markup already shows the first render.** A
+     * value that differs is recorded and never written, so the page keeps the
+     * server's, and a template that differs throws. The server has no children,
+     * so anything a component reads from its children waits for the update after
+     * hydration, which `finishHydration` asks for. Without a server's markup the
+     * first render reads them and there is one render.
+     */
+    protected get hydrating(): boolean;
+    /**
+     * Asks for the update a hydration put off, so the reads it skipped happen.
+     *
+     * Called from `firstUpdated`, the end of the hydrating update. The render it
+     * schedules can only follow that one, which is the exception Lit's
+     * change-in-update warning names, and it happens only on a page a server
+     * rendered.
+     */
+    protected finishHydration(): void;
+    /**
+     * Whether this render can know the children.
+     *
+     * A server cannot: its element shim carries attributes and no tree, so
+     * `children` is undefined there. A render hydrating what a server sent must
+     * not, because it has to be the server's render. Anywhere else it can. A
+     * component whose render depends on its children reads them through
+     * `knownChildren`, and treats "not known" as its own answer rather than as
+     * "none": a list that renders its empty state because nobody has looked yet is
+     * the one thing an empty state must never do.
+     */
+    protected get childrenKnown(): boolean;
+    /** The children a render may read: all of them where they are known, and none otherwise. */
+    protected get knownChildren(): Element[];
+    /**
+     * Whether this element's slots route by name although it asked to assign them
+     * by hand.
+     *
+     * **A declarative shadow root is always the by-name kind.** HTML has no way to
+     * ask for manual assignment, so a component that assigns by hand and hydrates
+     * a server's root gets one where `slot.assign()` does nothing, and its
+     * children land wherever their `slot` attribute sends them. The way through is
+     * to write that attribute, which is what `route` does. Only there: on a root
+     * this element made, assignment stays manual and the consumer's markup is
+     * never touched, which is what a React consumer's hydration requires.
+     */
+    protected get assignsByName(): boolean;
+    /**
+     * Sends a child to a slot by name, on a root that routes by name.
+     *
+     * `undefined` is the default slot. Written only when it differs, so routing
+     * the same child again on every update writes nothing.
+     */
+    protected route(child: Element, name: string | undefined): void;
     /**
      * Announces an event, having first bound whatever React is holding for it.
      *

package/dist/helix-element/helix-element.js

@@ -130,6 +130,7 @@ export class HelixElement extends LitElement {
     constructor() {
         super();
         this.resolveSettled = () => { };
+        this.fromServer = false;
         this.stopInner = (event) => {
             if (event.target !== this) {
                 event.stopPropagation();
@@ -140,6 +141,39 @@ export class HelixElement extends LitElement {
             this.resolveSettled = resolve;
         });
     }
+    createRenderRoot() {
+        this.fromServer = this.shadowRoot !== null;
+        return super.createRenderRoot();
+    }
+    get hydrating() {
+        return this.fromServer && !this.hasUpdated;
+    }
+    finishHydration() {
+        if (this.fromServer) {
+            this.requestUpdate();
+        }
+    }
+    get childrenKnown() {
+        return this.children !== undefined && !this.hydrating;
+    }
+    get knownChildren() {
+        return this.childrenKnown ? [...this.children] : [];
+    }
+    get assignsByName() {
+        const asked = this.constructor.shadowRootOptions.slotAssignment;
+        return (asked === 'manual' &&
+            typeof ShadowRoot !== 'undefined' &&
+            this.renderRoot instanceof ShadowRoot &&
+            this.renderRoot.slotAssignment !== 'manual');
+    }
+    route(child, name) {
+        if (name === undefined) {
+            child.removeAttribute('slot');
+        }
+        else if (child.getAttribute('slot') !== name) {
+            child.setAttribute('slot', name);
+        }
+    }
     dispatchEvent(event) {
         bindReactHandler(this, event);
         return super.dispatchEvent(event);

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { SourceController, type SourceHost, } from './controllers/source-control
 export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-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 { type CaretDetail, type ChangeDetail, type CompleteDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, 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';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
 export { MixinChartSource, type MixinChartSourceInterface, PALETTE, seriesIndex, } from './mixins/mixin-chart-source/mixin-chart-source.js';

package/dist/index.js

@@ -14,7 +14,7 @@ export { SourceController, } from './controllers/source-controller/source-contro
 export { TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { VirtualizeController, } from './controllers/virtualize-controller/virtualize-controller.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
-export { 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, } from './events/events.js';
+export { HelixActivateEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCaretEvent, HelixCompleteEvent, HelixConsoleEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixFacetEvent, HelixFilterEvent, HelixHistoryEvent, HelixNavigateEvent, HelixNextEvent, HelixPreviousEvent, HelixReadEvent, HelixReorderEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixTourAskEvent, } from './events/events.js';
 export { HelixElement } from './helix-element/helix-element.js';
 export { HelixFormElement } from './helix-form-element/helix-form-element.js';
 export { MixinChartSource, PALETTE, seriesIndex, } from './mixins/mixin-chart-source/mixin-chart-source.js';

package/dist/mixins/mixin-collection/mixin-collection.d.ts

@@ -1,4 +1,5 @@
-import { type LitElement, nothing, type TemplateResult } from 'lit';
+import { nothing, type TemplateResult } from 'lit';
+import type { HelixElement } from '../../helix-element/helix-element.js';
 type Constructor<T> = new (...args: any[]) => T;
 /**
  * The API a collection has for the two states that are not its content.
@@ -18,6 +19,8 @@ export declare class CollectionElement {
     protected renderStatus(hasContent: boolean): TemplateResult | typeof nothing;
     /** Binds to a rows slot's `slotchange`, and answers `hasRows` from it. */
     protected countRows(event: Event): void;
+    /** What the rows slot is given, read from the host so a first render has it. */
+    protected get slotted(): Element[];
     /**
      * Whether there is anything to show, as far as anything can tell.
      *
@@ -48,5 +51,5 @@ export declare class CollectionElement {
  * apply this, rather than here.** See `MixinField` for why a class-level tag on
  * a mixin reaches no manifest.
  */
-export declare const MixinCollection: <T extends Constructor<LitElement>>(Base: T) => Constructor<CollectionElement> & T;
+export declare const MixinCollection: <T extends Constructor<HelixElement>>(Base: T) => Constructor<CollectionElement> & T;
 export {};

package/dist/mixins/mixin-collection/mixin-collection.js

@@ -23,18 +23,24 @@ export const MixinCollection = (Base) => {
         get hasRows() {
             return this.slotCounted ? this.slotRows > 0 : true;
         }
-        updated(changed) {
-            super.updated?.(changed);
-            const slot = this.renderRoot?.querySelector?.('slot:not([name])');
-            if (!slot) {
+        get slotted() {
+            return [...(this.children ?? [])].filter((child) => child.slot === '');
+        }
+        willUpdate(changed) {
+            super.willUpdate(changed);
+            if (this.children === undefined || this.hydrating) {
                 return;
             }
-            const rows = slot.assignedElements().length;
+            const rows = this.slotted.length;
             this.slotCounted = true;
             if (rows !== this.slotRows) {
                 this.slotRows = rows;
             }
         }
+        firstUpdated(changed) {
+            super.firstUpdated(changed);
+            this.finishHydration();
+        }
         renderStatus(hasContent) {
             if (this.loading) {
                 return html `<p part="loading" role="status">${this.loadingText}</p>`;

package/package.json

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