@fusion.dev/helix-core 0.135.0 → 0.136.0

package/custom-elements.json

@@ -8078,6 +8078,22 @@
             "module": "./utils/relative-time/relative-time.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "reportUsage",
+          "declaration": {
+            "name": "reportUsage",
+            "module": "./utils/report-usage/report-usage.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "USAGE_SLOT",
+          "declaration": {
+            "name": "USAGE_SLOT",
+            "module": "./utils/report-usage/report-usage.js"
+          }
+        },
         {
           "kind": "js",
           "name": "reportValues",
@@ -14312,6 +14328,53 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/report-usage/report-usage.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "USAGE_SLOT",
+          "description": "The key the listener is kept under. `@fusion.dev/helix-diagnostics` names the same string."
+        },
+        {
+          "kind": "function",
+          "name": "reportUsage",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "element",
+              "type": {
+                "text": "HTMLElement"
+              }
+            }
+          ],
+          "description": "Tells the listener, where there is one, that `element` has rendered for the\nfirst time.\n\n**A listener that throws never breaks the element.** The error is thrown\nagain on a later microtask, so it reaches the console and the page's error\nhandlers, and the render that called this finishes as if nothing listened."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "USAGE_SLOT",
+          "declaration": {
+            "name": "USAGE_SLOT",
+            "module": "src/utils/report-usage/report-usage.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "reportUsage",
+          "declaration": {
+            "name": "reportUsage",
+            "module": "src/utils/report-usage/report-usage.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/report-values/report-values.ts",

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

@@ -1,5 +1,6 @@
 import { css, LitElement } from 'lit';
 import { unsafeStatic } from 'lit/static-html.js';
+import { reportUsage } from '../utils/report-usage/report-usage.js';
 import { applyReactProperties, auditReactProps, bindReactHandler, reactPropsOf, } from './react-bridge.js';
 const BOX_SIZING = css `
   *,
@@ -114,6 +115,7 @@ export class HelixElement extends LitElement {
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
+        reportUsage(this);
         let applied = applyReactProperties(this);
         requestAnimationFrame(() => {
             this.toggleState('settled', true);

package/dist/index.d.ts

@@ -63,6 +63,7 @@ export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
 export { type ColorBytes, readColor } from './utils/read-color/read-color.js';
 export { type Row, type RowCell, readRows, readSeries, type Series, type SeriesPoint, } from './utils/read-series/read-series.js';
 export { type Relative, relativeTime, } from './utils/relative-time/relative-time.js';
+export { reportUsage, USAGE_SLOT } from './utils/report-usage/report-usage.js';
 export { reportValues } from './utils/report-values/report-values.js';
 export { type ChangeRequestOptions, requestChange, } from './utils/request-change/request-change.js';
 export { type ActivatableItem, resolveActiveItem, } from './utils/resolve-active-item/resolve-active-item.js';

package/dist/index.js

@@ -63,6 +63,7 @@ export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
 export { readColor } from './utils/read-color/read-color.js';
 export { readRows, readSeries, } from './utils/read-series/read-series.js';
 export { relativeTime, } from './utils/relative-time/relative-time.js';
+export { reportUsage, USAGE_SLOT } from './utils/report-usage/report-usage.js';
 export { reportValues } from './utils/report-values/report-values.js';
 export { requestChange, } from './utils/request-change/request-change.js';
 export { resolveActiveItem, } from './utils/resolve-active-item/resolve-active-item.js';

package/dist/utils/report-usage/report-usage.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a rendered element is told to whoever is counting usage.
+ *
+ * **One slot on `globalThis`, under a registered symbol, and empty by default.**
+ * `@fusion.dev/helix-diagnostics` fills it from `watch()` and counts what
+ * renders: the tags, the axes set on them, and the named slots filled. With
+ * nothing in the slot, which is every page that has not asked, an element pays
+ * one property read and a type check once, after its first render.
+ *
+ * **A registered symbol and not an export**, for two reasons. Diagnostics does
+ * not depend on the library it diagnoses, so it cannot import a setter from
+ * here, and a page holding two copies of Helix runs two copies of this module:
+ * `Symbol.for` is the one key both copies and the collector agree on, so every
+ * copy's elements are counted.
+ *
+ * **Counting only, never sending.** This module holds no network code and
+ * never will; what the listener does with an element is the listener's.
+ */
+/** The key the listener is kept under. `@fusion.dev/helix-diagnostics` names the same string. */
+export declare const USAGE_SLOT: unique symbol;
+/**
+ * Tells the listener, where there is one, that `element` has rendered for the
+ * first time.
+ *
+ * **A listener that throws never breaks the element.** The error is thrown
+ * again on a later microtask, so it reaches the console and the page's error
+ * handlers, and the render that called this finishes as if nothing listened.
+ */
+export declare const reportUsage: (element: HTMLElement) => void;

package/dist/utils/report-usage/report-usage.js

@@ -0,0 +1,15 @@
+export const USAGE_SLOT = Symbol.for('fusion.dev/helix/usage');
+export const reportUsage = (element) => {
+    const listener = globalThis[USAGE_SLOT];
+    if (typeof listener !== 'function') {
+        return;
+    }
+    try {
+        listener(element);
+    }
+    catch (error) {
+        queueMicrotask(() => {
+            throw error;
+        });
+    }
+};

package/package.json

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