@kbach/ui 0.1.0-beta.0

package/README.md

@@ -0,0 +1,473 @@
+# @kbach/ui
+
+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
+
+```
+npm install @kbach/ui
+```
+
+[npm package](https://www.npmjs.com/package/@kbach/ui)
+
+## 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/ui" } }
+```
+
+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 | **[Next.js setup](#nextjs-setup)** — Runtime setup, plus one App Router-specific detail |
+| 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:
+
+**1. Add the plugin:**
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { kbach } from '@kbach/ui/vite';
+
+export default defineConfig({ plugins: [kbach()] });
+```
+
+**2. Create an empty stylesheet with the markers, and import it once:**
+
+```css
+/* src/kbach.css */
+/* kbach:start */
+/* kbach:end */
+```
+
+```ts
+// main.tsx
+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/ui';
+
+export default function Root() {
+  return <ThemeProvider defaultMode="system"><App /></ThemeProvider>;
+}
+```
+
+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`).
+
+```ts
+// vite.config.ts
+import { reactRouter } from '@react-router/dev/vite';
+import { defineConfig } from 'vite';
+import { kbach } from '@kbach/ui/vite'; // omit if using Runtime setup instead
+
+export default defineConfig({ plugins: [kbach(), reactRouter()] });
+```
+
+(React Router library mode — `createBrowserRouter`, no SSR — has no such conflict; set it up like any Vite + React app.)
+
+## Runtime setup
+
+Client-side CSS injection — works with any bundler (Vite, webpack, Turbopack, Metro-for-web, …), no build plugin. Next.js always uses this (see [Next.js setup](#nextjs-setup) below for the one extra detail), or use it on Vite if you'd rather not wire up the plugin yet. This is the whole setup:
+
+```jsx
+import { ThemeProvider, KbachReset } from '@kbach/ui';
+
+export default function Root() {
+  return (
+    <ThemeProvider defaultMode="system">
+      <KbachReset />
+      <App />
+    </ThemeProvider>
+  );
+}
+```
+
+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.
+
+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 above in the same app — pick one.
+
+## Next.js setup
+
+Next.js is always [Runtime setup](#runtime-setup) above — Static CSS doesn't apply (webpack/Turbopack, not Vite). The `tsconfig.json` step from [Setup](#setup) applies as-is; SWC reads `jsxImportSource` the same way Vite does.
+
+The one Next.js-specific detail: render `<KbachReset />` once in the root App Router `layout.tsx` (inside `<head>`, or right after `<ThemeProvider>` opens) so the Server Component HTML has the base reset without waiting on hydration:
+
+```jsx
+// app/layout.tsx
+import { ThemeProvider, KbachReset } from '@kbach/ui';
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <ThemeProvider defaultMode="system">
+          <KbachReset />
+          {children}
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+Without `<KbachReset />` there, expect a flash of raw browser defaults (native button border, arrow-less `<select>`, etc.) on first paint until hydration completes. Utility classes beyond the base reset still wait on hydration either way — a known limitation of the runtime-only path (Static CSS isn't available for webpack/Turbopack), not a per-project bug.
+
+`@kbach/ui`'s compiled output ships its own `"use client"` directive, so App Router Server Components can use `className`, `styled()`, hooks, `<ThemeProvider>`, and `<KbachReset>` directly — no manual `'use client'` wrapper needed anywhere in your own components.
+
+## React Native / Expo setup
+
+Same `npm install @kbach/ui` — 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/ui/babel',
+    ],
+  };
+};
+```
+
+Or the one-liner helper: `const { createKbachConfig } = require('@kbach/ui/native'); module.exports = createKbachConfig();` — identical result. Merging into an existing config: `withKbachBabel({ presets: [...] })`, also from `@kbach/ui/native`. After changing this file, clear the Metro cache: `npx expo start --clear`.
+
+**2. Wrap your app:**
+
+```jsx
+import { ThemeProvider } from '@kbach/ui/native';
+
+export default function App() {
+  return (
+    <ThemeProvider defaultMode="system">
+      <AppContent />
+    </ThemeProvider>
+  );
+}
+```
+
+This is a native-aware `ThemeProvider` — reads `useColorScheme()`/`useWindowDimensions()` automatically, no extra props needed. Import it from `@kbach/ui/native`, not the plain `ThemeProvider` from `@kbach/ui` — 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/ui` 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/ui/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/ui';
+  import { ThemeProvider } from '@kbach/ui/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/ui';
+
+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>
+```
+
+Extra classes at use time via `kb` merge with the base classes.
+
+### cx(...classes)
+
+```jsx
+import { cx } from '@kbach/ui';
+
+<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:
+
+```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()
+
+```js
+const { mode, resolvedMode, isDark, setMode, toggle, config } = useTheme();
+```
+
+| 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 |
+
+### 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/ui';
+
+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:
+
+```ts
+import { useColors, type DefaultColorName } from '@kbach/ui';
+
+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) |
+
+```jsx
+<div className="before:content-['*'] before:text-red-6 relative" />
+```
+
+**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/ui';
+  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/ui/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-ui.md](./kbach-ui.md) — complete utility list, every modifier, all config options, covers web and React Native/Expo.
+
+`@kbach/native` is deprecated and no longer maintained — its last published npm version is frozen as a compatibility shim re-exporting this package. Install `@kbach/ui` directly for new projects.