npm - @cronus-ui/theme - Versions diffs - 0.6.0 - Mend

@cronus-ui/theme 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Cronus
+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 ADDED Viewed

@@ -0,0 +1,190 @@
+# @cronus-ui/theme
+The Cronus UI runtime theming engine — a React provider and hook that apply
+[`@cronus-ui/tokens`](../tokens) to your app and let you re-theme any subtree live.
+Theming happens entirely through CSS custom properties: switching theme, toggling
+light/dark, or overriding a token (radius, primary, border, …) updates the whole
+subtree instantly **without re-rendering the components below it**. This is what
+makes brand portals, per-tenant styling, and visual preview builders cheap.
+You need this package if you render `@cronus-ui/ui` components and want runtime theme
+control, mode switching, or token overrides. (It is also the only supported way to
+inject the `--cronus-*` variables when running on Tailwind v3.)
+## Install
+> Published on npm under the `@cronus-ui` scope.
+```sh
+# npm
+npm i @cronus-ui/theme @cronus-ui/tokens
+# pnpm
+pnpm add @cronus-ui/theme @cronus-ui/tokens
+# bun
+bun add @cronus-ui/theme @cronus-ui/tokens
+```
+### Prerequisites
+- **React 19** (also works with React 18.3+) — `react` and `react-dom` are peer
+  dependencies.
+- [`@cronus-ui/tokens`](../tokens) — the token data this provider applies (installed
+  alongside above; on Tailwind v4 also import `@cronus-ui/tokens/styles.css` once).
+## Usage
+Wrap your app at the framework root. Use `asRoot` so the theme/mode attributes
+are written to `<html>` and the whole document is themed.
+```tsx
+// app/layout.tsx (Next.js App Router) — or your root component
+import "@cronus-ui/tokens/styles.css";
+import { CronusUIProvider } from "@cronus-ui/theme";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <CronusUIProvider asRoot defaultThemeName="aurora" defaultModeName="dark">
+          {children}
+        </CronusUIProvider>
+      </body>
+    </html>
+  );
+}
+```
+### Avoiding a flash of the wrong theme
+When you use `asRoot` with a `storageKey`, the provider restores the saved
+theme/mode from `localStorage` in an effect that runs **after** first paint — so
+a returning visitor whose saved choice differs from the defaults briefly sees the
+default theme before it swaps (a "flash of the wrong theme", or FOUC).
+Render `<CronusThemeScript>` in your document `<head>` to apply the saved
+theme/mode **before** paint. It emits one tiny inline script that reads the same
+`storageKey` and sets the `data-cronus-theme` / `data-cronus-mode` attributes and
+the `dark` class on `<html>` exactly as the provider does.
+```tsx
+// app/layout.tsx (Next.js App Router)
+import { CronusThemeScript, CronusUIProvider } from "@cronus-ui/theme";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    // suppressHydrationWarning: the script mutates <html> before React hydrates.
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <CronusThemeScript
+          storageKey="cronus-ui-theme"
+          defaultThemeName="aurora"
+          defaultModeName="dark"
+        />
+      </head>
+      <body>
+        <CronusUIProvider asRoot storageKey="cronus-ui-theme">
+          {children}
+        </CronusUIProvider>
+      </body>
+    </html>
+  );
+}
+```
+Pass the **same** `storageKey` to both the script and the provider. Add
+`suppressHydrationWarning` to `<html>` because the script changes those
+attributes before hydration; without it React logs a hydration mismatch. For a
+strict CSP, pass a `nonce` to `<CronusThemeScript nonce={nonce} />`.
+### `useTheme`
+Read and control the active theme from anywhere inside the provider.
+```tsx
+"use client";
+import { useTheme } from "@cronus-ui/theme";
+export function ThemeControls() {
+  const { theme, mode, setTheme, setMode, toggleMode, setOverrides } = useTheme();
+  return (
+    <div>
+      <button onClick={toggleMode}>Mode: {mode}</button>
+      <button onClick={() => setTheme(theme === "aurora" ? "neutral" : "aurora")}>
+        Theme: {theme}
+      </button>
+      {/* Re-theme the whole subtree at runtime — no component re-render: */}
+      <button
+        onClick={() =>
+          setOverrides({
+            radius: "16px",
+            primary: "oklch(0.685 0.169 237.3)",
+            fontDisplay: "Inter, sans-serif",
+          })
+        }
+      >
+        Apply brand theme
+      </button>
+    </div>
+  );
+}
+```
+Calling `useTheme()` outside a `<CronusUIProvider>` throws.
+## API
+### `<CronusUIProvider>`
+| Prop               | Type             | Default    | Description                                                                 |
+| ------------------ | ---------------- | ---------- | --------------------------------------------------------------------------- |
+| `defaultThemeName` | `ThemeName`      | `"aurora"` | Initial theme (`"aurora"` \| `"neutral"` \| `"midnight"` \| `"sunset"` \| `"emerald"`). |
+| `defaultModeName`  | `Mode`           | `"dark"`   | Initial mode (`"light"` \| `"dark"`).                                       |
+| `overrides`        | `ThemeOverrides` | —          | Seed per-scope token overrides (initial value only; later use `setOverrides`). |
+| `asRoot`           | `boolean`        | `false`    | Write attributes to `<html>` (whole document) instead of a wrapper `<div>`. |
+| `storageKey`       | `string`         | —          | Persist the theme/mode choice to `localStorage` under this key.             |
+| `className`        | `string`         | —          | Extra classes for the wrapper `<div>` (ignored when `asRoot`).              |
+When `asRoot` is `false`, the provider renders a `<div>` that themes only its
+subtree — useful for previews and isolated brand sections.
+> `overrides` is reactive: change its **content** (e.g. from a controlled
+> parent) and the themed element updates. A re-render that passes a new object of
+> equal content does not loop or reset live overrides. `setOverrides` from
+> `useTheme` still drives uncontrolled changes.
+### `<CronusThemeScript>`
+Inline anti-FOUC head script (see [Avoiding a flash of the wrong
+theme](#avoiding-a-flash-of-the-wrong-theme)).
+| Prop               | Type        | Default    | Description                                                       |
+| ------------------ | ----------- | ---------- | ----------------------------------------------------------------- |
+| `storageKey`       | `string`    | —          | Required. The same key passed to `<CronusUIProvider storageKey>`.  |
+| `defaultThemeName` | `ThemeName` | `"aurora"` | Theme applied when storage is empty or unreadable.                |
+| `defaultModeName`  | `Mode`      | `"dark"`   | Mode applied when storage is empty or unreadable.                 |
+| `nonce`            | `string`    | —          | CSP nonce forwarded to the inline `<script>`.                     |
+### `useTheme(): ThemeContextValue`
+Returns `{ theme, mode, overrides, setTheme, setMode, toggleMode, setOverrides }`.
+`ThemeName`, `Mode`, and `ThemeOverrides` come from [`@cronus-ui/tokens`](../tokens).
+## How it works
+`overrides` are converted to a `{ "--cronus-*": value }` style object
+(via `@cronus-ui/tokens`) and set on the themed element; the `@cronus-ui/tokens` Tailwind
+bridge maps utilities like `bg-primary` and `rounded-lg` onto those variables.
+Because everything resolves through CSS variables, overriding a token restyles the
+subtree with no React re-render of the components it contains.
+## Related packages
+- [`@cronus-ui/tokens`](../tokens) — the token source this provider applies.
+- [`@cronus-ui/ui`](../ui) — the components that render against the applied tokens.
+- See the [docs site](../../apps/www) for the live theme builder.
+## License
+MIT

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+export type { CronusUIProviderProps } from "./provider.js";
+export { CronusUIProvider } from "./provider.js";
+export type { CronusThemeScriptProps } from "./theme-script.js";
+export { CronusThemeScript } from "./theme-script.js";
+export type { ThemeContextValue } from "./use-theme.js";
+export { useOptionalThemeMode, useTheme } from "./use-theme.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js ADDED Viewed

@@ -0,0 +1,4 @@
+export { CronusUIProvider } from "./provider.js";
+export { CronusThemeScript } from "./theme-script.js";
+export { useOptionalThemeMode, useTheme } from "./use-theme.js";
+//# sourceMappingURL=index.js.map

package/dist/provider.d.ts ADDED Viewed

@@ -0,0 +1,27 @@
+import { type Mode, type ThemeName, type ThemeOverrides } from "@cronus-ui/tokens";
+import { type ReactNode } from "react";
+export interface CronusUIProviderProps {
+    children: ReactNode;
+    /** Initial theme. @default "aurora" */
+    defaultThemeName?: ThemeName;
+    /** Initial mode. @default "dark" */
+    defaultModeName?: Mode;
+    /** Per-scope token overrides (radius, primary, border, ...). */
+    overrides?: ThemeOverrides;
+    /**
+     * When true, attributes are written to <html> so the whole document is
+     * themed. When false (default), they are written to a wrapper <div> so a
+     * subtree can be themed independently (useful for the ThemeBuilder preview).
+     */
+    asRoot?: boolean;
+    /** Persist theme/mode choice to localStorage under this key. */
+    storageKey?: string;
+    className?: string;
+}
+/**
+ * Themes its subtree purely via CSS custom properties — no per-component
+ * re-render, no context churn beyond the controls themselves. Overriding
+ * `radius`, `primary`, `border`, etc. updates the entire subtree instantly.
+ */
+export declare function CronusUIProvider({ children, defaultThemeName, defaultModeName, overrides, asRoot, storageKey, className, }: CronusUIProviderProps): import("react").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.js ADDED Viewed

@@ -0,0 +1,110 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defaultMode, defaultTheme, tokensToCssVars, } from "@cronus-ui/tokens";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { ThemeContext } from "./use-theme.js";
+function applyRootAttributes(theme, mode) {
+    if (typeof document === "undefined")
+        return;
+    const el = document.documentElement;
+    el.dataset.cronusTheme = theme;
+    el.dataset.cronusMode = mode;
+    el.classList.toggle("dark", mode === "dark");
+}
+/**
+ * Themes its subtree purely via CSS custom properties — no per-component
+ * re-render, no context churn beyond the controls themselves. Overriding
+ * `radius`, `primary`, `border`, etc. updates the entire subtree instantly.
+ */
+export function CronusUIProvider({ children, defaultThemeName = defaultTheme, defaultModeName = defaultMode, overrides, asRoot = false, storageKey, className, }) {
+    const [theme, setThemeState] = useState(defaultThemeName);
+    const [mode, setModeState] = useState(defaultModeName);
+    // `overrides` seeds the initial value; the effect below keeps it in sync when
+    // the prop's CONTENT changes (controlled usage), while setScopedOverrides
+    // still drives uncontrolled changes via setOverrides() (e.g. the
+    // ThemeBuilder). Syncing on a stable serialization — not the object identity —
+    // means a re-render with an equal-content new reference neither loops nor
+    // resets the live overrides.
+    const [scopedOverrides, setScopedOverrides] = useState(() => overrides ?? {});
+    // Make the controlled `overrides` prop reactive. Keying on the JSON instead of
+    // the object reference avoids the infinite loop an inline `overrides={{...}}`
+    // (new reference every render) would otherwise cause.
+    const overridesKey = JSON.stringify(overrides ?? {});
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `overridesKey` is the stable serialization of `overrides`; depending on the object reference is exactly what we must avoid.
+    useEffect(() => {
+        setScopedOverrides(overrides ?? {});
+    }, [overridesKey]);
+    // Hydrate from storage once on mount.
+    useEffect(() => {
+        if (!storageKey || typeof window === "undefined")
+            return;
+        try {
+            const raw = window.localStorage.getItem(storageKey);
+            if (!raw)
+                return;
+            const saved = JSON.parse(raw);
+            if (saved.theme)
+                setThemeState(saved.theme);
+            if (saved.mode)
+                setModeState(saved.mode);
+        }
+        catch {
+            // ignore malformed storage
+        }
+    }, [storageKey]);
+    const persist = useCallback((next) => {
+        if (!storageKey || typeof window === "undefined")
+            return;
+        try {
+            window.localStorage.setItem(storageKey, JSON.stringify(next));
+        }
+        catch {
+            // ignore quota / privacy errors
+        }
+    }, [storageKey]);
+    const setTheme = useCallback((next) => {
+        setThemeState(next);
+        persist({ theme: next, mode });
+    }, [mode, persist]);
+    const setMode = useCallback((next) => {
+        setModeState(next);
+        persist({ theme, mode: next });
+    }, [theme, persist]);
+    const toggleMode = useCallback(() => {
+        setModeState((prev) => {
+            const next = prev === "dark" ? "light" : "dark";
+            persist({ theme, mode: next });
+            return next;
+        });
+    }, [theme, persist]);
+    // Sync <html> attributes + overrides when used as the document root.
+    useEffect(() => {
+        if (!asRoot)
+            return;
+        applyRootAttributes(theme, mode);
+        if (typeof document === "undefined")
+            return;
+        const el = document.documentElement;
+        const vars = tokensToCssVars(scopedOverrides);
+        for (const [prop, val] of Object.entries(vars))
+            el.style.setProperty(prop, val);
+        return () => {
+            for (const prop of Object.keys(vars))
+                el.style.removeProperty(prop);
+        };
+    }, [asRoot, theme, mode, scopedOverrides]);
+    const value = useMemo(() => ({
+        theme,
+        mode,
+        overrides: scopedOverrides,
+        setTheme,
+        setMode,
+        toggleMode,
+        setOverrides: setScopedOverrides,
+    }), [theme, mode, scopedOverrides, setTheme, setMode, toggleMode]);
+    const style = useMemo(() => tokensToCssVars(scopedOverrides), [scopedOverrides]);
+    return (_jsx(ThemeContext.Provider, { value: value, children: asRoot ? (children) : (_jsx("div", { "data-cronus-theme": theme, "data-cronus-mode": mode, className: [mode === "dark" ? "dark" : null, "text-fg", className]
+                .filter(Boolean)
+                .join(" "), style: style, children: children })) }));
+}
+//# sourceMappingURL=provider.js.map

package/dist/theme-script.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import { type Mode, type ThemeName } from "@cronus-ui/tokens";
+export interface CronusThemeScriptProps {
+    /**
+     * The same `storageKey` passed to `<CronusUIProvider>`. The script reads the
+     * persisted `{ theme, mode }` from `localStorage[storageKey]`.
+     */
+    storageKey: string;
+    /** Theme to apply when storage is empty/unreadable. @default "aurora" */
+    defaultThemeName?: ThemeName;
+    /** Mode to apply when storage is empty/unreadable. @default "dark" */
+    defaultModeName?: Mode;
+    /** CSP nonce forwarded to the inline `<script nonce>`. */
+    nonce?: string;
+}
+/**
+ * Inline head script that applies the persisted theme/mode to `<html>` BEFORE
+ * first paint, eliminating the flash of the default theme that otherwise occurs
+ * while `<CronusUIProvider asRoot storageKey>` hydrates from `localStorage` in a
+ * post-paint effect.
+ *
+ * Place it inside `<head>` (above the app) and add `suppressHydrationWarning` to
+ * the `<html>` element, since this mutates `<html>` before React hydrates.
+ *
+ * ```tsx
+ * <html lang="en" suppressHydrationWarning>
+ *   <head>
+ *     <CronusThemeScript storageKey="theme" defaultThemeName="aurora" defaultModeName="dark" />
+ *   </head>
+ *   ...
+ * </html>
+ * ```
+ */
+export declare function CronusThemeScript({ storageKey, defaultThemeName, defaultModeName, nonce, }: CronusThemeScriptProps): import("react").JSX.Element;
+//# sourceMappingURL=theme-script.d.ts.map

package/dist/theme-script.js ADDED Viewed

@@ -0,0 +1,41 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defaultMode, defaultTheme } from "@cronus-ui/tokens";
+/**
+ * Builds the dependency-free IIFE source. The body mirrors the provider's
+ * `applyRootAttributes` byte-for-byte (dataset.cronusTheme / dataset.cronusMode /
+ * classList.toggle("dark", …)) so the pre-paint state matches what React would
+ * compute on hydration. All interpolated values are `JSON.stringify`-encoded so
+ * a storage key or default containing quotes can't break out of the script.
+ */
+function buildScript(storageKey, defaultThemeName, defaultModeName) {
+    // Defaults are applied first and the storage read overrides them, so a quota /
+    // malformed-JSON throw still leaves <html> on the SSR default the provider
+    // reconciles to on hydration (rather than a bare, attribute-less root).
+    return `(function(){var d=document.documentElement,t=${JSON.stringify(defaultThemeName)},m=${JSON.stringify(defaultModeName)};try{var s=localStorage.getItem(${JSON.stringify(storageKey)});if(s){var p=JSON.parse(s);if(p&&p.theme)t=p.theme;if(p&&p.mode)m=p.mode;}}catch(e){}d.dataset.cronusTheme=t;d.dataset.cronusMode=m;d.classList.toggle("dark",m==="dark");})();`;
+}
+/**
+ * Inline head script that applies the persisted theme/mode to `<html>` BEFORE
+ * first paint, eliminating the flash of the default theme that otherwise occurs
+ * while `<CronusUIProvider asRoot storageKey>` hydrates from `localStorage` in a
+ * post-paint effect.
+ *
+ * Place it inside `<head>` (above the app) and add `suppressHydrationWarning` to
+ * the `<html>` element, since this mutates `<html>` before React hydrates.
+ *
+ * ```tsx
+ * <html lang="en" suppressHydrationWarning>
+ *   <head>
+ *     <CronusThemeScript storageKey="theme" defaultThemeName="aurora" defaultModeName="dark" />
+ *   </head>
+ *   ...
+ * </html>
+ * ```
+ */
+export function CronusThemeScript({ storageKey, defaultThemeName = defaultTheme, defaultModeName = defaultMode, nonce, }) {
+    return (_jsx("script", {
+        // biome-ignore lint/security/noDangerouslySetInnerHtml: required to inline a pre-paint anti-FOUC script; all interpolated values are JSON.stringify-encoded.
+        dangerouslySetInnerHTML: {
+            __html: buildScript(storageKey, defaultThemeName, defaultModeName),
+        }, nonce: nonce }));
+}
+//# sourceMappingURL=theme-script.js.map

