@kbach/react-native 1.0.0-beta.1 → 1.0.0-beta.11

package/README.md

@@ -2,27 +2,18 @@
 
 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, Android-only.** Resolution runs through a Kotlin/JNI TurboModule
-> calling the same Rust core `@kbach/react` uses, so class semantics stay
-> identical across web and native. The native module ships prebuilt (see
-> Setup below) — no Rust toolchain or manual native wiring required — but
-> there's no iOS bridge yet.
+> 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
 ```
 
-That pulls in [`@kbach/android`](https://www.npmjs.com/package/@kbach/android)
-too — the actual native module — as a real dependency. Android's
-autolinking discovers it automatically the moment it's in `node_modules`;
-no manual `MainApplication.kt` edit needed.
-
-Add the Babel plugin so your app's JSX routes through Kbach's JSX runtime
-instead of `react/jsx-runtime`:
+### React Native CLI
 
 ```js
 // babel.config.js
@@ -32,74 +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).
-
-## 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 — iOS's discrete
-  `shadowColor`/`shadowOffset`/`shadowOpacity`/`shadowRadius` and Android's
-  `elevation`, both derived from the same named tiers (`sm`/`DEFAULT`/`md`/
-  `lg`/`xl`/`2xl`) `@kbach/react`'s CSS `box-shadow` scale uses — one class
-  produces a real shadow on both platforms. `shadow-inner` and arbitrary
-  `shadow-[...]` values aren't supported — neither platform's native shadow
-  API can express an inset shadow, and an arbitrary value is a raw CSS
-  string with no mechanical translation into discrete native props.
+Rebuild the Android app afterward so Gradle picks up the native module.
 
-## Dark mode
+### 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'],
+  plugins: ['@kbach/react-native/babel-plugin'],
+};
+```
+
+```sh
+npx expo prebuild
+npx expo run:android
+```
+
+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.
 
-Works standalone, with zero provider — same architecture as `@kbach/react`:
+### Expo Web
+
+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 { useGlobalDarkMode, toggleGlobalDarkMode } from '@kbach/react-native';
+const [mounted, setMounted] = useState(false);
+useEffect(() => setMounted(true), []);
 
-function ThemeToggle() {
-  const isDark = useGlobalDarkMode();
-  return <Pressable onPress={toggleGlobalDarkMode}><Text>{isDark ? 'Dark' : 'Light'}</Text></Pressable>;
-}
+<View className={mounted ? 'bg-gray-1 dark:bg-gray-12' : 'bg-gray-1'} />;
 ```
 
-Or the optional `<ThemeProvider>` / `useTheme()` pair, reading and writing
-the exact same global store:
+## Dark mode
 
 ```tsx
-import { ThemeProvider, useTheme } from '@kbach/react-native';
+import { useTheme } from '@kbach/react-native';
 
-function Toggle() {
+function ThemeToggle() {
   const { mode, isDark, setMode, toggle } = useTheme();
   return <Pressable onPress={toggle}><Text>{mode}</Text></Pressable>;
 }
+```
+
+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 { useColors } from '@kbach/react-native';
+
+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/android/build.gradle

