@fusion.dev/helix-core 0.135.0 → 0.137.0

package/custom-elements.json

@@ -8078,6 +8078,38 @@
             "module": "./utils/relative-time/relative-time.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "noteVersion",
+          "declaration": {
+            "name": "noteVersion",
+            "module": "./utils/report-usage/report-usage.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": "VERSIONS_SLOT",
+          "declaration": {
+            "name": "VERSIONS_SLOT",
+            "module": "./utils/report-usage/report-usage.js"
+          }
+        },
         {
           "kind": "js",
           "name": "reportValues",
@@ -8365,6 +8397,14 @@
             "name": "writtenNumbers",
             "module": "./utils/written-list/written-list.js"
           }
+        },
+        {
+          "kind": "js",
+          "name": "VERSION",
+          "declaration": {
+            "name": "VERSION",
+            "module": "./version.js"
+          }
         }
       ]
     },
@@ -14312,6 +14352,84 @@
         }
       ]
     },
+    {
+      "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": "variable",
+          "name": "VERSIONS_SLOT",
+          "description": "The key the loaded versions are listed under: every copy of core on the\npage adds its own once, so a page holding two copies lists two.\n`@fusion.dev/helix-diagnostics` compares the list with the version its\nmanifest names.\n\n**On `globalThis` and not on the element classes**, where a field would be\nlisted as a member of every component in the manifest and on every\nreference page."
+        },
+        {
+          "kind": "function",
+          "name": "noteVersion",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "description": "Adds this copy's version to the page's list, once."
+        },
+        {
+          "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": "VERSIONS_SLOT",
+          "declaration": {
+            "name": "VERSIONS_SLOT",
+            "module": "src/utils/report-usage/report-usage.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "noteVersion",
+          "declaration": {
+            "name": "noteVersion",
+            "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",
@@ -15326,6 +15444,35 @@
           }
         }
       ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/version.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "VERSION",
+          "type": {
+            "text": "string"
+          },
+          "default": "'0.137.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."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "VERSION",
+          "declaration": {
+            "name": "VERSION",
+            "module": "src/version.ts"
+          }
+        }
+      ]
     }
-  ]
+  ],
+  "helix": {
+    "package": "@fusion.dev/helix-core",
+    "version": "0.137.0"
+  }
 }

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

@@ -1,5 +1,6 @@
 import { css, LitElement } from 'lit';
 import { unsafeStatic } from 'lit/static-html.js';
+import { noteVersion, 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);
@@ -146,3 +148,4 @@ export const whenHydrated = (element, write) => {
         write();
     }
 };
+noteVersion();

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 { noteVersion, reportUsage, USAGE_SLOT, VERSIONS_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';
@@ -80,3 +81,4 @@ export { dateAsValue, isDateValue, isTimeValue, minutesAsValue, numberAsValue, t
 export { watchTheme } from './utils/watch-theme/watch-theme.js';
 export { writeTime } from './utils/write-time/write-time.js';
 export { writtenList, writtenNumbers } from './utils/written-list/written-list.js';
+export { VERSION } from './version.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 { noteVersion, reportUsage, USAGE_SLOT, VERSIONS_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';
@@ -80,3 +81,4 @@ export { dateAsValue, isDateValue, isTimeValue, minutesAsValue, numberAsValue, t
 export { watchTheme } from './utils/watch-theme/watch-theme.js';
 export { writeTime } from './utils/write-time/write-time.js';
 export { writtenList, writtenNumbers } from './utils/written-list/written-list.js';
+export { VERSION } from './version.js';

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

@@ -0,0 +1,42 @@
+/**
+ * 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;
+/**
+ * The key the loaded versions are listed under: every copy of core on the
+ * page adds its own once, so a page holding two copies lists two.
+ * `@fusion.dev/helix-diagnostics` compares the list with the version its
+ * manifest names.
+ *
+ * **On `globalThis` and not on the element classes**, where a field would be
+ * listed as a member of every component in the manifest and on every
+ * reference page.
+ */
+export declare const VERSIONS_SLOT: unique symbol;
+/** Adds this copy's version to the page's list, once. */
+export declare const noteVersion: () => void;
+/**
+ * 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,25 @@
+import { VERSION } from '../../version.js';
+export const USAGE_SLOT = Symbol.for('fusion.dev/helix/usage');
+export const VERSIONS_SLOT = Symbol.for('fusion.dev/helix/versions');
+export const noteVersion = () => {
+    const store = globalThis;
+    const listed = Array.isArray(store[VERSIONS_SLOT]) ? store[VERSIONS_SLOT] : [];
+    if (!listed.includes(VERSION)) {
+        listed.push(VERSION);
+    }
+    store[VERSIONS_SLOT] = listed;
+};
+export const reportUsage = (element) => {
+    const listener = globalThis[USAGE_SLOT];
+    if (typeof listener !== 'function') {
+        return;
+    }
+    try {
+        listener(element);
+    }
+    catch (error) {
+        queueMicrotask(() => {
+            throw error;
+        });
+    }
+};

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The version of the package this file ships in.
+ *
+ * **Written by `fusion/scripts/version.mjs`** wherever it writes the package's
+ * `package.json`, and stamped back into the repository beside it after a
+ * 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.137.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.137.0';

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.137.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.137.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.135.0",
-    "@fusion.dev/helix-testing": "0.135.0",
+    "@fusion.dev/helix-cem": "0.137.0",
+    "@fusion.dev/helix-testing": "0.137.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },