@uxf/core-react 11.114.0 → 11.120.0

package/README.md

@@ -623,6 +623,50 @@ const {
 
 ---
 
+## Global Context
+
+`createGlobalContext` is a thin wrapper around `React.createContext` that caches the resulting Context object on `globalThis`, keyed by a unique name. Use it instead of `createContext` for any Context exported from a library package.
+
+### Why it exists
+
+Under Turbopack a single `"use client"` module can be evaluated more than once — typically once per `"use client"` boundary that imports it. Each evaluation calls `createContext(...)` separately, producing distinct Context identities in the same JS realm. The `Provider` ends up writing into one identity and `useContext` reads from another, so consumers silently fall back to the default value. Caching the Context on `globalThis` collapses all evaluations to a single identity.
+
+Webpack does not exhibit this because its chunking layer deduplicates by module ID; Turbopack does not (yet) guarantee that for client-boundary modules.
+
+### Usage
+
+```tsx
+import { createGlobalContext } from "@uxf/core-react/global-context";
+import { useContext } from "react";
+
+const themeContext = createGlobalContext<"light" | "dark">("ui/theme", "light");
+
+export const ThemeProvider = themeContext.Provider;
+
+export function useTheme() {
+    return useContext(themeContext);
+}
+```
+
+### Naming convention
+
+The `name` argument must be unique across the monorepo. Use `"<package>/<context>"`, for example:
+
+- `"core-react/translations"`
+- `"localize/locale"`
+- `"ui/color-scheme"`
+
+The same name on subsequent calls returns the original Context — the `defaultValue` argument is honored only on the first call.
+
+### When to use it
+
+Use `createGlobalContext` for any Context that is:
+
+- exported from a library package (`@uxf/*`), or
+- consumed from more than one `"use client"` boundary.
+
+For Contexts that are private to a single app file and never imported elsewhere, plain `React.createContext` is fine.
+
 ## Translations
 
 Provides a translation system that can be used in both single-language and multi-language projects.

package/clickable/use-anchor-props.js

@@ -14,10 +14,12 @@ function useAnchorProps(props, options = {}) {
     const isSubmitType = type === "submit";
     const isButton = isSubmitType || (0, is_not_nil_1.isNotNil)(onClick);
     const tabIndexInteractive = isBusyOrDisabled ? -1 : tabIndex;
+    const isClickable = !isBusyOrDisabled && isButton;
+    const isHyperlink = !isBusyOrDisabled && Boolean(href);
     const simulatedButton = (0, _use_simulated_button_1._useSimulatedButton)({
         analyticsCallback,
-        isClickable: !isBusyOrDisabled || isButton,
-        isHyperlink: !isBusyOrDisabled || Boolean(href),
+        isClickable,
+        isHyperlink,
         onClick,
         onKeyDown,
         onKeyUp,

package/clickable/use-clickable-props.js

@@ -13,9 +13,10 @@ function useClickableProps(props, options = {}) {
     const isBusyOrDisabled = isBusy || isDisabledOrAriaDisabled;
     const isSubmitType = type === "submit";
     const isButton = isSubmitType || (0, is_not_nil_1.isNotNil)(onClick);
+    const isClickable = !isBusyOrDisabled && isButton;
     const simulatedButton = (0, _use_simulated_button_1._useSimulatedButton)({
         analyticsCallback,
-        isClickable: !isBusyOrDisabled || isButton,
+        isClickable,
         isHyperlink: false,
         onClick,
         onKeyDown,

package/global-context/index.d.ts

@@ -0,0 +1,16 @@
+import { Context } from "react";
+/**
+ * Creates a React Context cached on globalThis. Under Turbopack a single
+ * "use client" module can be evaluated more than once (per chunk/boundary),
+ * which would otherwise produce different Context identities — Provider and
+ * useContext would not meet. Caching by `name` guarantees a single identity
+ * across evaluations within one React runtime.
+ *
+ * Note: the cache is partitioned per React runtime (server vs client),
+ * because the two runtimes have incompatible Context shapes.
+ *
+ * `name` must be unique across the monorepo; recommended convention:
+ * "<package>/<context>", e.g. "core-react/translations", "localize/locale",
+ * "ui/color-scheme".
+ */
+export declare function createGlobalContext<T>(name: string, defaultValue: T): Context<T>;

package/global-context/index.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGlobalContext = createGlobalContext;
+// NOTE: This file intentionally has no "use client" directive.
+// createContext is a server-safe React API (not a hook), and adding "use client"
+// here would turn this module into a client reference, making module-scope calls
+// to createGlobalContext from non-"use client" Context files (e.g. ui/context.ts)
+// resolve to a proxy object on the server — Provider would then no longer be a
+// real component and prerender would fail with "Element type is invalid".
+// Consumers that need useContext put "use client" on their own module.
+const react_1 = require("react");
+// Why two-level keying:
+// In Next App Router (Next 16 + React 19) the server runtime loads a different
+// React build than the client runtime (the `react-server` export condition).
+// Each build has its own `createContext` function and produces Context objects
+// with different internal shapes — they are NOT interchangeable. A naive
+// `globalThis`-only singleton would serve the server-React Context to client
+// code (or vice versa) and React rejects the foreign object with
+// "Element type is invalid: ... got: object" at prerender.
+//
+// Outer WeakMap is keyed by the calling React's `createContext` function —
+// distinct per React runtime, so server and client get separate registries.
+// Inner Map then dedupes contexts by `name` within one runtime, which is the
+// actual fix for the Turbopack chunk-duplication problem we set out to solve.
+const REGISTRY_KEY = "__uxf_react_context_registry__";
+function getRegistry() {
+    const g = globalThis;
+    if (!g[REGISTRY_KEY]) {
+        g[REGISTRY_KEY] = new WeakMap();
+    }
+    let perRuntime = g[REGISTRY_KEY].get(react_1.createContext);
+    if (!perRuntime) {
+        perRuntime = new Map();
+        g[REGISTRY_KEY].set(react_1.createContext, perRuntime);
+    }
+    return perRuntime;
+}
+/**
+ * Creates a React Context cached on globalThis. Under Turbopack a single
+ * "use client" module can be evaluated more than once (per chunk/boundary),
+ * which would otherwise produce different Context identities — Provider and
+ * useContext would not meet. Caching by `name` guarantees a single identity
+ * across evaluations within one React runtime.
+ *
+ * Note: the cache is partitioned per React runtime (server vs client),
+ * because the two runtimes have incompatible Context shapes.
+ *
+ * `name` must be unique across the monorepo; recommended convention:
+ * "<package>/<context>", e.g. "core-react/translations", "localize/locale",
+ * "ui/color-scheme".
+ */
+function createGlobalContext(name, defaultValue) {
+    const registry = getRegistry();
+    const existing = registry.get(name);
+    if (existing) {
+        return existing;
+    }
+    const ctx = (0, react_1.createContext)(defaultValue);
+    ctx.displayName = `UxfGlobal(${name})`;
+    registry.set(name, ctx);
+    return ctx;
+}

package/global-context/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/global-context/index.test.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_1 = require("@testing-library/react");
+const react_2 = __importStar(require("react"));
+const index_1 = require("./index");
+const REGISTRY_KEY = "__uxf_react_context_registry__";
+function clearRegistry() {
+    const g = globalThis;
+    delete g[REGISTRY_KEY];
+}
+describe("createGlobalContext", () => {
+    beforeEach(() => {
+        clearRegistry();
+    });
+    it("returns a React Context with a Provider", () => {
+        const ctx = (0, index_1.createGlobalContext)("test/basic", "default");
+        expect(ctx).toBeDefined();
+        expect(ctx.Provider).toBeDefined();
+    });
+    it("returns the same Context instance for the same name", () => {
+        const first = (0, index_1.createGlobalContext)("test/identity", "default");
+        const second = (0, index_1.createGlobalContext)("test/identity", "default");
+        expect(second).toBe(first);
+    });
+    it("returns different Context instances for different names", () => {
+        const a = (0, index_1.createGlobalContext)("test/a", "a");
+        const b = (0, index_1.createGlobalContext)("test/b", "b");
+        expect(a).not.toBe(b);
+    });
+    it("caches by name and ignores subsequent defaultValue arguments", () => {
+        const first = (0, index_1.createGlobalContext)("test/cache", "first-default");
+        const second = (0, index_1.createGlobalContext)("test/cache", "second-default");
+        expect(second).toBe(first);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useContext)(first));
+        expect(result.current).toBe("first-default");
+    });
+    it("sets displayName for React DevTools", () => {
+        const ctx = (0, index_1.createGlobalContext)("test/display-name", 0);
+        expect(ctx.displayName).toBe("UxfGlobal(test/display-name)");
+    });
+    it("returns the provided value through Provider/useContext", () => {
+        const ctx = (0, index_1.createGlobalContext)("test/provider-consumer", "default");
+        function Consumer() {
+            const value = (0, react_2.useContext)(ctx);
+            return react_2.default.createElement("span", null, value);
+        }
+        function Wrapper(props) {
+            return react_2.default.createElement(ctx.Provider, { value: "provided" }, props.children);
+        }
+        (0, react_1.render)(react_2.default.createElement(Wrapper, null,
+            react_2.default.createElement(Consumer, null)));
+        expect(react_1.screen.getByText("provided").textContent).toBe("provided");
+    });
+    it("returns the default value when no Provider is mounted", () => {
+        const ctx = (0, index_1.createGlobalContext)("test/no-provider", "fallback");
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useContext)(ctx));
+        expect(result.current).toBe("fallback");
+    });
+    it("persists context identity on globalThis across registry lookups", () => {
+        const first = (0, index_1.createGlobalContext)("test/persist", "x");
+        const g = globalThis;
+        const perRuntime = g[REGISTRY_KEY].get(react_2.createContext);
+        const stored = perRuntime === null || perRuntime === void 0 ? void 0 : perRuntime.get("test/persist");
+        expect(stored).toBe(first);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/core-react",
-    "version": "11.114.0",
+    "version": "11.120.0",
     "description": "UXF Core",
     "author": "UX Fans s.r.o",
     "license": "MIT",

package/translations/index.js

@@ -4,8 +4,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TranslationsProvider = void 0;
 exports.useUxfTranslation = useUxfTranslation;
 const react_1 = require("react");
+const global_context_1 = require("../global-context");
 /* intellisense and linting is broken with any other more specific type */
-const translationsContext = (0, react_1.createContext)((key) => key); // eslint-disable-line @typescript-eslint/no-explicit-any
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const translationsContext = (0, global_context_1.createGlobalContext)("core-react/translations", (key) => key);
 exports.TranslationsProvider = translationsContext.Provider;
 function useUxfTranslation() {
     return (0, react_1.useContext)(translationsContext);