@kbach/react 1.0.0-beta.2 → 1.0.0-beta.20

package/README.md

@@ -24,22 +24,18 @@ export default defineConfig({
 });
 ```
 
-```css
-/* src/kbach.css */
-/* kbach:start */
-/* kbach:end */
-```
+That's it — the plugin finds or creates your `kbach.css` on its own,
+wherever your source actually lives (`src/`, `app/`, ...; see "Where does
+`kbach.css` go?" below if you want to know exactly where or control it).
+Import it once from your entry point and render normally:
 
 ```tsx
 // main.tsx
-import { initKbach } from '@kbach/react';
 import { createRoot } from 'react-dom/client';
 import App from './App';
 import './kbach.css';
 
-initKbach().then(() => {
-  createRoot(document.getElementById('root')!).render(<App />);
-});
+createRoot(document.getElementById('root')!).render(<App />);
 ```
 
 ```tsx
@@ -48,20 +44,208 @@ initKbach().then(() => {
 </div>
 ```
 
+No `initKbach()`/async step before your first render: `className` here is
+a plain string prop, resolved entirely by the CSS `@kbach/react/vite`
+already generated at build time, same as any other static stylesheet —
+nothing here calls into the WASM engine at render time, so there's nothing
+to await.
+
+### Where does `kbach.css` go?
+
+You don't need to think about this for the common case — skip to
+[React Router](#react-router)/[Next.js](#nextjs) if that's what brought you
+here. For everyone else: the plugin looks for a file already containing
+`/* kbach:start */`/`/* kbach:end */` markers under each of your `include`
+directories (`src`, `app`, `pages`, `components` by default) and the
+project root, in that order, and keeps using whichever one it finds. If
+none exists yet, it creates `<first-existing-include-dir>/kbach.css` for
+you, markers included — you never have to hand-author that file. Pass
+`cssFile` to `kbach()` only if you want to pin the location explicitly
+(a path outside every `include` dir, or more than one candidate present at
+once).
+
+`initKbach()` (still exported from `@kbach/react`) is only needed for two
+opt-in features that genuinely do call into the Rust/WASM engine at
+runtime: the dynamic [`kb()`](#dynamic-classes) function, and the optional
+`@kbach/react/jsx-runtime` (a `jsxImportSource` override that intercepts
+*every* element's `className` automatically instead of relying on the
+static build). If you use either, `await initKbach()` once before your
+first render, same as before.
+
+## React Router
+
+React Router is a client-side routing library with no build-tool coupling
+of its own, so it layers on top of the exact same Vite + `kbach.css` setup
+either way — but which "either way" depends on which of React Router's two
+genuinely different modes you're using.
+
+**Library mode** (you call `createRoot` yourself — `createBrowserRouter` +
+`<RouterProvider>`, or the classic `<BrowserRouter>` component): needs
+nothing beyond the Quick Start above.
+
+```tsx
+// main.tsx
+import { createRoot } from 'react-dom/client';
+import { RouterProvider, createBrowserRouter } from 'react-router';
+import './kbach.css';
+import Home from './routes/home';
+import About from './routes/about';
+
+const router = createBrowserRouter([
+  { path: '/', Component: Home },
+  { path: '/about', Component: About },
+]);
+
+createRoot(document.getElementById('root')!).render(<RouterProvider router={router} />);
+```
+
+**Framework mode** (`npx create-react-router@latest` — file-based routing
+under `app/`, its own Vite plugin, SSR by default):
+
+```ts
+// vite.config.ts
+import { reactRouter } from '@react-router/dev/vite';
+import { kbach } from '@kbach/react/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [kbach(), reactRouter()],
+});
+```
+
+Same `kbach()` call as everywhere else — its `app/`-vs-`src/` convention
+is exactly what auto-detection (above) exists for, so there's nothing
+React-Router-specific to configure. The one real gotcha is unrelated to
+Kbach at all: **don't call `createRoot` yourself in `app/root.tsx`** — the
+framework's own generated client/server entry points already do this;
+`root.tsx` only ever *exports* a `Layout`/default component. Adding your
+own `createRoot(...).render(...)` at that file's top level runs during SSR
+too, where `document` doesn't exist, and crashes the build immediately.
+`app/root.tsx` needs only:
+
+```tsx
+import './kbach.css';
+export default function App() {
+  return <Outlet />;
+}
+```
+
+Either mode: every route's own components use `className` exactly like any
+other component — routing has no effect on how Kbach resolves classes,
+since resolution already happened at build time, before routing even
+enters the picture.
+
+## Next.js
+
+Next.js uses webpack/Turbopack, not Vite, so `@kbach/react/vite` doesn't
+apply — use `@kbach/react/postcss` instead, which does the exact same
+build-time class-string scanning and CSS generation (they share the same
+underlying engine), just wired into PostCSS, which both of Next.js's
+bundlers already run for you with zero extra config.
+
+```js
+// postcss.config.js
+module.exports = {
+  plugins: {
+    '@kbach/react/postcss': {},
+  },
+};
+```
+
+```css
+/* app/globals.css (App Router) or styles/globals.css (Pages Router) */
+/* kbach:start */
+/* kbach:end */
+```
+
+```tsx
+// app/layout.tsx
+import './globals.css';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Plain `className="..."` strings on Server Components work with zero extra
+setup — the CSS already exists at build time, same as any other static
+stylesheet. Hook-based exports (`useTheme`, `useColors`, `<ThemeProvider>`)
+already carry their own `'use client'` directive, so importing them into a
+Client Component just works; importing one into a Server Component is a
+compile-time error the same way importing `useState` into one would be —
+that's React's own rule, not a Kbach limitation.
+
+`root`/`theme`/`config`/`include`/`safelist` options all match
+`@kbach/react/vite`'s exactly (see `KbachPluginOptions`, above) — `root`
+additionally defaults to `process.cwd()` rather than a bundler-resolved
+project root, since PostCSS has no equivalent to Vite's own resolved
+`root` to read; pass it explicitly if your `postcss.config.js` doesn't
+live at your project root (e.g. a monorepo app).
+
 ## Dark mode
 
