@rootnative/core 0.0.0-alpha.3 → 0.0.0-alpha.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/llms.txt CHANGED
@@ -1,8 +1,8 @@
1
1
  # @rootnative/core — Theme System for React Native
2
2
 
3
- > Version: 0.0.0-alpha.3
4
- > Peer deps: react >=18, react-native >=0.72
5
- > Optional: @material/material-color-utilities >=0.4.0 (for createMaterialTheme)
3
+ > Version: 0.0.0-alpha.31
4
+ > Peer deps: react >=19.3.0 <20.0.0, react-native >=0.88.0 <0.89.0, @rootnative/inertia >=0.0.22 <0.1.0 (required — every animation runs on it)
5
+ > createMaterialTheme needs no extra install — its color engine (@material/material-color-utilities) is bundled behind the create-theme subpath
6
6
 
7
7
  ## Quick Start
8
8
 
@@ -20,6 +20,21 @@ export default function App() {
20
20
 
21
21
  ## API
22
22
 
23
+ ### When to pick which — theme paths
24
+
25
+ Ask this first. Every path below ends in the same `<ThemeProvider theme={...}>`.
26
+
27
+ | You want | Reach for |
28
+ | --- | --- |
29
+ | MD3 defaults, no setup | `<ThemeProvider>` alone (light), or `theme={{ light: lightTheme, dark: darkTheme }}` to follow the OS |
30
+ | A full MD3 palette from one brand color | `createMaterialTheme(seed)` from `@rootnative/core/create-theme` |
31
+ | MD3 with a few token overrides | Spread over `lightTheme` / `darkTheme` (see the custom-theme example under ThemeProvider) |
32
+ | MD3 with sharper or rounder corners | The `roundness` option on `createMaterialTheme`, or `applyRoundness()` on an existing theme |
33
+ | A fully custom design system (your own tokens) | `defineTheme<MyTheme>()` + `useTheme<MyTheme>()` |
34
+ | Light/dark switching and persistence | The `{ light, dark }` pair + `useThemeMode()`; add `storage` to persist |
35
+ | One part of the app with its own colors | A nested `ThemeProvider` with its own pair (see Nested providers) |
36
+ | No light flash for dark readers of a static web export | `schemeGuardScript` + `schemeGuardCss` from `@rootnative/core/static-export` in the HTML shell |
37
+
23
38
  ### ThemeProvider
24
39
 
25
40
  Wrap your app root to supply the theme to all components. Works with any design system — Material Design 3 or custom themes. Defaults to the MD3 light theme when no theme is provided.
@@ -33,8 +48,24 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
33
48
  // Dark theme
34
49
  <ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
35
50
 
36
- // Custom theme
51
+ // Light/dark, following the OS setting
37
52
  import { lightTheme } from '@rootnative/core'
53
+
54
+ <ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
55
+ {children}
56
+ </ThemeProvider>
57
+
58
+ // ...and remembering the user's override across launches
59
+ import AsyncStorage from '@react-native-async-storage/async-storage'
60
+
61
+ <ThemeProvider
62
+ theme={{ light: lightTheme, dark: darkTheme }}
63
+ storage={AsyncStorage}
64
+ >
65
+ {children}
66
+ </ThemeProvider>
67
+
68
+ // Custom theme
38
69
  import type { Theme } from '@rootnative/core'
39
70
 
40
71
  const custom: Theme = {
@@ -45,9 +76,82 @@ const custom: Theme = {
45
76
  ```
46
77
 
47
78
  Props:
48
- - `theme?: BaseTheme` — Theme object. Default: `lightTheme` (MD3)
79
+ - `theme?: BaseTheme | { light: BaseTheme; dark: BaseTheme }` — A single theme, or a light/dark pair. A pair enables `useThemeMode()`. Default: `lightTheme` (MD3)
80
+ - `mode?: 'system' | 'light' | 'dark'` — Controlled mode. Leave unset and use `setMode()` instead. Pair with `onModeChange`. On a static web export, `'system'` renders light on the server and while the client hydrates, then follows the OS on the render after hydration. No hydration gate is needed around it. A dark-scheme reader sees light until hydration ends; see "Static export: the dark first paint (web)". A nested provider with a pair and none of `mode`, `defaultMode` and `storage` follows the mode of its parent; see "Nested providers"
81
+ - `defaultMode?: 'system' | 'light' | 'dark'` — Initial mode when uncontrolled. Default: `'system'`. On a nested provider, setting it gives the provider a mode of its own
82
+ - `onModeChange?: (mode: ThemeMode) => void`
83
+ - `storage?: { getItem, setItem }` — Persists the mode. Any AsyncStorage-shaped object; sync or async. Nothing is persisted unless you pass this. On a nested provider, setting it gives the provider a mode of its own, and it overwrites the mode the root stored: every provider uses the key `THEME_MODE_STORAGE_KEY` (`'rootnative.theme-mode'`)
84
+ - `iconResolver?: IconResolver` — Renders string icon names. Pass `mdiResolver` from `@rootnative/components/mdi` for MaterialDesignIcons, or your own. Without it a string name renders nothing and logs one warning. A nested provider without it uses the resolver of its parent
49
85
  - `children: ReactNode`
50
86
 
87
+ ### useThemeMode()
88
+
89
+ Reads and controls light/dark mode. Requires a provider given a `{ light, dark }` pair — it throws otherwise, since a single-theme provider has no mode to control.
90
+
91
+ Returns `{ mode, scheme, setMode, isReady }`:
92
+ - `mode` — what was asked for, including `'system'`
93
+ - `scheme` — the resolved `'light' | 'dark'` actually rendering. Use this to sync anything outside the theme, such as the status bar
94
+ - `setMode(mode)` — switches mode, and persists it when `storage` is set
95
+ - `isReady` — `false` until a persisted mode has loaded. Always `true` without `storage`. Gate a splash screen on it to avoid a launch flash
96
+
97
+ ```tsx
98
+ import { useThemeMode } from '@rootnative/core'
99
+ import { StatusBar } from 'expo-status-bar'
100
+
101
+ function ThemeToggle() {
102
+ const { scheme, setMode } = useThemeMode()
103
+
104
+ return (
105
+ <>
106
+ <StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
107
+ <Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')}>
108
+ Toggle theme
109
+ </Button>
110
+ </>
111
+ )
112
+ }
113
+ ```
114
+
115
+ ### Nested providers
116
+
117
+ A second `ThemeProvider` inside the root one gives one part of the app its own theme, for example the colors of an image:
118
+
119
+ ```tsx
120
+ import { createMaterialTheme } from '@rootnative/core/create-theme'
121
+
122
+ const themes = useMemo(() => {
123
+ const { lightTheme: light, darkTheme: dark } = createMaterialTheme(seed)
124
+ return { light, dark }
125
+ }, [seed])
126
+
127
+ <ThemeProvider theme={themes}>{children}</ThemeProvider>
128
+ ```
129
+
130
+ What a nested provider takes from its parent:
131
+ - **Icon resolver** — with no `iconResolver`, it uses the resolver of its parent.
132
+ - **Mode** — a nested provider with a pair, below a parent with a pair, follows the mode of the parent when it gets none of `mode`, `defaultMode` and `storage`. `useThemeMode()` below it reports the mode of the parent, and `setMode()` sets the mode of the parent. Pass any of the three props to give it a mode of its own.
133
+ - **Named transitions** — its `MotionConfig` merges with the one above, so the named transitions of the app stay.
134
+
135
+ A nested provider with a single theme has no mode, so `useThemeMode()` throws below it.
136
+
137
+ **An overlay carries the nested theme.** `Dialog`, `Menu`, `Tooltip`, `BottomSheet`, `SearchView`, the modal `NavigationDrawer` and the snackbar render through a `Portal` at the `PortalHost`, which is usually above the nested provider. `Portal` reads the theme, the mode, the icon resolver and the named transitions where you write the overlay, and provides them again at the host, so the overlay surface and every component in its content take the nested theme.
138
+
139
+ ### useThemeScope() and ThemeScopeProvider
140
+
141
+ The pair that `Portal` uses, for content you render at another place yourself, for example through `createPortal` or a third-party modal. `useThemeScope()` reads the theme, the mode, the icon resolver and the motion config of the call site as one `ThemeScope` value. `<ThemeScopeProvider scope={scope}>` provides that value to its children, as if the providers of the call site stood there. A `ThemeProvider` below it inherits from it the same way it inherits from a real parent. Treat `ThemeScope` as opaque.
142
+
143
+ ```tsx
144
+ import { ThemeScopeProvider, useThemeScope } from '@rootnative/core'
145
+
146
+ function MyPortal({ children }) {
147
+ const scope = useThemeScope()
148
+ return createPortal(
149
+ <ThemeScopeProvider scope={scope}>{children}</ThemeScopeProvider>,
150
+ host,
151
+ )
152
+ }
153
+ ```
154
+
51
155
  ### useTheme()
52
156
 
53
157
  Returns the current theme from the nearest `ThemeProvider`.
@@ -72,10 +176,10 @@ Identity function that validates a custom theme object against `BaseTheme`. Prov
72
176
 
73
177
  ```tsx
74
178
  import { defineTheme } from '@rootnative/core'
75
- import type { BaseTheme, TextStyle } from '@rootnative/core'
179
+ import type { BaseTheme, TypographyToken } from '@rootnative/core'
76
180
 
77
181
  interface MyColors { [key: string]: string; brand: string; background: string; text: string }
78
- interface MyTypography { [key: string]: TextStyle; heading: TextStyle; body: TextStyle }
182
+ interface MyTypography { [key: string]: TypographyToken; heading: TypographyToken; body: TypographyToken }
79
183
  interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography }
80
184
 
81
185
  const myTheme = defineTheme<MyTheme>({
@@ -84,9 +188,9 @@ const myTheme = defineTheme<MyTheme>({
84
188
  heading: { fontFamily: 'Inter', fontSize: 24, fontWeight: '700', lineHeight: 32, letterSpacing: 0 },
85
189
  body: { fontFamily: 'Inter', fontSize: 16, fontWeight: '400', lineHeight: 24, letterSpacing: 0.5 },
86
190
  },
87
- shape: { roundness: 1, cornerNone: 0, cornerExtraSmall: 4, cornerSmall: 8, cornerMedium: 12, cornerLarge: 16, cornerExtraLarge: 28, cornerFull: 9999 },
191
+ shape: { roundness: 1, cornerNone: 0, cornerExtraSmall: 4, cornerSmall: 8, cornerMedium: 12, cornerLarge: 16, cornerExtraLarge: 28, cornerFull: 999 },
88
192
  spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
89
- stateLayer: { pressedOpacity: 0.12, focusedOpacity: 0.12, hoveredOpacity: 0.08, disabledOpacity: 0.38 },
193
+ stateLayer: { pressedOpacity: 0.1, focusedOpacity: 0.1, hoveredOpacity: 0.08, draggedOpacity: 0.16, disabledOpacity: 0.38, disabledContainerOpacity: 0.12 },
90
194
  elevation: { ... },
91
195
  motion: { ... },
92
196
  })
@@ -99,9 +203,29 @@ Generates a complete MD3 light and dark theme from a single seed color. Uses Goo
99
203
  Defaults are byte-identical to the upstream MD3 `material-color-utilities` library — pure spec output.
100
204
 
101
205
  **Spec-aligned options:**
102
- - `variant?: 'tonalSpot' | 'neutral' | 'vibrant' | 'expressive' | 'fidelity' | 'content' | 'monochrome' | 'rainbow' | 'fruitSalad'` — MD3 scheme variant (default `'tonalSpot'`, the Material You default on Android 12+). Each is a spec-defined recipe for deriving the palette. Use `'monochrome'` for spec-legal pure-grey themes, `'vibrant'` for high-colorfulness, etc.
206
+ - `variant?: 'tonalSpot' | 'neutral' | 'vibrant' | 'expressive' | 'fidelity' | 'content' | 'monochrome' | 'rainbow' | 'fruitSalad'` — MD3 scheme variant (default `'tonalSpot'`, the Material You default on Android 12+). Each is a spec-defined recipe for deriving the palette. Use `'monochrome'` for spec-legal pure-grey themes, `'vibrant'` for high-colorfulness, etc. **Two variants move the primary hue away from your seed — see the table below.**
207
+
208
+ **Does the variant keep the seed hue?**
209
+
210
+ Ask this first if the seed is a brand color. `expressive` and `fruitSalad` rotate the primary hue by design — this is correct MD3 behavior, not a defect, but it means the generated `primary` is not your brand color. Example results for the seed `#E07A3F` (a strong orange):
211
+
212
+ | Variant | Light `primary` | Keeps the seed hue? |
213
+ | --- | --- | --- |
214
+ | `tonalSpot` | `#8d4e2a` | Yes |
215
+ | `neutral` | — | Yes (low chroma) |
216
+ | `vibrant` | `#9d4300` | Yes |
217
+ | `expressive` | `#585799` | **No — rotates to blue-violet** |
218
+ | `fidelity` | `#9b450b` | Yes — also returns the seed as `primaryContainer` |
219
+ | `content` | `#9b450b` | Yes |
220
+ | `monochrome` | — | Yes (chroma 0) |
221
+ | `rainbow` | `#984714` | Yes |
222
+ | `fruitSalad` | `#974066` | **No — rotates to magenta** |
223
+
224
+ Use `fidelity`, `content`, or `tonalSpot` to keep the seed hue. Pick `expressive` for colorfulness only when the palette does not have to match a brand color.
225
+
226
+ **`fidelity` pins `primaryContainer` to the seed in both modes.** With `variant: 'fidelity'` the seed is returned as `primaryContainer` in the light theme **and** the dark theme (`onPrimaryContainer` stays dark in both). This is upstream MD3 fidelity behavior: the scheme holds the source color exactly. Every other container role gets darker in dark mode, so a bright container with dark text can break the surface ramp. Override `primaryContainer` / `onPrimaryContainer` for the dark theme if the ramp matters more than seed fidelity.
103
227
  - `contrastLevel?: 'standard' | 'medium' | 'high'` — MD3 contrast preset (default `'standard'`). Maps to MD3 contrast values `0 / 0.5 / 1.0`. Use `'medium'` or `'high'` for WCAG AAA / low-vision modes.
104
- - `fontFamily?: string` — Custom font family applied to all 15 typography styles. When omitted, platform defaults are used (Roboto on Android, System on iOS).
228
+ - `fontFamily?: string` — Custom font family applied to all 30 typography styles (15 base + 15 emphasized). When omitted, platform defaults are used (Roboto on Android, System on iOS).
105
229
  - `roundness?: number` — Global corner-radius multiplier. `0` = sharp corners, `1` = default MD3 (default), `2` = double rounding. Does not affect `cornerNone` or `cornerFull`.
106
230
 
107
231
  **Explicit overrides (NOT part of MD3 spec — use only when no built-in `variant` covers your case):**
@@ -135,18 +259,27 @@ createMaterialTheme('#006A6A', { surfaceTone: 'neutral' })
135
259
  // Override: per-palette chroma
136
260
  createMaterialTheme('#006A6A', { seedAdjustments: { primary: 60, secondary: 32 } })
137
261
 
138
- // Use in provider
262
+ // Use in provider — pinned light
139
263
  <ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
140
264
 
141
- // Or with dark mode
142
- <ThemeProvider theme={isDark ? darkTheme : lightTheme}>{children}</ThemeProvider>
265
+ // Or hand both to the provider and let it follow the OS. Rename on
266
+ // destructure so the pair matches the prop's { light, dark } shape.
267
+ const { lightTheme: light, darkTheme: dark } = createMaterialTheme('#006A6A')
268
+
269
+ <ThemeProvider theme={{ light, dark }}>{children}</ThemeProvider>
143
270
  ```
144
271
 
145
272
  Returns: `{ lightTheme: Theme, darkTheme: Theme }`
146
273
 
147
- The generated themes include all 69 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
274
+ The generated themes include all 49 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
275
+
276
+ No extra install is needed: `@material/material-color-utilities` is bundled inside `@rootnative/core`, behind the `create-theme` subpath. Projects that never import the subpath never load it.
148
277
 
149
- Requires `@material/material-color-utilities` as a peer dependency: `npm install @material/material-color-utilities`
278
+ The subpath also imports nothing from `react-native`, so it runs in plain Node — print a palette from a script, check a theme in CI, or feed the roles to a design-token pipeline:
279
+
280
+ ```bash
281
+ node -e "import('@rootnative/core/create-theme').then(({ createMaterialTheme }) => console.log(createMaterialTheme('#006A6A').lightTheme.colors))"
282
+ ```
150
283
 
151
284
  ### applyRoundness(roundness)
152
285
 
@@ -181,29 +314,31 @@ material.defaultTopAppBarTokens
181
314
 
182
315
  ### Theme type hierarchy
183
316
 
184
- - `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TextStyle>`, plus shape, spacing, stateLayer, elevation, motion.
185
- - `Theme` — Material Design 3 theme. Extends `BaseTheme` with 69 MD3 color roles, 30 typography variants (15 base + 15 emphasized), and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
317
+ - `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
318
+ - `Theme` — Material Design 3 theme. Extends `BaseTheme` with 49 MD3 color roles, 30 typography variants (15 base + 15 emphasized), and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
186
319
 
187
320
  ### Theme structure
188
321
 
189
322
  ```
190
323
  BaseTheme {
191
324
  colors: Record<string, string>
192
- typography: Record<string, TextStyle>
325
+ typography: Record<string, TypographyToken>
193
326
  shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
194
327
  spacing: Spacing — xs, sm, md, lg, xl
195
- elevation: Elevation — level0..level3 (shadow properties)
196
- stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, disabledOpacity
328
+ elevation: Elevation — level0..level5 (shadow properties)
329
+ stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
197
330
  motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
198
331
  }
199
332
 
200
333
  Theme extends BaseTheme {
201
- colors: Colors — 69 MD3 color roles
334
+ colors: Colors — 49 MD3 color roles
202
335
  typography: Typography — 30 type scale variants: 15 base (displayLarge..labelSmall) + 15 MD3 Expressive emphasized (displayLargeEmphasized..labelSmallEmphasized)
203
- topAppBar?: TopAppBarTokens
336
+ topAppBar?: TopAppBarTokens — horizontalPadding, titleStartInset, smallContainerHeight, mediumContainerHeight, largeContainerHeight, topRowHeight, sideSlotMinHeight, iconFrameSize, mediumTitleBottomPadding, largeTitleBottomPadding (AppBar geometry in dp)
204
337
  }
205
338
  ```
206
339
 
340
+ `TopAppBarTokens`: `AppBar` follows the Compose `TopAppBarLayout` geometry. The title starts at `max(titleStartInset, horizontalPadding + leading width) + horizontalPadding` from the start edge (16dp with no leading content, 56dp after a 48dp navigation icon), and the last action ends `horizontalPadding` (4dp) from the end edge. No pair of token values puts both on one wider gutter: keep the tokens and pad the bar with `style` (`paddingStart: gutter - horizontalPadding - titleStartInset`, `paddingEnd: gutter - horizontalPadding`).
341
+
207
342
  Colors: primary, onPrimary, primaryContainer, onPrimaryContainer, primaryFixed, onPrimaryFixed, primaryFixedDim, onPrimaryFixedVariant, secondary (same pattern), tertiary (same pattern), error, onError, errorContainer, onErrorContainer, background, onBackground, surface, surfaceDim, surfaceBright, surfaceContainerLowest, surfaceContainerLow, surfaceContainer, surfaceContainerHigh, surfaceContainerHighest, onSurface, surfaceVariant, onSurfaceVariant, outline, outlineVariant, surfaceTint, shadow, scrim, inverseSurface, inverseOnSurface, inversePrimary
208
343
 
209
344
  Typography variants: displayLarge, displayMedium, displaySmall, headlineLarge, headlineMedium, headlineSmall, titleLarge, titleMedium, titleSmall, bodyLarge, bodyMedium, bodySmall, labelLarge, labelMedium, labelSmall — each with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing. Each also has an MD3 Expressive `<name>Emphasized` variant (same size/line height, weight one step heavier: 400→500, 500→700).
@@ -232,3 +367,60 @@ const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
232
367
 
233
368
  Type: `useBreakpointValue<T>(values: Partial<Record<Breakpoint, T>> & Record<'compact', T>): T`
234
369
 
370
+ ### useWindowDimensions()
371
+
372
+ Returns the window size, the same as `useWindowDimensions` from `react-native`, but hydration-safe. Use it instead of the `react-native` hook when a layout needs a number rather than a size class: a hero height, a carousel slot, a column count.
373
+
374
+ ```tsx
375
+ import { useWindowDimensions } from '@rootnative/core'
376
+
377
+ const { width } = useWindowDimensions()
378
+ const heroHeight = width * 0.56
379
+ ```
380
+
381
+ Type: `useWindowDimensions(): ScaledSize`
382
+
383
+ ### Breakpoints and static export (web)
384
+
385
+ The three hooks are hydration-safe, so **no `useHydrated` gate is needed at the call site**. The `useWindowDimensions` hook from `react-native` is **not**: on a static export it keeps the layout of a 0 wide window until the reader resizes the window.
386
+
387
+ A static export (`web.output: 'static'`) renders on a server with no DOM, where react-native-web's `Dimensions` is fixed at `width: 0` — so every breakpoint resolves to `compact` and that is what ships in the HTML. React 19 does **not** repair a `className`/`style` mismatch during hydration: it adopts the server DOM, keeps it, and fires no recoverable error, so a tablet would silently keep the phone layout.
388
+
389
+ `useWindowDimensions` therefore reports the server's 0 by 0 window for as long as the client is hydrating, matching that markup, and switches to the measured window on the re-render React schedules once hydration finishes. `useBreakpoint` reads it, so it reports `compact` for the same span, and a breakpoint and a raw width cannot disagree. On native and on a single-page web build there is no hydration, so the measured value is returned from the first render at no cost.
390
+
391
+ The practical consequence: a breakpoint-dependent layout **starts compact and widens a frame later** on a static export. That is unavoidable — the server cannot know the viewport — so design the compact variant to be the honest first paint. `Grid` inherits all of this, which matters because it resolves a `columns` map internally and leaves a consumer nowhere to put a gate of their own.
392
+
393
+ `ThemeProvider` reads the same hydration flag for `mode="system"`. The export server has no `matchMedia`, so react-native-web reports `'light'` there and the HTML ships the light theme. The provider keeps light while the client hydrates, then switches to the OS scheme on the same re-render as the window size. A reader with a dark system setting sees the light theme until hydration ends, which takes seconds on a phone; the next section hides it. The `useColorScheme` hook from `react-native` is **not** hydration-safe: a theme chosen from it stays light in a dark browser.
394
+
395
+ ### Static export: the dark first paint (web)
396
+
397
+ react-native-web writes each theme color into the HTML as an inline style, and CSS in the HTML shell cannot change an inline style. So on a static export a reader with a dark system setting sees the light page until the script downloads and hydrates: measured at 1.3 s on a fast computer and 5.5 s with a 4× CPU throttle and a 6.4 Mbit/s network, for 2.6 MB of script. A mode that `storage` restores loads after hydration too.
398
+
399
+ `@rootnative/core/static-export` hides that light page. Put its script and its CSS in the HTML shell (`app/+html.tsx` with Expo Router). The script must come before the body:
400
+
401
+ ```tsx
402
+ import { darkTheme } from '@rootnative/core'
403
+ import {
404
+ schemeGuardCss,
405
+ schemeGuardScript,
406
+ } from '@rootnative/core/static-export'
407
+
408
+ const SCHEME_GUARD_CSS = schemeGuardCss({
409
+ background: darkTheme.colors.background,
410
+ })
411
+
412
+ // inside <head>
413
+ <script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
414
+ <style dangerouslySetInnerHTML={{ __html: SCHEME_GUARD_CSS }} />
415
+ ```
416
+
417
+ 1. The script reads the stored mode (`localStorage`, key `THEME_MODE_STORAGE_KEY`), then the OS scheme, and writes the scheme to `<html>` as `data-rootnative-scheme` (`SCHEME_ATTRIBUTE`) before the body paints.
418
+ 2. For the dark scheme, the CSS hides `#root` and paints `background` under it.
419
+ 3. On the first render after hydration, with the stored mode loaded, `ThemeProvider` writes `data-rootnative-theme-ready` (`THEME_READY_ATTRIBUTE`) on `<html>`, and the page shows in the dark theme.
420
+
421
+ A light-scheme reader sees no change. Without JavaScript nothing is hidden. The cost: a dark-scheme reader sees content when hydration ends, so the Largest Contentful Paint is later for that reader. If the theme is not ready after 8 s, the page shows anyway (a failed script).
422
+
423
+ Options:
424
+ - `schemeGuardScript({ storageKey? })` — `storageKey?: string | null`, default `THEME_MODE_STORAGE_KEY`. `null` reads the OS scheme only. The script cannot see a mode that the app controls with `mode`; pass the key the app writes, or `null`
425
+ - `schemeGuardCss({ background, rootSelector?, timeoutMs? })` — `background`: the color under the hidden page, use the dark theme background. `rootSelector`: default `'#root'`, the element Expo hydrates into. `timeoutMs`: default `8000`
426
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rootnative/core",
3
- "version": "0.0.0-alpha.3",
3
+ "version": "0.0.0-alpha.31",
4
4
  "description": "Design-system agnostic theme engine for RootNative UI — a React Native component library. Ships with Material Design 3 out of the box.",
5
5
  "private": false,
6
6
  "sideEffects": false,
@@ -22,12 +22,21 @@
22
22
  "react-native": "./dist/create-theme/index.mjs",
23
23
  "import": "./dist/create-theme/index.mjs",
24
24
  "default": "./dist/create-theme/index.mjs"
25
+ },
26
+ "./static-export": {
27
+ "types": "./dist/static-export/index.d.mts",
28
+ "react-native": "./dist/static-export/index.mjs",
29
+ "import": "./dist/static-export/index.mjs",
30
+ "default": "./dist/static-export/index.mjs"
25
31
  }
26
32
  },
27
33
  "typesVersions": {
28
34
  "*": {
29
35
  "create-theme": [
30
36
  "dist/create-theme/index.d.mts"
37
+ ],
38
+ "static-export": [
39
+ "dist/static-export/index.d.mts"
31
40
  ]
32
41
  }
33
42
  },
@@ -53,32 +62,27 @@
53
62
  "md3"
54
63
  ],
