@mfeflow/theme 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @mfeflow/theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Design tokens as CSS variables for micro-frontends. The shell picks the theme once and writes `--mf-<token>` variables, `data-theme` and `color-scheme` on `<html>`; every remote inherits them. The choice is persisted, and `noFlashScript` applies it before first paint.
+
+## Install
+
+```sh
+pnpm add @mfeflow/theme @mfeflow/storage
+```
+
+`react` (19) is an optional peer dependency, needed only for `@mfeflow/theme/react`.
+
+## Usage
+
+In the shell:
+
+```tsx
+import { defineTheme, noFlashScript } from '@mfeflow/theme';
+import { ThemeProvider, useTheme } from '@mfeflow/theme/react';
+
+export const themes = [
+  defineTheme('light', { 'color-bg': '#ffffff', 'color-fg': '#111111' }),
+  defineTheme('dark', { 'color-bg': '#111111', 'color-fg': '#f5f5f5' }, { colorScheme: 'dark' }),
+];
+
+// <ThemeProvider themes={themes} defaultTheme="light"> ... </ThemeProvider>
+// Put noFlashScript(themes, { defaultTheme: 'light' }) in an inline <script> in the <head>.
+```
+
+In a remote, read the tokens:
+
+```css
+.card {
+  background: var(--mf-color-bg);
+}
+```
+
+Or in TypeScript, `cssVar('color-bg', '#fff')` returns `var(--mf-color-bg, #fff)`. `useTheme()` returns `{ theme, themes, setTheme }`.
+
+## Module Federation sharing
+
+Bucket: **singleton**. This package keeps page-wide state, so the shell and every remote must use one copy. `@mfeflow/rsbuild` shares it as a Module Federation singleton by default (`createShellConfig` and `createRemoteConfig`); if you configure sharing by hand, mark it `singleton: true`.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/** Token name → CSS value, e.g. `{ 'color-primary': '#2563eb', 'radius-md': '8px' }`. */
+export type ThemeTokens = Readonly<Record<string, string>>;
+export interface Theme {
+    readonly name: string;
+    readonly colorScheme: 'light' | 'dark';
+    readonly tokens: ThemeTokens;
+}
+/** Every token becomes `--mf-<token>` on `:root`. */
+export declare const CSS_VAR_PREFIX = "--mf-";
+/** Storage key (under the `shell` micro-frontend) for the chosen theme. */
+export declare const THEME_STORAGE_KEY = "theme";
+export declare const THEME_STORAGE_MFE = "shell";
+export declare function cssVarName(token: string): string;
+/** `var(--mf-<token>)`, for remotes that style with tokens. */
+export declare function cssVar(token: string, fallback?: string): string;
+export declare function defineTheme(name: string, tokens: ThemeTokens, options?: {
+    colorScheme?: 'light' | 'dark';
+}): Theme;
+/** CSS custom properties for a theme, keyed by variable name. */
+export declare function themeToCssVars(theme: Theme): Record<string, string>;
+/**
+ * Writes a theme onto `root` (default `<html>`): CSS variables, `data-theme`
+ * and `color-scheme`. Variables from the previous theme that the new one does
+ * not define are removed. Only the shell calls this; remotes just read tokens.
+ */
+export declare function applyTheme(theme: Theme, root?: HTMLElement): void;
+/** Picks the theme to show: stored choice, then the system dark preference, then the default. */
+export declare function resolveTheme(themes: readonly Theme[], stored: string | undefined, defaultTheme: string, prefersDark?: boolean): Theme;
+export interface NoFlashOptions {
+    defaultTheme: string;
+    /** Use the OS dark-mode preference when nothing is stored. Default true. */
+    followSystem?: boolean;
+}
+/**
+ * Source for an inline `<script>` in the shell's `<head>`. It applies the
+ * stored (or system) theme before first paint, so reloads never flash the
+ * default theme. It never throws.
+ */
+export declare function noFlashScript(themes: readonly Theme[], options: NoFlashOptions): string;

package/dist/index.js

