@kbach/react-native 1.0.0-beta.52 → 1.0.0-beta.54

package/AGENTS.md

@@ -14,7 +14,7 @@ and how the underlying engine is built, see the repo root's
 >
 > 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 §6.
+>    `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
@@ -189,6 +189,24 @@ also unavailable in Expo Go (no full-vocabulary resolver to check against).
 This is also exactly what iOS gets in every build type (§3) — the coverage
 gap isn't Expo-Go-specific, it's "whatever the JS-fallback engine covers."
 
+Within that scope it must match the Rust native engine exactly.
+`src/jsEngine/parity.test.ts` runs class strings through both (Rust via
+`packages/core-engine/dist-node`, so core-engine must be built first) and
+fails on any difference. Extend its `CASES` whenever a native-reaching
+resolver changes in either engine; the 2026-11 Tailwind v4 pass (exact-px
+border widths, `px`, two-axis `translate-*`/`skew-*`, `rotate-none`/
+`scale-none`, `flex-N`, formula `leading-N`, `rounded-xs`/`rounded-4xl`)
+and the Tailwind v4.3 values (`rounded-sm`, the `shadow-*` scale, outlines)
+are covered there. See root AGENTS.md §8.1 for what's web-only by design.
+
+**Rings (`ring-*`, `ring-offset-*`) apply no style on native**, on purpose:
+they're a `var()`-built CSS `box-shadow`. Both engines also drop every CSS
+custom property and `var()`-containing value before building the RN style
+(it used to leak through as keys like `KbRingWidth`). Use `border-*` or
+`shadow-*` for a native focus/selection outline. Text sizes on native set
+`fontSize` only (no Tailwind default line-height); add `leading-*` for an
+explicit native line height.
+
 ## 6. Dark mode
 
 Zero setup on all targets. On native `dark:` is resolved from a live
@@ -309,7 +327,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`
@@ -346,10 +364,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`.
@@ -379,6 +398,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
@@ -403,3 +435,43 @@ Subpath exports: `@kbach/react-native/babel-plugin`,
   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
@@ -191,3 +207,8 @@ for `kbach.config.js` and how the underlying engine is built.
 ## License
 
 MIT
+
+Tailwind CSS is a trademark of Tailwind Labs Inc. Kbach is an independent
+project and is not affiliated with, sponsored by, or endorsed by Tailwind Labs.
+See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the Tailwind CSS
+license notice.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+<!-- GENERATED from the repo root THIRD_PARTY_NOTICES.md by packages/core-engine/scripts/generate-notices.mjs. Edit the root file, then regenerate. -->
+
+# Third-party notices
+
+Kbach is MIT-licensed (see `LICENSE`). It also contains material from the
+project below, used under that project's license.
+
+## Tailwind CSS
+
+Kbach uses Tailwind CSS-compatible utility class names, and some of its
+default theme values (for example the spacing formula and the shadow, radius,
+blur, and line-height scales) are derived from Tailwind CSS.
+
+Tailwind CSS is a trademark of Tailwind Labs Inc. Kbach is an independent
+project and is not affiliated with, sponsored by, or endorsed by Tailwind Labs.
+
+Source: https://github.com/tailwindlabs/tailwindcss
+
+```
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```