@fusion.dev/helix-core 0.162.0 → 0.163.0

package/custom-elements.json

@@ -5501,6 +5501,117 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/controllers/upgrade-controller/upgrade-controller.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Calls back when a child that had not upgraded is defined.\n\n**A host that knows its children by their class does not know a child that\nhas not upgraded.** `instanceof` is false for it and a marker its class sets,\nsuch as `isNotification`, is missing. An upgrade changes no child list and no\nslot assignment, so neither a `MutationObserver` nor `slotchange` reports it,\nand the host keeps the answer it read before. Measured on the notification\nfeed: a row added while its definition was still loading was drawn nowhere,\nand the feed showed its empty line over it. A listbox did not select an\noption its `default-value` named, and a tree gave a late item no level.\n\nThis happens wherever a child's definition loads after the host's: a page\nthat adds children before its scripts finish, or a bundle that defines the\nhost first.\n\nIt looks when the host connects and at each child added after, and waits on\n`customElements.whenDefined` once for each name. `define` upgrades the\nelements in the document before that promise resolves, so the children have\ntheir class by the time the callback runs. The callback is the host's own\nresync, such as its `slotchange` handler, and is `requestUpdate` unless given\nsomething else to do. Watches from connection to disconnection.",
+          "name": "UpgradeController",
+          "members": [
+            {
+              "kind": "field",
+              "name": "watcher",
+              "type": {
+                "text": "MutationObserver | undefined"
+              },
+              "privacy": "private",
+              "default": "undefined"
+            },
+            {
+              "kind": "field",
+              "name": "waiting",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Set<string>()",
+              "description": "The names already waited on, so each is waited on once."
+            },
+            {
+              "kind": "field",
+              "name": "subtree",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "hostConnected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "hostDisconnected",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "look",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "element",
+                  "type": {
+                    "text": "Element"
+                  }
+                },
+                {
+                  "name": "added",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Waits on `element`, where it was added, and on what it holds where the subtree counts."
+            },
+            {
+              "kind": "method",
+              "name": "wait",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "element",
+                  "type": {
+                    "text": "Element"
+                  }
+                }
+              ]
+            }
+          ],
+          "helix": {}
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "UpgradeController",
+          "declaration": {
+            "name": "UpgradeController",
+            "module": "src/controllers/upgrade-controller/upgrade-controller.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/controllers/virtualize-controller/heights.ts",
@@ -13061,6 +13172,22 @@
             "module": "./controllers/token-color-controller/token-color-controller.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "UpgradeController",
+          "declaration": {
+            "name": "UpgradeController",
+            "module": "./controllers/upgrade-controller/upgrade-controller.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "UpgradeOptions",
+          "declaration": {
+            "name": "UpgradeOptions",
+            "module": "./controllers/upgrade-controller/upgrade-controller.js"
+          }
+        },
         {
           "kind": "js",
           "name": "Rendered",
@@ -33016,7 +33143,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.162.0'",
+          "default": "'0.163.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."
         }
       ],
@@ -33576,6 +33703,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.162.0"
+    "version": "0.163.0"
   }
 }

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

