@kbach/react 0.6.50 → 1.0.0-beta.0

package/README.md

@@ -1,61 +1,55 @@
 # @kbach/react
 
-Tailwind-like utility classes for React (web). Write `className` strings — a custom JSX runtime resolves them at render time. An optional Vite plugin outputs a static `kbach.css` for zero runtime cost.
-
-```jsx
-<div className="bg-white dark:bg-gray-10 p-4 rounded-xl shadow" />
-<div className="bg-blue-7 hover:bg-blue-8 dark:bg-indigo-6 rounded-lg px-6 py-3" />
-<div className="group">
-  <span className="opacity-0 group-hover:opacity-100 transition" />
-</div>
-```
-
-## Install
-
-```
+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
+
+```sh
 npm install @kbach/react
 ```
 
-[npm package](https://www.npmjs.com/package/@kbach/react)
-
-## Setup
-
-One step is always required, then pick **one** of the two setups below — they're independent, don't mix them.
-
-### Step 1 — JSX runtime (always required)
-
-**tsconfig.json:**
-
-```json
-{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@kbach/react" } }
-```
-
-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.
-
-### Which setup do I need?
-
-| Framework | Use |
-|---|---|
-| Vite, React Router library mode, CRA, other Vite-based | **[Static CSS setup](#static-css-setup)** (recommended) — zero runtime cost, catches typos at build time. [Runtime setup](#runtime-setup) is there if you'd rather skip the plugin for now. |
-| React Router, framework mode | **[Static CSS setup](#static-css-setup)** — and skip `@vitejs/plugin-react`, see note in that section |
-| Next.js | **[Runtime setup](#runtime-setup)** — Static CSS doesn't apply (webpack/Turbopack, not Vite) |
-| React Native, Expo | **[React Native / Expo setup](#react-native--expo-setup)** — different setup entirely (Babel preset, not the JSX runtime step above) |
-
-## Static CSS setup
-
-Vite only, and the recommended setup for any Vite-based app — a build-time plugin writes real CSS into a file you import at build time, so nothing is generated client-side and there's zero runtime cost. Three pieces, all required:
+## Quick start
 
-**1. Add the plugin:**
+Add the Vite plugin so your utility classes are resolved to real CSS at
+build time:
 
 ```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()] });
+export default defineConfig({
+  plugins: [kbach(), react()],
+});
 ```
 
-**2. Create an empty stylesheet with the markers, and import it once:**
+Create `src/kbach.css` with the markers the plugin writes between, and
+import it once:
 
 ```css
 /* src/kbach.css */
@@ -63,383 +57,89 @@ export default defineConfig({ plugins: [kbach()] });
 /* kbach:end */
 ```
 
-```ts
+```tsx
 // main.tsx
+import { initKbach } from '@kbach/react';
+import { createRoot } from 'react-dom/client';
+import App from './App';
 import './kbach.css';
-```
-
-This import is what actually switches the app over to Static CSS — the plugin alone only generates the file; without importing it, runtime injection stays active and you get both at once.
-
-**3. Wrap your app — no `<KbachReset />` here, `kbach.css` already includes the reset:**
 
-```jsx
-import { ThemeProvider } from '@kbach/react';
-
-export default function Root() {
-  return <ThemeProvider defaultMode="system"><App /></ThemeProvider>;
-}
+initKbach().then(() => {
+  createRoot(document.getElementById('root')!).render(<App />);
+});
 ```
 
-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 Runtime setup below. 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`).
+Then just use utility classes:
 
-```ts
-// vite.config.ts
-import { reactRouter } from '@react-router/dev/vite';
-import { defineConfig } from 'vite';
-import { kbach } from '@kbach/react/vite'; // omit if using Runtime setup instead
-
-export default defineConfig({ plugins: [kbach(), reactRouter()] });
+```tsx
+<div className="flex items-center gap-4 bg-blue-6 text-white p-4 rounded-lg">
+  Hello Kbach
+</div>
 ```
 
-(React Router library mode — `createBrowserRouter`, no SSR — has no such conflict; set it up like any Vite + React app.)
-
-## Runtime setup
+## Dark mode
 
-Client-side CSS injection — works with any bundler (Vite, webpack, Turbopack, Metro-for-web, …), no build plugin. The right choice for Next.js (Static CSS doesn't apply there), or if you'd rather not wire up a Vite plugin yet. This is the whole setup:
+Works standalone, with zero provider:
 
-```jsx
-import { ThemeProvider, KbachReset } from '@kbach/react';
+```tsx
+import { useGlobalDarkMode, toggleGlobalDarkMode } from '@kbach/react';
 
-export default function Root() {
-  return (
-    <ThemeProvider defaultMode="system">
-      <KbachReset />
-      <App />
-    </ThemeProvider>
-  );
+function ThemeToggle() {
+  const isDark = useGlobalDarkMode();
+  return <button onClick={toggleGlobalDarkMode}>{isDark ? 'Dark' : 'Light'}</button>;
 }
 ```
 
-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).
+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:
 
-Don't also set up Static CSS above in the same app — pick one.
+```tsx
+import { ThemeProvider, useTheme } from '@kbach/react';
 
-## React Native / Expo setup
-
-Same `npm install @kbach/react` — no separate package. Everything below (API, modifiers, color system) is the same import as web; only setup differs.
-
-**1. babel.config.js:**
-
-```js
-module.exports = function (api) {
-  api.cache(true);
-  return {
-    presets: [
-      'babel-preset-expo',
-      '@kbach/react/babel',
-    ],
-  };
-};
-```
-
-Or the one-liner helper: `const { createKbachConfig } = require('@kbach/react/native'); module.exports = createKbachConfig();` — identical result. Merging into an existing config: `withKbachBabel({ presets: [...] })`, also from `@kbach/react/native`. After changing this file, clear the Metro cache: `npx expo start --clear`.
-
-**2. Wrap your app:**
-
-```jsx
-import { ThemeProvider } from '@kbach/react/native';
-
-export default function App() {
-  return (
-    <ThemeProvider defaultMode="system">
-      <AppContent />
-    </ThemeProvider>
-  );
+function Toggle() {
+  const { mode, isDark, setMode, toggle } = useTheme();
+  return <button onClick={toggle}>{mode}</button>;
 }
-```
-
-This is a native-aware `ThemeProvider` — reads `useColorScheme()`/`useWindowDimensions()` automatically, no extra props needed. Import it from `@kbach/react/native`, not the plain `ThemeProvider` from `@kbach/react` — that one has no automatic RN wiring (colors scheme/window width would need to be passed in by hand).
-
-### Platform differences
-
-A handful of utilities are native-only or web-only:
-
-| | |
-|---|---|
-| Native-only | `tint-{color}` (Image/icon tinting), `perspective-{n}`, `backface-hidden`, `text-shadow`/`text-shadow-lg` |
-| Web-only, ignored on native (no warning) | `caret-*` `accent-*` `stroke-*` `fill-*` `touch-*` `float-*` `clear-*` `line-clamp-*` `scroll-*` `animate-*` `transition` `filter` `backdrop-filter` `print:` `before:` `after:` `selection:` `first-letter:` `first-line:` `marker:` `landscape:` `portrait:` `motion-reduce:` `motion-safe:` `contrast-more:` `contrast-less:` `rtl:` `ltr:` `grid` `grid-cols-*` `ring-offset-*` `outline-*` `cursor-*` `bg-gradient-*` |
-
-`ring`/`ring-{n}`/`ring-{color}` is a partial exception — RN has no box-shadow, so it falls back to `borderWidth`/`borderColor`, which *does* affect layout and shares properties with `border-*` (whichever class comes last wins if you combine both).
-
-CSS inheritance doesn't exist in React Native — apply font utilities to each `Text`, or define a styled component once: `const Body = styled(Text, 'font-sans text-gray-10 dark:text-white');`.
-
-### Expo Web / React Native Web
-
-In a browser (Expo Web, Metro web), `@kbach/react` switches to the same CSS-class strategy as plain web automatically:
-
-- RN components substitute to HTML: `View`/`ScrollView`→`div`, `Text`→`span`, `TextInput`→`input`/`textarea`, `Image`→`img`, `Pressable`/`TouchableOpacity`→`div[role=button]`
-- RN-only props (`onChangeText`, `source`, `secureTextEntry`, …) map to HTML equivalents
-- Register more: `registerWebElement(Animated.View, 'div')`
-- Recommended: use the Vite plugin same as [Static CSS setup](#static-css-setup) above — `import { kbach } from '@kbach/react/vite'` — and import `kbach.css` in your entry file, for zero runtime cost on the web target too
-- Not using the Vite plugin (the common case for Expo/Metro web, which has no Vite build step)? Render `<KbachReset />` once near your root — e.g. Expo Router's root `app/_layout.tsx`, inside `<ThemeProvider>`:
-
-  ```jsx
-  import { KbachReset } from '@kbach/react';
-  import { ThemeProvider } from '@kbach/react/native';
-
-  export default function RootLayout() {
-    return (
-      <ThemeProvider defaultMode="system">
-        <KbachReset />
-        <Slot />
-      </ThemeProvider>
-    );
-  }
-  ```
-
-  This ships the base reset as real markup instead of relying solely on the runtime injector.
-
-## Dark mode
-
-`<ThemeProvider>` powers every `dark:` class — detects OS color scheme, persists the user's choice, re-renders on change.
-
-```jsx
-<ThemeProvider
-  defaultMode="system"        // 'light' | 'dark' | 'system'
-  disablePersistence={false}  // true = don't remember across reloads
->
-  <App />
-</ThemeProvider>
-```
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `defaultMode` | `'light' \| 'dark' \| 'system'` | `'system'` | Starting mode |
-| `disablePersistence` | `boolean` | `false` | Skip saving to `localStorage` (web) / `AsyncStorage` (native) |
-| `config` | `FrameworkConfig` | global config | Scope a different config to this subtree |
-
-`darkMode` in `kbach.config.js` picks the matching strategy: `'attribute'` (default), `'class'`, or `'media'` (system-only). Toggle it with `useTheme()`'s `toggle()`/`setMode()` — see [API](#api).
-
-## API
-
-### className / kb
-
-`kb` is an alias for `className` — works on any element.
-
-```jsx
-<button className="bg-blue-7 hover:bg-blue-8 pressed:bg-blue-9 rounded-lg px-4 py-2" />
-```
-
-### styled(Component, classes)
-
-```jsx
-import { styled } from '@kbach/react';
 
-const Card = styled('div', 'bg-white dark:bg-gray-9 rounded-2xl p-6 shadow');
-const Button = styled('button', 'bg-blue-7 hover:bg-blue-8 rounded-xl px-6 py-3');
-
-<Card kb="mt-4">
-  <Button kb="w-full">Submit</Button>
-</Card>
+<ThemeProvider defaultMode="system">
+  <Toggle />
+</ThemeProvider>;
 ```
 
-Extra classes at use time via `kb` merge with the base classes.
-
-### cx(...classes)
+## Theming
 
-```jsx
-import { cx } from '@kbach/react';
-
-<div className={cx('p-4 rounded-xl', isSelected && 'border-2 border-blue-6', isDisabled && 'opacity-50')} />
-```
-
-Falsy values ignored. Also works as pre-built style constants:
+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:
 
 ```ts
-export const container = cx('flex-1 bg-white dark:bg-gray-9 p-4');
-```
-
-### useStyles(classes, state?)
-
-```jsx
-const style = useStyles('bg-blue-6 dark:bg-indigo-6 px-3 py-1 rounded-full');
-const style2 = useStyles('bg-blue-5 pressed:bg-blue-7 rounded-lg', { pressed });
-```
-
-### kb(classes)
-
-Resolve outside a component:
-
-```js
-const cardStyle = kb('bg-white p-4 rounded-xl') as React.CSSProperties;
-```
-
-### useTheme()
+import { setTheme, defaultTheme } from '@kbach/react';
 
-```js
-const { mode, resolvedMode, isDark, setMode, toggle, config } = useTheme();
+setTheme({
+  ...defaultTheme,
+  colors: { ...defaultTheme.colors, brand: '#ff6b35' },
+});
 ```
 
-| Value | Type | Description |
-|---|---|---|
-| `mode` | `'light' \| 'dark' \| 'system'` | User-selected mode |
-| `resolvedMode` | `'light' \| 'dark'` | Resolved after system lookup |
-| `isDark` | `boolean` | `resolvedMode === 'dark'` |
-| `setMode` | `fn` | Set mode explicitly |
-| `toggle` | `fn` | Toggle light/dark |
-| `config` | `ResolvedConfig` | Full resolved config |
+## Runtime & dynamic classes
 
-### useIsDark() / useColors()
-
-```js
-const isDark = useIsDark();
-
-const colors = useColors();
-colors.blue[6]              // '#3b82f6'
-colors.blue['6/50']         // 'rgba(59,130,246,0.5)'
-colors.alpha('#ff6b35', 60) // 'rgba(255,107,53,0.6)'
-```
-
-### Typed theme tokens
-
-`useColors()` and `useSpacing()` are typed against the built-in theme by default (`DefaultColorName`/`DefaultSpacingKey`), so TypeScript autocompletes real color/spacing names and flags a typo (`colors.blu`, `spacing.ful`) as an error — no setup needed if you're on the default theme.
-
-```ts
-import { useSpacing } from '@kbach/react';
-
-const spacing = useSpacing();
-spacing[4]      // 16
-spacing.full    // '100%'
-spacing['1/2']  // '50%'
-```
-
-A customized `kbach.config.js` isn't visible to TypeScript — it's a plain `.js` file loaded at runtime, not a statically-analyzed module — so a project with extra colors or spacing keys needs to widen the type parameter by hand:
+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:
 
 ```ts
-import { useColors, type DefaultColorName } from '@kbach/react';
-
-const colors = useColors<DefaultColorName | 'brand'>();
-colors.brand[6] // now type-checks
-```
-
-This only affects the exported *types* — `useColors()`/`useSpacing()` called with no type argument behave exactly as before at runtime. If existing code was relying on a color/spacing name TypeScript couldn't previously catch (the old types had a blanket `[key: string]: any`), this may surface a new type error — the fix is the escape-hatch pattern above, not a code change.
-
-## Modifiers
-
-Chain in any order: `<div className="dark:sm:hover:p-4" />`
-
-| Category | Modifiers |
-|---|---|
-| Theme | `dark:` `light:` / `not-dark:` |
-| Interactive | `hover:` `focus:` `pressed:` `active:` `disabled:` `checked:` `visited:` `placeholder:` (all have `not-` variants) |
-| Structural | `first:` `last:` `odd:` `even:` `only:` `focus-within:` `focus-visible:` |
-| Pseudo-elements | `before:` `after:` `selection:` `first-letter:` `first-line:` `marker:` |
-| Responsive | `sm:`(576px) `md:`(768px) `lg:`(1024px) `xl:`(1280px) `2xl:`(1536px) |
-| Other | `print:` `landscape:`/`portrait:` `motion-reduce:`/`motion-safe:` `contrast-more:`/`contrast-less:` `rtl:`/`ltr:` `!` (important) |
+import { kb } from '@kbach/react';
 
-```jsx
-<div className="before:content-['*'] before:text-red-6 relative" />
+const className = kb(`bg-${userColor}-6`);
 ```
 
-**Group / peer:**
-
-```jsx
-<div className="group">
-  <span className="opacity-0 group-hover:opacity-100 transition" />
-</div>
-```
-
-Nested groups need names (`group/card`, `group-hover/card:`) or the inner element reacts to whichever `.group` is nearest, not necessarily the one you meant.
-
-## Arbitrary values
-
-```jsx
-<div className="bg-[#6366f1] p-[14px] w-[calc(100%-2rem)] text-[18px]" />
-```
-
-For a property with no named utility: `[property:value]` — e.g. `[mask-type:luminance]`, `[--my-var:10px]`. Underscores become spaces: `[background:url(/a.png)_no-repeat]`.
-
-## Color system
-
-12-shade scale, 1 lightest → 12 darkest: `bg-blue-6`, `text-gray-10`, `border-red-4/50`.
-
-Families: `slate gray zinc neutral stone red orange amber yellow lime green emerald teal cyan sky blue indigo violet purple fuchsia pink rose`
-Special: `transparent` `current` `black` `white`
-Opacity: `bg-blue-6/50` or `bg-blue-6/[0.15]`
-
-## CSS resets
-
-Included in `kbach.css`, runtime injection, and `<KbachReset />` alike:
-
-- Border-box everywhere; `border-*` utilities work without needing `border-solid`
-- `body` margin/padding cleared; headings/`p`/`ul`/`ol`/`a` styling cleared to inherit
-- `img`/`video`/`svg` block + max-width 100%
-- `button`/text inputs/`textarea` stripped of native appearance so `bg-`/`rounded-`/`p-` fully restyle them
-- Checkbox/radio/`select` keep native rendering (just typography/spacing normalized + `accent-color: currentColor`)
-
-## Configuration
-
-```js
-// kbach.config.js
-module.exports = {
-  darkMode: 'attribute', // 'attribute' | 'class' | 'media'
-
-  theme: {
-    colors: { brand: { 1: '#eff6ff', 6: '#3b82f6', 10: '#1e3a5f' } }, // replaces the section
-  },
-
-  extend: {
-    colors: { brand: { 6: '#6366f1' } }, // adds to defaults
-    spacing: { 18: '72px' },
-    screens: { '3xl': '1920px' },
-    fontFamily: { sans: 'Inter, sans-serif' },
-    keyframes: {
-      wiggle: { '0%, 100%': { transform: 'rotate(-3deg)' }, '50%': { transform: 'rotate(3deg)' } },
-    },
-    animation: { wiggle: 'wiggle 1s ease-in-out infinite' },
-  },
-
-  plugins: [
-    ({ addUtility, addVariant, theme }) => {
-      addUtility('border-brand', { borderColor: theme('colors.brand.6'), borderWidth: 2 });
-      addVariant('hocus', ':hover, :focus');
-    },
-  ],
-};
-```
-
-- `fontFamily.sans` set to anything but `'System'` auto-injects `body { font-family: … }`
-- Custom `@keyframes` are used as `animate-{name}`, and can be overridden inline: `animate-[wiggle_2s_ease-in-out]`
-- 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
+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.
 
-[kbach-react.md](./kbach-react.md) — complete utility list, every modifier, all config options, covers web and React Native/Expo.
+## License
 
-`@kbach/native` still exists on npm but is now just a deprecated compatibility shim re-exporting this package — install `@kbach/react` directly for new projects.
+MIT