55
64
  "peerDependencies": {
56
- "@material/material-color-utilities": ">=0.4.0",
57
- "@rootnative/inertia": "0.0.2",
58
- "react": ">=18.0.0",
59
- "react-native": ">=0.72.0"
60
- },
61
- "peerDependenciesMeta": {
62
- "@material/material-color-utilities": {
63
- "optional": true
64
- }
65
+ "@rootnative/inertia": ">=0.0.22 <0.1.0",
66
+ "react": ">=19.3.0 <20.0.0",
67
+ "react-native": ">=0.88.0 <0.89.0"
65
68
  },
66
69
  "devDependencies": {
67
70
  "@material/material-color-utilities": "^0.4.0",
68
- "@react-native/babel-preset": "^0.81.5",
69
- "@rootnative/inertia": "0.0.2",
71
+ "@react-native/babel-preset": "^0.88.0",
72
+ "@react-native/jest-preset": "^0.88.0",
73
+ "@rootnative/inertia": "0.0.22",
70
74
  "@testing-library/react-native": "^13.3.3",
71
75
  "@types/jest": "^29.5.14",
72
76
  "@types/react": "^19.0.0",
73
77
  "jest": "^29.7.0",
74
- "react": "19.1.0",
75
- "react-native": "0.81.5",
76
- "react-test-renderer": "19.1.0",
78
+ "react": "19.3.0",
79
+ "react-native": "0.88.0",
80
+ "react-test-renderer": "19.3.0",
77
81
  "tsup": "^8.0.0",
78
82
  "typescript": "^5.0.0"
79
83
  },
80
84
  "scripts": {
81
- "build": "tsup src/index.ts src/create-theme/index.ts --dts --format esm --outDir dist --clean",
85
+ "build": "tsup",
82
86
  "typecheck": "tsc --noEmit",
83
87
  "test": "jest",
84
88
  "lint": "eslint . --max-warnings 0"