@@ -0,0 +1,72 @@
+const CSS_VAR_PREFIX = '--mf-';
+const THEME_STORAGE_KEY = 'theme';
+const THEME_STORAGE_MFE = 'shell';
+const TOKEN = /^[a-z][a-z0-9-]*$/;
+const THEME_NAME = /^[a-z][a-z0-9-]*$/;
+function cssVarName(token) {
+    if (!TOKEN.test(token)) throw new Error(`Invalid token name "${token}": use lowercase letters, digits and dashes`);
+    return CSS_VAR_PREFIX + token;
+}
+function cssVar(token, fallback) {
+    return void 0 === fallback ? `var(${cssVarName(token)})` : `var(${cssVarName(token)}, ${fallback})`;
+}
+function defineTheme(name, tokens, options = {}) {
+    if (!THEME_NAME.test(name)) throw new Error(`Invalid theme name "${name}"`);
+    for (const token of Object.keys(tokens))cssVarName(token);
+    return Object.freeze({
+        name,
+        colorScheme: options.colorScheme ?? 'light',
+        tokens: Object.freeze({
+            ...tokens
+        })
+    });
+}
+function themeToCssVars(theme) {
+    const out = {};
+    for (const [token, value] of Object.entries(theme.tokens))out[cssVarName(token)] = value;
+    return out;
+}
+const applied = new WeakMap();
+function applyTheme(theme, root = document.documentElement) {
+    const vars = themeToCssVars(theme);
+    const previous = applied.get(root) ?? new Set();
+    for (const name of previous)if (!(name in vars)) root.style.removeProperty(name);
+    for (const [name, value] of Object.entries(vars))root.style.setProperty(name, value);
+    applied.set(root, new Set(Object.keys(vars)));
+    root.dataset.theme = theme.name;
+    root.style.colorScheme = theme.colorScheme;
+}
+function resolveTheme(themes, stored, defaultTheme, prefersDark = false) {
+    const byName = new Map(themes.map((t)=>[
+            t.name,
+            t
+        ]));
+    const fallback = byName.get(defaultTheme);
+    if (!fallback) throw new Error(`Default theme "${defaultTheme}" is not in the theme list`);
+    if (void 0 !== stored) {
+        const hit = byName.get(stored);
+        if (hit) return hit;
+    }
+    if (prefersDark) {
+        const dark = themes.find((t)=>'dark' === t.colorScheme);
+        if (dark) return dark;
+    }
+    return fallback;
+}
+function noFlashScript(themes, options) {
+    resolveTheme(themes, void 0, options.defaultTheme);
+    const data = JSON.stringify({
+        k: `${THEME_STORAGE_MFE}:${THEME_STORAGE_KEY}`,
+        d: options.defaultTheme,
+        s: options.followSystem ?? true,
+        t: Object.fromEntries(themes.map((t)=>[
+                t.name,
+                {
+                    c: t.colorScheme,
+                    v: themeToCssVars(t)
+                }
+            ]))
+    }).replace(/</g, '\\u003c');
+    return `(function(){try{var o=${data};var n;try{n=JSON.parse(localStorage.getItem(o.k)||'null')}catch(e){}if(!o.t[n]){n=o.d;if(o.s&&window.matchMedia&&window.matchMedia('(prefers-color-scheme: dark)').matches){for(var x in o.t){if(o.t[x].c==='dark'){n=x;break}}}}var t=o.t[n],r=document.documentElement;for(var v in t.v){r.style.setProperty(v,t.v[v])}r.setAttribute('data-theme',n);r.style.colorScheme=t.c}catch(e){}})();`;
+}
+export { CSS_VAR_PREFIX, THEME_STORAGE_KEY, THEME_STORAGE_MFE, applyTheme, cssVar, cssVarName, defineTheme, noFlashScript, resolveTheme, themeToCssVars };

package/dist/react.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from 'react';
+import { type MfeStorage } from '@mfeflow/storage';
+import { type Theme } from './index.js';
+export interface ThemeContextValue {
+    theme: Theme;
+    themes: readonly string[];
+    setTheme: (name: string) => void;
+}
+export interface ThemeProviderProps {
+    themes: readonly Theme[];
+    defaultTheme: string;
+    /** Use the OS dark-mode preference when nothing is stored. Default true. */
+    followSystem?: boolean;
+    /** Defaults to the shell's storage. */
+    storage?: MfeStorage;
+    /** Where CSS variables are written. Defaults to `<html>`. */
+    root?: HTMLElement;
+    children?: ReactNode;
+}
+/** Mount once, in the shell. Remotes call `useTheme()` or just use `cssVar()` tokens. */
+export declare function ThemeProvider({ themes, defaultTheme, followSystem, storage, root, children, }: ThemeProviderProps): import("react").JSX.Element;
+/** The active theme and a setter. Works in the shell and in any remote rendered inside it. */
+export declare function useTheme(): ThemeContextValue;

package/dist/react.js

@@ -0,0 +1,47 @@
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useLayoutEffect, useMemo } from "react";
+import { createStorage } from "@mfeflow/storage";
+import { useStoredState } from "@mfeflow/storage/react";
+import { THEME_STORAGE_KEY, THEME_STORAGE_MFE, applyTheme, resolveTheme } from "./index.js";
+const ThemeContext = /*#__PURE__*/ createContext(null);
+function isThemeName(value) {
+    return null === value || 'string' == typeof value;
+}
+function prefersDark() {
+    return "u" > typeof window && 'function' == typeof window.matchMedia ? window.matchMedia('(prefers-color-scheme: dark)').matches : false;
+}
+function ThemeProvider({ themes, defaultTheme, followSystem = true, storage, root, children }) {
+    const store = useMemo(()=>storage ?? createStorage(THEME_STORAGE_MFE), [
+        storage
+    ]);
+    const [stored, setStored] = useStoredState(store, THEME_STORAGE_KEY, null, isThemeName);
+    const theme = resolveTheme(themes, stored ?? void 0, defaultTheme, followSystem && null === stored && prefersDark());
+    useLayoutEffect(()=>{
+        applyTheme(theme, root);
+    }, [
+        theme,
+        root
+    ]);
+    const value = useMemo(()=>({
+            theme,
+            themes: themes.map((t)=>t.name),
+            setTheme: (name)=>{
+                if (!themes.some((t)=>t.name === name)) throw new Error(`Unknown theme "${name}"`);
+                setStored(name);
+            }
+        }), [
+        theme,
+        themes,
+        setStored
+    ]);
+    return /*#__PURE__*/ jsx(ThemeContext.Provider, {
+        value: value,
+        children: children
+    });
+}
+function useTheme() {
+    const value = useContext(ThemeContext);
+    if (!value) throw new Error('useTheme must be used inside <ThemeProvider> (mounted by the shell)');
+    return value;
+}
+export { ThemeProvider, useTheme };

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@mfeflow/theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Design tokens as CSS variables for micro-frontends: the shell sets the theme once, every remote inherits it. ThemeProvider, useTheme, persisted choice, no-flash script.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "theme",
+    "design-tokens",
+    "css-variables",
+    "dark-mode",
+    "react",
+    "rsbuild"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/theme"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mfeflow/storage": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "singleton"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }