@kbach/react-native 1.0.0-beta.4 → 1.0.0-beta.41

package/README.md

@@ -1,173 +1,125 @@
 # @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). 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
+
+| Target | What to do |
+| :-- | :-- |
+| **Expo Go** | Nothing. A pure-JS fallback engine loads automatically. |
+| **Expo Web** / `react-native-web` | Nothing. Resolves through the same CSS engine `@kbach/react` uses. |
+| **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 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:
+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.
-
-### 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 bridge
-  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}>`).
 
-```tsx
-import { ThemeProvider, useTheme } from '@kbach/react-native';
+## Colors as values
 
-function Toggle() {
-  const { mode, isDark, setMode, toggle } = useTheme();
-  return <Pressable onPress={toggle}><Text>{mode}</Text></Pressable>;
-}
+For a real color string rather than a class — a chart prop, a shadow color:
 
-<ThemeProvider defaultMode="system">
-  <Toggle />
-</ThemeProvider>;
+```tsx
+import { useColors } from '@kbach/react-native';
+
+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).
+
+Expo Go covers a documented subset of utilities (no grid, filters,
+gradients, or DOM-only typography). Expo Web and a real dev-client build
+cover the full set.
+
+See [AGENTS.md](https://github.com/semsakadanupol/kbach/blob/main/AGENTS.md)
+for the complete reference — modifier list, `calc()`/`min()`/`max()`
+support, dynamic tokens, monorepo setup, and how the engine works.
 
 ## License
 

package/dist/chunk-3AY4XSVY.mjs

@@ -0,0 +1,40 @@
+import {
+  resolveClassName
+} from "./chunk-A3PV4XGK.mjs";
+
+// src/jsxRuntimeCoreWeb.ts
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+function makeElement(isStaticChildren, type, props, key) {
+  return (isStaticChildren ? _jsxs : _jsx)(type, props, key);
+}
+function processElement(resolveClassName2, type, rawProps, key, isStaticChildren) {
+  if (type === null || typeof type === "symbol" || !rawProps) {
+    return makeElement(isStaticChildren, type, rawProps ?? {}, key);
+  }
+  const { className: classStrRaw, dataSet: userDataSet, ...rest } = rawProps;
+  if (typeof classStrRaw !== "string") {
+    return makeElement(isStaticChildren, type, rawProps, key);
+  }
+  const resolved = resolveClassName2(classStrRaw);
+  const dataSet = { ...userDataSet, kb: resolved };
+  return makeElement(isStaticChildren, type, { ...rest, className: classStrRaw, dataSet }, key);
+}
+function createJsxFunctionsWeb(resolveClassName2) {
+  function jsx2(type, props, key) {
+    return processElement(resolveClassName2, type, props, key, false);
+  }
+  function jsxs2(type, props, key) {
+    return processElement(resolveClassName2, type, props, key, true);
+  }
+  return { jsx: jsx2, jsxs: jsxs2 };
+}
+
+// src/jsx-runtime.web.tsx
+var { jsx, jsxs } = createJsxFunctionsWeb(resolveClassName);
+
+export {
+  Fragment,
+  jsx,
+  jsxs
+};