@fusion.dev/helix-core 0.0.9 → 0.0.10

package/README.md

@@ -0,0 +1,30 @@
+# @fusion.dev/helix-core
+
+The primitives both Helix tiers are built from: base classes, mixins, decorators
+and utilities.
+
+```sh
+npm install @fusion.dev/helix-core
+```
+
+Useful directly if you are writing custom elements that need to sit alongside
+Helix and behave the same way — controlled properties that answer, a single
+page-wide ticker rather than one timer per element, scroll-parent resolution that
+crosses shadow boundaries, and duplicate-registration detection.
+
+```js
+import { duplicateRegistrations } from '@fusion.dev/helix-core'
+
+// Two copies of a library on one page is silent: the first registration keeps
+// the tag and `instanceof` against the second is quietly false.
+console.log(duplicateRegistrations())
+```
+
+Most consumers get this transitively through
+[`@fusion.dev/helix`](https://www.npmjs.com/package/@fusion.dev/helix) or
+[`@fusion.dev/helix-headless`](https://www.npmjs.com/package/@fusion.dev/helix-headless)
+and never import it by name.
+
+[Documentation](https://helix.fusion.dev)
+
+MIT

package/custom-elements.json

@@ -7782,6 +7782,24 @@
       "kind": "javascript-module",
       "path": "src/utils/ticker/ticker.ts",
       "declarations": [
+        {
+          "kind": "function",
+          "name": "withClock",
+          "return": {
+            "type": {
+              "text": "(() => void)"
+            }
+          },
+          "parameters": [
+            {
+              "name": "clock",
+              "type": {
+                "text": "Clock"
+              }
+            }
+          ],
+          "description": "Replaces the ticker with an empty one on the given clock, and hands back the\nway to put the real one back.\n\n**On `globalThis` with the rest of it, deliberately.** The spec bundler emits\none bundle per family and the runner loads them all into one page, so a\nmodule-level clock would have the reach of one bundle while the timer it\nschedules has the reach of the document. That is the fault the arrangement\nabove exists to avoid, and this must not reintroduce it."
+        },
         {
           "kind": "function",
           "name": "subscribe",
@@ -7808,6 +7826,14 @@
         }
       ],
       "exports": [
+        {
+          "kind": "js",
+          "name": "withClock",
+          "declaration": {
+            "name": "withClock",
+            "module": "src/utils/ticker/ticker.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "subscribe",

package/dist/utils/ticker/ticker.d.ts

@@ -1,3 +1,33 @@
+/**
+ * The three platform calls this makes, taken as values so a test can drive them.
+ *
+ * **Not a configuration point.** It exists because the alternative is asserting
+ * on the machine: a spec that subscribes at 1000ms and waits 1400 is measuring
+ * how loaded the runner is, and a loaded runner eats 400ms. One did, on a green
+ * branch, and blocked a merge that had nothing wrong with it. A bigger margin is
+ * the same bug at a lower rate.
+ *
+ * Bun 1.1.43 is what this workspace pins, and it has `jest.useFakeTimers()`
+ * without `jest.advanceTimersByTime`, so there is nothing to advance a faked
+ * timer with. Measured rather than assumed: a spec asserting that function
+ * exists throws.
+ */
+export interface Clock {
+    clearTimer: (timer: ReturnType<typeof setTimeout>) => void;
+    now: () => number;
+    setTimer: (run: () => void, wait: number) => ReturnType<typeof setTimeout>;
+}
+/**
+ * Replaces the ticker with an empty one on the given clock, and hands back the
+ * way to put the real one back.
+ *
+ * **On `globalThis` with the rest of it, deliberately.** The spec bundler emits
+ * one bundle per family and the runner loads them all into one page, so a
+ * module-level clock would have the reach of one bundle while the timer it
+ * schedules has the reach of the document. That is the fault the arrangement
+ * above exists to avoid, and this must not reintroduce it.
+ */
+export declare const withClock: (clock: Clock) => (() => void);
 /**
  * Asks to be run in `delay` milliseconds, and returns the way to stop asking.
  *

package/dist/utils/ticker/ticker.js

@@ -1,18 +1,43 @@
+const REAL = {
+    clearTimer: (timer) => {
+        clearTimeout(timer);
+    },
+    now: () => Date.now(),
+    setTimer: (run, wait) => setTimeout(run, wait),
+};
 const KEY = Symbol.for('helix.ticker');
 const ticker = () => {
     const global = globalThis;
     let found = global[KEY];
     if (!found) {
-        found = { timer: undefined, waiting: new Set() };
+        found = { clock: REAL, timer: undefined, waiting: new Set() };
         global[KEY] = found;
     }
     return found;
 };
+/**
+ * Replaces the ticker with an empty one on the given clock, and hands back the
+ * way to put the real one back.
+ *
+ * **On `globalThis` with the rest of it, deliberately.** The spec bundler emits
+ * one bundle per family and the runner loads them all into one page, so a
+ * module-level clock would have the reach of one bundle while the timer it
+ * schedules has the reach of the document. That is the fault the arrangement
+ * above exists to avoid, and this must not reintroduce it.
+ */
+export const withClock = (clock) => {
+    const global = globalThis;
+    const before = global[KEY];
+    global[KEY] = { clock, timer: undefined, waiting: new Set() };
+    return () => {
+        global[KEY] = before;
+    };
+};
 /** Sets the one timeout, for the soonest thing anybody is waiting on. */
 const schedule = () => {
     const held = ticker();
     if (held.timer !== undefined) {
-        clearTimeout(held.timer);
+        held.clock.clearTimer(held.timer);
         held.timer = undefined;
     }
     if (held.waiting.size === 0) {
@@ -21,10 +46,10 @@ const schedule = () => {
     const soonest = Math.min(...[...held.waiting].map((one) => one.at));
     /* Floored at a second: a subscriber handed a zero would be re-armed inside the
        callback that fired it, which is a busy loop wearing a timer's clothes. */
-    const wait = Math.max(1000, soonest - Date.now());
-    held.timer = setTimeout(() => {
+    const wait = Math.max(1000, soonest - held.clock.now());
+    held.timer = held.clock.setTimer(() => {
         held.timer = undefined;
-        const now = Date.now();
+        const now = held.clock.now();
         /* Copied before iterating, because every callback re-subscribes and would
            otherwise be walked again inside the same pass. */
         for (const one of [...held.waiting]) {
@@ -45,7 +70,7 @@ const schedule = () => {
  */
 export const subscribe = (delay, run) => {
     const held = ticker();
-    const entry = { at: Date.now() + delay, run };
+    const entry = { at: held.clock.now() + delay, run };
     held.waiting.add(entry);
     schedule();
     return () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -33,12 +33,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.0.9"
+    "@fusion.dev/helix-icons": "0.0.10"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.0.9",
-    "@fusion.dev/helix-testing": "0.0.9",
+    "@fusion.dev/helix-cem": "0.0.10",
+    "@fusion.dev/helix-testing": "0.0.10",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",