@@ -0,0 +1,47 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** Where an `UpgradeController` looks for children that have not upgraded. */
+export interface UpgradeOptions {
+    /**
+     * Whether to look through every descendant. Off, it looks at the host's own
+     * children. Turn it on for a host that finds its items inside wrappers, as a
+     * radio group does.
+     */
+    subtree?: boolean;
+}
+/**
+ * Calls back when a child that had not upgraded is defined.
+ *
+ * **A host that knows its children by their class does not know a child that
+ * has not upgraded.** `instanceof` is false for it and a marker its class sets,
+ * such as `isNotification`, is missing. An upgrade changes no child list and no
+ * slot assignment, so neither a `MutationObserver` nor `slotchange` reports it,
+ * and the host keeps the answer it read before. Measured on the notification
+ * feed: a row added while its definition was still loading was drawn nowhere,
+ * and the feed showed its empty line over it. A listbox did not select an
+ * option its `default-value` named, and a tree gave a late item no level.
+ *
+ * This happens wherever a child's definition loads after the host's: a page
+ * that adds children before its scripts finish, or a bundle that defines the
+ * host first.
+ *
+ * It looks when the host connects and at each child added after, and waits on
+ * `customElements.whenDefined` once for each name. `define` upgrades the
+ * elements in the document before that promise resolves, so the children have
+ * their class by the time the callback runs. The callback is the host's own
+ * resync, such as its `slotchange` handler, and is `requestUpdate` unless given
+ * something else to do. Watches from connection to disconnection.
+ */
+export declare class UpgradeController implements ReactiveController {
+    private readonly host;
+    private readonly upgraded;
+    private watcher;
+    /** The names already waited on, so each is waited on once. */
+    private readonly waiting;
+    private readonly subtree;
+    constructor(host: ReactiveControllerHost & Element, upgraded?: () => void, options?: UpgradeOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Waits on `element`, where it was added, and on what it holds where the subtree counts. */
+    private look;
+    private wait;
+}

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

@@ -0,0 +1,53 @@
+export class UpgradeController {
+    constructor(host, upgraded = () => host.requestUpdate(), options = {}) {
+        this.host = host;
+        this.upgraded = upgraded;
+        this.watcher = undefined;
+        this.waiting = new Set();
+        this.subtree = options.subtree ?? false;
+        host.addController(this);
+    }
+    hostConnected() {
+        if (typeof MutationObserver === 'undefined' || typeof customElements === 'undefined') {
+            return;
+        }
+        this.look(this.host, false);
+        this.watcher ??= new MutationObserver((records) => {
+            for (const record of records) {
+                for (const node of record.addedNodes) {
+                    if (node.nodeType === Node.ELEMENT_NODE) {
+                        this.look(node, true);
+                    }
+                }
+            }
+        });
+        this.watcher.observe(this.host, { childList: true, subtree: this.subtree });
+    }
+    hostDisconnected() {
+        this.watcher?.disconnect();
+    }
+    look(element, added) {
+        if (added) {
+            this.wait(element);
+        }
+        const inside = this.subtree
+            ? element.querySelectorAll('*')
+            : element === this.host
+                ? element.children
+                : [];
+        for (const child of inside) {
+            this.wait(child);
+        }
+    }
+    wait(element) {
+        const name = element.localName;
+        if (!name.includes('-') || this.waiting.has(name) || customElements.get(name) !== undefined) {
+            return;
+        }
+        this.waiting.add(name);
+        void customElements.whenDefined(name).then(() => {
+            this.waiting.delete(name);
+            this.upgraded();
+        });
+    }
+}

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export { SourceController, type SourceHost, } from './controllers/source-control
 export { drawStatus, type SayOptions, StatusController, } from './controllers/status-controller/status-controller.js';
 export { SwipeController, type SwipeOptions, } from './controllers/swipe-controller/swipe-controller.js';
 export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
+export { UpgradeController, type UpgradeOptions, } from './controllers/upgrade-controller/upgrade-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 ActivateDetail, type AuraFallbackDetail, type BandDetail, type CanvasView, type CaretDetail, type ChangeDetail, type CompleteDetail, type ConnectDetail, type ConsoleDetail, type CopyDetail, type CreateDetail, type DismissDetail, type FacetDetail, type FilterDetail, type GraphFilterDetail, type GraphLayoutDetail, type GraphPartChangeDetail, type GraphSignalDetail, HelixActionEvent, HelixActivateEvent, HelixAuraFallbackEvent, HelixBandEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeReorderEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixClearEvent, HelixCollapseEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyErrorEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixEditEvent, HelixEndEvent, HelixExpandEvent, HelixFacetEvent, HelixFilterEvent, HelixFilteredEvent, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, HelixHistoryEvent, HelixLoadEvent, HelixLoadMoreEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPanelResizeEvent, HelixPinEvent, HelixPressEvent, HelixPreviewEvent, HelixPreviousEvent, HelixRangeChangeEvent, HelixReadEvent, HelixReadingChangeEvent, HelixReadingPressEvent, HelixReconnectEvent, HelixRejectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixReorderedEvent, HelixResizedEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSelectedEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixSortedEvent, HelixSplitEvent, HelixStrandsFallbackEvent, HelixToggleEvent, HelixTourAskEvent, HelixTourStatusEvent, HelixTypingEvent, type MapClusterDetail, type MapPanDetail, type MapPartChangeDetail, type MapRotateDetail, type MapTiltDetail, type MapZoomDetail, type MoveDetail, type NavigateDetail, type OpenDetail, type PressDetail, type PressPointerType, type RangeDetail, type ReadDetail, type ReadingDetail, type ReconnectDetail, type Refusal, type RefusedFile, type RejectDetail, type RelabelDetail, type RemoveDetail, type ReorderDetail, type ResizeDetail, type ScrolledDetail, type SelectDetail, type SendDetail, type ShortcutDetail, type SkipDetail, type SortDetail, type StrandsFallbackDetail, type ToggleDetail, type TourStatusDetail, type TypingDetail, type ViewportPanDetail, type ViewportZoomDetail, } from './events/events.js';

package/dist/index.js

@@ -31,6 +31,7 @@ export { SourceController, } from './controllers/source-controller/source-contro
 export { drawStatus, StatusController, } from './controllers/status-controller/status-controller.js';
 export { SwipeController, } from './controllers/swipe-controller/swipe-controller.js';
 export { TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
+export { UpgradeController, } from './controllers/upgrade-controller/upgrade-controller.js';
 export { VirtualizeController, } from './controllers/virtualize-controller/virtualize-controller.js';
 export { eventsForTag, registerElementEvents } from './events/element-events.js';
 export { HelixActionEvent, HelixActivateEvent, HelixAuraFallbackEvent, HelixBandEvent, HelixBeforeActivateEvent, HelixBeforeChangeEvent, HelixBeforeCloseEvent, HelixBeforeCollapseEvent, HelixBeforeEditEvent, HelixBeforeMoveEvent, HelixBeforeOpenEvent, HelixBeforePanelResizeEvent, HelixBeforePinEvent, HelixBeforeReconnectEvent, HelixBeforeRelabelEvent, HelixBeforeReorderEvent, HelixBeforeResizeEvent, HelixBeforeSplitEvent, HelixBeforeToggleEvent, HelixCanvasEditEvent, HelixCanvasPanEvent, HelixCanvasViewEvent, HelixCanvasZoomEvent, HelixCaretEvent, HelixClearEvent, HelixCollapseEvent, HelixCompleteEvent, HelixConnectEvent, HelixConsoleEvent, HelixCopyErrorEvent, HelixCopyEvent, HelixCreateEvent, HelixDismissEvent, HelixEditEvent, HelixEndEvent, HelixExpandEvent, HelixFacetEvent, HelixFilterEvent, HelixFilteredEvent, HelixGraphFilterEvent, HelixGraphLayoutEvent, HelixGraphPanEvent, HelixGraphPartChangeEvent, HelixGraphReadyEvent, HelixGraphSignalEvent, HelixGraphZoomEvent, HelixHistoryEvent, HelixLoadEvent, HelixLoadMoreEvent, HelixMapClusterEvent, HelixMapPanEvent, HelixMapPartChangeEvent, HelixMapReadyEvent, HelixMapRotateEvent, HelixMapTiltEvent, HelixMapZoomEvent, HelixMoveEvent, HelixNavigateEvent, HelixNextEvent, HelixPanelResizeEvent, HelixPinEvent, HelixPressEvent, HelixPreviewEvent, HelixPreviousEvent, HelixRangeChangeEvent, HelixReadEvent, HelixReadingChangeEvent, HelixReadingPressEvent, HelixReconnectEvent, HelixRejectEvent, HelixRelabelEvent, HelixRemoveEvent, HelixReorderEvent, HelixReorderedEvent, HelixResizedEvent, HelixResizeEvent, HelixSampleEndEvent, HelixSampleStartEvent, HelixScrolledEvent, HelixSelectEvent, HelixSelectedEvent, HelixSendEvent, HelixShortcutEvent, HelixSortEvent, HelixSortedEvent, HelixSplitEvent, HelixStrandsFallbackEvent, HelixToggleEvent, HelixTourAskEvent, HelixTourStatusEvent, HelixTypingEvent, } from './events/events.js';

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

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.162.0';
+export const VERSION = '0.163.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.162.0",
+  "version": "0.163.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.162.0"
+    "@fusion.dev/helix-icons": "0.163.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.162.0",
-    "@fusion.dev/helix-testing": "0.162.0",
+    "@fusion.dev/helix-cem": "0.163.0",
+    "@fusion.dev/helix-testing": "0.163.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },