@kbach/react 1.0.0-beta.23 → 1.0.0-beta.25

package/AGENTS.md

@@ -0,0 +1,129 @@
+# `@kbach/react` — reference for AI assistants
+
+The web binding of [Kbach](https://github.com/semsakadanupol/kbach) — the
+same Tailwind-v4-shaped class-name vocabulary as `@kbach/react-native`,
+resolved at **build time** into a real CSS file via a shared Rust/WASM
+core. This file covers `@kbach/react` only; for the cross-package
+overview, `kbach.config.js` reference, the color palette, and how the
+underlying engine is built, see the repo root's
+[AGENTS.md](https://github.com/semsakadanupol/kbach/blob/main/AGENTS.md).
+
+---
+
+## 1. Install + wire up the build
+
+```sh
+npm install @kbach/react@beta
+```
+
+**Vite:**
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { kbach } from '@kbach/react/vite';
+
+export default defineConfig({ plugins: [kbach(), react()] });
+```
+
+**Next.js / any PostCSS bundler:**
+
+```js
+// postcss.config.js
+module.exports = { plugins: { '@kbach/react/postcss': {} } };
+```
+
+```css
+/* globals.css — the plugin fills between these markers */
+/* kbach:start */
+/* kbach:end */
+```
+
+Then import the generated CSS once from your entry point
+(`import './kbach.css'` for Vite; `import './globals.css'` for PostCSS) and
+write `className="..."` normally.
+
+## 2. How resolution works
+
+1. At build time the plugin walks your `include` dirs (`src`, `app`,
+   `pages`, `components` by default), extracts every string that looks like
+   a class list, and hands each to the WASM engine.
+2. The engine parses each class → emits CSS rules (with the correct
+   `@media` / selector wrappers for modifiers).
+3. Rules are written between the `/* kbach:start */` / `/* kbach:end */`
+   markers of a `kbach.css` file. The plugin finds an existing marked file
+   under your source dirs or the project root, else creates one; pass
+   `cssFile` to pin the path.
+4. At runtime `className` is a plain string prop — **nothing calls the
+   engine**, the CSS already exists. No async init.
+
+## 3. Runtime pieces (opt-in, these DO call the engine)
+
+- **`kb(dynamicClassString)`** — resolve a class list assembled from
+  runtime data (`kb(\`bg-${color}-6\`)`). Requires `await initKbach()` once
+  before first use. Prefer a `safelist: [...]` plugin entry when the
+  possible values are known ahead of time (stays fully static).
+- **`@kbach/react/jsx-runtime`** — a `jsxImportSource` override that
+  intercepts *every* element's `className` at runtime instead of relying on
+  the static scan. Also needs `await initKbach()`.
+
+## 4. Dark mode
+
+`dark:` classes work through plain CSS with zero setup, following the OS
+(`@media (prefers-color-scheme)`).
+
+For a **manual toggle**, add one line to `kbach.config.js`:
+
+```js
+export default { darkMode: 'attribute' }; // or 'class'
+```
+
+Nothing else — the plugin auto-discovers the file, and the runtime reads
+the strategy back out of the generated CSS. Then:
+
+```tsx
+import { useTheme } from '@kbach/react';
+const { mode, isDark, toggle, setMode } = useTheme();
+```
+
+No provider needed (`useTheme` reads a global store). `<ThemeProvider
+defaultMode="dark">` only seeds a startup default. Outside React:
+`getGlobalDarkMode()` / `toggleGlobalDarkMode()` / `setGlobalThemeMode()`.
+
+Pure-runtime (`kb()`-only, no build step): call `applyKbachConfig({
+darkMode: 'attribute' })` yourself once before first render.
+
+## 5. Plugin options (`KbachPluginOptions`)
+
+`root`, `theme` (a resolved `ThemeConfig`), `config` (a `KbachConfig`, same
+shape as `kbach.config.js` — see the root AGENTS.md's config reference),
+`include` (dirs to scan), `safelist` (classes to always emit), `cssFile`
+(explicit output path). PostCSS: `root` defaults to `process.cwd()`; pass
+it if `postcss.config.js` isn't at the project root.
+
+## 6. Exports
+
+`initKbach`, `isKbachReady`, `kb`, `disableRuntimeCSS`,
+`isRuntimeCSSDisabled`, `setTheme`, `getTheme`, `defaultTheme`,
+`KbachReset`, `resolveKbachConfig`, `applyKbachConfig`, `useTheme`,
+`ThemeProvider`, `useColors`, `clsx`, `getGlobalDarkMode`,
+`getGlobalThemeMode`, `setGlobalThemeMode`, `toggleGlobalDarkMode`,
+`subscribeGlobalDarkMode`. Types: `ThemeConfig`, `ColorEntry`,
+`ContainerConfig`, `DarkModeStrategy`, `KbachConfig`, `ThemeState`,
+`ThemeProviderProps`, `ThemeMode`, `ColorsAPI`, `ColorScale`, `ClassValue`.
+
+## 7. Common failure modes
+
+- **Build fails after adding/editing `kbach.config.js`** — an unquoted
+  hyphenated object key (`surface-dim:` instead of `'surface-dim':`) is a
+  syntax error; `loadConfigFile` (vite-plugin/index.ts) re-throws it
+  rather than silently falling back to defaults, so the whole build fails
+  loudly. Quote the key.
+- **A dynamic `kb(...)` call returns nothing / throws** — `initKbach()`
+  hasn't resolved yet. It's async; await it once before the first `kb()`
+  call, or prefer a static `safelist` entry when the value set is known
+  ahead of time.
+- **A class works in one file but not another** — it's outside every
+  `include` dir the plugin scans (default: `src`, `app`, `pages`,
+  `components`). Add the directory via the plugin's `include` option.

package/dist/{chunk-QYTXXF22.mjs → chunk-KTRJZDVE.mjs}

@@ -299,11 +299,28 @@ function splitClassTokens(str) {
   return str.split(/\s+/).filter(Boolean);
 }
 var NOT_A_CLASS_NAME_RE = /[${}]|-$|^[?:&|!"'=<>]+$/;
+function hasUnbracketedParen(token) {
+  let bracketDepth = 0;
+  for (const ch of token) {
+    if (ch === "[") bracketDepth++;
+    else if (ch === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+    else if ((ch === "(" || ch === ")") && bracketDepth === 0) return true;
+  }
+  return false;
+}
 function pushTokens(str, into) {
   for (const tok of splitClassTokens(str)) {
-    if (tok && !NOT_A_CLASS_NAME_RE.test(tok)) into.add(tok);
+    if (tok && !NOT_A_CLASS_NAME_RE.test(tok) && !hasUnbracketedParen(tok)) into.add(tok);
   }
 }
+var JSX_CHILD_CONTEXT_WINDOW = 40;
+var JSX_CHILD_BEFORE_RE = />\s*\{\s*$/;
+var JSX_CHILD_AFTER_RE = /^\s*\}\s*</;
+function isJsxExpressionChildTemplateLiteral(code, matchStart, matchEnd) {
+  const before = code.slice(Math.max(0, matchStart - JSX_CHILD_CONTEXT_WINDOW), matchStart);
+  const after = code.slice(matchEnd, matchEnd + JSX_CHILD_CONTEXT_WINDOW);
+  return JSX_CHILD_BEFORE_RE.test(before) && JSX_CHILD_AFTER_RE.test(after);
+}
 function pushTemplateLiteralBody(body, into) {
   const interpolationRe = /\$\{(?:[^{}]|\{[^{}]*\})*\}/g;
   let im;
@@ -374,7 +391,10 @@ function extractClassStrings(rawCode) {
     if (depth === 0) pushClassLikeStrings(block, found);
   }
   const templateRe = /`([^`]{1,2000})`/g;
-  while ((m = templateRe.exec(code)) !== null) pushTemplateLiteralBody(m[1], found);
+  while ((m = templateRe.exec(code)) !== null) {
+    if (isJsxExpressionChildTemplateLiteral(code, m.index, templateRe.lastIndex)) continue;
+    pushTemplateLiteralBody(m[1], found);
+  }
   return [...found];
 }
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", ".next", ".output", ".git", ".svn", ".cache", "coverage"]);

package/dist/postcss-plugin.js

@@ -128,11 +128,28 @@ function splitClassTokens(str) {
   return str.split(/\s+/).filter(Boolean);
 }
 var NOT_A_CLASS_NAME_RE = /[${}]|-$|^[?:&|!"'=<>]+$/;
+function hasUnbracketedParen(token) {
+  let bracketDepth = 0;
+  for (const ch of token) {
+    if (ch === "[") bracketDepth++;
+    else if (ch === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+    else if ((ch === "(" || ch === ")") && bracketDepth === 0) return true;
+  }
+  return false;
+}
 function pushTokens(str, into) {
   for (const tok of splitClassTokens(str)) {
-    if (tok && !NOT_A_CLASS_NAME_RE.test(tok)) into.add(tok);
+    if (tok && !NOT_A_CLASS_NAME_RE.test(tok) && !hasUnbracketedParen(tok)) into.add(tok);
   }
 }
+var JSX_CHILD_CONTEXT_WINDOW = 40;
+var JSX_CHILD_BEFORE_RE = />\s*\{\s*$/;
+var JSX_CHILD_AFTER_RE = /^\s*\}\s*</;
+function isJsxExpressionChildTemplateLiteral(code, matchStart, matchEnd) {
+  const before = code.slice(Math.max(0, matchStart - JSX_CHILD_CONTEXT_WINDOW), matchStart);
+  const after = code.slice(matchEnd, matchEnd + JSX_CHILD_CONTEXT_WINDOW);
+  return JSX_CHILD_BEFORE_RE.test(before) && JSX_CHILD_AFTER_RE.test(after);
+}
 function pushTemplateLiteralBody(body, into) {
   const interpolationRe = /\$\{(?:[^{}]|\{[^{}]*\})*\}/g;
   let im;
@@ -203,7 +220,10 @@ function extractClassStrings(rawCode) {
     if (depth === 0) pushClassLikeStrings(block, found);
   }
   const templateRe = /`([^`]{1,2000})`/g;
-  while ((m = templateRe.exec(code)) !== null) pushTemplateLiteralBody(m[1], found);
+  while ((m = templateRe.exec(code)) !== null) {
+    if (isJsxExpressionChildTemplateLiteral(code, m.index, templateRe.lastIndex)) continue;
+    pushTemplateLiteralBody(m[1], found);
+  }
   return [...found];
 }
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", ".next", ".output", ".git", ".svn", ".cache", "coverage"]);
@@ -1251,3 +1271,5 @@ function kbachPostcss(options = {}) {
   };
 }
 kbachPostcss.postcss = true;
+
+module.exports = module.exports.default;

package/dist/postcss-plugin.mjs

@@ -6,7 +6,7 @@ import {
   highlight,
   kbachTag,
   resolveEffectiveTheme
-} from "./chunk-QYTXXF22.mjs";
+} from "./chunk-KTRJZDVE.mjs";
 import "./chunk-43FOLRQA.mjs";
 import "./chunk-OVKVZA7B.mjs";
 

package/dist/vite-plugin.js

@@ -919,11 +919,28 @@ function splitClassTokens(str) {
   return str.split(/\s+/).filter(Boolean);
 }
 var NOT_A_CLASS_NAME_RE = /[${}]|-$|^[?:&|!"'=<>]+$/;
+function hasUnbracketedParen(token) {
+  let bracketDepth = 0;
+  for (const ch of token) {
+    if (ch === "[") bracketDepth++;
+    else if (ch === "]") bracketDepth = Math.max(0, bracketDepth - 1);
+    else if ((ch === "(" || ch === ")") && bracketDepth === 0) return true;
+  }
+  return false;
+}
 function pushTokens(str, into) {
   for (const tok of splitClassTokens(str)) {
-    if (tok && !NOT_A_CLASS_NAME_RE.test(tok)) into.add(tok);
+    if (tok && !NOT_A_CLASS_NAME_RE.test(tok) && !hasUnbracketedParen(tok)) into.add(tok);
   }
 }
+var JSX_CHILD_CONTEXT_WINDOW = 40;
+var JSX_CHILD_BEFORE_RE = />\s*\{\s*$/;
+var JSX_CHILD_AFTER_RE = /^\s*\}\s*</;
+function isJsxExpressionChildTemplateLiteral(code, matchStart, matchEnd) {
+  const before = code.slice(Math.max(0, matchStart - JSX_CHILD_CONTEXT_WINDOW), matchStart);
+  const after = code.slice(matchEnd, matchEnd + JSX_CHILD_CONTEXT_WINDOW);
+  return JSX_CHILD_BEFORE_RE.test(before) && JSX_CHILD_AFTER_RE.test(after);
+}
 function pushTemplateLiteralBody(body, into) {
   const interpolationRe = /\$\{(?:[^{}]|\{[^{}]*\})*\}/g;
   let im;
@@ -994,7 +1011,10 @@ function extractClassStrings(rawCode) {
     if (depth === 0) pushClassLikeStrings(block, found);
   }
   const templateRe = /`([^`]{1,2000})`/g;
-  while ((m = templateRe.exec(code)) !== null) pushTemplateLiteralBody(m[1], found);
+  while ((m = templateRe.exec(code)) !== null) {
+    if (isJsxExpressionChildTemplateLiteral(code, m.index, templateRe.lastIndex)) continue;
+    pushTemplateLiteralBody(m[1], found);
+  }
   return [...found];
 }
 var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", ".next", ".output", ".git", ".svn", ".cache", "coverage"]);

package/dist/vite-plugin.mjs

@@ -5,7 +5,7 @@ import {
   kbach,
   loadConfigFile,
   resolveEffectiveTheme
-} from "./chunk-QYTXXF22.mjs";
+} from "./chunk-KTRJZDVE.mjs";
 import "./chunk-43FOLRQA.mjs";
 import "./chunk-OVKVZA7B.mjs";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "1.0.0-beta.23",
+  "version": "1.0.0-beta.25",
   "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",
@@ -25,7 +25,8 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "source": "./src/index.ts",
   "main": "./dist/index.js",
@@ -64,7 +65,7 @@
     }
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/fix-postcss-cjs-interop.mjs",
     "dev": "tsup --watch",
     "test": "vitest run --passWithNoTests",
     "test:coverage": "vitest run --coverage --passWithNoTests",