+**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>
+```
+
+**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 — at your project root
+export default { darkMode: 'attribute' };
+```
+
+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()`:
+
 ```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.
+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
 
@@ -77,16 +261,20 @@ setTheme({
 ## Dynamic classes
 
 Classes that appear literally in your source are resolved at build time.
-For classes assembled from truly dynamic data, use `kb()`:
+For classes assembled from truly dynamic data, use `kb()` — this is the
+one thing in this package that genuinely calls into the WASM engine at
+runtime, so `await initKbach()` once at startup before the first `kb()`
+call (or before rendering, if you can't guarantee it runs first otherwise):
 
 ```ts
-import { kb } from '@kbach/react';
+import { initKbach, kb } from '@kbach/react';
 
+await initKbach();
 const className = kb(`bg-${userColor}-6`);
 ```
 
 Prefer a `safelist` entry in the plugin config when the possible values are
-known ahead of time — keeps everything static.
+known ahead of time — keeps everything static, no `initKbach()` needed.
 
 ## Reading colors as values
 

package/dist/chunk-43FOLRQA.mjs

@@ -0,0 +1,234 @@
+import {
+  defaultTheme,
+  detectDarkModeStrategyFromDom,
+  getTheme,
+  setTheme
+} from "./chunk-OVKVZA7B.mjs";
+
+// src/darkModeStore.ts
+var STORAGE_KEY = "kbach-theme";
+var listeners = /* @__PURE__ */ new Set();
+function systemPrefersDark() {
+  if (typeof window === "undefined" || !window.matchMedia) return false;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+function storage() {
+  return typeof window === "undefined" ? null : window.localStorage;
+}
+function readPersistedMode() {
+  const ls = storage();
+  if (!ls) return null;
+  try {
+    const raw = ls.getItem(STORAGE_KEY);
+    return raw === "light" || raw === "dark" || raw === "system" ? raw : null;
+  } catch {
+    return null;
+  }
+}
+function resolveIsDark(m) {
+  return m === "system" ? systemPrefersDark() : m === "dark";
+}
+function applyToDom(dark) {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  const strategy = getTheme().darkMode;
+  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";
+var isDark = resolveIsDark(mode);
+applyToDom(isDark);
+if (typeof window !== "undefined" && window.matchMedia) {
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onSystemChange = (event) => {
+    if (mode !== "system") return;
+    isDark = event.matches;
+    applyToDom(isDark);
+    notify();
+  };
+  if (mq.addEventListener) mq.addEventListener("change", onSystemChange);
+  else mq.addListener(onSystemChange);
+}
+function notify() {
+  for (const listener of listeners) listener();
+}
+function resyncDomWithActiveTheme() {
+  applyToDom(isDark);
+}
+function getGlobalDarkMode() {
+  return isDark;
+}
+function getGlobalThemeMode() {
+  return mode;
+}
+function setGlobalThemeMode(nextMode) {
+  mode = nextMode;
+  isDark = resolveIsDark(nextMode);
+  applyToDom(isDark);
+  const ls = storage();
+  if (ls) {
+    try {
+      ls.setItem(STORAGE_KEY, nextMode);
+    } catch {
+    }
+  }
+  notify();
+}
+function toggleGlobalDarkMode() {
+  setGlobalThemeMode(isDark ? "light" : "dark");
+}
+function subscribeGlobalDarkMode(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function seedDefaultMode(fallback) {
+  if (hadPersistedMode || mode === fallback) return;
+  mode = fallback;
+  isDark = resolveIsDark(fallback);
+  applyToDom(isDark);
+  notify();
+}
+
+// src/colorVariables.ts
+function parseHexRgb(hex) {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(hex.trim());
+  if (!m) return null;
+  let h = m[1];
+  if (h.length === 3) h = h.split("").map((c) => c + c).join("");
+  const n = parseInt(h, 16);
+  return [n >> 16 & 255, n >> 8 & 255, n & 255];
+}
+function wrapDarkDecls(strategy, decls) {
+  switch (strategy) {
+    case "class":
+      return `.dark { ${decls} }`;
+    case "media":
+      return `@media (prefers-color-scheme: dark) { :root { ${decls} } }`;
+    case "attribute":
+    default:
+      return `[data-theme="dark"] { ${decls} }`;
+  }
+}
+var STYLE_ID = "kbach-colors";
+var injectedForTheme = null;
+function ensureColorVariablesInjected(theme) {
+  if (typeof document === "undefined") return;
+  if (injectedForTheme === theme) return;
+  injectedForTheme = theme;
+  const lightDecls = [];
+  const darkDecls = [];
+  for (const [name, value] of Object.entries(theme.colors)) {
+    if (typeof value === "string") continue;
+    const light = parseHexRgb(value.light);
+    const dark = parseHexRgb(value.dark);
+    if (!light || !dark) continue;
+    lightDecls.push(`--kb-color-${name}: ${light.join(",")};`);
+    darkDecls.push(`--kb-color-${name}: ${dark.join(",")};`);
+  }
+  let el = document.getElementById(STYLE_ID);
+  if (lightDecls.length === 0) {
+    el?.remove();
+    return;
+  }
+  if (!el) {
+    el = document.createElement("style");
+    el.id = STYLE_ID;
+    document.head.insertBefore(el, document.head.firstChild);
+  }
+  el.textContent = `:root { ${lightDecls.join(" ")} }
+${wrapDarkDecls(theme.darkMode, darkDecls.join(" "))}`;
+}
+
+// src/config.ts
+function applyOpacityToHex(hex, opacityText) {
+  const rgb = parseHexRgb(hex);
+  if (!rgb) return hex;
+  const a = Number(opacityText) / 100;
+  const clamped = Number.isFinite(a) ? Math.min(1, Math.max(0, a)) : 1;
+  return `rgba(${rgb.join(",")},${clamped})`;
+}
+function resolveColorEntry(value, lookup) {
+  if (typeof value !== "string") return value;
+  const slash = value.indexOf("/");
+  const name = slash === -1 ? value : value.slice(0, slash);
+  const opacity = slash === -1 ? void 0 : value.slice(slash + 1);
+  const base = lookup(name);
+  if (base === void 0) return value;
+  if (opacity === void 0) return base;
+  return typeof base === "string" ? applyOpacityToHex(base, opacity) : { light: applyOpacityToHex(base.light, opacity), dark: applyOpacityToHex(base.dark, opacity) };
+}
+function resolveColors(extend, existing) {
+  const { dark: darkExtend, ...lightExtend } = extend;
+  const resolved = {};
+  const lookup = (name) => resolved[name] ?? existing[name];
+  for (const [name, value] of Object.entries(lightExtend)) {
+    if (typeof value === "object" && value !== null && !("light" in value) && !("dark" in value)) continue;
+    resolved[name] = resolveColorEntry(value, lookup);
+  }
+  if (darkExtend) {
+    const resolvedDark = {};
+    const lookupDark = (name) => {
+      const found = resolvedDark[name] ?? existing[name];
+      return typeof found === "string" ? found : void 0;
+    };
+    for (const [name, value] of Object.entries(darkExtend)) {
+      const entry = resolveColorEntry(value, lookupDark);
+      resolvedDark[name] = typeof entry === "string" ? entry : entry.dark;
+    }
+    for (const [name, darkValue] of Object.entries(resolvedDark)) {
+      const lightEntry = resolved[name];
+      if (lightEntry === void 0 || typeof lightEntry !== "string") continue;
+      resolved[name] = { light: lightEntry, dark: darkValue };
+    }
+  }
+  return resolved;
+}
+function resolveKbachConfig(config) {
+  let theme = { ...defaultTheme, ...config.theme };
+  if (config.extend?.colors) {
+    theme = { ...theme, colors: { ...theme.colors, ...resolveColors(config.extend.colors, theme.colors) } };
+  }
+  if (config.extend?.spacing) {
+    theme = { ...theme, spacing: { ...theme.spacing, ...config.extend.spacing } };
+  }
+  if (config.extend?.screens) {
+    theme = { ...theme, screens: { ...theme.screens, ...config.extend.screens } };
+  }
+  if (config.extend?.fontFamily) {
+    theme = { ...theme, fontFamily: { ...theme.fontFamily, ...config.extend.fontFamily } };
+  }
+  if (config.extend?.container) {
+    theme = { ...theme, container: { ...theme.container, ...config.extend.container } };
+  }
+  if (config.darkMode) {
+    theme = { ...theme, darkMode: config.darkMode };
+  }
+  return theme;
+}
+function applyKbachConfig(config) {
+  const theme = resolveKbachConfig(config);
+  setTheme(theme);
+  resyncDomWithActiveTheme();
+  return theme;
+}
+
+export {
+  parseHexRgb,
+  ensureColorVariablesInjected,
+  getGlobalDarkMode,
+  getGlobalThemeMode,
+  setGlobalThemeMode,
+  toggleGlobalDarkMode,
+  subscribeGlobalDarkMode,
+  seedDefaultMode,
+  resolveKbachConfig,
+  applyKbachConfig
+};

package/dist/{chunk-PAJ6KHDB.mjs → chunk-5EXGGZMA.mjs}

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

package/dist/{chunk-ZQJKL2MV.mjs → chunk-BJEOK2VK.mjs}

@@ -2,7 +2,7 @@ import {
   BASE_RESET,
   RESET_STYLE_ID,
   getThemeJson
-} from "./chunk-N5HCQIBB.mjs";
+} from "./chunk-OVKVZA7B.mjs";
 
 // src/wasmLoader.ts
 import init, { generate_css as wasmGenerateCss } from "@kbach/core-engine";
@@ -22,7 +22,7 @@ function isKbachReady() {
 function generateCss(classString, themeJson) {
   if (!ready) {
     throw new Error(
-      "[kbach] generateCss() was called before initKbach() resolved. Call `await initKbach()` once at startup (e.g. before rendering your app) before using kb()."
+      "[Kbach] generateCss() was called before initKbach() resolved. Call `await initKbach()` once at startup (e.g. before rendering your app) before using kb()."
     );
   }
   return wasmGenerateCss(classString, themeJson);
@@ -79,9 +79,23 @@ function ensureResetInjected() {
   el.textContent = BASE_RESET;
   document.head.insertBefore(el, document.head.firstChild);
 }
+var KB_CACHE_MAX = 500;
+var kbCache = /* @__PURE__ */ new Map();
+var cachedForThemeJson = null;
 function kb(classString) {
-  const json = generateCss(classString, getThemeJson());
-  const { className, rules } = JSON.parse(json);
+  const themeJson = getThemeJson();
+  if (themeJson !== cachedForThemeJson) {
+    kbCache.clear();
+    cachedForThemeJson = themeJson;
+  }
+  let result = kbCache.get(classString);
+  if (result === void 0) {
+    const json = generateCss(classString, themeJson);
+    result = JSON.parse(json);
+    if (kbCache.size >= KB_CACHE_MAX) kbCache.clear();
+    kbCache.set(classString, result);
+  }
+  const { className, rules } = result;
   if (!runtimeCSSDisabled) {
     ensureResetInjected();
     for (const { rule, order } of rules) {