@@ -0,0 +1,36 @@
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+apply plugin: "com.facebook.react"
+
+def getExtOrDefault(name) {
+    return rootProject.ext.has(name) ? rootProject.ext.get(name) : null
+}
+
+android {
+    // NOT "com.kbachnative" — that's the app module's own namespace (Phase 5
+    // deliberately made the app's package match KbachModule's Kotlin package
+    // for simpler JNI symbol names), and AGP requires unique namespaces per
+    // module. This is purely a Gradle build-identity value, separate from
+    // the actual `package com.kbachnative` declared in the .kt files below —
+    // JNI symbol resolution depends on that Kotlin package, not this.
+    namespace "com.kbachnative.nativemodule"
+    compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+    defaultConfig {
+        minSdkVersion getExtOrDefault("minSdkVersion")
+        targetSdkVersion getExtOrDefault("targetSdkVersion")
+    }
+}
+
+repositories {
+    google()
+    maven {
+        // All of React Native (JS, Obj-C sources, Android binaries) is installed from npm.
+        url "$rootDir/../node_modules/react-native/android"
+    }
+    mavenCentral()
+}
+
+dependencies {
+    implementation "com.facebook.react:react-native:+"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,14 @@
+<!--
+  Deliberately NO `package="..."` attribute here, even though this
+  module's Kotlin package (com.kbachnative, see KbachModule.kt) differs
+  from its Gradle build.gradle `namespace` (com.kbachnative.nativemodule)
+  — adding one here to help React Native's autolinking guess the right
+  Kotlin package (see react-native.config.js at this package's root, which
+  fixes that instead) breaks the actual Gradle build on AGP 9+: it now
+  hard-errors ("Setting the namespace via the package attribute in the
+  source AndroidManifest.xml is no longer supported") whenever the
+  manifest's package doesn't match the namespace exactly. If you're
+  tempted to add one back to fix an autolinking symbol-resolution error,
+  fix react-native.config.js's packageImportPath/packageInstance instead.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/com/kbachnative/KbachModule.kt

@@ -0,0 +1,83 @@
+package com.kbachnative
+
+import com.facebook.react.bridge.ReactApplicationContext
+
+/**
+ * Bridges to the same Rust core engine every other Kbach platform uses
+ * (packages/core-engine) — via JNI here instead of WASM. The native
+ * `generateCss`/`resolveStyle` externs below (in the companion object) must
+ * match `Java_com_kbachnative_KbachModule_generateCss`/`resolveStyle`'s
+ * signatures exactly (packages/core-engine/src/jni_bridge.rs): STATIC
+ * native methods (hence @JvmStatic in a companion object, not instance
+ * methods — the Rust side takes JClass, not JObject, as its second
+ * parameter).
+ *
+ * TurboModule since Phase 13 (was the legacy bridge's
+ * `isBlockingSynchronousMethod` support directly on `ReactContextBaseJavaModule`
+ * before) — extends the Codegen-generated `NativeKbachModuleSpec`
+ * (packages/react-native/specs/NativeKbachModule.ts -> this package's own
+ * codegenConfig in package.json, discovered via autolinking ->
+ * android/build/generated/source/codegen/java/com/kbachnative/NativeKbachModuleSpec.java),
+ * which already provides `getName()` and declares `generateCss`/`resolveStyle`
+ * as abstract `@ReactMethod(isBlockingSynchronousMethod = true)` methods —
+ * Codegen still routes a synchronously-returning TurboModule method through
+ * that same Android bridge mechanism; the real gain here is JSI-backed
+ * dispatch + build-time type checking against the JS spec, not the removal
+ * of `isBlockingSynchronousMethod` as a concept.
+ *
+ * The companion's JNI externs are named `nativeGenerateCss`/`nativeResolveStyle`
+ * — NOT the same names as the spec's `generateCss`/`resolveStyle` overrides.
+ * Tried keeping identical names first (disambiguated via an explicit
+ * `Companion.generateCss(...)` qualifier) since that would've meant zero
+ * Rust changes, but that fails to compile: `@JvmStatic` duplicates each
+ * companion function directly onto the outer class for Java-interop
+ * purposes, which collides at the JVM bytecode level with the identically-
+ * named, identically-shaped instance override ("platform declaration
+ * clash"), regardless of how the Kotlin-source call site is qualified. The
+ * rename requires matching `Java_com_kbachnative_KbachModule_nativeGenerateCss`/
+ * `nativeResolveStyle` `#[no_mangle]` export names in
+ * packages/core-engine/src/jni_bridge.rs — JNI's implicit symbol linking
+ * binds by the extern's own method name, not by whatever calls it.
+ *
+ * Moved here from apps/native-sandbox/android/app in Phase 13 — Android
+ * autolinking only discovers native modules from npm dependencies with
+ * their own `android/` folder, never from native code declared directly
+ * inside the app itself, so `KbachModule` had to become a real (locally
+ * `file:`-linked) package to be found by `TurboModuleRegistry.getEnforcing`.
+ * Originally that "real package" was a separate `@kbach/android` npm
+ * package; later folded directly into `@kbach/react-native` (this
+ * package's own `android/` folder, sibling to its `src/`) once it became
+ * clear the same autolinking requirement is satisfied just as well by a
+ * SINGLE npm package containing both JS and native code — the same layout
+ * react-native-safe-area-context itself uses — so consumers only ever run
+ * one `npm install @kbach/react-native`, not two.
+ */
+class KbachModule(reactContext: ReactApplicationContext) : NativeKbachModuleSpec(reactContext) {
+
+    companion object {
+        init {
+            System.loadLibrary("kbach_core_engine")
+        }
+
+        @JvmStatic
+        external fun nativeGenerateCss(classString: String, themeJson: String): String
+
+        @JvmStatic
+        external fun nativeResolveStyle(classString: String, themeJson: String, colorScheme: String, pressed: Boolean, width: Double): String
+    }
+
+    override fun generateCss(classString: String, themeJson: String): String {
+        return nativeGenerateCss(classString, themeJson)
+    }
+
+    /**
+     * `colorScheme` ("light"/"dark", from Appearance.getColorScheme() on the
+     * JS side) gates whether `dark:` declarations are applied; `pressed`
+     * (only ever true when the caller is RN's Pressable) gates `active:`;
+     * `width` (the JS side's current `Dimensions.get('window').width`) gates
+     * `sm:`/`md:`/`lg:`/`xl:`/`2xl:` against the theme's `screens` scale.
+     */
+    override fun resolveStyle(classString: String, themeJson: String, colorScheme: String, pressed: Boolean, width: Double): String {
+        return nativeResolveStyle(classString, themeJson, colorScheme, pressed, width)
+    }
+}

package/android/src/main/java/com/kbachnative/KbachPackage.kt

@@ -0,0 +1,54 @@
+package com.kbachnative
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * `BaseReactPackage` (not plain `ReactPackage`) since Phase 13's TurboModule
+ * migration — a plain `ReactPackage`'s `createNativeModules()`-provided
+ * modules stay visible to the legacy `NativeModules` interop but are never
+ * consulted by `TurboModuleRegistry`'s resolution path, which only walks
+ * packages that can answer `getModule(name, ...)` directly. Modeled on
+ * react-native-safe-area-context's own `SafeAreaContextPackage.kt` (a real,
+ * New-Architecture-compatible package already in this project's
+ * dependencies) rather than reflection over a `@ReactModule` annotation —
+ * KbachModule doesn't have one, and there's only ever this one module, so
+ * building its `ReactModuleInfo` directly is simpler than adding an
+ * annotation just to read it back via reflection.
+ *
+ * Auto-discovered via Android autolinking, not manually registered in
+ * apps/native-sandbox's MainApplication.kt — same as SafeAreaContextPackage
+ * already was, and the entire reason this module became a real npm package
+ * with its own `android/` folder (this one — `@kbach/react-native` itself,
+ * see KbachModule.kt's own doc comment) in Phase 13 rather than living
+ * inside the app.
+ */
+class KbachPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return if (name == NativeKbachModuleSpec.NAME) KbachModule(reactContext) else null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider {
+            mapOf(
+                NativeKbachModuleSpec.NAME to
+                    ReactModuleInfo(
+                        NativeKbachModuleSpec.NAME,
+                        KbachModule::class.java.name,
+                        false, // canOverrideExistingModule
+                        false, // needsEagerInit
+                        false, // isCxxModule
+                        true, // isTurboModule
+                    )
+            )
+        }
+    }
+
+    override fun createViewManagers(reactContext: ReactApplicationContext): List<ViewManager<*, *>> {
+        return emptyList()
+    }
+}