package/dist/use-theme.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import type { Mode, ThemeName, ThemeOverrides } from "@cronus-ui/tokens";
+export interface ThemeContextValue {
+    theme: ThemeName;
+    mode: Mode;
+    overrides: ThemeOverrides;
+    setTheme: (theme: ThemeName) => void;
+    setMode: (mode: Mode) => void;
+    toggleMode: () => void;
+    setOverrides: (overrides: ThemeOverrides) => void;
+}
+export declare const ThemeContext: import("react").Context<ThemeContextValue | null>;
+export declare function useTheme(): ThemeContextValue;
+/** Mode from the nearest provider, or null outside one. */
+export declare function useOptionalThemeMode(): Mode | null;
+//# sourceMappingURL=use-theme.d.ts.map

package/dist/use-theme.js ADDED Viewed

@@ -0,0 +1,15 @@
+"use client";
+import { createContext, useContext } from "react";
+export const ThemeContext = createContext(null);
+export function useTheme() {
+    const ctx = useContext(ThemeContext);
+    if (!ctx) {
+        throw new Error("useTheme must be used within a <CronusUIProvider>");
+    }
+    return ctx;
+}
+/** Mode from the nearest provider, or null outside one. */
+export function useOptionalThemeMode() {
+    return useContext(ThemeContext)?.mode ?? null;
+}
+//# sourceMappingURL=use-theme.js.map

package/package.json ADDED Viewed

@@ -0,0 +1,63 @@
+{
+  "name": "@cronus-ui/theme",
+  "version": "0.6.0",
+  "description": "Cronus runtime theming engine — CronusUIProvider + useTheme (CSS-var only, no re-render).",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "Cronus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pedrogbraz/cronus-ui.git",
+    "directory": "packages/theme"
+  },
+  "homepage": "https://aicronus.com",
+  "bugs": {
+    "url": "https://github.com/pedrogbraz/cronus-ui/issues"
+  },
+  "keywords": [
+    "cronus",
+    "design-system",
+    "react",
+    "tailwind",
+    "ui",
+    "components"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@cronus-ui/tokens": "0.6.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}