@kbach/react 1.0.0-beta.13 → 1.0.0-beta.15

package/README.md

@@ -188,56 +188,64 @@ live at your project root (e.g. a monorepo app).
 
 ## Dark mode
 
-By default, `dark:` classes follow the OS `prefers-color-scheme` setting via
-plain CSS — zero config, zero JS required, works even if your app never
-imports anything from `@kbach/react`'s runtime:
+**Following the OS setting — zero setup.** `dark:` classes already work,
+via plain CSS, with nothing to configure:
 
 ```tsx
 <div className="bg-white dark:bg-neutral-12">...</div>
 ```
 
-This default (`darkMode: 'media'`) can't be overridden by an in-app toggle —
-`@media (prefers-color-scheme)` only ever reflects the real OS setting. To
-add a manual light/dark switcher, opt into `darkMode: 'class'` or
-`'attribute'` (writes `.dark`/`data-theme` onto `<html>` instead) — this
-needs setting in **two places**, since they solve two different problems:
-
-1. **Build-time**, via `kbach.config.js` or the plugin's `config`/`theme`
-   option — controls which selector the generated CSS for `dark:` classes
-   compiles to (`[data-theme="dark"] .dark\:bg-neutral-12` vs
-   `.dark .dark\:bg-neutral-12` vs a plain `@media` query).
-2. **Runtime**, via `applyKbachConfig()` — controls what `useTheme()`'s
-   `toggle()`/`setMode()` actually write to the DOM. This is a *separate*
-   module from the build step above (it has to be: the plugin runs in
-   Node during your build, this runs in the browser) — setting only the
-   plugin option compiles the right CSS but leaves the toggle a silent
-   no-op, since the runtime still thinks the strategy is the `'media'`
-   default and has nothing to write to the DOM for it.
+**A manual light/dark toggle — one file, no other setup.** `@media
+(prefers-color-scheme)` (the default above) can't be flipped by a button —
+it only ever reflects the OS. For a real toggle, add one file:
 
 ```js
-// kbach.config.js — build-time, read by the Vite/PostCSS plugin
+// kbach.config.js — at your project root
 export default { darkMode: 'attribute' };
 ```
 
