@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/README.md +77 -13
- package/dist/chunk-OK7DBCK4.mjs +12 -0
- package/dist/{chunk-QQ3ME6R7.mjs → chunk-Y5CU4C2C.mjs} +29 -7
- package/dist/chunk-Y6FXYEAI.mjs +10 -0
- package/dist/create-theme/index.d.mts +1 -1
- package/dist/create-theme/index.mjs +5152 -19
- package/dist/index.d.mts +267 -10
- package/dist/index.mjs +198 -12
- package/dist/static-export/index.d.mts +119 -0
- package/dist/static-export/index.mjs +55 -0
- package/dist/{types-C8j9GvU_.d.mts → types-BQpoSlhx.d.mts} +67 -41
- package/llms.txt +215 -23
- package/package.json +20 -16
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.
|
|
4
|
-
> Peer deps: react >=
|
|
5
|
-
>
|
|
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
|
-
//
|
|
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` —
|
|
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,
|
|
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]:
|
|
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:
|
|
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.
|
|
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
|
|
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
|
|
142
|
-
|
|
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
|
|
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
|
-
|
|
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,
|
|
185
|
-
- `Theme` — Material Design 3 theme. Extends `BaseTheme` with
|
|
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,
|
|
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..
|
|
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 —
|
|
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
|
+
"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
|
-
"@
|
|
57
|
-
"
|
|
58
|
-
"react": ">=
|
|
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.
|
|
69
|
-
"@
|
|
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.
|
|
75
|
-
"react-native": "0.
|
|
76
|
-
"react-test-renderer": "19.
|
|
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
|
|
85
|
+
"build": "tsup",
|
|
82
86
|
"typecheck": "tsc --noEmit",
|
|
83
87
|
"test": "jest",
|
|
84
88
|
"lint": "eslint . --max-warnings 0"
|