@kbach/react-native 1.0.0-beta.20 → 1.0.0-beta.22

package/README.md

@@ -58,9 +58,10 @@ way, no extra config.
 ### 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.
+`@kbach/react` uses on the DOM, with the FULL modifier set (`group-hover:`,
+`peer-hover:`, container queries, `has-[...]:`, etc.) — everything real
+Tailwind supports. Native supports a smaller, explicitly-scoped subset; see
+"Modifiers on native" below for exactly what that covers.
 
 **Static rendering (SSR) caveat:** `dark:`/responsive classes on content
 that's part of the initial pre-rendered HTML resolve against the *server*,
@@ -124,6 +125,38 @@ module.exports = config; // (React Native CLI: mergeConfig(getDefaultConfig(proj
 A single, non-monorepo `npm install` never hits this — only relevant if your
 app and `@kbach/react-native` share a workspace root.
 
+## Modifiers on native
+
+Native has no CSS selector/cascade engine, so only a fixed, explicitly
+supported set of modifiers actually applies — everything else (`group-*:`,
+`peer-*:`, `has-[...]:`, `aria-*:`, `data-*:`, container queries, ...)
+parses without error but never takes effect. Supported today:
+
+- **`dark:`** — reacts to the OS/app color scheme, see "Dark mode" below.
+- **`sm:`/`md:`/`lg:`/`xl:`/`2xl:`** — reacts to `useWindowDimensions()`
+  crossing the matching `theme.screens` breakpoint (rotation/resize/fold).
+- **`active:`** — `Pressable`'s own press state, via its style-callback API.
+- **`hover:`** — tracked via `onHoverIn`/`onHoverOut`, which RN only ever
+  fires on a platform with real pointer input (iOS 13+/Android/macOS/
+  Windows via a mouse/trackpad/Apple Pencil hover) — inert (never fires) on
+  a touch-only device, the same way real Tailwind's `hover:` already
+  degrades on a touch-only *browser*. Composing it onto any host type is
+  harmless even where it never fires.
+- **`focus:`** — tracked via `onFocus`/`onBlur` (keyboard/external-keyboard/
+  TV-remote/tab navigation, and `TextInput` focus).
+- **`disabled:`** — reads the element's own `disabled` prop directly; no
+  event tracking needed, since a prop change already re-renders normally.
+- Any combination of the above chained on one class (`sm:dark:bg-blue-8`,
+  `hover:focus:opacity-100`) requires every named condition to hold at once
+  — chain order never matters (`dark:sm:` and `sm:dark:` are equivalent).
+
+`group-hover:`/`peer-hover:` and friends are NOT implemented on native —
+doing so needs a React Context bridge (propagating an ancestor's hover/
+press/focus state down to descendants, since there's no `.group`/`.peer`
+selector relationship to lean on) that doesn't exist today. If you need
+group/peer-style coordination on native right now, lift the shared state
+into a parent component yourself and pass it down as an explicit prop.
+
 ## Dark mode
 
 ```tsx
@@ -140,8 +173,26 @@ 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.
+app launches by default (no forced storage dependency). To persist, pass
+any async key-value store exposing `getItem`/`setItem` as `<ThemeProvider
+persist>` — `@react-native-async-storage/async-storage`'s default export
+already matches this shape exactly:
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { ThemeProvider } from '@kbach/react-native';
+
+<ThemeProvider persist={AsyncStorage}>
+  <App />
+</ThemeProvider>;
+```
+
+The persisted mode (if any) is read once on mount and wins over
+`defaultMode`; every later explicit choice is written back automatically.
+`false` by default — this package still never imports a storage library
+itself, so nothing changes for apps that don't opt in. Prefer wiring your
+own storage manually instead? `setGlobalThemeMode()` before your first
+render still works exactly as before.
 
 ## Reading colors as values
 
@@ -189,12 +240,15 @@ way — no such unit exists on native at all. It already works fine on web
 (real CSS); on native the declaration is dropped and a `console.warn`
 explains why (dev builds only).
 
-**Percentage-relative width/height** (`calc(100%-3rem)`, `calc(50%+16px)`)
-IS supported, differently: since native has no way to know "100% of what"
-ahead of time, this measures the element's own real layout instead —
+**Percentage-relative width/height** (`calc(100%-3rem)`, `calc(50%+16px)`,
+`min(50%,20rem)`, `max(1rem,5%)`, `clamp(16rem,50%,32rem)`) IS supported,
+differently: since native has no way to know "100% of what" ahead of time,
+this measures the element's own real layout instead —
 
 ```tsx
 <View className="w-[calc(100%_-_3rem)]" />
+<View className="w-[min(50%,20rem)]" />        // half the parent, capped at a fixed size
+<View className="w-[clamp(16rem,50%,32rem)]" />
 ```
 
 Renders once at a plain `100%` (a real RN percentage, resolved correctly by
@@ -203,9 +257,14 @@ event, then immediately corrects to the actual computed number once
 measured — a genuine one-frame measure-then-snap, not instant math like the
 constant-only case above, and it keeps re-measuring on every layout (screen
 rotation, parent resize, ...) rather than freezing after the first value.
-Scoped to exactly one percentage term plus one constant term on `width`/
-`height` only — `calc(50%-50%)`, other properties, or anything with `*`/`/`
-falls through to the same drop-and-warn behavior as before.
+Scoped narrowly, same "reduce fully or bail" philosophy as the constant-only
+case: `calc()` takes exactly one percentage term plus one constant term;
+`min()`/`max()` take two or more comma-separated arguments, each EITHER a
+plain percentage or a constant px/rem expression (not both mixed in one
+argument — `min(50%-1rem,20rem)` is out of scope); `clamp()` takes exactly
+three. `width`/`height` only in every case — other properties, or anything
+that doesn't reduce fully, falls through to the same drop-and-warn behavior
+as before.
 
 **Arbitrary values can't contain literal spaces** — this is a pre-existing
 rule (real Tailwind has the same one), not specific to `calc()`: a space
@@ -264,8 +323,8 @@ On web, `setDynamicToken` writes the real CSS custom property to the DOM —
 every element using it repaints instantly via the browser's own CSS engine,
 no React re-render involved. On native, the className is substituted with
 the token's current value before every resolve, and an element referencing
-a token re-renders/repaints on its own when that specific token changes
-(same `key`-remount mechanism `dark:` and `sm:`/`md:`/... already use — see
+a token re-renders/repaints on its own when that token changes (same
+subscription mechanism `dark:` and `sm:`/`md:`/... already use — see
 `jsxRuntimeCore.ts`'s own doc comments). An unregistered token name falls
 through to the same native invalid-value warning above.