npm - @wrksz/themes - Versions diffs - 0.1.0 → 0.2.1 - Mend

@wrksz/themes 0.1.0 → 0.2.1

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 (5) hide show

package/README.md CHANGED Viewed

@@ -1 +1,193 @@
-# themes
+<img src=".github/images/banner.png" alt="@wrksz/themes" width="100%" />
+# @wrksz/themes
+[![npm version](https://img.shields.io/npm/v/@wrksz/themes)](https://www.npmjs.com/package/@wrksz/themes)
+Modern theme management for Next.js 16+ and React 19+. Drop-in replacement for `next-themes` - fixes every known bug and adds missing features.
+```bash
+bun add @wrksz/themes
+# or
+npm install @wrksz/themes
+```
+## Setup
+Add the provider to your root layout. Add `suppressHydrationWarning` to `<html>` to prevent hydration warnings caused by the inline theme script running before React hydrates.
+```tsx
+// app/layout.tsx
+import { ThemeProvider } from "@wrksz/themes";
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+## Usage
+```tsx
+"use client";
+import { useTheme } from "@wrksz/themes";
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  return (
+    <button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+      Toggle theme
+    </button>
+  );
+}
+```
+## API
+### `ThemeProvider`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `themes` | `string[]` | `["light", "dark"]` | Available themes |
+| `defaultTheme` | `string` | `"system"` | Theme used when no preference is stored |
+| `forcedTheme` | `string` | - | Force a specific theme, ignoring user preference |
+| `enableSystem` | `boolean` | `true` | Detect system preference via `prefers-color-scheme` |
+| `enableColorScheme` | `boolean` | `true` | Set native `color-scheme` CSS property |
+| `attribute` | `string \| string[]` | `"class"` | HTML attribute(s) to set on target element (`"class"`, `"data-theme"`, etc.) |
+| `value` | `Record<string, string>` | - | Map theme names to attribute values |
+| `target` | `string` | `"html"` | Element to apply theme to (`"html"`, `"body"`, or a CSS selector) |
+| `storageKey` | `string` | `"theme"` | Key used for storage |
+| `storage` | `"localStorage" \| "sessionStorage" \| "none"` | `"localStorage"` | Where to persist the theme |
+| `disableTransitionOnChange` | `boolean` | `false` | Disable CSS transitions when switching themes |
+| `themeColor` | `string \| Record<string, string>` | - | Update `<meta name="theme-color">` on theme change |
+| `nonce` | `string` | - | CSP nonce for the inline script |
+| `onThemeChange` | `(theme: string) => void` | - | Called whenever the resolved theme changes |
+### `useTheme`
+```tsx
+const {
+  theme,         // Current theme - may be "system"
+  resolvedTheme, // Actual theme - never "system"
+  systemTheme,   // System preference: "light" | "dark" | undefined
+  forcedTheme,   // Forced theme if set
+  themes,        // Available themes
+  setTheme,      // Set theme
+} = useTheme();
+```
+Supports generics for full type safety:
+```tsx
+type AppTheme = "light" | "dark" | "high-contrast";
+const { theme, setTheme } = useTheme<AppTheme>();
+// theme: AppTheme | "system" | undefined
+// setTheme: (theme: AppTheme | "system") => void
+```
+## Examples
+### Custom themes with Tailwind
+```tsx
+<ThemeProvider
+  themes={["light", "dark", "high-contrast"]}
+  attribute="class"
+>
+  {children}
+</ThemeProvider>
+```
+### Data attribute instead of class
+```tsx
+<ThemeProvider attribute="data-theme">
+  {children}
+</ThemeProvider>
+```
+```css
+[data-theme="dark"] { --bg: #000; }
+[data-theme="light"] { --bg: #fff; }
+```
+### Custom attribute values
+```tsx
+<ThemeProvider
+  themes={["light", "dark"]}
+  attribute="data-mode"
+  value={{ light: "light-mode", dark: "dark-mode" }}
+>
+  {children}
+</ThemeProvider>
+```
+### Meta theme-color (Safari / PWA)
+```tsx
+<ThemeProvider
+  themeColor={{ light: "#ffffff", dark: "#0a0a0a" }}
+>
+  {children}
+</ThemeProvider>
+```
+Works with CSS variables too:
+```tsx
+<ThemeProvider themeColor="var(--color-background)">
+  {children}
+</ThemeProvider>
+```
+### Disable storage
+```tsx
+// No persistence - always uses defaultTheme or system preference
+<ThemeProvider storage="none" defaultTheme="dark">
+  {children}
+</ThemeProvider>
+```
+### Forced theme per page
+```tsx
+// app/dashboard/layout.tsx
+<ThemeProvider forcedTheme="dark">
+  {children}
+</ThemeProvider>
+```
+### Class on body instead of html
+```tsx
+<ThemeProvider target="body">
+  {children}
+</ThemeProvider>
+```
+## Why not `next-themes`?
+| Issue | next-themes | @wrksz/themes |
+|-------|-------------|---------------|
+| React 19 script warning | Yes | Fixed (RSC split) |
+| `__name` minification bug | Yes | Fixed |
+| React 19 Activity/cacheComponents stale theme | Yes | Fixed (`useSyncExternalStore`) |
+| `sessionStorage` support | No | Yes |
+| Disable storage | No | Yes (`storage: "none"`) |
+| `meta theme-color` support | No | Yes (`themeColor` prop) |
+| Generic types | No | Yes (`useTheme<AppTheme>()`) |
+| Zero runtime dependencies | Yes | Yes |
+## License
+MIT

package/dist/index.d.ts CHANGED Viewed

@@ -1,2 +1,56 @@
-declare function Button(props: React.ComponentProps<"button">): React.ReactNode;
-export { Button };
+import { ReactNode } from "react";
+type DefaultTheme = "light" | "dark" | "system";
+type Attribute = "class" | `data-${string}`;
+type ValueObject = Record<string, string>;
+type StorageType = "localStorage" | "sessionStorage" | "none";
+/** Per-theme colors for meta theme-color, or a single string for all themes */
+type ThemeColor = string | Partial<Record<string, string>>;
+type ThemeProviderProps<Themes extends string = DefaultTheme> = {
+	children: ReactNode;
+	/** All available themes */
+	themes?: Themes[];
+	/** Forced theme, overrides everything */
+	forcedTheme?: Themes;
+	/** Enable system preference via prefers-color-scheme */
+	enableSystem?: boolean;
+	/** Default theme when no preference stored */
+	defaultTheme?: Themes | "system";
+	/** HTML attribute(s) to set on target element */
+	attribute?: Attribute | Attribute[];
+	/** Map theme name to attribute value */
+	value?: ValueObject;
+	/** Target element to apply theme to, defaults to <html> */
+	target?: "html" | "body" | string;
+	/** Disable CSS transitions on theme change */
+	disableTransitionOnChange?: boolean;
+	/** Where to persist theme */
+	storage?: StorageType;
+	/** Storage key */
+	storageKey?: string;
+	/** Set native color-scheme CSS property */
+	enableColorScheme?: boolean;
+	/** Nonce for CSP */
+	nonce?: string;
+	/** Called when theme changes */
+	onThemeChange?: (theme: Themes) => void;
+	/** Colors for meta theme-color tag, per theme or a single value */
+	themeColor?: ThemeColor;
+};
+type ThemeContextValue<Themes extends string = DefaultTheme> = {
+	/** Current theme (may be "system") */
+	theme: Themes | "system" | undefined;
+	/** Resolved theme - never "system" */
+	resolvedTheme: Themes | undefined;
+	/** System preference */
+	systemTheme: "light" | "dark" | undefined;
+	/** Forced theme if set */
+	forcedTheme: Themes | undefined;
+	/** All available themes */
+	themes: Themes[];
+	/** Set theme */
+	setTheme: (theme: Themes | "system" | ((current: Themes | "system" | undefined) => Themes | "system")) => void;
+};
+declare function useTheme<Themes extends string = DefaultTheme>(): ThemeContextValue<Themes>;
+import { ReactElement } from "react";
+declare function ThemeProvider<Themes extends string = DefaultTheme>({ children, themes, forcedTheme, enableSystem, defaultTheme, attribute, value: valueMap, target, disableTransitionOnChange, storage, storageKey, enableColorScheme, nonce, onThemeChange, themeColor }: ThemeProviderProps<Themes>): ReactElement;
+export { useTheme, ValueObject, ThemeProviderProps, ThemeProvider, ThemeContextValue, ThemeColor, StorageType, DefaultTheme, Attribute };

package/dist/index.js CHANGED Viewed

@@ -1,12 +1,343 @@
-// src/components/button.tsx
+"use client";
+// src/context.ts
+import { createContext, useContext } from "react";
+var ThemeContext = createContext(undefined);
+function useTheme() {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return ctx;
+}
+// src/client-provider.tsx
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+// src/store.ts
+var state = { theme: undefined, systemTheme: undefined };
+var listeners = new Set;
+function emit() {
+  for (const listener of listeners)
+    listener();
+}
+var SERVER_SNAPSHOT = { theme: undefined, systemTheme: undefined };
+var themeStore = {
+  subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+  getSnapshot() {
+    return state;
+  },
+  getServerSnapshot() {
+    return SERVER_SNAPSHOT;
+  },
+  setTheme(theme) {
+    if (state.theme === theme)
+      return;
+    state = { ...state, theme };
+    emit();
+  },
+  setSystemTheme(systemTheme) {
+    if (state.systemTheme === systemTheme)
+      return;
+    state = { ...state, systemTheme };
+    emit();
+  }
+};
+// src/client-provider.tsx
 import { jsxDEV } from "react/jsx-dev-runtime";
-function Button(props) {
-  return /* @__PURE__ */ jsxDEV("button", {
-    type: "button",
-    "data-slot": "button",
-    ...props
+var DEFAULT_THEMES = ["light", "dark"];
+function resolveThemeColor(themeColor, resolved) {
+  if (typeof themeColor === "string")
+    return themeColor;
+  return themeColor[resolved];
+}
+function updateMetaThemeColor(color) {
+  if (!color)
+    return;
+  let meta = document.querySelector('meta[name="theme-color"]');
+  if (!meta) {
+    meta = document.createElement("meta");
+    meta.name = "theme-color";
+    document.head.appendChild(meta);
+  }
+  meta.content = color;
+}
+function ClientThemeProvider({
+  children,
+  themes = DEFAULT_THEMES,
+  forcedTheme,
+  enableSystem = true,
+  defaultTheme,
+  attribute = "class",
+  value: valueMap,
+  target = "html",
+  disableTransitionOnChange = false,
+  storage = "localStorage",
+  storageKey = "theme",
+  enableColorScheme = true,
+  themeColor,
+  onThemeChange
+}) {
+  const resolvedDefault = defaultTheme ?? (enableSystem ? "system" : "light");
+  const { theme, systemTheme } = useSyncExternalStore(themeStore.subscribe, themeStore.getSnapshot, themeStore.getServerSnapshot);
+  const resolvedTheme = forcedTheme ?? (theme === "system" || theme === undefined ? systemTheme : theme);
+  const onThemeChangeRef = useRef(onThemeChange);
+  useEffect(() => {
+    onThemeChangeRef.current = onThemeChange;
+  });
+  const getTargetEl = useCallback(() => {
+    if (target === "html")
+      return document.documentElement;
+    if (target === "body")
+      return document.body;
+    return document.querySelector(target);
+  }, [target]);
+  const applyToDom = useCallback((resolved) => {
+    const el = getTargetEl();
+    if (!el)
+      return;
+    const attrValue = valueMap?.[resolved] ?? resolved;
+    const attrs = Array.isArray(attribute) ? attribute : [attribute];
+    if (disableTransitionOnChange) {
+      const style = document.createElement("style");
+      style.textContent = "*,*::before,*::after{transition:none!important}";
+      document.head.appendChild(style);
+      requestAnimationFrame(() => requestAnimationFrame(() => document.head.removeChild(style)));
+    }
+    for (const attr of attrs) {
+      if (attr === "class") {
+        const toRemove = themes.map((t) => valueMap?.[t] ?? t);
+        el.classList.remove(...toRemove);
+        el.classList.add(attrValue);
+      } else {
+        el.setAttribute(attr, attrValue);
+      }
+    }
+    if (enableColorScheme && (resolved === "light" || resolved === "dark")) {
+      el.style.colorScheme = resolved;
+    }
+    if (themeColor) {
+      updateMetaThemeColor(resolveThemeColor(themeColor, resolved));
+    }
+  }, [
+    attribute,
+    disableTransitionOnChange,
+    enableColorScheme,
+    getTargetEl,
+    themes,
+    valueMap,
+    themeColor
+  ]);
+  useEffect(() => {
+    if (forcedTheme) {
+      themeStore.setTheme(forcedTheme);
+      return;
+    }
+    let stored = null;
+    try {
+      if (storage !== "none") {
+        const store = storage === "localStorage" ? localStorage : sessionStorage;
+        stored = store.getItem(storageKey);
+      }
+    } catch {}
+    const initial = stored && themes.includes(stored) ? stored : resolvedDefault;
+    themeStore.setTheme(initial);
+  }, [forcedTheme, resolvedDefault, storage, storageKey, themes]);
+  useEffect(() => {
+    if (!enableSystem)
+      return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    themeStore.setSystemTheme(mq.matches ? "dark" : "light");
+    const handler = (e) => {
+      const next = e.matches ? "dark" : "light";
+      themeStore.setSystemTheme(next);
+      const current = themeStore.getSnapshot().theme;
+      if (current === "system" || current === undefined) {
+        applyToDom(next);
+        onThemeChangeRef.current?.(next);
+      }
+    };
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, [enableSystem, applyToDom]);
+  useEffect(() => {
+    if (storage === "none")
+      return;
+    const handler = (e) => {
+      if (e.key !== storageKey || !e.newValue)
+        return;
+      if (themes.includes(e.newValue)) {
+        const newTheme = e.newValue;
+        const resolved = newTheme === "system" ? themeStore.getSnapshot().systemTheme ?? "light" : newTheme;
+        themeStore.setTheme(newTheme);
+        applyToDom(resolved);
+      }
+    };
+    window.addEventListener("storage", handler);
+    return () => window.removeEventListener("storage", handler);
+  }, [storage, storageKey, themes, applyToDom]);
+  const setTheme = useCallback((next) => {
+    if (forcedTheme)
+      return;
+    const current = themeStore.getSnapshot().theme;
+    const newTheme = typeof next === "function" ? next(current) : next;
+    const resolved = newTheme === "system" ? themeStore.getSnapshot().systemTheme ?? "light" : newTheme;
+    themeStore.setTheme(newTheme);
+    applyToDom(resolved);
+    onThemeChangeRef.current?.(resolved);
+    try {
+      if (storage !== "none") {
+        const store = storage === "localStorage" ? localStorage : sessionStorage;
+        store.setItem(storageKey, newTheme);
+      }
+    } catch {}
+  }, [applyToDom, forcedTheme, storage, storageKey]);
+  const contextValue = {
+    theme: forcedTheme ?? theme,
+    resolvedTheme,
+    systemTheme,
+    forcedTheme,
+    themes,
+    setTheme
+  };
+  return /* @__PURE__ */ jsxDEV(ThemeContext.Provider, {
+    value: contextValue,
+    children
   }, undefined, false, undefined, this);
 }
+// src/script.ts
+function themeScript(storageKey, attribute, defaultTheme, enableSystem, enableColorScheme, forcedTheme, themes, value, target, storage, themeColors) {
+  let theme;
+  if (forcedTheme) {
+    theme = forcedTheme;
+  } else {
+    let stored = null;
+    try {
+      if (storage !== "none") {
+        const store = storage === "localStorage" ? localStorage : sessionStorage;
+        stored = store.getItem(storageKey);
+      }
+    } catch {}
+    theme = stored && themes.includes(stored) ? stored : defaultTheme;
+  }
+  if (theme === "system") {
+    theme = enableSystem ? matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light" : defaultTheme;
+  }
+  const attrValue = value?.[theme] || theme;
+  const el = target === "html" ? document.documentElement : target === "body" ? document.body : document.querySelector(target);
+  if (!el)
+    return;
+  const attrs = Array.isArray(attribute) ? attribute : [attribute];
+  for (const attr of attrs) {
+    if (attr === "class") {
+      const toRemove = themes.map((t) => value?.[t] || t);
+      el.classList.remove(...toRemove);
+      el.classList.add(attrValue);
+    } else {
+      el.setAttribute(attr, attrValue);
+    }
+  }
+  if (enableColorScheme && (theme === "light" || theme === "dark")) {
+    el.style.colorScheme = theme;
+  }
+  if (themeColors) {
+    const color = typeof themeColors === "string" ? themeColors : themeColors[theme];
+    if (color) {
+      let meta = document.querySelector('meta[name="theme-color"]');
+      if (!meta) {
+        meta = document.createElement("meta");
+        meta.setAttribute("name", "theme-color");
+        document.head.appendChild(meta);
+      }
+      meta.setAttribute("content", color);
+    }
+  }
+}
+function getScript(config) {
+  const fn = themeScript.toString().replace(/\s*__name\s*\([^)]*\)\s*;?\s*/g, "");
+  const args = [
+    JSON.stringify(config.storageKey),
+    JSON.stringify(config.attribute),
+    JSON.stringify(config.defaultTheme),
+    String(config.enableSystem),
+    String(config.enableColorScheme),
+    JSON.stringify(config.forcedTheme ?? null),
+    JSON.stringify(config.themes),
+    JSON.stringify(config.value ?? null),
+    JSON.stringify(config.target),
+    JSON.stringify(config.storage),
+    JSON.stringify(config.themeColors ?? null)
+  ].join(",");
+  return `(${fn})(${args})`;
+}
+// src/provider.tsx
+import { jsxDEV as jsxDEV2, Fragment } from "react/jsx-dev-runtime";
+var DEFAULT_THEMES2 = ["light", "dark"];
+function ThemeProvider({
+  children,
+  themes = DEFAULT_THEMES2,
+  forcedTheme,
+  enableSystem = true,
+  defaultTheme,
+  attribute = "class",
+  value: valueMap,
+  target = "html",
+  disableTransitionOnChange = false,
+  storage = "localStorage",
+  storageKey = "theme",
+  enableColorScheme = true,
+  nonce,
+  onThemeChange,
+  themeColor
+}) {
+  const resolvedDefault = defaultTheme ?? (enableSystem ? "system" : "light");
+  return /* @__PURE__ */ jsxDEV2(Fragment, {
+    children: [
+      /* @__PURE__ */ jsxDEV2("script", {
+        dangerouslySetInnerHTML: {
+          __html: getScript({
+            storageKey,
+            attribute,
+            defaultTheme: resolvedDefault,
+            enableSystem,
+            enableColorScheme,
+            forcedTheme,
+            themes,
+            value: valueMap,
+            target,
+            storage,
+            themeColors: themeColor
+          })
+        },
+        nonce
+      }, undefined, false, undefined, this),
+      /* @__PURE__ */ jsxDEV2(ClientThemeProvider, {
+        themes,
+        forcedTheme,
+        enableSystem,
+        defaultTheme,
+        attribute,
+        value: valueMap,
+        target,
+        disableTransitionOnChange,
+        storage,
+        storageKey,
+        enableColorScheme,
+        themeColor,
+        onThemeChange,
+        children
+      }, undefined, false, undefined, this)
+    ]
+  }, undefined, true, undefined, this);
+}
 export {
-  Button
+  useTheme,
+  ThemeProvider
 };

package/package.json CHANGED Viewed

@@ -1,7 +1,11 @@
 {
   "name": "@wrksz/themes",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A modern, fully-featured theme management library for Next.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jakubwarkusz/themes"
+  },
   "license": "MIT",
   "files": [
     "dist"
@@ -13,7 +17,7 @@
     "lint": "biome check src",
     "lint:fix": "biome check --write src",
     "format": "biome format --write src",
-    "prepare": ""
+    "prepare": "[ \"$CI\" = \"true\" ] || lefthook install"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.8",

package/dist/index.css DELETED Viewed

@@ -1,29 +0,0 @@
-/* src/styles.css */
-:root {
-  --button-bg: #007bff;
-  --button-bg-hover: #006fe6;
-  --button-text: #fff;
-}
-@media (prefers-color-scheme: dark) {
-  :root {
-    --button-bg: #3089e8;
-    --button-bg-hover: #4796eb;
-    --button-text: #fff;
-  }
-}
-[data-slot="button"] {
-  background: var(--button-bg);
-  color: var(--button-text);
-  cursor: pointer;
-  border: none;
-  border-radius: .5rem;
-  padding: .6rem 1.2rem;
-  font-size: .875rem;
-  font-weight: 500;
-}
-[data-slot="button"]:hover {
-  background: var(--button-bg-hover);
-}