@kbach/react 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -1,32 +1,11 @@
 # @kbach/react
 
-A utility-first styling engine for React, powered by a real Rust/WASM core.
-Kbach aims for full [Tailwind CSS v4](https://tailwindcss.com) feature
-parity — grid, transforms, filters, gradients, animations, container
-queries, arbitrary values, and a parameterized variant system (`has-*`,
-`data-*`, `aria-*`, `not-*`, generalized `group-*`/`peer-*`, and more) — with
-its own 22-family + metals color palette as the one deliberate difference.
-
-> **Beta.** The API is close to stable but may still change before `1.0.0`.
-> Feedback and issues are very welcome.
-
-## Why Kbach
-
-- **A real engine, not a lookup table.** Every class is resolved by the same
-  Rust/WASM core at build time (via the Vite plugin) and at runtime (via
-  `kb()`), so build-time and runtime output can never drift apart.
-- **Static by default.** The Vite plugin scans your source and writes a real,
-  plain `kbach.css` file — no runtime style injection needed, no
-  flash-of-unstyled-content, no client-side CSS-in-JS overhead.
-- **Dark mode that works without a provider.** Toggle/set/subscribe to dark
-  mode from anywhere — a plain function, an event handler, a component that
-  never wants React Context — with an optional `<ThemeProvider>` as a thin
-  wrapper around the exact same store.
-- **Composable by nature.** Utility class strings are just strings — combine
-  them with plain arrays, ternaries, or template literals. No bespoke
-  composition API required.
-
-## Installation
+A utility-first styling engine for React, powered by a Rust/WASM core.
+Tailwind CSS v4 feature parity, plus Kbach's own color palette.
+
+> Beta — API may still change before 1.0.0.
+
+## Install
 
 ```sh
 npm install @kbach/react
@@ -34,9 +13,6 @@ npm install @kbach/react
 
 ## Quick start
 
-Add the Vite plugin so your utility classes are resolved to real CSS at
-build time:
-
 ```ts
 // vite.config.ts
 import { defineConfig } from 'vite';
@@ -48,71 +24,222 @@ export default defineConfig({
 });
 ```
 
-Create `src/kbach.css` with the markers the plugin writes between, and
-import it once:
-
-```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 />);
 ```
 
-Then just use utility classes:
-
 ```tsx
 <div className="flex items-center gap-4 bg-blue-6 text-white p-4 rounded-lg">
   Hello Kbach
 </div>
 ```
 
-## Dark mode
+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 },
+]);
 
-Works standalone, with zero provider:
+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 { useGlobalDarkMode, toggleGlobalDarkMode } from '@kbach/react';
+import './kbach.css';
+export default function App() {
+  return <Outlet />;
+}
+```
 
-function ThemeToggle() {
-  const isDark = useGlobalDarkMode();
-  return <button onClick={toggleGlobalDarkMode}>{isDark ? 'Dark' : 'Light'}</button>;
+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>
+  );
 }
 ```
 
-Or opt into the optional `<ThemeProvider>` / `useTheme()` pair — both read
-and write the exact same global store, so they always stay in sync with the
-standalone functions above:
+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
+
+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:
+
+```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.
+
+```js
+// kbach.config.js — build-time, read by the Vite/PostCSS plugin
+export default { darkMode: 'attribute' };
+```
 
 ```tsx
-import { ThemeProvider, useTheme } from '@kbach/react';
+// app entry (e.g. root.tsx / main.tsx) — runtime, same value as above
+import { applyKbachConfig, useTheme } from '@kbach/react';
 
-function Toggle() {
+applyKbachConfig({ darkMode: 'attribute' }); // call once, before first render
+
+function ThemeToggle() {
   const { mode, isDark, setMode, toggle } = useTheme();
   return <button onClick={toggle}>{mode}</button>;
 }
-
-<ThemeProvider defaultMode="system">
-  <Toggle />
-</ThemeProvider>;
 ```
 
-## Theming
+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'`.
 
-Customize the color palette, spacing scale, breakpoints, and dark-mode
-strategy via `setTheme()` (call once, before your first render) — the same
-theme object is used by both the runtime and the Vite plugin, so the two
-never fall out of sync:
+## Theming
 
 ```ts
 import { setTheme, defaultTheme } from '@kbach/react';
@@ -123,22 +250,52 @@ setTheme({
 });
 ```
 
-## Runtime & dynamic classes
+## Dynamic classes
 
-Every class name that appears literally in your source is resolved at build
-time. For a class name assembled from truly dynamic data (e.g. user input)
-with no static occurrence anywhere in your source, call `kb()` — it resolves
-and injects the CSS at runtime and returns the class name unchanged:
+Classes that appear literally in your source are resolved at build time.
+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`);
 ```
 
