@fusion.dev/helix-core 0.24.0 → 0.25.0

package/custom-elements.json

@@ -1473,15 +1473,36 @@
                 "text": "MutationObserver | undefined"
               }
             },
+            {
+              "kind": "field",
+              "name": "#deferred",
+              "privacy": "private",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether a hydrating render was told there was nothing, and needs the render after."
+            },
             {
               "kind": "field",
               "name": "element",
               "type": {
                 "text": "Element | null"
               },
-              "description": "The element `for` names, or null where there is nothing to name it in.\n\nNull on the server as well, since resolving an id wants a document. Every\nchart inherits that: the table is served whole and the drawing arrives on\nhydration.",
+              "description": "The element `for` names, or null where there is nothing to name it in.\n\nNull on the server as well, since resolving an id wants a document. Every\nchart inherits that: the table is served whole and the drawing arrives on\nhydration.\n\n**And null while hydrating what a server sent**, which drew nothing, because\nthe render that hydrates has to be the server's: a drawing that differs is\na template Lit throws on. The update after it, which this asks for, draws.",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "#resolve",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Element | null"
+                }
+              },
+              "description": "The element `for` names, whatever the host is rendering.\n\nApart from `element` because the watcher needs the table while a render\ncannot have it: attached on connect, which on a server's page is before\nthe render that hydrates, it resolved nothing there and never watched, so a\ntable a page filled afterwards drew no line."
+            },
             {
               "kind": "field",
               "name": "series",
@@ -1500,6 +1521,15 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "hostUpdated",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "hostDisconnected",
@@ -3412,6 +3442,16 @@
               "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": "field",
+              "name": "serverRendered",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this element hydrated a server's markup rather than rendering its own.\n\nFor what happened before hydration and cannot be heard after it: an image\nthe parser fetched fires `load` or `error` before any listener exists, so a\ncomponent asks the image instead, once, when this is true.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "finishHydration",
@@ -3546,6 +3586,30 @@
             "tier": "core"
           },
           "customElement": true
+        },
+        {
+          "kind": "function",
+          "name": "whenHydrated",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "Element"
+              }
+            },
+            {
+              "name": "write",
+              "type": {
+                "text": "() => void"
+              }
+            }
+          ],
+          "description": "Writes to a child element once it has hydrated, or now where it is not\nhydrating.\n\n**For a parent that sets state on the elements it holds.** On a page a server\nrendered, the parent's `updated` can run before a child's own first update,\nand a property written then is in the child's hydrating render, which has to\nbe the server's: a mark the markup never showed, and Lit throws. Waiting for\nthat render lets it match and the write land in the one after. Anywhere else\nthe write is immediate, so a client's first render already has it."
         }
       ],
       "exports": [
@@ -3556,6 +3620,14 @@
             "name": "HelixElement",
             "module": "src/helix-element/helix-element.ts"
           }
+        },
+        {
+          "kind": "js",
+          "name": "whenHydrated",
+          "declaration": {
+            "name": "whenHydrated",
+            "module": "src/helix-element/helix-element.ts"
+          }
         }
       ]
     },
@@ -3798,6 +3870,20 @@
                 "module": "src/helix-element/helix-element.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "serverRendered",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "protected",
+              "description": "Whether this element hydrated a server's markup rather than rendering its own.\n\nFor what happened before hydration and cannot be heard after it: an image\nthe parser fetched fires `load` or `error` before any listener exists, so a\ncomponent asks the image instead, once, when this is true.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixElement",
+                "module": "src/helix-element/helix-element.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "finishHydration",
@@ -4745,6 +4831,14 @@
             "module": "./helix-element/helix-element.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "whenHydrated",
