@zentrades-ui/theme 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# @zentrades-ui/theme
+
+React theme provider that converts Zen UI tokens into CSS custom properties.
+
+## Installation
+
+```bash
+pnpm add @zentrades-ui/theme @zentrades-ui/tokens
+```
+
+## Usage
+
+Wrap your application with `ThemeProvider`:
+
+```tsx
+import { ThemeProvider } from "@zentrades-ui/theme";
+import { defaultTokens } from "@zentrades-ui/tokens";
+
+function App() {
+  return (
+    <ThemeProvider mode="light" tokens={defaultTokens}>
+      <YourApp />
+    </ThemeProvider>
+  );
+}
+```
+
+## Theme Modes
+
+The provider supports `light` and `dark` modes:
+
+```tsx
+// Light mode (default)
+<ThemeProvider mode="light" tokens={defaultTokens}>
+
+// Dark mode
+<ThemeProvider mode="dark" tokens={defaultTokens}>
+```
+
+## Dynamic Theme Switching
+
+Use the `useTheme` hook to access and change the current mode:
+
+```tsx
+import { useTheme } from "@zentrades-ui/theme";
+
+function ThemeToggle() {
+  const { mode, setMode } = useTheme();
+
+  return (
+    <button onClick={() => setMode(mode === "light" ? "dark" : "light")}>
+      Current: {mode}
+    </button>
+  );
+}
+```
+
+## CSS Variables
+
+The provider generates CSS variables on the target element (defaults to `document.documentElement`). All variable names are normalized to lowercase with hyphens.
+
+### Color Variables
+
+```css
+/* Content colors */
+var(--zen-color-contentprimary)
+var(--zen-color-contentsecondary)
+var(--zen-color-contenttertiary)
+var(--zen-color-contentbrand)
+var(--zen-color-contentinverse)
+
+/* Background colors */
+var(--zen-color-backgroundprimary)
+var(--zen-color-backgroundsecondary)
+var(--zen-color-backgroundbrand)
+
+/* Border colors */
+var(--zen-color-borderprimary)
+var(--zen-color-bordersecondary)
+
+/* Surface levels */
+var(--zen-color-surfacel0)
+var(--zen-color-surfacel1)
+var(--zen-color-surfacel2)
+/* ... up to surfacel6 */
+```
+
+### Spacing Variables
+
+```css
+var(--zen-space-1)   /* 1px */
+var(--zen-space-2)   /* 2px */
+var(--zen-space-4)   /* 4px */
+var(--zen-space-6)   /* 6px */
+var(--zen-space-8)   /* 8px */
+/* ... and more */
+```
+
+### Typography Variables
+
+```css
+/* Font families */
+var(--zen-font-geist)
+var(--zen-font-mono)
+
+/* Font sizes */
+var(--zen-font-size-xs)
+var(--zen-font-size-s)
+var(--zen-font-size-m)
+var(--zen-font-size-l)
+/* ... up to 8xl */
+
+/* Font weights */
+var(--zen-font-weight-regular)
+var(--zen-font-weight-medium)
+var(--zen-font-weight-semibold)
+var(--zen-font-weight-bold)
+
+/* Line heights */
+var(--zen-line-height-xs)
+var(--zen-line-height-s)
+/* ... */
+```
+
+### Border Variables
+
+```css
+/* Border radius */
+var(--zen-radius-xs)
+var(--zen-radius-sm)
+var(--zen-radius-md)
+var(--zen-radius-lg)
+var(--zen-radius-xl)
+var(--zen-radius-pill)
+var(--zen-radius-circle)
+
+/* Border width */
+var(--zen-border-none)
+var(--zen-border-xs)
+var(--zen-border-s)
+var(--zen-border-m)
+var(--zen-border-l)
+```
+
+### Shadow Variables
+
+```css
+var(--zen-shadow-l0)
+var(--zen-shadow-l1)
+var(--zen-shadow-l2)
+/* ... up to l7 */
+```
+
+## Custom Target Element
+
+Apply theme variables to a specific element instead of the document root:
+
+```tsx
+const containerRef = useRef<HTMLDivElement>(null);
+
+<ThemeProvider mode="light" tokens={defaultTokens} target={containerRef.current}>
+  <div ref={containerRef}>
+    {/* Theme variables only available within this container */}
+  </div>
+</ThemeProvider>
+```
+
+## Example: Using Variables in Styles
+
+```tsx
+function MyComponent() {
+  return (
+    <div
+      style={{
+        background: "var(--zen-color-backgroundprimary)",
+        color: "var(--zen-color-contentprimary)",
+        padding: "var(--zen-space-4)",
+        borderRadius: "var(--zen-radius-md)",
+        fontFamily: "var(--zen-font-geist)",
+        fontSize: "var(--zen-font-size-m)",
+      }}
+    >
+      Styled with Zen UI tokens
+    </div>
+  );
+}
+```

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@zentrades-ui/theme",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Theme runtime for Zen UI.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@vanilla-extract/css": "^1.17.1",
+    "@zentrades-ui/tokens": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "typescript": "^5.9.3"
+  }
+}

package/src/ThemeProvider.tsx