-```tsx
-// app entry (e.g. root.tsx / main.tsx) — runtime, same value as above
-import { applyKbachConfig, useTheme } from '@kbach/react';
+That's it. Don't pass anything to `kbach()`/`'@kbach/react/postcss'` and
+don't call anything at app startup — both sides pick this up on their own
+(the plugin auto-discovers the file; the runtime reads the strategy back
+out of the CSS the plugin already generated). Then just use `useTheme()`:
 
-applyKbachConfig({ darkMode: 'attribute' }); // call once, before first render
+```tsx
+import { useTheme } from '@kbach/react';
 
 function ThemeToggle() {
-  const { mode, isDark, setMode, toggle } = useTheme();
+  const { mode, toggle } = useTheme();
   return <button onClick={toggle}>{mode}</button>;
 }
 ```
 
-Works anywhere, no provider needed. `<ThemeProvider defaultMode="dark">` is
-optional, for seeding a startup default. Outside React (plain functions,
-event handlers), use `getGlobalDarkMode()`/`toggleGlobalDarkMode()` instead.
-Note: `useTheme()`/`toggleGlobalDarkMode()` still track `isDark` correctly
-under the default `'media'` strategy too (and even without ever calling
-`applyKbachConfig()`) — they just won't visibly affect `dark:` classes
-unless the runtime has also been told about `'class'`/`'attribute'`.
+Works anywhere in the tree, no provider required. `<ThemeProvider
+defaultMode="dark">` is optional, only for seeding a startup default.
+Outside React, use `getGlobalDarkMode()`/`toggleGlobalDarkMode()` directly.
+
+<details>
+<summary>Not using the static plugin, or need to set the strategy explicitly?</summary>
+
+There's nothing for the runtime to auto-detect if no build step ever
+generates `dark:` CSS (a pure runtime `kb()`-only setup) — call
+`applyKbachConfig()` yourself once, before your first render, instead:
+
+```tsx
+import { applyKbachConfig } from '@kbach/react';
+
+applyKbachConfig({ darkMode: 'attribute' });
+```
+
+An explicit call like this always wins over whatever the CSS auto-detect
+found, if the two ever disagree. If you do reach for it alongside the
+plugin, import the same `kbach.config.js` rather than retyping the value —
+`import kbachConfig from '../kbach.config.js'; applyKbachConfig(kbachConfig);`.
+
+`useTheme()`/`toggleGlobalDarkMode()` still track `isDark` correctly under
+the default `'media'` strategy too, with none of the above — they just
+won't visibly affect `dark:` classes until the runtime knows about
+`'class'`/`'attribute'` one way or another.
+
+</details>
 
 ## Theming
 

package/dist/{chunk-7G7TMQL6.mjs → chunk-D7OC2AE7.mjs}

@@ -1,6 +1,6 @@
 import {
   kb
-} from "./chunk-U4FGKMNH.mjs";
+} from "./chunk-KJY3W4GF.mjs";
 
 // src/jsx-runtime.tsx
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";

package/dist/{chunk-U4FGKMNH.mjs → chunk-KJY3W4GF.mjs}

@@ -2,7 +2,7 @@ import {
   BASE_RESET,
   RESET_STYLE_ID,
   getThemeJson
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/wasmLoader.ts
 import init, { generate_css as wasmGenerateCss } from "@kbach/core-engine";

package/dist/{chunk-EOSN5CYG.mjs → chunk-OVKVZA7B.mjs}

@@ -377,6 +377,13 @@ function getTheme() {
 function getThemeJson() {
   return activeThemeJson;
 }
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/reset.ts
 var RESET_STYLE_ID = "kbach-reset";
@@ -467,6 +474,7 @@ export {
   setTheme,
   getTheme,
   getThemeJson,
+  detectDarkModeStrategyFromDom,
   RESET_STYLE_ID,
   BASE_RESET,
   buildResetCSS

package/dist/{chunk-77PKNQ2K.mjs → chunk-OWWJ2PME.mjs}

@@ -1,8 +1,9 @@
 import {
   defaultTheme,
+  detectDarkModeStrategyFromDom,
   getTheme,
   setTheme
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/darkModeStore.ts
 var STORAGE_KEY = "kbach-theme";
@@ -31,13 +32,15 @@ function applyToDom(dark) {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
   const strategy = getTheme().darkMode;
-  if (strategy === "class") {
-    root.classList.toggle("dark", dark);
-    root.classList.toggle("light", !dark);
-  } else if (strategy === "attribute") {
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
     root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
   }
 }
+detectDarkModeStrategyFromDom();
 var persistedMode = readPersistedMode();
 var hadPersistedMode = persistedMode !== null;
 var mode = persistedMode ?? "system";

package/dist/{chunk-FJUZ2ZYT.mjs → chunk-XV2ZLURB.mjs}

@@ -1,10 +1,10 @@
 import {
   resolveKbachConfig
-} from "./chunk-77PKNQ2K.mjs";
+} from "./chunk-OWWJ2PME.mjs";
 import {
   buildResetCSS,
   defaultTheme
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/vite-plugin/index.ts
 import { readFileSync as readFileSync3, writeFileSync, mkdirSync, existsSync, statSync as statSync2 } from "fs";
@@ -181,11 +181,9 @@ function formatKbachCSS(tokenRules, theme, usedTags) {
   const spacingMap = buildSpacingVarMap(theme, compact);
   const { text, declarations } = applyVarMap(compact, colorMap, spacingMap);
   const lines = ["/* Generated by Kbach \u2014 do not edit */", "", buildResetCSS(usedTags)];
-  if (declarations.size > 0) {
-    lines.push("", ":root {");
-    for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
-    lines.push("}");
-  }
+  lines.push("", ":root {", `  --kb-dark-mode: ${theme.darkMode};`);
+  for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
+  lines.push("}");
   lines.push("", prettifyCSS(text));
   return lines.join("\n");
 }

package/dist/index.js

@@ -455,6 +455,13 @@ function getTheme() {
 function getThemeJson() {
   return activeThemeJson;
 }
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/reset.ts
 var RESET_STYLE_ID = "kbach-reset";
@@ -697,13 +704,15 @@ function applyToDom(dark) {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
   const strategy = getTheme().darkMode;
-  if (strategy === "class") {
-    root.classList.toggle("dark", dark);
-    root.classList.toggle("light", !dark);
-  } else if (strategy === "attribute") {
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
     root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
   }
 }
+detectDarkModeStrategyFromDom();
 var persistedMode = readPersistedMode();
 var hadPersistedMode = persistedMode !== null;
 var mode = persistedMode ?? "system";

package/dist/index.mjs

@@ -4,7 +4,7 @@ import {
   isKbachReady,
   isRuntimeCSSDisabled,
   kb
-} from "./chunk-U4FGKMNH.mjs";
+} from "./chunk-KJY3W4GF.mjs";
 import {
   applyKbachConfig,
   ensureColorVariablesInjected,
@@ -16,14 +16,14 @@ import {
   setGlobalThemeMode,
   subscribeGlobalDarkMode,
   toggleGlobalDarkMode
-} from "./chunk-77PKNQ2K.mjs";
+} from "./chunk-OWWJ2PME.mjs";
 import {
   BASE_RESET,
   RESET_STYLE_ID,
   defaultTheme,
   getTheme,
   setTheme
-} from "./chunk-EOSN5CYG.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/KbachReset.tsx
 import { jsx } from "react/jsx-runtime";

package/dist/jsx-dev-runtime.mjs

@@ -2,9 +2,9 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-7G7TMQL6.mjs";
-import "./chunk-U4FGKMNH.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-D7OC2AE7.mjs";
+import "./chunk-KJY3W4GF.mjs";
+import "./chunk-OVKVZA7B.mjs";
 
 // src/jsx-dev-runtime.tsx
 function jsxDEV(type, props, key, isStaticChildren, source, self) {

package/dist/jsx-runtime.mjs

@@ -2,9 +2,9 @@ import {
   Fragment,
   jsx,
   jsxs
-} from "./chunk-7G7TMQL6.mjs";
-import "./chunk-U4FGKMNH.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-D7OC2AE7.mjs";
+import "./chunk-KJY3W4GF.mjs";
+import "./chunk-OVKVZA7B.mjs";
 export {
   Fragment,
   jsx,

package/dist/postcss-plugin.js

@@ -476,11 +476,9 @@ function formatKbachCSS(tokenRules, theme, usedTags) {
   const spacingMap = buildSpacingVarMap(theme, compact);
   const { text, declarations } = applyVarMap(compact, colorMap, spacingMap);
   const lines = ["/* Generated by Kbach \u2014 do not edit */", "", buildResetCSS(usedTags)];
-  if (declarations.size > 0) {
-    lines.push("", ":root {");
-    for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
-    lines.push("}");
-  }
+  lines.push("", ":root {", `  --kb-dark-mode: ${theme.darkMode};`);
+  for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
+  lines.push("}");
   lines.push("", prettifyCSS(text));
   return lines.join("\n");
 }
@@ -990,9 +988,20 @@ var defaultTheme = {
 };
 var activeTheme = defaultTheme;
 var activeThemeJson = JSON.stringify(defaultTheme);
+function setTheme(theme) {
+  activeTheme = theme;
+  activeThemeJson = JSON.stringify(theme);
+}
 function getTheme() {
   return activeTheme;
 }
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/colorVariables.ts
 function parseHexRgb(hex) {
@@ -1031,13 +1040,15 @@ function applyToDom(dark) {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
   const strategy = getTheme().darkMode;
-  if (strategy === "class") {
-    root.classList.toggle("dark", dark);
-    root.classList.toggle("light", !dark);
-  } else if (strategy === "attribute") {
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
     root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
   }
 }
+detectDarkModeStrategyFromDom();
 var persistedMode = readPersistedMode();
 var mode = persistedMode ?? "system";
 var isDark = resolveIsDark(mode);

package/dist/postcss-plugin.mjs

@@ -2,9 +2,9 @@ import {
   DEFAULT_SCAN_DIRS,
   createKbachStaticCssEngine,
   resolveEffectiveTheme
-} from "./chunk-FJUZ2ZYT.mjs";
-import "./chunk-77PKNQ2K.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-XV2ZLURB.mjs";
+import "./chunk-OWWJ2PME.mjs";
+import "./chunk-OVKVZA7B.mjs";
 
 // src/postcss-plugin/index.ts
 import postcss from "postcss";

package/dist/vite-plugin.js

@@ -285,11 +285,9 @@ function formatKbachCSS(tokenRules, theme, usedTags) {
   const spacingMap = buildSpacingVarMap(theme, compact);
   const { text, declarations } = applyVarMap(compact, colorMap, spacingMap);
   const lines = ["/* Generated by Kbach \u2014 do not edit */", "", buildResetCSS(usedTags)];
-  if (declarations.size > 0) {
-    lines.push("", ":root {");
-    for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
-    lines.push("}");
-  }
+  lines.push("", ":root {", `  --kb-dark-mode: ${theme.darkMode};`);
+  for (const [varName, val] of declarations) lines.push(`  ${varName}: ${val};`);
+  lines.push("}");
   lines.push("", prettifyCSS(text));
   return lines.join("\n");
 }
@@ -1384,9 +1382,20 @@ var defaultTheme = {
 };
 var activeTheme = defaultTheme;
 var activeThemeJson = JSON.stringify(defaultTheme);
+function setTheme(theme) {
+  activeTheme = theme;
+  activeThemeJson = JSON.stringify(theme);
+}
 function getTheme() {
   return activeTheme;
 }
+var DARK_MODE_STRATEGIES = /* @__PURE__ */ new Set(["attribute", "class", "media"]);
+function detectDarkModeStrategyFromDom() {
+  if (typeof document === "undefined") return;
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--kb-dark-mode").trim();
+  if (!DARK_MODE_STRATEGIES.has(raw) || raw === activeTheme.darkMode) return;
+  setTheme({ ...activeTheme, darkMode: raw });
+}
 
 // src/colorVariables.ts
 function parseHexRgb(hex) {
@@ -1425,13 +1434,15 @@ function applyToDom(dark) {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
   const strategy = getTheme().darkMode;
-  if (strategy === "class") {
-    root.classList.toggle("dark", dark);
-    root.classList.toggle("light", !dark);
-  } else if (strategy === "attribute") {
+  root.classList.toggle("dark", strategy === "class" && dark);
+  root.classList.toggle("light", strategy === "class" && !dark);
+  if (strategy === "attribute") {
     root.setAttribute("data-theme", dark ? "dark" : "light");
+  } else {
+    root.removeAttribute("data-theme");
   }
 }
+detectDarkModeStrategyFromDom();
 var persistedMode = readPersistedMode();
 var mode = persistedMode ?? "system";
 var isDark = resolveIsDark(mode);

package/dist/vite-plugin.mjs

@@ -5,9 +5,9 @@ import {
   kbach,
   loadConfigFile,
   resolveEffectiveTheme
-} from "./chunk-FJUZ2ZYT.mjs";
-import "./chunk-77PKNQ2K.mjs";
-import "./chunk-EOSN5CYG.mjs";
+} from "./chunk-XV2ZLURB.mjs";
+import "./chunk-OWWJ2PME.mjs";
+import "./chunk-OVKVZA7B.mjs";
 export {
   CSS_SYNC_DEBOUNCE_MS,
   DEFAULT_SCAN_DIRS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "description": "A utility-first styling engine for React, powered by a real Rust/WASM core — Tailwind CSS v4 feature parity with Kbach's own color palette.",
   "keywords": ["css", "react", "tailwind", "utility-first", "wasm", "styling"],
   "license": "MIT",