@trackunit/react-components 3.2.4 → 3.3.0

package/index.cjs.js

@@ -1490,6 +1490,59 @@ const cvaSpinnerContainer = cssClassVarianceUtilities.cva({
 });
 const cvaSpinnerLabel = cssClassVarianceUtilities.cva({ base: ["self-center", "text-center", "text-current"] });
 
+/**
+ * Cycle duration, in milliseconds, matching Tailwind's `animate-spin` utility
+ * (`spin 1s linear infinite`) — the animation `Spinner` uses.
+ */
+const DEFAULT_SPIN_DURATION_MS = 1000;
+/**
+ * Synchronizes an `animate-spin` element's rotation phase to the shared wall clock, so every
+ * element using this hook — anywhere on the page, including across iframe boundaries — renders
+ * at the same point in its spin cycle regardless of when its DOM node, document, or iframe was
+ * created.
+ *
+ * On mount, in a layout effect, it writes a negative `animation-delay` —
+ * `-(Date.now() % durationMs)` — directly onto `ref.current`. A negative delay skips the
+ * animation forward by that amount, effectively pinning the element to `now`'s position in the
+ * cycle instead of starting fresh at phase 0. Because `Date.now()` is the same system clock
+ * everywhere, this keeps `animate-spin` elements visually synchronized across the whole page with
+ * no message-passing required.
+ *
+ * The sample is taken in a layout effect rather than during render: React's render phase can be
+ * time-sliced across several elements (a large table/page mount, a Suspense-covered subtree,
+ * etc.), so elements rendered in the same commit could otherwise sample the clock many
+ * milliseconds apart and end up visibly out of phase with each other. Layout effects for a given
+ * commit all run together, synchronously, right after the DOM mutations land and before paint —
+ * so every element written to in the same commit gets, for practical purposes, the same
+ * timestamp.
+ *
+ * The delay is written once, on mount, and then held fixed for the life of the element (the
+ * effect only re-runs if `ref` or `durationMs` change identity, which does not happen for a
+ * stable ref and a constant duration). Recomputing it on every render would be actively harmful:
+ * once a CSS animation is running, changing `animation-delay` does not re-anchor its phase to the
+ * new value — it recombines the new delay with the animation's own already-elapsed local clock,
+ * which desyncs the element instead of correcting it.
+ *
+ * Known trade-off: an element that is `display: none` at mount (a collapsed panel, inactive tab)
+ * doesn't have a running animation yet, so its delay is anchored to mount time rather than to
+ * when the animation actually starts once shown, and it does not resync after a
+ * backgrounded tab/iframe throttles the animation and later resumes it — both are acceptable
+ * trade-offs for a short-lived, purely decorative loading spinner.
+ *
+ * @param {RefObject<HTMLElement | null>} ref Ref to the element with the `animate-spin` animation.
+ * @param {number} durationMs Duration of one full spin cycle, in milliseconds, at mount time.
+ *   Must match the animation's own `animation-duration`. Defaults to 1000ms, matching
+ *   `Spinner`'s `animate-spin` usage.
+ */
+const useSyncedSpinDelay = (ref, durationMs = DEFAULT_SPIN_DURATION_MS) => {
+    react.useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.style.animationDelay = `${-(Date.now() % durationMs)}ms`;
+    }, [ref, durationMs]);
+};
+
 /**
  * Spinner provides visual feedback that data is being processed. It reassures users that their action is being handled
  * during short operations (1-5 seconds) such as saving, loading, or refreshing data.
@@ -1526,7 +1579,11 @@ const cvaSpinnerLabel = cssClassVarianceUtilities.cva({ base: ["self-center", "t
  * @returns {ReactElement} Spinner component
  */
 const Spinner = ({ mode = "light", size = "medium", centering = "centered", className, containerClassName, "data-testid": dataTestId = "spinner", label, style, ref, }) => {
-    return (jsxRuntime.jsx("div", { className: cvaSpinnerContainer({ centering, className: containerClassName }), ref: ref, style: style, children: jsxRuntime.jsxs("div", { className: cvaSpinnerContainerInner(), children: [jsxRuntime.jsx("div", { className: cvaSpinner({ size, mode, className }), "data-testid": dataTestId, role: "spinbutton" }), label ? jsxRuntime.jsx("span", { className: cvaSpinnerLabel(), children: label }) : null] }) }));
+    // Keeps every Spinner's rotation in phase with every other one on the page -- including
+    // spinners rendered in other iframes -- since the delay is derived from the shared wall clock.
+    const spinnerElRef = react.useRef(null);
+    useSyncedSpinDelay(spinnerElRef);
+    return (jsxRuntime.jsx("div", { className: cvaSpinnerContainer({ centering, className: containerClassName }), ref: ref, style: style, children: jsxRuntime.jsxs("div", { className: cvaSpinnerContainerInner(), children: [jsxRuntime.jsx("div", { className: cvaSpinner({ size, mode, className }), "data-testid": dataTestId, ref: spinnerElRef, role: "spinbutton" }), label ? jsxRuntime.jsx("span", { className: cvaSpinnerLabel(), children: label }) : null] }) }));
 };
 
 const cvaButton = cssClassVarianceUtilities.cva({

package/index.esm.js

@@ -1489,6 +1489,59 @@ const cvaSpinnerContainer = cva({
 });
 const cvaSpinnerLabel = cva({ base: ["self-center", "text-center", "text-current"] });
 
+/**
+ * Cycle duration, in milliseconds, matching Tailwind's `animate-spin` utility
+ * (`spin 1s linear infinite`) — the animation `Spinner` uses.
+ */
+const DEFAULT_SPIN_DURATION_MS = 1000;
+/**
+ * Synchronizes an `animate-spin` element's rotation phase to the shared wall clock, so every
+ * element using this hook — anywhere on the page, including across iframe boundaries — renders
+ * at the same point in its spin cycle regardless of when its DOM node, document, or iframe was
+ * created.
+ *
+ * On mount, in a layout effect, it writes a negative `animation-delay` —
+ * `-(Date.now() % durationMs)` — directly onto `ref.current`. A negative delay skips the
+ * animation forward by that amount, effectively pinning the element to `now`'s position in the
+ * cycle instead of starting fresh at phase 0. Because `Date.now()` is the same system clock
+ * everywhere, this keeps `animate-spin` elements visually synchronized across the whole page with
+ * no message-passing required.
+ *
+ * The sample is taken in a layout effect rather than during render: React's render phase can be
+ * time-sliced across several elements (a large table/page mount, a Suspense-covered subtree,
+ * etc.), so elements rendered in the same commit could otherwise sample the clock many
+ * milliseconds apart and end up visibly out of phase with each other. Layout effects for a given
+ * commit all run together, synchronously, right after the DOM mutations land and before paint —
+ * so every element written to in the same commit gets, for practical purposes, the same
+ * timestamp.
+ *
+ * The delay is written once, on mount, and then held fixed for the life of the element (the
+ * effect only re-runs if `ref` or `durationMs` change identity, which does not happen for a
+ * stable ref and a constant duration). Recomputing it on every render would be actively harmful:
+ * once a CSS animation is running, changing `animation-delay` does not re-anchor its phase to the
+ * new value — it recombines the new delay with the animation's own already-elapsed local clock,
+ * which desyncs the element instead of correcting it.
+ *
+ * Known trade-off: an element that is `display: none` at mount (a collapsed panel, inactive tab)
+ * doesn't have a running animation yet, so its delay is anchored to mount time rather than to
+ * when the animation actually starts once shown, and it does not resync after a
+ * backgrounded tab/iframe throttles the animation and later resumes it — both are acceptable
+ * trade-offs for a short-lived, purely decorative loading spinner.
+ *
+ * @param {RefObject<HTMLElement | null>} ref Ref to the element with the `animate-spin` animation.
+ * @param {number} durationMs Duration of one full spin cycle, in milliseconds, at mount time.
+ *   Must match the animation's own `animation-duration`. Defaults to 1000ms, matching
+ *   `Spinner`'s `animate-spin` usage.
+ */
+const useSyncedSpinDelay = (ref, durationMs = DEFAULT_SPIN_DURATION_MS) => {
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        el.style.animationDelay = `${-(Date.now() % durationMs)}ms`;
+    }, [ref, durationMs]);
+};
+
 /**
  * Spinner provides visual feedback that data is being processed. It reassures users that their action is being handled
  * during short operations (1-5 seconds) such as saving, loading, or refreshing data.
@@ -1525,7 +1578,11 @@ const cvaSpinnerLabel = cva({ base: ["self-center", "text-center", "text-current
  * @returns {ReactElement} Spinner component
  */
 const Spinner = ({ mode = "light", size = "medium", centering = "centered", className, containerClassName, "data-testid": dataTestId = "spinner", label, style, ref, }) => {
-    return (jsx("div", { className: cvaSpinnerContainer({ centering, className: containerClassName }), ref: ref, style: style, children: jsxs("div", { className: cvaSpinnerContainerInner(), children: [jsx("div", { className: cvaSpinner({ size, mode, className }), "data-testid": dataTestId, role: "spinbutton" }), label ? jsx("span", { className: cvaSpinnerLabel(), children: label }) : null] }) }));
+    // Keeps every Spinner's rotation in phase with every other one on the page -- including
+    // spinners rendered in other iframes -- since the delay is derived from the shared wall clock.
+    const spinnerElRef = useRef(null);
+    useSyncedSpinDelay(spinnerElRef);
+    return (jsx("div", { className: cvaSpinnerContainer({ centering, className: containerClassName }), ref: ref, style: style, children: jsxs("div", { className: cvaSpinnerContainerInner(), children: [jsx("div", { className: cvaSpinner({ size, mode, className }), "data-testid": dataTestId, ref: spinnerElRef, role: "spinbutton" }), label ? jsx("span", { className: cvaSpinnerLabel(), children: label }) : null] }) }));
 };
 
 const cvaButton = cva({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "3.2.4",
+  "version": "3.3.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,16 +14,16 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.15.41",
-    "@trackunit/css-class-variance-utilities": "2.0.21",
-    "@trackunit/shared-utils": "1.16.56",
-    "@trackunit/ui-icons": "1.14.49",
+    "@trackunit/ui-design-tokens": "1.15.42",
+    "@trackunit/css-class-variance-utilities": "2.0.22",
+    "@trackunit/shared-utils": "1.16.57",
+    "@trackunit/ui-icons": "1.14.50",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "^3.14.3",
     "dequal": "^2.0.3",
     "fflate": "^0.8.2",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.5.7"
+    "@trackunit/i18n-library-translation": "2.5.9"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/Spinner/Spinner.d.ts

@@ -1,8 +1,8 @@
 import { ReactElement } from "react";
 import { CommonProps } from "../../common/CommonProps";
-import type { Styleable } from "../../common/Styleable";
 import { Refable } from "../../common/Refable";
 import { Size } from "../../common/Size";
+import type { Styleable } from "../../common/Styleable";
 type Centering = "horizontally" | "vertically" | "centered";
 export interface SpinnerProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
     /**

package/src/components/Spinner/useSyncedSpinDelay.d.ts

@@ -0,0 +1,46 @@
+import { type RefObject } from "react";
+/**
+ * Cycle duration, in milliseconds, matching Tailwind's `animate-spin` utility
+ * (`spin 1s linear infinite`) — the animation `Spinner` uses.
+ */
+export declare const DEFAULT_SPIN_DURATION_MS = 1000;
+/**
+ * Synchronizes an `animate-spin` element's rotation phase to the shared wall clock, so every
+ * element using this hook — anywhere on the page, including across iframe boundaries — renders
+ * at the same point in its spin cycle regardless of when its DOM node, document, or iframe was
+ * created.
+ *
+ * On mount, in a layout effect, it writes a negative `animation-delay` —
+ * `-(Date.now() % durationMs)` — directly onto `ref.current`. A negative delay skips the
+ * animation forward by that amount, effectively pinning the element to `now`'s position in the
+ * cycle instead of starting fresh at phase 0. Because `Date.now()` is the same system clock
+ * everywhere, this keeps `animate-spin` elements visually synchronized across the whole page with
+ * no message-passing required.
+ *
+ * The sample is taken in a layout effect rather than during render: React's render phase can be
+ * time-sliced across several elements (a large table/page mount, a Suspense-covered subtree,
+ * etc.), so elements rendered in the same commit could otherwise sample the clock many
+ * milliseconds apart and end up visibly out of phase with each other. Layout effects for a given
+ * commit all run together, synchronously, right after the DOM mutations land and before paint —
+ * so every element written to in the same commit gets, for practical purposes, the same
+ * timestamp.
+ *
+ * The delay is written once, on mount, and then held fixed for the life of the element (the
+ * effect only re-runs if `ref` or `durationMs` change identity, which does not happen for a
+ * stable ref and a constant duration). Recomputing it on every render would be actively harmful:
+ * once a CSS animation is running, changing `animation-delay` does not re-anchor its phase to the
+ * new value — it recombines the new delay with the animation's own already-elapsed local clock,
+ * which desyncs the element instead of correcting it.
+ *
+ * Known trade-off: an element that is `display: none` at mount (a collapsed panel, inactive tab)
+ * doesn't have a running animation yet, so its delay is anchored to mount time rather than to
+ * when the animation actually starts once shown, and it does not resync after a
+ * backgrounded tab/iframe throttles the animation and later resumes it — both are acceptable
+ * trade-offs for a short-lived, purely decorative loading spinner.
+ *
+ * @param {RefObject<HTMLElement | null>} ref Ref to the element with the `animate-spin` animation.
+ * @param {number} durationMs Duration of one full spin cycle, in milliseconds, at mount time.
+ *   Must match the animation's own `animation-duration`. Defaults to 1000ms, matching
+ *   `Spinner`'s `animate-spin` usage.
+ */
+export declare const useSyncedSpinDelay: (ref: RefObject<HTMLElement | null>, durationMs?: number) => void;