@kbach/react-native 1.0.0-beta.51 → 1.0.0-beta.53

package/AGENTS.md

@@ -9,6 +9,23 @@ cross-package overview, `kbach.config.js` reference, the color palette,
 and how the underlying engine is built, see the repo root's
 [AGENTS.md](https://github.com/semsakadanupol/kbach/blob/main/AGENTS.md).
 
+> **Before writing a single class here, know these three things —
+> Tailwind familiarity actively misleads on all three:**
+>
+> 1. Color shades are `1`–`12` (lightest→darkest), not Tailwind's
+>    `50`–`950` — `bg-blue-500` resolves to nothing; the real class is
+>    `bg-blue-6`. Full palette: root AGENTS.md §7.
+> 2. `group-*`, `peer-*`, `has-[…]`, container queries, grid, and pseudo-
+>    elements (`before:`/`after:`) are real Tailwind syntax that PARSES
+>    here but applies **zero style, with no warning** — native has no
+>    cascade/DOM to support them. See §4's "Not supported" list. A typo
+>    DOES warn; an unsupported-but-valid utility does not — don't assume
+>    silence means it worked.
+> 3. The babel plugin (§1 below) is required on **every** target,
+>    including Expo Go — without it `className` does literally nothing,
+>    silently, no error. This is the single most common real setup bug
+>    reported against this package.
+
 ---
 
 ## 1. Install + setup
@@ -220,6 +237,23 @@ Outside React: `getGlobalDarkMode()` / `toggleGlobalDarkMode()` /
   engine (a space splits the class token). Use underscores if you want them
   for readability: `w-[calc(100%_-_3rem)]`.
 
+### 7.1 Arbitrary values elsewhere — same px/rem-only rule
+
+Not just `calc()`: any arbitrary value RN needs as a plain number (font
+size, spacing, radii, ...) follows the identical rule. `text-[20px]` and
+`text-[1.5rem]` work (`rem` × 16, same as everywhere else); `text-[2em]`,
+`text-[50%]`, `text-[10vh]`/`text-[10vw]` don't — `em` needs the parent's
+own cascaded font-size and `%`/viewport units need real layout, neither
+of which exists at native resolve time — dropped with the same dev-only
+`console.warn`, never a crash. Identical on Expo Go's JS-fallback engine
+(`jsEngine/resolveStyle.ts` mirrors `resolve_style.rs`'s `rn_style_value`
+exactly). Web (including Expo Web) has none of this restriction — real
+CSS resolves every unit natively.
+
+**`text-[…]` specifically needs `< 1.0.0-beta.52` excluded** — every
+arbitrary `text-[…]` value, including a plain `text-[10px]`, silently
+resolved nothing at all on native/Expo Go before that version (see §13).
+
 ## 8. Dynamic tokens (native counterpart to CSS custom properties)
 
 ```tsx
@@ -275,7 +309,7 @@ colors.get('brand');   // a custom color, typed as plain `string`
 
 `colors.blue[6]` returns the same value in both light and dark mode
 unless `blue-6` itself is defined in the theme as a `{ light, dark }` pair
-(§5.1 of the root AGENTS.md) — define a color as mode-aware in
+(§6.1 of the root AGENTS.md) — define a color as mode-aware in
 `kbach.config.js` if you want it to differ by mode.
 
 `colors.brand` (a custom flat color) is typed `string | ColorScale`
@@ -312,10 +346,11 @@ and `react` at `projectRoot/node_modules/...`. A plain non-monorepo
 `setDynamicToken`, `getDynamicToken`, `deleteDynamicToken`,
 `subscribeDynamicTokens`, `useDynamicToken`, `clsx`, `getGlobalDarkMode`,
 `getGlobalThemeMode`, `setGlobalThemeMode`, `toggleGlobalDarkMode`,
-`subscribeGlobalDarkMode`. Types: `ThemeConfig`, `ColorEntry`,
-`ContainerConfig`, `StyleObject`, `KbachConfig`, `ThemeState`,
-`ThemeProviderProps`, `ThemeStorageAdapter`, `ThemeMode`, `ColorsAPI`,
-`ColorScale`, `ClassValue`.
+`subscribeGlobalDarkMode`, `Button`, `Paragraph`, `H1`, `H2`, `H3`, `H4`,
+`H5`, `H6` (§14). Types: `ThemeConfig`, `ColorEntry`, `ContainerConfig`,
+`StyleObject`, `KbachConfig`, `ThemeState`, `ThemeProviderProps`,
+`ThemeStorageAdapter`, `ThemeMode`, `ColorsAPI`, `ColorScale`,
+`ClassValue`, `ButtonProps`, `ParagraphProps`, `HeadingProps`.
 
 Subpath exports: `@kbach/react-native/babel-plugin`,
 `@kbach/react-native/jsx-runtime`, `@kbach/react-native/jsx-dev-runtime`.
@@ -345,6 +380,19 @@ Subpath exports: `@kbach/react-native/babel-plugin`,
   missing. It's required on every target, not just Android/dev-client
   builds; without it nothing routes `className` through this package's
   jsx-runtime at all, so RN just silently ignores the unrecognized prop.
+- **`useColors().get('yourCustomColor')` returns the literal name, not
+  the color, on Expo Web — icons/fills using it render invisible** —
+  stale `@kbach/react-native` (`< 1.0.0-beta.53`). Root cause: on web,
+  this package loads as two separate module instances in the same
+  bundle — a bare `import` resolves through package.json's `import`
+  condition, but the babel plugin's injected
+  `require('@kbach/react-native').applyKbachConfig(...)` always resolves
+  through `require` — so `kbach.config.js`'s custom colors landed in one
+  instance's theme state while every component's own `useColors()` read
+  the other, untouched one. Fixed by routing `theme.ts`'s active-theme
+  state through a `globalThis`-backed slot instead of a plain
+  module-scope variable, so both instances share it regardless of which
+  one set it. Update.
 - **`ERROR [Error: Unable to find node on an unmounted component.]` on
   Expo Fast Refresh, especially right after editing `kbach.config.js`** —
   stale `@kbach/react-native` (`< 1.0.0-beta.51`). Root cause: the babel
@@ -359,3 +407,53 @@ Subpath exports: `@kbach/react-native/babel-plugin`,
   React Native Fast Refresh race. `setTheme` is idempotent by content
   since beta.51 (compares against the theme's own JSON serialization
   before replacing it); update.
+- **`text-[10px]` (or any other arbitrary `text-[…]` value) does nothing
+  on native or Expo Go** — stale `@kbach/react-native` (`< 1.0.0-beta.52`).
+  The native dispatcher's `resolve_text_native` (`resolvers/mod.rs`) never
+  got the arbitrary-value length check `color::resolve_text` (web) already
+  had — an arbitrary value skipped the font-size/align lookup entirely and
+  fell straight through to color resolution, which correctly rejected
+  "10px" as not a real color and silently dropped the whole declaration.
+  Fixed identically in both the Rust native dispatcher and its Expo Go JS-
+  fallback mirror (`jsEngine/resolveUtilityNative.ts`) in beta.52; update.
+  Web (including Expo Web) was never affected.
+
+## 14. Semantic HTML on Expo Web
+
+On Expo Web, `react-native-web` renders a bare `<View>`/`<Text>` as a
+plain `<div>`/`<span>` by default — confirmed directly in its own source.
+That's **not** a Kbach limitation: this package's jsx-runtime never reads
+or substitutes the JSX element type at all, so whatever tag shows up is
+exactly whatever component the app wrote.
+
+`react-native-web` already has a real fix for this that this package
+never gets in the way of: an `accessibilityRole`/`role` prop on ANY host
+component makes it render the matching real HTML element instead —
+`accessibilityRole="button"` → `<button>`, `accessibilityRole="header"` +
+`aria-level` (web-only; real native has no heading-LEVEL concept, only
+`header` itself) → `<h1>`-`<h6>`, `role="paragraph"` → `<p>`, and so on
+(`react-native-web`'s own `propsToAccessibilityComponent`). `role` covers
+every value in React Native's own typed `Role` union (`button`,
+`heading`, `list`, `listitem`, `navigation`, `main`, `form`, `article`,
+`banner`, `contentinfo`, `complementary`, `region`, ...); `"paragraph"`
+is the one react-native-web additionally supports that isn't in that
+union at all.
+
+This package exports a handful of convenience components that are just
+that prop, pre-set on the right underlying component — nothing beyond
+that, and writing `<Pressable accessibilityRole="button">` directly
+instead of `<Button>` behaves identically:
+
+```tsx
+import { Button, Paragraph, H1, H2, H3, H4, H5, H6 } from '@kbach/react-native';
+
+<Button className="px-4 py-2 rounded bg-blue-6" onPress={...}>Save</Button>
+<H1 className="text-2xl font-bold">Page title</H1>
+<Paragraph className="text-sm text-gray-7">Body copy.</Paragraph>
+```
+
+`className` keeps working on every one of these exactly like it does on
+a bare `Pressable`/`Text`. No `Div` or `Input` here on purpose: a plain
+`<View>` already is the right generic container, and `<TextInput>`
+already renders a real `<input>` (or `<textarea>` when `multiline`) by
+default, with no role needed at all.

package/README.md

@@ -145,6 +145,22 @@ colors.blue['6/50'];   // same at 50% opacity
 colors.get('brand');   // a custom color, typed as plain `string`
 ```
 
+## Semantic HTML on web
+
+On Expo Web, `<View>`/`<Text>` render as a plain `<div>`/`<span>` by
+default (`react-native-web`'s own choice, not this package's). For a real
+`<button>`/`<h1>`-`<h6>`/`<p>` instead, use these — each is just the
+right underlying component with its semantic role pre-set, so `className`
+keeps working exactly like it does on a bare `Pressable`/`Text`:
+
+```tsx
+import { Button, H1, Paragraph } from '@kbach/react-native';
+
+<H1 className="text-2xl font-bold">Page title</H1>
+<Paragraph className="text-sm text-gray-7">Body copy.</Paragraph>
+<Button className="px-4 py-2 rounded bg-blue-6" onPress={...}>Save</Button>
+```
+
 ## What differs on native
 
 React Native has no CSS cascade, so a fixed subset of modifiers is

package/dist/{chunk-KHQ2BWYH.mjs → chunk-3JQAZNJK.mjs}

@@ -1,6 +1,6 @@
 import {
   getTheme
-} from "./chunk-IJAXJVB4.mjs";
+} from "./chunk-P75PP2QR.mjs";
 
 // src/darkModeStore.ts
 import { Appearance } from "react-native";