+          "declaration": {
+            "name": "whenHydrated",
+            "module": "./helix-element/helix-element.js"
+          }
+        },
         {
           "kind": "js",
           "name": "HelixFormElement",

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

@@ -36,11 +36,16 @@ export declare class SourceController implements ReactiveController {
      * Null on the server as well, since resolving an id wants a document. Every
      * chart inherits that: the table is served whole and the drawing arrives on
      * hydration.
+     *
+     * **And null while hydrating what a server sent**, which drew nothing, because
+     * the render that hydrates has to be the server's: a drawing that differs is
+     * a template Lit throws on. The update after it, which this asks for, draws.
      */
     get element(): Element | null;
     /** The series it holds, or none. */
     get series(): Series[];
     hostConnected(): void;
+    hostUpdated(): void;
     hostDisconnected(): void;
     /**
      * Points the watcher at whatever `for` names now.

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

@@ -2,11 +2,19 @@ import { readSeries } from '../../utils/read-series/read-series.js';
 export class SourceController {
     #host;
     #observer;
+    #deferred = false;
     constructor(host) {
         this.#host = host;
         host.addController(this);
     }
     get element() {
+        if (this.#host.hydrating === true) {
+            this.#deferred = this.#host.for !== '';
+            return null;
+        }
+        return this.#resolve();
+    }
+    #resolve() {
         const host = this.#host;
         if (host.for === '') {
             return null;
@@ -31,13 +39,19 @@ export class SourceController {
     hostConnected() {
         this.watch();
     }
+    hostUpdated() {
+        if (this.#deferred) {
+            this.#deferred = false;
+            this.#host.requestUpdate();
+        }
+    }
     hostDisconnected() {
         this.#observer?.disconnect();
         this.#observer = undefined;
     }
     watch() {
         this.#observer?.disconnect();
-        const element = this.element;
+        const element = this.#resolve();
         if (!element || typeof MutationObserver === 'undefined') {
             return;
         }

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

@@ -134,6 +134,14 @@ export declare class HelixElement extends LitElement {
      * first render reads them and there is one render.
      */
     protected get hydrating(): boolean;
+    /**
+     * Whether this element hydrated a server's markup rather than rendering its own.
+     *
+     * For what happened before hydration and cannot be heard after it: an image
+     * the parser fetched fires `load` or `error` before any listener exists, so a
+     * component asks the image instead, once, when this is true.
+     */
+    protected get serverRendered(): boolean;
     /**
      * Asks for the update a hydration put off, so the reads it skipped happen.
      *
@@ -249,3 +257,15 @@ export declare class HelixElement extends LitElement {
      */
     protected firstUpdated(changed: PropertyValues): void;
 }
+/**
+ * Writes to a child element once it has hydrated, or now where it is not
+ * hydrating.
+ *
+ * **For a parent that sets state on the elements it holds.** On a page a server
+ * rendered, the parent's `updated` can run before a child's own first update,
+ * and a property written then is in the child's hydrating render, which has to
+ * be the server's: a mark the markup never showed, and Lit throws. Waiting for
+ * that render lets it match and the write land in the one after. Anywhere else
+ * the write is immediate, so a client's first render already has it.
+ */
+export declare const whenHydrated: (element: Element, write: () => void) => void;

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

@@ -148,6 +148,9 @@ export class HelixElement extends LitElement {
     get hydrating() {
         return this.fromServer && !this.hasUpdated;
     }
+    get serverRendered() {
+        return this.fromServer;
+    }
     finishHydration() {
         if (this.fromServer) {
             this.requestUpdate();
@@ -205,3 +208,12 @@ export class HelixElement extends LitElement {
         });
     }
 }
+export const whenHydrated = (element, write) => {
+    const child = element;
+    if (child.hydrating === true && child.updateComplete) {
+        void child.updateComplete.then(write);
+    }
+    else {
+        write();
+    }
+};

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { type TokenColor, TokenColorController, } from './controllers/token-colo
 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 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 { HelixElement, whenHydrated } 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';
 export { type CollectionElement, MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';

package/dist/index.js

@@ -15,7 +15,7 @@ export { TokenColorController, } from './controllers/token-color-controller/toke
 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, 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 { HelixElement, whenHydrated } 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';
 export { MixinCollection, } from './mixins/mixin-collection/mixin-collection.js';

package/package.json

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