@@ -0,0 +1,143 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+import { darkTheme, lightTheme, type ThemeMode } from "./theme.css";
+
+type AllowedThemeOptions = "light" | "dark" | "system";
+
+type ThemeContextValue = {
+  theme: AllowedThemeOptions;
+  effectiveTheme: ThemeMode;
+  setTheme: (mode: AllowedThemeOptions) => void;
+  toggleTheme: () => void;
+  themeClassName: string;
+};
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+const themeClassMap: Record<ThemeMode, string> = {
+  light: lightTheme,
+  dark: darkTheme,
+};
+
+export type ThemeProviderProps = {
+  children: ReactNode;
+  theme: AllowedThemeOptions;
+  effectiveTheme?: ThemeMode;
+  /**
+   * Handler invoked when `useTheme().setTheme` or `useTheme().toggleTheme` is called.
+   * Provide this to fully control the theme from the host application.
+   */
+  onThemeChange?: (mode: AllowedThemeOptions, specific?: ThemeMode) => void;
+  /**
+   * Optional element that should receive the theme class.
+   * Defaults to document.body when available.
+   */
+  target?: HTMLElement | null;
+};
+
+function getSystemTheme(): ThemeMode {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+}
+
+export function ThemeProvider({
+  children,
+  theme,
+  onThemeChange,
+  target,
+}: ThemeProviderProps) {
+  const previousClassRef = useRef<string | null>(null);
+
+  const effectiveTheme: ThemeMode =
+    theme === "system" ? getSystemTheme() : theme;
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const host = target ?? document.body;
+    if (!host) return;
+
+    const nextClass = themeClassMap[effectiveTheme];
+    const prev = previousClassRef.current;
+
+    if (prev && prev !== nextClass) {
+      host.classList.remove(prev);
+    }
+
+    host.classList.add(nextClass);
+    host.setAttribute("data-theme", effectiveTheme);
+    previousClassRef.current = nextClass;
+
+    return () => {
+      host.classList.remove(nextClass);
+      if (host.getAttribute("data-theme") === effectiveTheme) {
+        host.removeAttribute("data-theme");
+      }
+    };
+  }, [effectiveTheme, target]);
+
+  useEffect(() => {
+    if (theme !== "system") return;
+    if (typeof window === "undefined") return;
+
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const handler = () => {
+      onThemeChange?.("system", getSystemTheme());
+    };
+
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, [theme, onThemeChange]);
+
+  const setTheme = useCallback(
+    (mode: AllowedThemeOptions) => {
+      if (onThemeChange) {
+        onThemeChange(mode, effectiveTheme);
+        return;
+      }
+      console.warn(
+        "ThemeProvider: `setTheme` called but no `onThemeChange` handler was provided. The theme remains unchanged."
+      );
+    },
+    [onThemeChange, effectiveTheme]
+  );
+
+  const toggleTheme = useCallback(() => {
+    setTheme(theme === "light" ? "dark" : "light");
+  }, [setTheme, theme]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      effectiveTheme,
+      setTheme,
+      toggleTheme,
+      themeClassName: themeClassMap[effectiveTheme],
+    }),
+    [theme, effectiveTheme, setTheme, toggleTheme]
+  );
+
+  return (
+    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+  );
+}
+
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+}
+
+// Re-export types
+export type { ThemeMode, AllowedThemeOptions };

package/src/index.ts

@@ -0,0 +1,7 @@
+// ThemeProvider and hook
+export { ThemeProvider, useTheme } from "./ThemeProvider";
+export type { ThemeProviderProps, ThemeMode, AllowedThemeOptions } from "./ThemeProvider";
+
+// Vanilla Extract theme exports
+export { colorVars, lightTheme, darkTheme } from "./theme.css";
+export type { ColorVarName, Theme } from "./theme.css";

package/src/theme.css.ts

@@ -0,0 +1,44 @@
+import { createTheme, createThemeContract } from "@vanilla-extract/css";
+import { themedColorVars } from "@zentrades-ui/tokens";
+
+// Get all themed color keys
+const themedColorKeys = Object.keys(themedColorVars) as Array<
+  keyof typeof themedColorVars
+>;
+
+// Create the contract shape (all values null for contract definition)
+const themedContractShape = Object.fromEntries(
+  themedColorKeys.map((token) => [token, null])
+) as { [K in keyof typeof themedColorVars]: null };
+
+// Create the theme contract - this defines the CSS variable structure
+export const colorVars = createThemeContract({
+  ...themedContractShape,
+  transparent: null,
+});
+
+export type ThemeMode = "light" | "dark";
+export type ColorVarName = keyof typeof colorVars;
+
+type ThemedColorName = keyof typeof themedColorVars;
+type ThemedColorVariant = (typeof themedColorVars)[ThemedColorName];
+
+const themedEntries = themedColorKeys.map(
+  (token) =>
+    [token, themedColorVars[token]] as [ThemedColorName, ThemedColorVariant]
+);
+
+// Build theme values for a given mode
+const buildThemeValues = (mode: ThemeMode) =>
+  ({
+    ...Object.fromEntries(
+      themedEntries.map(([token, variants]) => [token, variants[mode]])
+    ),
+    transparent: "transparent",
+  }) as Record<ColorVarName, string>;
+
+// Create light and dark theme classes
+export const lightTheme = createTheme(colorVars, buildThemeValues("light"));
+export const darkTheme = createTheme(colorVars, buildThemeValues("dark"));
+
+export type Theme = Record<ColorVarName, string>;