@kbach/react 0.6.17 → 0.6.20

package/README.md

@@ -20,9 +20,9 @@ npm install @kbach/react
 
 ## Setup
 
-Two steps: configure the JSX runtime (always), then pick one styling method.
+One step is always required, then pick **one** of the two setups below — they're independent, don't mix them.
 
-### Step 1 — JSX runtime
+### Step 1 — JSX runtime (always required)
 
 **tsconfig.json:**
 
@@ -32,17 +32,17 @@ Two steps: configure the JSX runtime (always), then pick one styling method.
 
 That's the only setting needed — Vite, Next.js, and React Router all read it. Don't *also* set `jsxImportSource` on a bundler plugin (e.g. `@vitejs/plugin-react`); one source of truth avoids conflicts.
 
-### Step 2 — Styling method
-
-Not sure which? Check your framework first:
+### Which setup do I need?
 
 | Framework | Use |
 |---|---|
-| Next.js | **Quick setup** — Static CSS doesn't apply (webpack/Turbopack, not Vite) |
-| React Router, framework mode | **Static CSS setup** — and skip `@vitejs/plugin-react`, see note below |
-| Vite, React Router library mode, CRA, other | Either — Quick is faster to try, Static CSS is zero-cost for production |
+| Next.js | **[Runtime setup](#runtime-setup)** — Static CSS doesn't apply (webpack/Turbopack, not Vite) |
+| React Router, framework mode | **[Static CSS setup](#static-css-setup)** — and skip `@vitejs/plugin-react`, see note in that section |
+| Vite, React Router library mode, CRA, other | Either — Runtime is faster to try, Static CSS is zero-cost for production |
+
+## Runtime setup
 
-#### Quick setup — any bundler, client-side CSS injection
+Client-side CSS injection — works with any bundler (Vite, webpack, Turbopack, Metro-for-web, …), no build plugin. This is the whole setup:
 
 ```jsx
 import { ThemeProvider, KbachReset } from '@kbach/react';
@@ -57,11 +57,17 @@ export default function Root() {
 }
 ```
 
-Done. `<KbachReset />` renders the base reset (see [CSS resets](#css-resets)) as real markup instead of waiting on client JS — matters most for SSR, where it avoids a flash of unstyled browser defaults before hydration. `@kbach/react` ships its own `"use client"` directive, so this works in a Next.js Server Component tree with no wrapper needed — in Next.js, render it once in the root `layout.tsx`.
+That's it — done. `<KbachReset />` renders the base reset (see [CSS resets](#css-resets)) as real markup instead of waiting on client JS — matters most for SSR, where it avoids a flash of unstyled browser defaults before hydration. `@kbach/react` ships its own `"use client"` directive, so this works in a Next.js Server Component tree with no wrapper needed — in Next.js, render it once in the root `layout.tsx`.
+
+Using a custom `kbach.config.js`? Pass it to `ThemeProvider` too — see [Wiring the config in](#wiring-the-config-in--required-for-both-setups).
+
+Don't also set up Static CSS below in the same app — pick one.
+
+## Static CSS setup
 
-#### Static CSS setup — Vite only, zero runtime cost
+Vite only. A build-time plugin writes real CSS into a file you import at build time — nothing generated client-side, zero runtime cost. Three pieces, all required:
 
-A build-time plugin writes real CSS into a file you import — nothing generated client-side.
+**1. Add the plugin:**
 
 ```ts
 // vite.config.ts
@@ -71,6 +77,8 @@ import { kbach } from '@kbach/react/vite';
 export default defineConfig({ plugins: [kbach()] });
 ```
 
+**2. Create an empty stylesheet with the markers, and import it once:**
+
 ```css
 /* src/kbach.css */
 /* kbach:start */
@@ -82,16 +90,19 @@ export default defineConfig({ plugins: [kbach()] });
 import './kbach.css';
 ```
 
+**3. Wrap your app — no `<KbachReset />` here, `kbach.css` already includes the reset:**
+
 ```jsx
 import { ThemeProvider } from '@kbach/react';
-// No <KbachReset /> — kbach.css already includes the reset.
 
 export default function Root() {
   return <ThemeProvider defaultMode="system"><App /></ThemeProvider>;
 }
 ```
 
-The plugin scans your source at build time and writes CSS between the markers — importing `kbach.css` auto-disables runtime injection. It also warns in the terminal (with a clickable `file:line`) for any class it doesn't recognize as a real utility or an existing CSS rule elsewhere in the project — usually a typo.
+Done. The plugin scans your source at build time and writes CSS between the markers — importing `kbach.css` auto-disables runtime injection, so there's no double-styling between this and the Runtime setup above. It also warns in the terminal (with a clickable `file:line`) for any class it doesn't recognize as a real utility or an existing CSS rule elsewhere in the project — usually a typo.
+
+Using a custom `kbach.config.js`? It needs to be wired in **twice** here — once to `kbach()` above (step 1) so the generated CSS reflects it, and once to `ThemeProvider` (step 3) so dark mode/`useColors()`/animations do too. See [Wiring the config in](#wiring-the-config-in--required-for-both-setups) — easy to only do one and have the other silently fall back to defaults.
 
 **React Router framework mode:** don't add `@vitejs/plugin-react` — `reactRouter()` already provides JSX handling, and both together crash the page (`Identifier 'RefreshRuntime' has already been declared`).
 
@@ -99,7 +110,7 @@ The plugin scans your source at build time and writes CSS between the markers
 // vite.config.ts
 import { reactRouter } from '@react-router/dev/vite';
 import { defineConfig } from 'vite';
-import { kbach } from '@kbach/react/vite'; // omit if using Quick setup instead
+import { kbach } from '@kbach/react/vite'; // omit if using Runtime setup instead
 
 export default defineConfig({ plugins: [kbach(), reactRouter()] });
 ```
@@ -296,6 +307,35 @@ module.exports = {
 - Colors can alias each other: `primary: 'blue-6'`, `brand: { 6: 'primary' }`
 - Runtime update: `updateConfig({ extend: { ... } }); clearCache();`
 
+### Wiring the config in — required for both setups
+
+`kbach.config.js` isn't picked up automatically. It has to be imported and passed in explicitly, and **where** depends on which of the two things it affects:
+
+- **Runtime** — dark mode strategy, `useColors()`, custom `@keyframes`/`animation`, and (for SSR) the default-font fallback rendered before your stylesheet takes over. Needed by **both** [Runtime setup](#runtime-setup) and [Static CSS setup](#static-css-setup) — pass it to `ThemeProvider`:
+
+  ```jsx
+  import { ThemeProvider } from '@kbach/react';
+  import kbachConfig from '../kbach.config';
+
+  <ThemeProvider defaultMode="system" config={kbachConfig}>
+    <App />
+  </ThemeProvider>
+  ```
+
+  (Equivalent to calling `updateConfig(kbachConfig)` once before anything renders — `ThemeProvider`'s `config` prop does this for you and keeps the global store in sync if it ever changes.)
+
+- **Build-time** — what the Vite plugin actually scans your source against and generates CSS for. Only relevant to [Static CSS setup](#static-css-setup) — pass it to the plugin itself:
+
+  ```ts
+  // vite.config.ts
+  import { kbach } from '@kbach/react/vite';
+  import kbachConfig from './kbach.config';
+
+  export default defineConfig({ plugins: [kbach(kbachConfig)] });
+  ```
+
+Skipping the runtime one is an easy mistake under Static CSS setup specifically — the generated `kbach.css` will look correct (it *does* have your customizations baked in), while dark mode, `useColors()`, and custom animations silently fall back to Kbach's defaults instead of your config, since nothing ever told the running app what you'd customized.
+
 ## Full reference
 
 [kbach-react.md](./kbach-react.md) — complete utility list, every modifier, all config options.

package/dist/vite-plugin.js

@@ -3176,9 +3176,96 @@ function buildColorVarMap(theme, usedCSS) {
   }
   return { replacements, declarations };
 }
+var SPACING_PROPS = /* @__PURE__ */ new Set([
+  "padding",
+  "padding-top",
+  "padding-right",
+  "padding-bottom",
+  "padding-left",
+  "margin",
+  "margin-top",
+  "margin-right",
+  "margin-bottom",
+  "margin-left",
+  "gap",
+  "column-gap",
+  "row-gap",
+  "width",
+  "height",
+  "min-width",
+  "min-height",
+  "max-width",
+  "max-height",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "flex-basis"
+]);
+function buildSpacingVarMap(theme, usedCSS) {
+  const pxToKey = /* @__PURE__ */ new Map();
+  for (const [key, val] of Object.entries(theme.spacing ?? {})) {
+    if (typeof val === "number" && !pxToKey.has(val)) pxToKey.set(val, key);
+  }
+  const replacements = /* @__PURE__ */ new Map();
+  const declarations = /* @__PURE__ */ new Map();
+  const varNameFor = (key) => `--spacing-${key.replace(/\./g, "_")}`;
+  const declRe = /([a-z-]+): (\d+(?:\.\d+)?)px/g;
+  let m;
+  while ((m = declRe.exec(usedCSS)) !== null) {
+    const [, prop, numStr] = m;
+    if (!SPACING_PROPS.has(prop)) continue;
+    const key = pxToKey.get(parseFloat(numStr));
+    if (key === void 0) continue;
+    const varName = varNameFor(key);
+    replacements.set(`${prop}: ${numStr}px`, `${prop}: var(${varName})`);
+    declarations.set(varName, `${numStr}px`);
+  }
+  const transformRe = /(translateX|translateY)\((\d+(?:\.\d+)?)px\)/g;
+  while ((m = transformRe.exec(usedCSS)) !== null) {
+    const [, fn, numStr] = m;
+    const key = pxToKey.get(parseFloat(numStr));
+    if (key === void 0) continue;
+    const varName = varNameFor(key);
+    replacements.set(`${fn}(${numStr}px)`, `${fn}(var(${varName}))`);
+    declarations.set(varName, `${numStr}px`);
+  }
+  return { replacements, declarations };
+}
+function prettifyCSS(css) {
+  const out = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of css) {
+    if (ch === "{") {
+      const selector = current.trim();
+      if (selector) out.push(`${"  ".repeat(depth)}${selector} {`);
+      depth++;
+      current = "";
+    } else if (ch === "}") {
+      const decl = current.trim();
+      if (decl) out.push(`${"  ".repeat(depth)}${decl};`);
+      depth = Math.max(0, depth - 1);
+      out.push(`${"  ".repeat(depth)}}`);
+      current = "";
+    } else if (ch === ";") {
+      const decl = current.trim();
+      if (decl) out.push(`${"  ".repeat(depth)}${decl};`);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  const trailing = current.trim();
+  if (trailing) out.push(trailing);
+  return out.join("\n");
+}
 function formatKbachCSS(tokenCSS, theme, responsiveRe) {
   const allRaw = [...tokenCSS.values()].filter(Boolean).join("\n");
-  const { replacements, declarations } = buildColorVarMap(theme, allRaw);
+  const colorVars = buildColorVarMap(theme, allRaw);
+  const spacingVars = buildSpacingVarMap(theme, allRaw);
+  const replacements = new Map([...colorVars.replacements, ...spacingVars.replacements]);
+  const declarations = new Map([...colorVars.declarations, ...spacingVars.declarations]);
   const sortedReplacements = [...replacements].sort(([a], [b]) => b.length - a.length);
   function applyVars(css) {
     for (const [pattern, replacement] of sortedReplacements)
@@ -3190,7 +3277,7 @@ function formatKbachCSS(tokenCSS, theme, responsiveRe) {
     if (!css) continue;
     const label = classifyToken(token, responsiveRe);
     if (!groups.has(label)) groups.set(label, []);
-    groups.get(label).push(applyVars(css));
+    groups.get(label).push(prettifyCSS(applyVars(css)));
   }
   const out = ["/* Generated by Kbach \u2014 do not edit */"];
   if (declarations.size > 0) {
@@ -3201,13 +3288,13 @@ function formatKbachCSS(tokenCSS, theme, responsiveRe) {
   const globalCSS = buildThemeGlobal(theme);
   if (globalCSS) out.push(`
 /* Global */
-${globalCSS}`);
+${prettifyCSS(globalCSS)}`);
   for (const label of GROUP_ORDER) {
     const items = groups.get(label) ?? [];
     if (!items.length) continue;
     out.push(`
 /* ${label} */`);
-    out.push(items.join("\n"));
+    out.push(items.join("\n\n"));
   }
   return out.join("\n");
 }

package/dist/vite-plugin.mjs

@@ -3142,9 +3142,96 @@ function buildColorVarMap(theme, usedCSS) {
   }
   return { replacements, declarations };
 }
+var SPACING_PROPS = /* @__PURE__ */ new Set([
+  "padding",
+  "padding-top",
+  "padding-right",
+  "padding-bottom",
+  "padding-left",
+  "margin",
+  "margin-top",
+  "margin-right",
+  "margin-bottom",
+  "margin-left",
+  "gap",
+  "column-gap",
+  "row-gap",
+  "width",
+  "height",
+  "min-width",
+  "min-height",
+  "max-width",
+  "max-height",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "flex-basis"
+]);
+function buildSpacingVarMap(theme, usedCSS) {
+  const pxToKey = /* @__PURE__ */ new Map();
+  for (const [key, val] of Object.entries(theme.spacing ?? {})) {
+    if (typeof val === "number" && !pxToKey.has(val)) pxToKey.set(val, key);
+  }
+  const replacements = /* @__PURE__ */ new Map();
+  const declarations = /* @__PURE__ */ new Map();
+  const varNameFor = (key) => `--spacing-${key.replace(/\./g, "_")}`;
+  const declRe = /([a-z-]+): (\d+(?:\.\d+)?)px/g;
+  let m;
+  while ((m = declRe.exec(usedCSS)) !== null) {
+    const [, prop, numStr] = m;
+    if (!SPACING_PROPS.has(prop)) continue;
+    const key = pxToKey.get(parseFloat(numStr));
+    if (key === void 0) continue;
+    const varName = varNameFor(key);
+    replacements.set(`${prop}: ${numStr}px`, `${prop}: var(${varName})`);
+    declarations.set(varName, `${numStr}px`);
+  }
+  const transformRe = /(translateX|translateY)\((\d+(?:\.\d+)?)px\)/g;
+  while ((m = transformRe.exec(usedCSS)) !== null) {
+    const [, fn, numStr] = m;
+    const key = pxToKey.get(parseFloat(numStr));
+    if (key === void 0) continue;
+    const varName = varNameFor(key);
+    replacements.set(`${fn}(${numStr}px)`, `${fn}(var(${varName}))`);
+    declarations.set(varName, `${numStr}px`);
+  }
+  return { replacements, declarations };
+}
+function prettifyCSS(css) {
+  const out = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of css) {
+    if (ch === "{") {
+      const selector = current.trim();
+      if (selector) out.push(`${"  ".repeat(depth)}${selector} {`);
+      depth++;
+      current = "";
+    } else if (ch === "}") {
+      const decl = current.trim();
+      if (decl) out.push(`${"  ".repeat(depth)}${decl};`);
+      depth = Math.max(0, depth - 1);
+      out.push(`${"  ".repeat(depth)}}`);
+      current = "";
+    } else if (ch === ";") {
+      const decl = current.trim();
+      if (decl) out.push(`${"  ".repeat(depth)}${decl};`);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  const trailing = current.trim();
+  if (trailing) out.push(trailing);
+  return out.join("\n");
+}
 function formatKbachCSS(tokenCSS, theme, responsiveRe) {
   const allRaw = [...tokenCSS.values()].filter(Boolean).join("\n");
-  const { replacements, declarations } = buildColorVarMap(theme, allRaw);
+  const colorVars = buildColorVarMap(theme, allRaw);
+  const spacingVars = buildSpacingVarMap(theme, allRaw);
+  const replacements = new Map([...colorVars.replacements, ...spacingVars.replacements]);
+  const declarations = new Map([...colorVars.declarations, ...spacingVars.declarations]);
   const sortedReplacements = [...replacements].sort(([a], [b]) => b.length - a.length);
   function applyVars(css) {
     for (const [pattern, replacement] of sortedReplacements)
@@ -3156,7 +3243,7 @@ function formatKbachCSS(tokenCSS, theme, responsiveRe) {
     if (!css) continue;
     const label = classifyToken(token, responsiveRe);
     if (!groups.has(label)) groups.set(label, []);
-    groups.get(label).push(applyVars(css));
+    groups.get(label).push(prettifyCSS(applyVars(css)));
   }
   const out = ["/* Generated by Kbach \u2014 do not edit */"];
   if (declarations.size > 0) {
@@ -3167,13 +3254,13 @@ function formatKbachCSS(tokenCSS, theme, responsiveRe) {
   const globalCSS = buildThemeGlobal(theme);
   if (globalCSS) out.push(`
 /* Global */
-${globalCSS}`);
+${prettifyCSS(globalCSS)}`);
   for (const label of GROUP_ORDER) {
     const items = groups.get(label) ?? [];
     if (!items.length) continue;
     out.push(`
 /* ${label} */`);
-    out.push(items.join("\n"));
+    out.push(items.join("\n\n"));
   }
   return out.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbach/react",
-  "version": "0.6.17",
+  "version": "0.6.20",
   "description": "React / React Native components and hooks for the Kbach framework",
   "source": "./src/index.ts",
   "main": "./dist/index.js",