theme-watcher 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+> [!IMPORTANT]
+> This program was written by GPT-5.3 Codex.
+
+# theme-watcher
+
+Plug-and-play theme syncing for React SPAs.
+
+## Install
+
+```bash
+npm i theme-watcher
+```
+
+## Quick start
+
+```tsx
+import { useTheme, ThemeWatcher } from "theme-watcher";
+
+function App() {
+  const { set, get } = useTheme();
+
+  return (
+    <>
+      <ThemeWatcher />
+      <button onClick={() => set("dark")}>Dark</button>
+      <pre>{get()}</pre>
+    </>
+  );
+}
+```
+
+## API
+
+### `<ThemeWatcher />`
+
+Mount once near your app root.
+
+Props:
+- `theme?: "light" | "dark"` controlled override
+- `storageKey?: string` default: `"theme-watcher"`
+- `attribute?: "data-theme" | "class"` default: `"data-theme"`
+- `defaultTheme?: "light" | "dark" | "system"` default: `"system"`
+
+### `useTheme()`
+
+Returns:
+- `theme` stored preference (`"light" | "dark" | "system"`)
+- `resolvedTheme` active applied theme (`"light" | "dark"`)
+- `source` where the current value came from (`"prop" | "storage" | "default" | "system"`)
+- `set(theme)` set and persist preference
+- `get()` get persisted preference
+
+## Behavior notes
+
+- Priority order: `theme prop` -> `localStorage` -> `defaultTheme` -> system theme.
+- `system` mode updates live when `prefers-color-scheme` changes.
+- Cross-tab updates are synced through `storage` events.
+- Package is ESM-only.
+
+## Development
+
+This repo uses Bun for package management and scripts, but the published package has no Bun runtime dependency.
+
+```bash
+bun install
+bun run typecheck
+bun run test
+bun run build
+```

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+type Theme = "light" | "dark";
+type ThemePreference = Theme | "system";
+type ThemeSource = "prop" | "storage" | "default" | "system";
+type ThemeAttribute = "data-theme" | "class";
+interface ThemeState {
+    theme: ThemePreference;
+    resolvedTheme: Theme;
+    source: ThemeSource;
+}
+interface ThemeWatcherProps {
+    theme?: Theme;
+    storageKey?: string;
+    attribute?: ThemeAttribute;
+    defaultTheme?: ThemePreference;
+}
+interface ThemeApi extends ThemeState {
+    set: (theme: ThemePreference) => void;
+    get: () => ThemePreference;
+}
+
+declare function ThemeWatcher({ theme, storageKey, attribute, defaultTheme }: ThemeWatcherProps): null;
+
+declare function useTheme(): ThemeApi;
+
+export { type Theme, type ThemeApi, type ThemeAttribute, type ThemePreference, type ThemeSource, type ThemeState, ThemeWatcher, type ThemeWatcherProps, useTheme };

package/dist/index.js