package/dist/chunk-4DQXTAM3.mjs

@@ -0,0 +1,63 @@
+import {
+  getGlobalDarkMode
+} from "./chunk-RBJXE32L.mjs";
+
+// src/jsxRuntimeCore.ts
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment } from "react";
+import { Pressable } from "react-native";
+function makeElement(isStaticChildren, type, props, key) {
+  return (isStaticChildren ? _jsxs : _jsx)(type, props, key);
+}
+function resolvedStyleFor(resolveStyle, classStrRaw, userStyle, pressed) {
+  const resolved = resolveStyle(classStrRaw, pressed);
+  if (userStyle === void 0) {
+    return resolved;
+  }
+  if (typeof userStyle === "function") {
+    return [resolved, userStyle({ pressed })];
+  }
+  return [resolved, userStyle];
+}
+var DARK_MODIFIER_RE = /(^|\s)dark:/;
+function darkModeKeySuffix(classStrRaw) {
+  return DARK_MODIFIER_RE.test(classStrRaw) ? `:kb-dark-${getGlobalDarkMode()}` : "";
+}
+function processElement(resolveStyle, type, rawProps, key, isStaticChildren) {
+  if (type === null || typeof type === "symbol" || !rawProps) {
+    return makeElement(isStaticChildren, type, rawProps ?? {}, key);
+  }
+  const { className: classStrRaw, style: userStyle, ...rest } = rawProps;
+  if (typeof classStrRaw !== "string") {
+    return makeElement(isStaticChildren, type, rawProps, key);
+  }
+  const finalStyle = type === Pressable ? (state) => resolvedStyleFor(resolveStyle, classStrRaw, userStyle, state.pressed) : resolvedStyleFor(resolveStyle, classStrRaw, userStyle, false);
+  const suffix = darkModeKeySuffix(classStrRaw);
+  const finalKey = suffix ? `${key ?? ""}${suffix}` : key;
+  return makeElement(isStaticChildren, type, { ...rest, style: finalStyle }, finalKey);
+}
+function createJsxFunctions(resolveStyle) {
+  function jsx(type, props, key) {
+    return processElement(resolveStyle, type, props, key, false);
+  }
+  function jsxs(type, props, key) {
+    return processElement(resolveStyle, type, props, key, true);
+  }
+  return { jsx, jsxs };
+}
+function createJsxDEV(jsx, jsxs) {
+  return function jsxDEV(type, props, key, isStaticChildren, source, self) {
+    const element = (isStaticChildren ? jsxs : jsx)(type, props, key);
+    if (source && element && typeof element === "object" && Object.isExtensible(element)) {
+      element._source = source;
+      element._self = self;
+    }
+    return element;
+  };
+}
+
+export {
+  Fragment,
+  createJsxFunctions,
+  createJsxDEV
+};

package/dist/chunk-5MU6PEXV.mjs

@@ -0,0 +1,14 @@
+import {
+  resolveStyle
+} from "./chunk-XHL653X2.mjs";
+import {
+  createJsxFunctions
+} from "./chunk-4DQXTAM3.mjs";
+
+// src/jsx-runtime.tsx
+var { jsx, jsxs } = createJsxFunctions(resolveStyle);
+
+export {
+  jsx,
+  jsxs
+};