@kbach/react-native 1.0.0-beta.7 → 1.0.0-beta.9

package/README.md

@@ -2,34 +2,19 @@
 
 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.
+resolved to a `StyleSheet`-ready style object instead of injected 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 native wiring required.
 
-## Setup
+## Install
 
 ```sh
 npm install @kbach/react-native
 ```
 
-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.
-
 ### React Native CLI
 
-Add the Babel plugin so your app's JSX routes through Kbach's JSX runtime
-instead of `react/jsx-runtime`:
-
 ```js
 // babel.config.js
 module.exports = {
@@ -38,188 +23,104 @@ module.exports = {
 };
 ```
 
-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:
+Rebuild the Android app afterward so Gradle picks up the native module.
+
+### Expo Go
+
+Works out of the box — no prebuild, no dev client, nothing to configure.
+Expo Go can't load third-party native code, so this falls back to a pure-JS
+engine automatically. Covers layout, spacing, border/radius, plain colors,
+font-weight, text-transform/decoration, line-height, letter-spacing, and
+shadows. Doesn't cover grid, transforms, filters, gradients, or DOM-only
+typography — same scope native itself excludes.
+
+### Expo (dev client / prebuild)
+
+Gets you the full native engine instead of the JS fallback:
 
 ```js
 // babel.config.js
 module.exports = {
-  presets: ['babel-preset-expo'], // not '@react-native/babel-preset'
+  presets: ['babel-preset-expo'],
   plugins: ['@kbach/react-native/babel-plugin'],
 };
 ```
 
 ```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
+npx expo prebuild
+npx expo run:android
 ```
 
-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).
+Requires the New Architecture enabled (`"newArchEnabled": true` in
+`app.json`, on by default in current Expo SDKs). EAS Build works the same
+way, no extra config.
 
 ### 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"`
-(client bundles) and `"node"` (Expo Router's static-rendering/SSR bundles
-— a genuinely separate resolution axis from `platform: 'web'`, see
-`nativeBridge.web.ts`'s own doc comment) export conditions; 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.
-
-#### Expo Router static rendering: `dark:`/responsive on the FIRST paint
-
-If you use [static rendering](https://docs.expo.dev/router/reference/static-rendering/)
-(`web.output: "static"` — Expo Router's SSR/pre-render feature), any
-`dark:`/`sm:`/etc. class on content that's part of the **initial,
-pre-rendered HTML** resolves against whatever the **server** (Node.js, no
-real display/viewport) reports — not the visiting browser's actual OS
-preference or window size. React's hydration then adopts that
-server-rendered markup as-is rather than silently overwriting it with the
-client's own (correct) values, because a `style`-attribute-only difference
-doesn't fail hydration the way a text-content mismatch does. Concretely: a
-user with their OS in dark mode can see a `dark:` class resolve to its
-*light* value on first paint, with no error or warning anywhere.
-
-**This isn't a Kbach bug** — it's the same fundamental constraint every
-OS-preference-based styling system has under SSR (Next.js's own dark-mode
-docs describe the identical problem and fix). The standard fix applies
-here unchanged: don't resolve preference-dependent classes on
-initially-server-rendered content at all; defer them to after your app has
-mounted client-side, e.g.:
+Works out of the box — resolves through the same real-CSS engine
+`@kbach/react` uses on the DOM, with full modifier support (`hover:`,
+`focus:`, `group-hover:`, container queries, etc.), not just the
+`dark:`/`active:`/responsive subset native supports.
+
+**Static rendering (SSR) caveat:** `dark:`/responsive classes on content
+that's part of the initial pre-rendered HTML resolve against the *server*,
+not the visiting browser — so a user in dark mode can briefly see the light
+version on first paint. Defer preference-dependent classes until mounted:
 
 ```tsx
-import { useEffect, useState } from 'react';
-import { Text, View } from 'react-native';
-
-function ThemedScreen() {
-  const [mounted, setMounted] = useState(false);
-  useEffect(() => setMounted(true), []);
-
-  // Neutral on the server AND on the client's first paint (matches exactly,
-  // no hydration mismatch) — only becomes preference-aware once mounted.
-  return (
-    <View className={mounted ? 'bg-gray-1 dark:bg-gray-12' : 'bg-gray-1'}>
-      <Text>Hello</Text>
-    </View>
-  );
-}
-```
+const [mounted, setMounted] = useState(false);
+useEffect(() => setMounted(true), []);
 
-Content that only ever renders client-side (not part of the statically
-pre-rendered route) is unaffected — this only matters for what's visible
-before your first `useEffect` runs.
-
-## 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.
+<View className={mounted ? 'bg-gray-1 dark:bg-gray-12' : 'bg-gray-1'} />;
+```
 
 ## Dark mode
 
-Works standalone, with zero provider — same architecture as `@kbach/react`:
-
 ```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();
+  return <Pressable onPress={toggle}><Text>{mode}</Text></Pressable>;
 }
 ```
 
-Or the optional `<ThemeProvider>` / `useTheme()` pair, reading and writing
-the exact same global store:
+Works anywhere, no provider needed. `<ThemeProvider defaultMode="dark">` is
+optional, for seeding a startup default. Outside React, use
+`getGlobalDarkMode()`/`toggleGlobalDarkMode()` instead.
+
+Follows the OS setting live until overridden, and isn't persisted across
+app launches (no built-in storage dependency). To persist, read your own
+storage at startup and call `setGlobalThemeMode()` before your first render.
+
+## Reading colors as values
+
+For anywhere you need a real color, not a `className` — a chart prop, a
+native shadow color:
 
 ```tsx
-import { ThemeProvider, useTheme } from '@kbach/react-native';
+import { useColors } from '@kbach/react-native';
 
-function Toggle() {
-  const { mode, isDark, setMode, toggle } = useTheme();
-  return <Pressable onPress={toggle}><Text>{mode}</Text></Pressable>;
-}
+const colors = useColors();
+colors.blue[6];       // '#2563eb' — static, same value in both modes
+colors.blue['6/50'];  // same, at 50% opacity
+```
+
+Any color can be defined in the theme as a plain string (static) or a
+`{ light, dark }` pair — fully manual, resolved per the current dark-mode
+state:
 
-<ThemeProvider defaultMode="system">
-  <Toggle />
-</ThemeProvider>;
+```ts
+setTheme({
+  ...defaultTheme,
+  colors: { ...defaultTheme.colors, brand: { light: '#2563eb', dark: '#93c5fd' } },
+});
 ```
 
-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.
+A shade-family lookup (`colors.blue[n]`) auto-mirrors to shade `13 - n` in
+dark mode — this palette's own convention is 1 = lightest, 12 = darkest, so
+that's the same visual weight relative to its own background, no manual
+`colors.blue[isDark ? 7 : 6]` needed.
 
 ## License
 

package/dist/{chunk-OJQAJLYT.mjs → chunk-DOWW44F7.mjs}

@@ -1,6 +1,6 @@
 import {
   resolveStyle
-} from "./chunk-FG5E4NLJ.mjs";
+} from "./chunk-SY5OAY2C.mjs";
 import {
   createJsxFunctions
 } from "./chunk-DLIXI5OW.mjs";