@@ -0,0 +1,182 @@
+// src/ThemeWatcher.tsx
+import { useEffect } from "react";
+
+// src/theme-store.ts
+var DEFAULT_CONFIG = {
+  storageKey: "theme-watcher",
+  attribute: "data-theme",
+  defaultTheme: "system"
+};
+var VALID_PREFERENCES = /* @__PURE__ */ new Set(["light", "dark", "system"]);
+var config = { ...DEFAULT_CONFIG };
+var controlledTheme;
+var state = {
+  theme: "system",
+  resolvedTheme: "light",
+  source: "system"
+};
+var subscribers = /* @__PURE__ */ new Set();
+var mediaQueryList = null;
+var initialized = false;
+var watcherCount = 0;
+function isBrowserReady() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function readStoredTheme() {
+  if (!isBrowserReady()) return null;
+  try {
+    const value = window.localStorage.getItem(config.storageKey);
+    if (!value || !VALID_PREFERENCES.has(value)) {
+      return null;
+    }
+    return value;
+  } catch {
+    return null;
+  }
+}
+function writeStoredTheme(theme) {
+  if (!isBrowserReady()) return;
+  try {
+    window.localStorage.setItem(config.storageKey, theme);
+  } catch {
+    return;
+  }
+}
+function resolveSystemTheme() {
+  if (!isBrowserReady()) return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveTheme(propTheme, stored, defaultTheme) {
+  if (propTheme) {
+    return { theme: propTheme, resolvedTheme: propTheme, source: "prop" };
+  }
+  const effective = stored ?? defaultTheme;
+  if (effective === "system") {
+    return {
+      theme: "system",
+      resolvedTheme: resolveSystemTheme(),
+      source: stored ? "storage" : defaultTheme === "system" ? "system" : "default"
+    };
+  }
+  const source = stored ? "storage" : "default";
+  return { theme: effective, resolvedTheme: effective, source };
+}
+function applyDomTheme(resolvedTheme) {
+  if (!isBrowserReady()) return;
+  const root = document.documentElement;
+  if (config.attribute === "class") {
+    root.classList.toggle("dark", resolvedTheme === "dark");
+    root.classList.toggle("light", resolvedTheme === "light");
+    return;
+  }
+  root.setAttribute("data-theme", resolvedTheme);
+}
+function emit() {
+  for (const callback of subscribers) {
+    callback();
+  }
+}
+function recompute() {
+  const stored = readStoredTheme();
+  state = resolveTheme(controlledTheme, stored, config.defaultTheme);
+  applyDomTheme(state.resolvedTheme);
+  emit();
+}
+function handleMediaChange() {
+  if (controlledTheme || state.theme !== "system") return;
+  recompute();
+}
+function handleStorage(event) {
+  if (event.key !== config.storageKey) return;
+  recompute();
+}
+function attachListeners() {
+  if (!isBrowserReady() || mediaQueryList) return;
+  mediaQueryList = window.matchMedia("(prefers-color-scheme: dark)");
+  mediaQueryList.addEventListener("change", handleMediaChange);
+  window.addEventListener("storage", handleStorage);
+}
+function detachListeners() {
+  if (!isBrowserReady() || !mediaQueryList) return;
+  mediaQueryList.removeEventListener("change", handleMediaChange);
+  window.removeEventListener("storage", handleStorage);
+  mediaQueryList = null;
+}
+function configureStore(nextConfig, propTheme) {
+  config = {
+    ...config,
+    ...nextConfig
+  };
+  controlledTheme = propTheme;
+  recompute();
+}
+function mountWatcher(nextConfig, propTheme) {
+  watcherCount += 1;
+  if (!initialized) {
+    initialized = true;
+    attachListeners();
+  }
+  configureStore(nextConfig, propTheme);
+  return () => {
+    watcherCount -= 1;
+    if (watcherCount <= 0) {
+      watcherCount = 0;
+      controlledTheme = void 0;
+      detachListeners();
+    }
+  };
+}
+function subscribe(callback) {
+  subscribers.add(callback);
+  return () => {
+    subscribers.delete(callback);
+  };
+}
+function setTheme(theme) {
+  if (!VALID_PREFERENCES.has(theme)) return;
+  writeStoredTheme(theme);
+  state = resolveTheme(controlledTheme, theme, config.defaultTheme);
+  applyDomTheme(state.resolvedTheme);
+  emit();
+}
+function getTheme() {
+  return readStoredTheme() ?? config.defaultTheme;
+}
+function getState() {
+  return state;
+}
+function getServerSnapshot() {
+  return {
+    theme: config.defaultTheme,
+    resolvedTheme: config.defaultTheme === "dark" ? "dark" : "light",
+    source: "default"
+  };
+}
+
+// src/ThemeWatcher.tsx
+function ThemeWatcher({
+  theme,
+  storageKey = "theme-watcher",
+  attribute = "data-theme",
+  defaultTheme = "system"
+}) {
+  useEffect(() => {
+    return mountWatcher({ storageKey, attribute, defaultTheme }, theme);
+  }, [theme, storageKey, attribute, defaultTheme]);
+  return null;
+}
+
+// src/useTheme.ts
+import { useSyncExternalStore } from "react";
+function useTheme() {
+  const state2 = useSyncExternalStore(subscribe, getState, getServerSnapshot);
+  return {
+    ...state2,
+    set: setTheme,
+    get: getTheme
+  };
+}
+export {
+  ThemeWatcher,
+  useTheme
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "theme-watcher",
+  "version": "0.1.0",
+  "description": "Plug-and-play theme watcher for React SPAs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.11",
+    "@types/react-dom": "^19.1.7",
+    "jsdom": "^26.1.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}