-If you're using the static build (the default with the Vite plugin), prefer
-a `safelist` entry in the plugin config for known-but-dynamic values instead
-— it keeps everything static with zero runtime cost.
+Prefer a `safelist` entry in the plugin config when the possible values are
+known ahead of time — keeps everything static, no `initKbach()` needed.
+
+## Reading colors as values
+
+For anywhere you need a real color, not a `className` (an SVG `fill`, a
+chart library prop):
+
+```tsx
+import { useColors } from '@kbach/react';
+
+const colors = useColors();
+colors.blue[6];       // '#2563eb' — static, same value in both modes
+colors.blue['6/50'];  // same, at 50% opacity
+colors.surface;       // 'rgb(var(--kb-color-surface))' if defined as light/dark
+```
+
+Any color — a shade-family entry like `blue-6` or a standalone name like
+`surface` — can be defined in the theme as a plain string (static) or a
+`{ light, dark }` pair, fully manual:
+
+```ts
+setTheme({
+  ...defaultTheme,
+  colors: { ...defaultTheme.colors, surface: { light: '#f9fafb', dark: '#111827' } },
+});
+```
+
+A plain color always resolves to its literal value. A `{ light, dark }`
+color resolves to a live CSS variable instead of a fixed hex — it stays
+correct across theme changes with zero re-render.
 
 ## License
 

package/dist/chunk-4Y2QXNJY.mjs

@@ -0,0 +1,115 @@
+import {
+  defaultTheme,
+  setTheme
+} from "./chunk-EOSN5CYG.mjs";
+
+// 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 resolved = {};
+  const lookup = (name) => resolved[name] ?? existing[name];
+  for (const [name, value] of Object.entries(extend)) {
+    resolved[name] = resolveColorEntry(value, lookup);
+  }
+  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);
+  return theme;
+}
+
+export {
+  parseHexRgb,
+  ensureColorVariablesInjected,
+  resolveKbachConfig,
+  applyKbachConfig
+};

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

@@ -284,14 +284,15 @@ var defaultTheme = {
   // Real Tailwind's default spacing scale in full — every step is exactly
   // `n * 4px` (Tailwind's base spacing unit), including the fractional
   // `.5` steps (`1.5` -> 6px, `2.5` -> 10px, `3.5` -> 14px) and the "px"
-  // literal (a bare 1px, for `p-px`-style hairline spacing). Previously
-  // this only had {0,1,2,4,6,8} — a handful of spot-checked values, not
-  // the real scale — so anything else (`p-3`, `w-5`, `border-2`, `gap-10`,
-  // ...) silently failed to resolve (an unknown spacing key returns `None`
-  // the same way an unknown class does, with no error). "0" itself is
-  // still needed explicitly (not derivable as "any number * 4") for the
-  // same reason it always was: `sticky top-0` needs an actual "0" key to
-  // resolve at all, not just fall through as unresolvable.
+  // literal (a bare 1px, for `p-px`-style hairline spacing). This table is
+  // only the "usual stops", though — the Rust/JS engines' shared
+  // `spacing_px`/`spacingPx` helper falls back to Tailwind v4's own live
+  // `n * 4px` formula for any bare numeric step NOT listed here (`p-0.25`,
+  // `gap-1.75`, `w-13`, ...), so this table exists to name the common
+  // values and give a theme customization something to override, not to
+  // enumerate every resolvable step. "px" is the one exception that must
+  // stay listed explicitly — it isn't a number, so the formula can't
+  // derive it.
   spacing: {
     "0": 0,
     "px": 1,
@@ -336,7 +337,33 @@ var defaultTheme = {
     xl: 1280,
     "2xl": 1536
   },
-  darkMode: "attribute"
+  // Byte-for-byte the same three stacks
+  // packages/core-engine/src/resolvers/typography.rs's `font_family_value`
+  // falls back to — kept here too (rather than leaving this empty and
+  // relying purely on the Rust-side fallback) so `defaultTheme.fontFamily.sans`
+  // is a real, readable value for anything that wants to extend rather
+  // than replace it (see `KbachConfig.extend.fontFamily` in config.ts).
+  fontFamily: {
+    sans: 'ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
+    serif: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+    mono: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace'
+  },
+  // Matches real Tailwind's own default (`darkMode: 'media'`): pure
+  // `@media (prefers-color-scheme: dark)`, works with zero JS — a project
+  // using only static `className` strings gets working `dark:` classes
+  // out of the box, with no runtime import required to write `data-theme`/
+  // `.dark` onto `<html>` (see darkModeStore.ts's `applyToDom`). The
+  // tradeoff: `'media'` can't be overridden by a manual light/dark toggle —
+  // `useTheme()`/`toggleGlobalDarkMode()` still track `isDark` correctly
+  // for JS consumers, but flipping it has no visible effect on `dark:`
+  // classes, since the browser's media query only ever reflects the real
+  // OS setting. Opt into `darkMode: 'class'` or `'attribute'` explicitly
+  // (via `kbach.config.js` or the `config`/`theme` plugin option) as soon
+  // as an app wants a real in-app toggle.
+  darkMode: "media",
+  // Empty by default, matching real Tailwind's own defaults (no forced
+  // centering/padding) — see `ContainerConfig`'s own doc comment.
+  container: {}
 };
 var activeTheme = defaultTheme;
 var activeThemeJson = JSON.stringify(defaultTheme);