@kbach/react-native 1.0.0-beta.5 → 1.0.0-beta.50

package/README.md

@@ -1,179 +1,185 @@
 # @kbach/react-native
 
-Kbach's utility-class styling engine for React Native — the same class
-names as [`@kbach/react`](https://www.npmjs.com/package/@kbach/react),
-resolved to a real `StyleSheet`-ready style object instead of injected CSS.
+Utility-class styling for React Native — the same class names as
+[`@kbach/react`](https://www.npmjs.com/package/@kbach/react), resolved to a
+`StyleSheet`-ready style object instead of CSS.
 
-> **Beta.** Native (Android-only, no iOS bridge yet) resolves through a
-> Kotlin/JNI TurboModule; Expo Web / react-native-web resolves through the
-> same Rust engine compiled to WASM instead — both call the identical
-> resolution logic, so class semantics stay identical everywhere. The
-> native module ships prebuilt (see Setup below) — no Rust toolchain or
-> manual native wiring required on any platform.
+> **Beta.** Native is Android-only (no iOS bridge yet) — on iOS, every
+> build (dev client, CLI, EAS) runs the same reduced-coverage JS-fallback
+> engine as Expo Go, not the full native engine. Ships a prebuilt native
+> module — no Rust toolchain or manual linking.
 
-## Setup
+## Install
 
 ```sh
-npm install @kbach/react-native
+npm install @kbach/react-native@beta
 ```
 
-One package, nothing else to install — the Kotlin TurboModule and its
-prebuilt native `.so` ship inside this same package's own `android/`
-folder. Android's autolinking discovers it automatically the moment it's
-in `node_modules`; no manual `MainApplication.kt` edit needed. Works the
-same way whether your app was created with the React Native CLI or with
-Expo — **except Expo Go**, which can never load this (or any) custom
-native module; see below.
+## Setup
+
+The babel plugin (below) is **required on every target, including Expo
+Go** — it's the only thing that makes `className` get intercepted at all;
+without it, `className` is just an unrecognized prop RN silently ignores
+(no styling, no warning). What differs per target is what happens *after*
+that:
+
+| Target | Setup |
+| :-- | :-- |
+| **Expo Go** | Add the babel plugin (below). A pure-JS fallback engine loads automatically after that — no other setup. |
+| **Expo Web** / `react-native-web` | Add the babel plugin (below). Resolves through the same CSS engine `@kbach/react` uses after that — no other setup. |
+| **Expo dev client / prebuild / EAS** | Add the babel plugin (below), then `npx expo prebuild && npx expo run:android`. |
+| **React Native CLI** | Add the babel plugin (below), then restart Metro with `--reset-cache` and rebuild the app. |
 
-### React Native CLI
+The babel plugin, added to your existing `babel.config.js`:
 
-Add the Babel plugin so your app's JSX routes through Kbach's JSX runtime
-instead of `react/jsx-runtime`:
+```js
+// Expo — keep the function form your project already has:
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['@kbach/react-native/babel-plugin'],
+  };
+};
+```
 
 ```js
-// babel.config.js
+// React Native CLI:
 module.exports = {
   presets: ['module:@react-native/babel-preset'],
   plugins: ['@kbach/react-native/babel-plugin'],
 };
 ```
 
-Then rebuild the Android app (`npm run android`, or a clean Gradle build if
-you're re-running one that's already built) so Gradle picks up the new
-native module. See `apps/native-sandbox` in the
-[repo](https://github.com/semsakadanupol/kbach) for a full working
-reference project, including the Metro config a monorepo setup like this
-one needs (a plain single-app install doesn't need any of that — it's
-only relevant if you're linking packages locally instead of installing
-from npm).
-
-### Expo (native — Android)
-
-**Expo Go can never work with this package, and that isn't specific to
-Kbach.** Expo Go is a single fixed binary Expo pre-builds and ships
-through the app stores, containing only the native code Expo bundled into
-it at their own build time — there is no mechanism for *any* third-party
-package to add native code to it at runtime, whether that's a raw
-TurboModule (what this package uses) or even Expo's own Modules API. This
-is exactly why the **dev client** concept exists: a custom build of your
-app — built once via `expo prebuild`/`expo run:android`, functionally the
-same "real native project" as the CLI path above — that *does* include
-this module:
+A plain JS reload isn't enough after adding the plugin or editing
+`kbach.config.js` — Metro's transform cache doesn't reliably pick up a
+babel config change on its own. Restart with `--reset-cache` (`npx
+react-native start --reset-cache` / `npx expo start --clear`).
+
+Then write classes:
+
+```tsx
+import { View, Text } from 'react-native';
+
+<View className="flex-1 items-center justify-center bg-white dark:bg-black">
+  <Text className="text-lg font-bold">Hello Kbach</Text>
+</View>;
+```
+
+## Theme
+
+Optional. Create `kbach.config.js` at your project root — the babel plugin
+picks it up automatically, no import or `applyKbachConfig()` call needed:
 
 ```js
-// babel.config.js
+// kbach.config.js
 module.exports = {
-  presets: ['babel-preset-expo'], // not '@react-native/babel-preset'
-  plugins: ['@kbach/react-native/babel-plugin'],
+  extend: {
+    colors: {
+      brand: '#ff6b35',
+      surface: 'gray-2',
+      dark: { surface: 'gray-11' }, // makes `bg-surface` mode-aware
+    },
+  },
 };
 ```
 
-```sh
-npx expo prebuild    # generates android/ (and ios/, which this package doesn't support yet)
-npx expo run:android # builds and installs a dev client with the native module included
-```
+It's plain JavaScript — **quote any key containing a hyphen**
+(`'surface-dim': '#121318'`).
 
-Also requires the New Architecture enabled (Expo's default in current SDK
-versions) — the native module is a TurboModule, which doesn't exist under
-the legacy bridge at all. If you're on an older SDK/config with the New
-Architecture off, turn it on in `app.json`
-(`"newArchEnabled": true` under `expo`) before prebuilding.
-
-EAS Build works the same way — it runs the same `prebuild` step, so no
-extra configuration beyond the two steps above.
-
-See `apps/expo-sandbox` in the [repo](https://github.com/semsakadanupol/kbach)
-for a full working reference project covering both this section and Expo
-Web below — including the `metro.config.js` a monorepo setup like this one
-needs (a plain single-app install doesn't need it).
-
-### Expo Web
-
-**Works — no extra setup, no separate package, no init call.** `expo start
---web` (and EAS's web builds) render through `react-native-web` —
-`View`/`Text`/etc. become real DOM elements with real CSS, not a
-Kotlin/JNI bridge, so on web this package resolves classes through the
-same Rust engine [`@kbach/react`](https://www.npmjs.com/package/@kbach/react)
-uses — WASM instead of JNI — automatically. Metro picks the right
-implementation per platform on its own via this package's `"browser"`
-export condition; your app code and JSX never change. The WASM module
-initializes itself eagerly (synchronously, at import time — no `await`
-needed before your first render, unlike a from-scratch WASM setup).
-
-The only thing this doesn't cover on web is an iOS-parity feature gap —
-everything web-side resolves through the exact same
-[`resolve_style.rs`](https://github.com/semsakadanupol/kbach/blob/main/packages/core-engine/src/resolve_style.rs)
-logic real native uses, so see this README's "What this is" section above
-for what's covered.
-
-## What this is
-
-- A JSX runtime (`@kbach/react-native/jsx-runtime`) that intercepts
-  `className`/`kb` props on every element and calls into the native/WASM
-  bridge (whichever platform you're on) to resolve them to a style object,
-  synchronously, on every render.
-- A Babel plugin (`@kbach/react-native/babel-plugin`) that routes your
-  app's own files (never `node_modules`) through that JSX runtime via a
-  per-file `@jsxImportSource` pragma.
-- `setTheme()`/`getTheme()` for customizing the color palette and spacing
-  scale — the same `ThemeConfig` shape `@kbach/react` uses, kept as an
-  independent type here so a native-only project isn't forced to depend on
-  a web-oriented package.
-- `shadow-*` resolves to real native shadows — RN's discrete
-  `shadowColor`/`shadowOffset`/`shadowOpacity`/`shadowRadius` props plus
-  Android's `elevation` (both emitted together; `elevation` is what
-  actually renders a shadow on Android — the `shadow*` props are iOS-only
-  in RN itself, ready for whenever this package gets an iOS bridge),
-  derived from the same named tiers (`sm`/`DEFAULT`/`md`/`lg`/`xl`/`2xl`)
-  `@kbach/react`'s CSS `box-shadow` scale uses. `shadow-inner` and
-  arbitrary `shadow-[...]` values aren't supported — RN's native shadow
-  props can't express an inset shadow, and an arbitrary value is a raw CSS
-  string with no mechanical translation into discrete native props.
-- Responsive breakpoints (`sm:`/`md:`/`lg:`/`xl:`/`2xl:`) — gated live
-  against the current window width (`Dimensions.get('window').width`),
-  same mobile-first "min-width and up" semantics as web, and freely
-  combinable with `dark:`/`active:` (e.g. `dark:md:bg-blue-8`). Call RN's
-  own `useWindowDimensions()` somewhere in your tree to re-render on
-  rotation/resize — same role `useColorScheme()` plays for `dark:` below.
+Full config reference (colors, spacing, breakpoints, fonts, dark mode) is
+in [AGENTS.md](https://github.com/semsakadanupol/kbach/blob/main/AGENTS.md).
 
 ## Dark mode
 
-Works standalone, with zero provider — same architecture as `@kbach/react`:
+Zero setup on every target. `dark:` classes react to the OS setting;
+`useTheme()` gives you a manual toggle:
 
 ```tsx
-import { useGlobalDarkMode, toggleGlobalDarkMode } from '@kbach/react-native';
+import { useTheme } from '@kbach/react-native';
 
-function ThemeToggle() {
-  const isDark = useGlobalDarkMode();
-  return <Pressable onPress={toggleGlobalDarkMode}><Text>{isDark ? 'Dark' : 'Light'}</Text></Pressable>;
-}
+const { mode, isDark, setMode, toggle } = useTheme();
 ```
 
-Or the optional `<ThemeProvider>` / `useTheme()` pair, reading and writing
-the exact same global store:
+Works anywhere, no provider. `<ThemeProvider>` is optional — for seeding a
+startup default and opt-in persistence (`<ThemeProvider persist={AsyncStorage}>`).
+Mount at most one — a second instance logs a dev warning, since dark mode
+is one global store, not scoped per provider.
+
+## Dynamic values
+
+For a value that changes at runtime without touching component state —
+a live accent color, a user-picked theme:
 
 ```tsx
-import { ThemeProvider, useTheme } from '@kbach/react-native';
+import { setDynamicToken, useDynamicToken } from '@kbach/react-native';
+
+setDynamicToken('accent', '#8b5cf6');
 
-function Toggle() {
-  const { mode, isDark, setMode, toggle } = useTheme();
-  return <Pressable onPress={toggle}><Text>{mode}</Text></Pressable>;
-}
+<View className="bg-[var(--accent)]" />; // updates instantly, everywhere it's used
+const accent = useDynamicToken('accent'); // '#8b5cf6' | undefined, reactive
+```
+
+Call `setDynamicToken` from a component's own render (guarded to fire
+once), not from module top-level — see
+[AGENTS.md §8](https://github.com/semsakadanupol/kbach/blob/main/packages/react-native/AGENTS.md)
+for why and the exact pattern.
+
+## Colors as values
+
+For a real color string rather than a class — a chart prop, a shadow color:
+
+```tsx
+import { useColors } from '@kbach/react-native';
 
-<ThemeProvider defaultMode="system">
-  <Toggle />
-</ThemeProvider>;
+const colors = useColors();
+colors.blue[6];        // '#2563eb'
+colors.blue['6/50'];   // same at 50% opacity
+colors.get('brand');   // a custom color, typed as plain `string`
 ```
 
-By default the mode follows the OS `Appearance` setting live until you
-explicitly override it — and **isn't persisted across app launches**.
-There's no React-Native-builtin equivalent of `localStorage`, and adding
-one would mean forcing a real native dependency (e.g.
-`@react-native-async-storage/async-storage`) on every consumer, even ones
-that don't want it. If you want persistence, read your own storage at
-startup and call `setGlobalThemeMode()` with the result before your first
-render — the same "seed once" shape `<ThemeProvider defaultMode>` itself
-uses internally.
+## What differs on native
+
+React Native has no CSS cascade, so a fixed subset of modifiers is
+supported — `dark:`, `sm:`–`2xl:`, `active:`, `hover:`, `focus:`,
+`disabled:`, and `data-[…]:`/`aria-[…]:`. `group-*`/`peer-*`/`has-[…]` and
+container queries parse without error but do not apply. When two classes
+set the same property the more-specific one wins regardless of source
+order (`dark:bg-black bg-white` → black in dark mode).
+
+`hover:` only fires for pointer-capable input (mouse/trackpad) — it's
+inert on pure touch, so don't expect it to do anything on a phone/tablet
+with no attached pointer.
+
+`disabled:`/`aria-[…]:`/`data-[…]:` read that exact element's own props —
+never a parent's, since there's no `group-disabled:`-style cascade to
+inherit through. `<Pressable disabled><Text className="disabled:text-gray-5">`
+does nothing to the `Text`, silently, because `Text` never received a
+`disabled` prop of its own; the prop has to be repeated on whichever
+element the modifier is written on:
+`<Pressable disabled><Text disabled className="disabled:text-gray-5">`.
+
+Expo Go, and iOS in ANY build type (no native engine there yet — see the
+callout at the top), cover the same documented subset of utilities (no
+grid, filters, gradients, or DOM-only typography). Expo Web and a real
+**Android** dev-client/CLI build cover the full set.
+
+A malformed or misused value fails safely — a deduped, dev-only
+`console.warn` naming the offending class and the fix, never a crash or
+silently-wrong output. Confirmed across CSS-injection attempts, invalid
+`calc()` operands, and double-mounting.
+
+`clsx()` — this package's own bundled copy, `import { clsx } from
+'@kbach/react-native'` — composes conditional class strings the same way
+the standalone `clsx` package does. You don't need it for `dark:`/`sm:`/
+etc. (those work as plain classes), but it's there for `isActive &&
+'bg-blue-6'`-style composition.
+
+See [this package's own AGENTS.md](https://github.com/semsakadanupol/kbach/blob/main/packages/react-native/AGENTS.md)
+for the complete reference — modifier list, `calc()`/`min()`/`max()`/
+`clamp()` support, dynamic tokens, monorepo setup, and failure modes; see
+the [root AGENTS.md](https://github.com/semsakadanupol/kbach/blob/main/AGENTS.md)
+for `kbach.config.js` and how the underlying engine is built.
 
 ## License