@rootnative/core 0.0.0-alpha.27 → 0.0.0-alpha.29
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 +43 -3
- package/dist/chunk-OK7DBCK4.mjs +12 -0
- package/dist/{chunk-HMQZLDPN.mjs → chunk-Y5CU4C2C.mjs} +3 -6
- package/dist/chunk-Y6FXYEAI.mjs +10 -0
- package/dist/create-theme/index.mjs +2 -1
- package/dist/index.d.mts +77 -7
- package/dist/index.mjs +82 -17
- package/dist/static-export/index.d.mts +119 -0
- package/dist/static-export/index.mjs +55 -0
- package/llms.txt +81 -7
- package/package.json +19 -10
package/README.md
CHANGED
|
@@ -14,7 +14,7 @@ Design-system agnostic theme engine for [RootNative UI](https://github.com/rootn
|
|
|
14
14
|
pnpm add @rootnative/core @rootnative/inertia
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
Peer dependencies: `react >=19.
|
|
17
|
+
Peer dependencies: `react >=19.3.0`, `react-native >=0.88.0 <0.89.0`, `@rootnative/inertia >=0.0.20 <0.1.0`
|
|
18
18
|
|
|
19
19
|
`@rootnative/inertia` is required — every animation in the library runs on it.
|
|
20
20
|
npm and pnpm install required peers automatically; Yarn classic does not, so add
|
|
@@ -49,7 +49,7 @@ Provides the theme context to all child components. Works with any design system
|
|
|
49
49
|
| Prop | Type | Default | Description |
|
|
50
50
|
|------|------|---------|-------------|
|
|
51
51
|
| `theme` | `BaseTheme` | `lightTheme` (MD3) | Theme object |
|
|
52
|
-
| `iconResolver` | `IconResolver` | none | Resolves string icon names (`leadingIcon="check"`) to icon nodes. Set once at the app root to use Lucide, SF Symbols, custom SVGs, etc. Pre-built adapters: [`@rootnative/icons`](https://www.npmjs.com/package/@rootnative/icons) |
|
|
52
|
+
| `iconResolver` | `IconResolver` | none | Resolves string icon names (`leadingIcon="check"`) to icon nodes. Set once at the app root to use Lucide, SF Symbols, custom SVGs, etc. Pre-built adapters: [`@rootnative/icons`](https://www.npmjs.com/package/@rootnative/icons). A nested provider without it uses the resolver of its parent |
|
|
53
53
|
| `children` | `ReactNode` | — | App content |
|
|
54
54
|
|
|
55
55
|
### useTheme()
|
|
@@ -163,6 +163,44 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
|
|
|
163
163
|
<ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
|
|
164
164
|
```
|
|
165
165
|
|
|
166
|
+
### Nested providers
|
|
167
|
+
|
|
168
|
+
A second `ThemeProvider` inside the root one gives one part of the app its own
|
|
169
|
+
theme. It takes the icon resolver of its parent when it gets no
|
|
170
|
+
`iconResolver`. With a `{ light, dark }` pair and none of `mode`,
|
|
171
|
+
`defaultMode` and `storage`, it follows the mode of its parent, and its
|
|
172
|
+
`setMode()` sets the mode of the parent. An overlay (`Dialog`, `Menu`, ...)
|
|
173
|
+
renders its content at the `PortalHost`, so the components inside it take the
|
|
174
|
+
theme of the provider above the host. The
|
|
175
|
+
[theming guide](https://rootnative.github.io/ui/theming#nested-providers)
|
|
176
|
+
shows the two fixes.
|
|
177
|
+
|
|
178
|
+
### Static export: the dark first paint
|
|
179
|
+
|
|
180
|
+
The HTML of a static web export holds the light theme, so a reader with a dark
|
|
181
|
+
system setting sees the light page until hydration ends. The
|
|
182
|
+
`@rootnative/core/static-export` subpath hides it. Put both in the HTML shell
|
|
183
|
+
(`app/+html.tsx` with Expo Router), before the body:
|
|
184
|
+
|
|
185
|
+
```tsx
|
|
186
|
+
import { darkTheme } from '@rootnative/core'
|
|
187
|
+
import {
|
|
188
|
+
schemeGuardCss,
|
|
189
|
+
schemeGuardScript,
|
|
190
|
+
} from '@rootnative/core/static-export'
|
|
191
|
+
|
|
192
|
+
<script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
|
|
193
|
+
<style
|
|
194
|
+
dangerouslySetInnerHTML={{
|
|
195
|
+
__html: schemeGuardCss({ background: darkTheme.colors.background }),
|
|
196
|
+
}}
|
|
197
|
+
/>
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
A reader with a dark scheme then sees the dark background until
|
|
201
|
+
`ThemeProvider` shows the dark theme. A reader with a light scheme sees no
|
|
202
|
+
change.
|
|
203
|
+
|
|
166
204
|
### useBreakpoint()
|
|
167
205
|
|
|
168
206
|
Returns the current MD3 window size class: `'compact'` | `'medium'` | `'expanded'` | `'large'` | `'extraLarge'`.
|
|
@@ -188,8 +226,10 @@ const { width } = useWindowDimensions()
|
|
|
188
226
|
- `ThemeProvider` — Theme context provider (works with any design system, defaults to MD3)
|
|
189
227
|
- `useTheme` — Access current theme (generic)
|
|
190
228
|
- `useIconResolver` — Access the configured icon resolver
|
|
229
|
+
- `useThemeScope` / `ThemeScopeProvider` — Read the providers of one place as one value, and provide them again at another place, for content rendered through a portal
|
|
191
230
|
- `defineTheme` — Type-safe theme creation helper
|
|
192
231
|
- `createMaterialTheme` — Generate MD3 themes from a seed color (import from `@rootnative/core/create-theme`)
|
|
232
|
+
- `schemeGuardScript` / `schemeGuardCss` — Hide the light first paint of a static web export from a dark-scheme reader (import from `@rootnative/core/static-export`, with `SCHEME_ATTRIBUTE` and `THEME_READY_ATTRIBUTE`)
|
|
193
233
|
- `applyRoundness` — Scale MD3 corner radius tokens by a multiplier
|
|
194
234
|
- `material` — MD3 preset object (`lightTheme`, `darkTheme`, `defaultTopAppBarTokens`)
|
|
195
235
|
- `useBreakpoint` / `breakpoints` — Current window size class
|
|
@@ -198,7 +238,7 @@ const { width } = useWindowDimensions()
|
|
|
198
238
|
- `lightTheme` / `darkTheme` — Built-in MD3 themes
|
|
199
239
|
- `defaultTopAppBarTokens` — MD3 top app bar defaults
|
|
200
240
|
- `motionTransitions` — The named-transition registry mounted by `ThemeProvider`
|
|
201
|
-
- `BaseTheme`, `Theme`, `MaterialTheme`, `Colors`, `Typography`, `TypographyToken`, `FontWeight`, `Shape`, `Spacing`, `Elevation`, `ElevationLevel`, `ShadowOffset`, `StateLayer`, `Motion`, `MotionSpring`, `TopAppBarTokens`, `IconResolver`, `IconRenderProps`, `IconSource`, `ThemeProviderProps`, `Breakpoint`, `BreakpointValues` — Types
|
|
241
|
+
- `BaseTheme`, `Theme`, `MaterialTheme`, `Colors`, `Typography`, `TypographyToken`, `FontWeight`, `Shape`, `Spacing`, `Elevation`, `ElevationLevel`, `ShadowOffset`, `StateLayer`, `Motion`, `MotionSpring`, `TopAppBarTokens`, `IconResolver`, `IconRenderProps`, `IconSource`, `ThemeProviderProps`, `ThemeScope`, `ThemeScopeProviderProps`, `Breakpoint`, `BreakpointValues` — Types
|
|
202
242
|
|
|
203
243
|
## Docs
|
|
204
244
|
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
// src/static-export/attributes.ts
|
|
2
|
+
var SCHEME_ATTRIBUTE = "data-rootnative-scheme";
|
|
3
|
+
var THEME_READY_ATTRIBUTE = "data-rootnative-theme-ready";
|
|
4
|
+
|
|
5
|
+
// src/provider/storageKey.ts
|
|
6
|
+
var THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
|
|
7
|
+
|
|
8
|
+
export {
|
|
9
|
+
SCHEME_ATTRIBUTE,
|
|
10
|
+
THEME_READY_ATTRIBUTE,
|
|
11
|
+
THEME_MODE_STORAGE_KEY
|
|
12
|
+
};
|
|
@@ -1,9 +1,6 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
}
|
|
4
|
-
if (typeof require !== "undefined") return require.apply(this, arguments);
|
|
5
|
-
throw Error('Dynamic require of "' + x + '" is not supported');
|
|
6
|
-
});
|
|
1
|
+
import {
|
|
2
|
+
__require
|
|
3
|
+
} from "./chunk-Y6FXYEAI.mjs";
|
|
7
4
|
|
|
8
5
|
// src/theme/topAppBar.ts
|
|
9
6
|
var defaultTopAppBarTokens = {
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
|
|
2
|
+
get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
|
|
3
|
+
}) : x)(function(x) {
|
|
4
|
+
if (typeof require !== "undefined") return require.apply(this, arguments);
|
|
5
|
+
throw Error('Dynamic require of "' + x + '" is not supported');
|
|
6
|
+
});
|
|
7
|
+
|
|
8
|
+
export {
|
|
9
|
+
__require
|
|
10
|
+
};
|
|
@@ -3,7 +3,8 @@ import {
|
|
|
3
3
|
defaultTopAppBarTokens,
|
|
4
4
|
defaultTypography,
|
|
5
5
|
lightTheme
|
|
6
|
-
} from "../chunk-
|
|
6
|
+
} from "../chunk-Y5CU4C2C.mjs";
|
|
7
|
+
import "../chunk-Y6FXYEAI.mjs";
|
|
7
8
|
|
|
8
9
|
// ../../node_modules/@material/material-color-utilities/utils/math_utils.js
|
|
9
10
|
function signum(num) {
|
package/dist/index.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { T as Theme, a as TopAppBarTokens, B as BaseTheme, M as Motion, S as Shape } from './types-BQpoSlhx.mjs';
|
|
2
2
|
export { C as Colors, E as Elevation, b as ElevationLevel, F as FontWeight, c as MaterialTheme, d as MotionSpring, e as ShadowOffset, f as Spacing, g as StateLayer, h as Typography, i as TypographyToken } from './types-BQpoSlhx.mjs';
|
|
3
|
-
import { TransitionConfig, NamedTransitions } from '@rootnative/inertia';
|
|
3
|
+
import { TransitionConfig, NamedTransitions, MotionConfigValue } from '@rootnative/inertia';
|
|
4
4
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
5
5
|
import * as React from 'react';
|
|
6
6
|
import { ScaledSize } from 'react-native';
|
|
@@ -152,8 +152,6 @@ interface ThemePair {
|
|
|
152
152
|
light: BaseTheme;
|
|
153
153
|
dark: BaseTheme;
|
|
154
154
|
}
|
|
155
|
-
/** Storage key for the persisted mode. Namespaced to avoid app collisions. */
|
|
156
|
-
declare const THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
|
|
157
155
|
interface ThemeProviderProps {
|
|
158
156
|
/**
|
|
159
157
|
* Theme object to provide to all child components via context.
|
|
@@ -176,15 +174,22 @@ interface ThemeProviderProps {
|
|
|
176
174
|
* provider then never changes it on its own, so pair it with `onModeChange`.
|
|
177
175
|
*
|
|
178
176
|
* On a static web export, `'system'` renders light on the server and while
|
|
179
|
-
* the client hydrates, then switches to the OS scheme on the
|
|
180
|
-
* The server cannot know the scheme, so
|
|
177
|
+
* the client hydrates, then switches to the OS scheme on the render after
|
|
178
|
+
* hydration. The server cannot know the scheme, so a dark-scheme reader sees
|
|
179
|
+
* the light theme until hydration ends. `schemeGuardCss` from
|
|
180
|
+
* `@rootnative/core/static-export` hides that light paint.
|
|
181
|
+
*
|
|
182
|
+
* A nested provider with a pair, under a parent provider with a pair,
|
|
183
|
+
* follows the mode of the parent when it gets none of `mode`, `defaultMode`
|
|
184
|
+
* and `storage`. Its `setMode()` then sets the mode of the parent.
|
|
181
185
|
*
|
|
182
186
|
* @default 'system'
|
|
183
187
|
*/
|
|
184
188
|
mode?: ThemeMode;
|
|
185
189
|
/**
|
|
186
190
|
* Initial mode for the uncontrolled case. A persisted value from `storage`
|
|
187
|
-
* wins over this once it loads.
|
|
191
|
+
* wins over this once it loads. On a nested provider, setting it gives the
|
|
192
|
+
* provider a mode of its own.
|
|
188
193
|
*
|
|
189
194
|
* @default 'system'
|
|
190
195
|
*/
|
|
@@ -199,6 +204,10 @@ interface ThemeProviderProps {
|
|
|
199
204
|
* Ignored when `mode` is controlled: your own state is then the source of
|
|
200
205
|
* truth and persisting behind it would fight it.
|
|
201
206
|
*
|
|
207
|
+
* On a nested provider, setting it gives the provider a mode of its own.
|
|
208
|
+
* Every provider uses the same storage key, so a nested provider with
|
|
209
|
+
* `storage` overwrites the mode that the root provider stored.
|
|
210
|
+
*
|
|
202
211
|
* @example
|
|
203
212
|
* import AsyncStorage from '@react-native-async-storage/async-storage'
|
|
204
213
|
*
|
|
@@ -210,6 +219,8 @@ interface ThemeProviderProps {
|
|
|
210
219
|
* Set this once at the app root to use SF Symbols, Lucide, custom SVGs,
|
|
211
220
|
* etc. `mdiResolver` from `@rootnative/components/mdi` gives MaterialDesignIcons.
|
|
212
221
|
*
|
|
222
|
+
* A nested provider without it uses the resolver of its parent.
|
|
223
|
+
*
|
|
213
224
|
* @example
|
|
214
225
|
* import { Check, ArrowRight } from 'lucide-react-native'
|
|
215
226
|
*
|
|
@@ -254,9 +265,21 @@ interface ThemeProviderProps {
|
|
|
254
265
|
* <ThemeProvider theme={myTheme}>
|
|
255
266
|
* <App />
|
|
256
267
|
* </ThemeProvider>
|
|
268
|
+
*
|
|
269
|
+
* @example
|
|
270
|
+
* // A nested pair for one screen. It follows the mode and the icon resolver
|
|
271
|
+
* // of the root provider.
|
|
272
|
+
* const { lightTheme: light, darkTheme: dark } = createMaterialTheme(seed)
|
|
273
|
+
*
|
|
274
|
+
* <ThemeProvider theme={{ light, dark }}>
|
|
275
|
+
* <Screen />
|
|
276
|
+
* </ThemeProvider>
|
|
257
277
|
*/
|
|
258
278
|
declare function ThemeProvider({ theme, mode: controlledMode, defaultMode, onModeChange, storage, iconResolver, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
|
|
259
279
|
|
|
280
|
+
/** Storage key for the persisted mode. Namespaced to avoid app collisions. */
|
|
281
|
+
declare const THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
|
|
282
|
+
|
|
260
283
|
/**
|
|
261
284
|
* Returns the current theme from the nearest `ThemeProvider`.
|
|
262
285
|
*
|
|
@@ -296,6 +319,53 @@ declare function useThemeMode(): ThemeModeContextValue;
|
|
|
296
319
|
*/
|
|
297
320
|
declare function useIconResolver(): IconResolver | null;
|
|
298
321
|
|
|
322
|
+
/**
|
|
323
|
+
* Everything a `ThemeProvider` gives its descendants, read at one place in
|
|
324
|
+
* the tree so that it can be provided again at another. Treat it as opaque:
|
|
325
|
+
* read it with `useThemeScope()` and hand it to `ThemeScopeProvider`.
|
|
326
|
+
*/
|
|
327
|
+
interface ThemeScope {
|
|
328
|
+
/** The resolved theme at the call site. */
|
|
329
|
+
readonly theme: BaseTheme;
|
|
330
|
+
/** The mode value at the call site; `null` under a single-theme provider. */
|
|
331
|
+
readonly mode: ThemeModeContextValue | null;
|
|
332
|
+
/** The icon resolver at the call site; `null` when none is set. */
|
|
333
|
+
readonly iconResolver: IconResolver | null;
|
|
334
|
+
/** The merged motion config at the call site. */
|
|
335
|
+
readonly motion: MotionConfigValue;
|
|
336
|
+
}
|
|
337
|
+
/**
|
|
338
|
+
* Reads the theme, the mode, the icon resolver and the motion config of the
|
|
339
|
+
* nearest providers, as one value for `ThemeScopeProvider`.
|
|
340
|
+
*
|
|
341
|
+
* Use the pair when you render content at another place in the tree, for
|
|
342
|
+
* example through a portal. The content then reads the theme of the place
|
|
343
|
+
* where you wrote it, not the theme of the place where it renders.
|
|
344
|
+
* `@rootnative/components` does this in `Portal`, so every overlay follows
|
|
345
|
+
* the provider it is written under.
|
|
346
|
+
*
|
|
347
|
+
* @example
|
|
348
|
+
* function MyPortal({ children }) {
|
|
349
|
+
* const scope = useThemeScope()
|
|
350
|
+
* return createPortal(
|
|
351
|
+
* <ThemeScopeProvider scope={scope}>{children}</ThemeScopeProvider>,
|
|
352
|
+
* host,
|
|
353
|
+
* )
|
|
354
|
+
* }
|
|
355
|
+
*/
|
|
356
|
+
declare function useThemeScope(): ThemeScope;
|
|
357
|
+
interface ThemeScopeProviderProps {
|
|
358
|
+
/** The value that `useThemeScope()` returned at the place to copy. */
|
|
359
|
+
scope: ThemeScope;
|
|
360
|
+
children: React.ReactNode;
|
|
361
|
+
}
|
|
362
|
+
/**
|
|
363
|
+
* Provides a `ThemeScope` to its descendants, as if the providers at the
|
|
364
|
+
* place that read it stood here. A `ThemeProvider` below it inherits from it
|
|
365
|
+
* the same way it inherits from a real parent provider.
|
|
366
|
+
*/
|
|
367
|
+
declare function ThemeScopeProvider({ scope, children, }: ThemeScopeProviderProps): react_jsx_runtime.JSX.Element;
|
|
368
|
+
|
|
299
369
|
/**
|
|
300
370
|
* Material Design 3 window size classes.
|
|
301
371
|
* @see https://m3.material.io/foundations/layout/applying-layout/window-size-classes
|
|
@@ -398,4 +468,4 @@ declare const material: {
|
|
|
398
468
|
readonly defaultTopAppBarTokens: TopAppBarTokens;
|
|
399
469
|
};
|
|
400
470
|
|
|
401
|
-
export { BaseTheme, type Breakpoint, type BreakpointValues, type ColorScheme, type IconRenderProps, type IconResolver, type IconSource, Motion, Shape, THEME_MODE_STORAGE_KEY, Theme, type ThemeMode, type ThemeModeContextValue, type ThemeModeStorage, type ThemePair, ThemeProvider, type ThemeProviderProps, TopAppBarTokens, applyRoundness, breakpoints, darkTheme, defaultTopAppBarTokens, defineTheme, lightTheme, material, motionTransitions, useBreakpoint, useBreakpointValue, useIconResolver, useTheme, useThemeMode, useWindowDimensions };
|
|
471
|
+
export { BaseTheme, type Breakpoint, type BreakpointValues, type ColorScheme, type IconRenderProps, type IconResolver, type IconSource, Motion, Shape, THEME_MODE_STORAGE_KEY, Theme, type ThemeMode, type ThemeModeContextValue, type ThemeModeStorage, type ThemePair, ThemeProvider, type ThemeProviderProps, type ThemeScope, ThemeScopeProvider, type ThemeScopeProviderProps, TopAppBarTokens, applyRoundness, breakpoints, darkTheme, defaultTopAppBarTokens, defineTheme, lightTheme, material, motionTransitions, useBreakpoint, useBreakpointValue, useIconResolver, useTheme, useThemeMode, useThemeScope, useWindowDimensions };
|
package/dist/index.mjs
CHANGED
|
@@ -3,7 +3,12 @@ import {
|
|
|
3
3
|
defaultTopAppBarTokens,
|
|
4
4
|
defaultTypography,
|
|
5
5
|
lightTheme
|
|
6
|
-
} from "./chunk-
|
|
6
|
+
} from "./chunk-Y5CU4C2C.mjs";
|
|
7
|
+
import {
|
|
8
|
+
THEME_MODE_STORAGE_KEY,
|
|
9
|
+
THEME_READY_ATTRIBUTE
|
|
10
|
+
} from "./chunk-OK7DBCK4.mjs";
|
|
11
|
+
import "./chunk-Y6FXYEAI.mjs";
|
|
7
12
|
|
|
8
13
|
// src/theme/dark.ts
|
|
9
14
|
var darkTheme = {
|
|
@@ -227,6 +232,15 @@ function useIsHydrating() {
|
|
|
227
232
|
);
|
|
228
233
|
}
|
|
229
234
|
|
|
235
|
+
// src/internal/useMarkThemeReady.ts
|
|
236
|
+
import { useEffect } from "react";
|
|
237
|
+
function useMarkThemeReady(isFinal) {
|
|
238
|
+
useEffect(() => {
|
|
239
|
+
if (!isFinal || typeof document === "undefined") return;
|
|
240
|
+
document.documentElement.setAttribute(THEME_READY_ATTRIBUTE, "");
|
|
241
|
+
}, [isFinal]);
|
|
242
|
+
}
|
|
243
|
+
|
|
230
244
|
// src/provider/IconResolverContext.ts
|
|
231
245
|
import * as React from "react";
|
|
232
246
|
var IconResolverContext = React.createContext(
|
|
@@ -243,7 +257,6 @@ var ThemeModeContext = React3.createContext(null);
|
|
|
243
257
|
|
|
244
258
|
// src/provider/ThemeProvider.tsx
|
|
245
259
|
import { jsx } from "react/jsx-runtime";
|
|
246
|
-
var THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
|
|
247
260
|
function isThemePair(theme) {
|
|
248
261
|
return !("colors" in theme);
|
|
249
262
|
}
|
|
@@ -253,18 +266,24 @@ function isThemeMode(value) {
|
|
|
253
266
|
function ThemeProvider({
|
|
254
267
|
theme,
|
|
255
268
|
mode: controlledMode,
|
|
256
|
-
defaultMode
|
|
269
|
+
defaultMode,
|
|
257
270
|
onModeChange,
|
|
258
271
|
storage,
|
|
259
272
|
iconResolver,
|
|
260
273
|
children
|
|
261
274
|
}) {
|
|
262
275
|
const pair = theme && isThemePair(theme) ? theme : null;
|
|
276
|
+
const parentModeValue = React4.useContext(ThemeModeContext);
|
|
277
|
+
const parentIconResolver = React4.useContext(IconResolverContext);
|
|
278
|
+
const inheritedMode = pair && controlledMode === void 0 && defaultMode === void 0 && storage === void 0 ? parentModeValue : null;
|
|
263
279
|
const measuredScheme = useColorScheme();
|
|
264
|
-
const
|
|
265
|
-
const
|
|
280
|
+
const isHydrating = useIsHydrating();
|
|
281
|
+
const systemScheme = isHydrating ? "light" : measuredScheme;
|
|
282
|
+
const [uncontrolledMode, setUncontrolledMode] = React4.useState(
|
|
283
|
+
defaultMode != null ? defaultMode : "system"
|
|
284
|
+
);
|
|
266
285
|
const isControlled = controlledMode !== void 0;
|
|
267
|
-
const
|
|
286
|
+
const ownMode = isControlled ? controlledMode : uncontrolledMode;
|
|
268
287
|
const [isReady, setIsReady] = React4.useState(
|
|
269
288
|
() => !storage || isControlled || !pair
|
|
270
289
|
);
|
|
@@ -298,9 +317,15 @@ function ThemeProvider({
|
|
|
298
317
|
cancelled = true;
|
|
299
318
|
};
|
|
300
319
|
}, [shouldLoad]);
|
|
320
|
+
const setParentMode = inheritedMode == null ? void 0 : inheritedMode.setMode;
|
|
301
321
|
const setMode = React4.useCallback(
|
|
302
322
|
(nextMode) => {
|
|
303
323
|
var _a;
|
|
324
|
+
if (setParentMode) {
|
|
325
|
+
setParentMode(nextMode);
|
|
326
|
+
onModeChange == null ? void 0 : onModeChange(nextMode);
|
|
327
|
+
return;
|
|
328
|
+
}
|
|
304
329
|
if (!isControlled) {
|
|
305
330
|
setUncontrolledMode(nextMode);
|
|
306
331
|
}
|
|
@@ -317,31 +342,41 @@ function ThemeProvider({
|
|
|
317
342
|
}
|
|
318
343
|
}
|
|
319
344
|
},
|
|
320
|
-
[isControlled, onModeChange]
|
|
345
|
+
[setParentMode, isControlled, onModeChange]
|
|
321
346
|
);
|
|
322
|
-
const
|
|
347
|
+
const ownScheme = ownMode === "system" ? systemScheme === "dark" ? "dark" : "light" : ownMode;
|
|
348
|
+
const mode = inheritedMode ? inheritedMode.mode : ownMode;
|
|
349
|
+
const scheme = inheritedMode ? inheritedMode.scheme : ownScheme;
|
|
350
|
+
const ready = inheritedMode ? inheritedMode.isReady : isReady;
|
|
351
|
+
useMarkThemeReady(!isHydrating && ready);
|
|
323
352
|
const resolvedTheme = pair ? scheme === "dark" ? pair.dark : pair.light : theme != null ? theme : lightTheme;
|
|
324
353
|
const modeValue = React4.useMemo(
|
|
325
|
-
() => pair ? { mode, scheme, setMode, isReady } : null,
|
|
326
|
-
[pair, mode, scheme, setMode,
|
|
354
|
+
() => pair ? { mode, scheme, setMode, isReady: ready } : null,
|
|
355
|
+
[pair, mode, scheme, setMode, ready]
|
|
327
356
|
);
|
|
328
357
|
const transitions = React4.useMemo(
|
|
329
358
|
() => motionTransitions(resolvedTheme.motion),
|
|
330
359
|
[resolvedTheme.motion]
|
|
331
360
|
);
|
|
332
|
-
return /* @__PURE__ */ jsx(ThemeContext.Provider, { value: resolvedTheme, children: /* @__PURE__ */ jsx(ThemeModeContext.Provider, { value: modeValue, children: /* @__PURE__ */ jsx(
|
|
361
|
+
return /* @__PURE__ */ jsx(ThemeContext.Provider, { value: resolvedTheme, children: /* @__PURE__ */ jsx(ThemeModeContext.Provider, { value: modeValue, children: /* @__PURE__ */ jsx(
|
|
362
|
+
IconResolverContext.Provider,
|
|
363
|
+
{
|
|
364
|
+
value: iconResolver != null ? iconResolver : parentIconResolver,
|
|
365
|
+
children: /* @__PURE__ */ jsx(MotionConfig, { transitions, children })
|
|
366
|
+
}
|
|
367
|
+
) }) });
|
|
333
368
|
}
|
|
334
369
|
|
|
335
370
|
// src/provider/useTheme.ts
|
|
336
|
-
import { useContext } from "react";
|
|
371
|
+
import { useContext as useContext2 } from "react";
|
|
337
372
|
function useTheme() {
|
|
338
|
-
return
|
|
373
|
+
return useContext2(ThemeContext);
|
|
339
374
|
}
|
|
340
375
|
|
|
341
376
|
// src/provider/useThemeMode.ts
|
|
342
|
-
import { useContext as
|
|
377
|
+
import { useContext as useContext3 } from "react";
|
|
343
378
|
function useThemeMode() {
|
|
344
|
-
const value =
|
|
379
|
+
const value = useContext3(ThemeModeContext);
|
|
345
380
|
if (value === null) {
|
|
346
381
|
throw new Error(
|
|
347
382
|
"useThemeMode() requires a <ThemeProvider theme={{ light, dark }}>. A provider with a single theme has no light/dark mode to control."
|
|
@@ -351,9 +386,37 @@ function useThemeMode() {
|
|
|
351
386
|
}
|
|
352
387
|
|
|
353
388
|
// src/provider/useIconResolver.ts
|
|
354
|
-
import { useContext as
|
|
389
|
+
import { useContext as useContext4 } from "react";
|
|
355
390
|
function useIconResolver() {
|
|
356
|
-
return
|
|
391
|
+
return useContext4(IconResolverContext);
|
|
392
|
+
}
|
|
393
|
+
|
|
394
|
+
// src/provider/ThemeScope.tsx
|
|
395
|
+
import { MotionConfig as MotionConfig2, useMotionConfig } from "@rootnative/inertia";
|
|
396
|
+
import * as React5 from "react";
|
|
397
|
+
import { jsx as jsx2 } from "react/jsx-runtime";
|
|
398
|
+
function useThemeScope() {
|
|
399
|
+
const theme = React5.useContext(ThemeContext);
|
|
400
|
+
const mode = React5.useContext(ThemeModeContext);
|
|
401
|
+
const iconResolver = React5.useContext(IconResolverContext);
|
|
402
|
+
const motion = useMotionConfig();
|
|
403
|
+
return React5.useMemo(
|
|
404
|
+
() => ({ theme, mode, iconResolver, motion }),
|
|
405
|
+
[theme, mode, iconResolver, motion]
|
|
406
|
+
);
|
|
407
|
+
}
|
|
408
|
+
function ThemeScopeProvider({
|
|
409
|
+
scope,
|
|
410
|
+
children
|
|
411
|
+
}) {
|
|
412
|
+
return /* @__PURE__ */ jsx2(ThemeContext.Provider, { value: scope.theme, children: /* @__PURE__ */ jsx2(ThemeModeContext.Provider, { value: scope.mode, children: /* @__PURE__ */ jsx2(IconResolverContext.Provider, { value: scope.iconResolver, children: /* @__PURE__ */ jsx2(
|
|
413
|
+
MotionConfig2,
|
|
414
|
+
{
|
|
415
|
+
reducedMotion: scope.motion.reducedMotion,
|
|
416
|
+
transitions: scope.motion.transitions,
|
|
417
|
+
children
|
|
418
|
+
}
|
|
419
|
+
) }) }) });
|
|
357
420
|
}
|
|
358
421
|
|
|
359
422
|
// src/responsive/useWindowDimensions.ts
|
|
@@ -416,6 +479,7 @@ var material = {
|
|
|
416
479
|
export {
|
|
417
480
|
THEME_MODE_STORAGE_KEY,
|
|
418
481
|
ThemeProvider,
|
|
482
|
+
ThemeScopeProvider,
|
|
419
483
|
applyRoundness,
|
|
420
484
|
breakpoints,
|
|
421
485
|
darkTheme,
|
|
@@ -429,5 +493,6 @@ export {
|
|
|
429
493
|
useIconResolver,
|
|
430
494
|
useTheme,
|
|
431
495
|
useThemeMode,
|
|
496
|
+
useThemeScope,
|
|
432
497
|
useWindowDimensions
|
|
433
498
|
};
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/** Options for `schemeGuardScript`. */
|
|
2
|
+
interface SchemeGuardScriptOptions {
|
|
3
|
+
/**
|
|
4
|
+
* The `localStorage` key that holds the mode the reader chose. A stored
|
|
5
|
+
* `'light'` or `'dark'` wins over the OS scheme, as it does in
|
|
6
|
+
* `ThemeProvider`. Pass `null` when the app does not keep the mode in
|
|
7
|
+
* `localStorage` under one key: the script then reads the OS scheme only.
|
|
8
|
+
*
|
|
9
|
+
* @default THEME_MODE_STORAGE_KEY ('rootnative.theme-mode'), the key that
|
|
10
|
+
* `ThemeProvider` writes through `storage`
|
|
11
|
+
*/
|
|
12
|
+
storageKey?: string | null;
|
|
13
|
+
}
|
|
14
|
+
/** Options for `schemeGuardCss`. */
|
|
15
|
+
interface SchemeGuardCssOptions {
|
|
16
|
+
/**
|
|
17
|
+
* The CSS color that a dark-scheme reader sees while the page is hidden.
|
|
18
|
+
* Use the background color of the dark theme, for example
|
|
19
|
+
* `darkTheme.colors.background`.
|
|
20
|
+
*/
|
|
21
|
+
background: string;
|
|
22
|
+
/**
|
|
23
|
+
* The element that holds the app. The guard hides it until the theme is
|
|
24
|
+
* ready.
|
|
25
|
+
*
|
|
26
|
+
* @default '#root', the element Expo hydrates into
|
|
27
|
+
*/
|
|
28
|
+
rootSelector?: string;
|
|
29
|
+
/**
|
|
30
|
+
* How long to wait for the theme before the page shows anyway, in
|
|
31
|
+
* milliseconds. This is for a bundle that fails to load. A short value
|
|
32
|
+
* shows the light page to a dark-scheme reader on a slow connection; a long
|
|
33
|
+
* value keeps a reader with a failed bundle on an empty page.
|
|
34
|
+
*
|
|
35
|
+
* @default 8000
|
|
36
|
+
*/
|
|
37
|
+
timeoutMs?: number;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* The source of an inline script for the `<head>` of a static export. It
|
|
42
|
+
* finds the scheme the reader will get after hydration and writes it to
|
|
43
|
+
* `<html>` as `SCHEME_ATTRIBUTE`, before the body paints.
|
|
44
|
+
*
|
|
45
|
+
* ## The problem it solves
|
|
46
|
+
*
|
|
47
|
+
* The export server cannot know the color scheme of the reader, so the HTML
|
|
48
|
+
* holds the light theme. react-native-web writes each theme color into the
|
|
49
|
+
* HTML as an inline style, and shell CSS cannot change an inline style. So a
|
|
50
|
+
* reader with a dark scheme sees the light page until the bundle downloads
|
|
51
|
+
* and hydrates: about 1.3 s on a fast computer, and more than 5 s on a slow
|
|
52
|
+
* phone. A mode stored with `storage` loads after hydration, so a reader who
|
|
53
|
+
* chose dark sees the same light page.
|
|
54
|
+
*
|
|
55
|
+
* This script and `schemeGuardCss` hide the page from a dark-scheme reader
|
|
56
|
+
* until `ThemeProvider` shows the final theme. A light-scheme reader sees no
|
|
57
|
+
* change. Without JavaScript the script does not run, so nothing is hidden.
|
|
58
|
+
*
|
|
59
|
+
* ## How to use it
|
|
60
|
+
*
|
|
61
|
+
* Put both in the HTML shell — for Expo Router that is `app/+html.tsx`. The
|
|
62
|
+
* script must come before the body:
|
|
63
|
+
*
|
|
64
|
+
* ```tsx
|
|
65
|
+
* import { darkTheme } from '@rootnative/core'
|
|
66
|
+
* import {
|
|
67
|
+
* schemeGuardCss,
|
|
68
|
+
* schemeGuardScript,
|
|
69
|
+
* } from '@rootnative/core/static-export'
|
|
70
|
+
*
|
|
71
|
+
* <head>
|
|
72
|
+
* <script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
|
|
73
|
+
* <style
|
|
74
|
+
* dangerouslySetInnerHTML={{
|
|
75
|
+
* __html: schemeGuardCss({ background: darkTheme.colors.background }),
|
|
76
|
+
* }}
|
|
77
|
+
* />
|
|
78
|
+
* </head>
|
|
79
|
+
* ```
|
|
80
|
+
*
|
|
81
|
+
* The scheme comes from the same sources as `ThemeProvider` uses: a stored
|
|
82
|
+
* `'light'` or `'dark'` first, then the OS scheme. The script cannot see a
|
|
83
|
+
* mode that the app controls with `mode`. It then reads the OS scheme, and
|
|
84
|
+
* the page can stay hidden until hydration for a reader who will see light.
|
|
85
|
+
*/
|
|
86
|
+
declare function schemeGuardScript(options?: SchemeGuardScriptOptions): string;
|
|
87
|
+
/**
|
|
88
|
+
* CSS for the HTML shell of a static export. For a reader whose scheme is
|
|
89
|
+
* dark, it hides the app element and paints `background` until
|
|
90
|
+
* `ThemeProvider` marks the theme as ready. See `schemeGuardScript` for the
|
|
91
|
+
* problem, and for the script that this CSS needs.
|
|
92
|
+
*
|
|
93
|
+
* The hidden page keeps its layout, so nothing moves when it shows. The cost
|
|
94
|
+
* is time: a dark-scheme reader sees content when hydration ends, not when the
|
|
95
|
+
* HTML arrives, so the Largest Contentful Paint is later for that reader.
|
|
96
|
+
*
|
|
97
|
+
* If the theme is not ready after `timeoutMs`, the page shows anyway. That is
|
|
98
|
+
* for a bundle that fails to load.
|
|
99
|
+
*/
|
|
100
|
+
declare function schemeGuardCss(options: SchemeGuardCssOptions): string;
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* The two `<html>` attributes the scheme guard is built on. The shell script
|
|
104
|
+
* and `ThemeProvider` write them, and `schemeGuardCss` reads them, so the
|
|
105
|
+
* writers and the CSS share one spelling.
|
|
106
|
+
*/
|
|
107
|
+
/**
|
|
108
|
+
* Set on `<html>` by `schemeGuardScript`, before the body paints, to the
|
|
109
|
+
* scheme the reader will get after hydration: `'dark'` or `'light'`.
|
|
110
|
+
*/
|
|
111
|
+
declare const SCHEME_ATTRIBUTE = "data-rootnative-scheme";
|
|
112
|
+
/**
|
|
113
|
+
* Set on `<html>` by `ThemeProvider` on web, on the first render after
|
|
114
|
+
* hydration with the stored mode loaded. From then on the theme on screen is
|
|
115
|
+
* the final one, so the guard stands down.
|
|
116
|
+
*/
|
|
117
|
+
declare const THEME_READY_ATTRIBUTE = "data-rootnative-theme-ready";
|
|
118
|
+
|
|
119
|
+
export { SCHEME_ATTRIBUTE, type SchemeGuardCssOptions, type SchemeGuardScriptOptions, THEME_READY_ATTRIBUTE, schemeGuardCss, schemeGuardScript };
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import {
|
|
2
|
+
SCHEME_ATTRIBUTE,
|
|
3
|
+
THEME_MODE_STORAGE_KEY,
|
|
4
|
+
THEME_READY_ATTRIBUTE
|
|
5
|
+
} from "../chunk-OK7DBCK4.mjs";
|
|
6
|
+
import "../chunk-Y6FXYEAI.mjs";
|
|
7
|
+
|
|
8
|
+
// src/static-export/schemeGuard.ts
|
|
9
|
+
var KEYFRAMES = "rootnative-scheme-guard";
|
|
10
|
+
var DEFAULT_ROOT_SELECTOR = "#root";
|
|
11
|
+
var DEFAULT_TIMEOUT_MS = 8e3;
|
|
12
|
+
function scriptLiteral(value) {
|
|
13
|
+
return JSON.stringify(value).replace(/</g, "\\u003c");
|
|
14
|
+
}
|
|
15
|
+
function schemeGuardScript(options) {
|
|
16
|
+
const storageKey = (options == null ? void 0 : options.storageKey) === void 0 ? THEME_MODE_STORAGE_KEY : options.storageKey;
|
|
17
|
+
const readStored = storageKey === null ? "" : `try { stored = window.localStorage.getItem(${scriptLiteral(storageKey)}) } catch (e) {}
|
|
18
|
+
`;
|
|
19
|
+
return `(function () {
|
|
20
|
+
try {
|
|
21
|
+
var stored = null
|
|
22
|
+
${readStored}var scheme = stored === 'dark' || stored === 'light'
|
|
23
|
+
? stored
|
|
24
|
+
: window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
|
|
25
|
+
? 'dark'
|
|
26
|
+
: 'light'
|
|
27
|
+
document.documentElement.setAttribute(${scriptLiteral(SCHEME_ATTRIBUTE)}, scheme)
|
|
28
|
+
} catch (e) {}
|
|
29
|
+
})()
|
|
30
|
+
`;
|
|
31
|
+
}
|
|
32
|
+
function schemeGuardCss(options) {
|
|
33
|
+
var _a, _b;
|
|
34
|
+
const root = (_a = options.rootSelector) != null ? _a : DEFAULT_ROOT_SELECTOR;
|
|
35
|
+
const timeout = (_b = options.timeoutMs) != null ? _b : DEFAULT_TIMEOUT_MS;
|
|
36
|
+
const guarded = `html[${SCHEME_ATTRIBUTE}='dark']:not([${THEME_READY_ATTRIBUTE}])`;
|
|
37
|
+
return `@keyframes ${KEYFRAMES} {
|
|
38
|
+
to { visibility: visible; }
|
|
39
|
+
}
|
|
40
|
+
${guarded},
|
|
41
|
+
${guarded} body {
|
|
42
|
+
background-color: ${options.background};
|
|
43
|
+
}
|
|
44
|
+
${guarded} ${root} {
|
|
45
|
+
visibility: hidden;
|
|
46
|
+
animation: ${KEYFRAMES} 0s ${timeout}ms forwards;
|
|
47
|
+
}
|
|
48
|
+
`;
|
|
49
|
+
}
|
|
50
|
+
export {
|
|
51
|
+
SCHEME_ATTRIBUTE,
|
|
52
|
+
THEME_READY_ATTRIBUTE,
|
|
53
|
+
schemeGuardCss,
|
|
54
|
+
schemeGuardScript
|
|
55
|
+
};
|
package/llms.txt
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @rootnative/core — Theme System for React Native
|
|
2
2
|
|
|
3
|
-
> Version: 0.0.0-alpha.
|
|
4
|
-
> Peer deps: react >=19.
|
|
3
|
+
> Version: 0.0.0-alpha.29
|
|
4
|
+
> Peer deps: react >=19.3.0 <20.0.0, react-native >=0.88.0 <0.89.0, @rootnative/inertia >=0.0.20 <0.1.0 (required — every animation runs on it)
|
|
5
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
|
|
@@ -32,6 +32,8 @@ Ask this first. Every path below ends in the same `<ThemeProvider theme={...}>`.
|
|
|
32
32
|
| MD3 with sharper or rounder corners | The `roundness` option on `createMaterialTheme`, or `applyRoundness()` on an existing theme |
|
|
33
33
|
| A fully custom design system (your own tokens) | `defineTheme<MyTheme>()` + `useTheme<MyTheme>()` |
|
|
34
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 |
|
|
35
37
|
|
|
36
38
|
### ThemeProvider
|
|
37
39
|
|
|
@@ -75,11 +77,11 @@ const custom: Theme = {
|
|
|
75
77
|
|
|
76
78
|
Props:
|
|
77
79
|
- `theme?: BaseTheme | { light: BaseTheme; dark: BaseTheme }` — A single theme, or a light/dark pair. A pair enables `useThemeMode()`. Default: `lightTheme` (MD3)
|
|
78
|
-
- `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
|
|
79
|
-
- `defaultMode?: 'system' | 'light' | 'dark'` — Initial mode when uncontrolled. Default: `'system'
|
|
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
|
|
80
82
|
- `onModeChange?: (mode: ThemeMode) => void`
|
|
81
|
-
- `storage?: { getItem, setItem }` — Persists the mode. Any AsyncStorage-shaped object; sync or async. Nothing is persisted unless you pass this
|
|
82
|
-
- `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
|
|
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
|
|
83
85
|
- `children: ReactNode`
|
|
84
86
|
|
|
85
87
|
### useThemeMode()
|
|
@@ -110,6 +112,46 @@ function ThemeToggle() {
|
|
|
110
112
|
}
|
|
111
113
|
```
|
|
112
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
|
+
|
|
113
155
|
### useTheme()
|
|
114
156
|
|
|
115
157
|
Returns the current theme from the nearest `ThemeProvider`.
|
|
@@ -348,5 +390,37 @@ A static export (`web.output: 'static'`) renders on a server with no DOM, where
|
|
|
348
390
|
|
|
349
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.
|
|
350
392
|
|
|
351
|
-
`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
|
|
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`
|
|
352
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.29",
|
|
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,22 +62,22 @@
|
|
|
53
62
|
"md3"
|
|
54
63
|
],
|
|
55
64
|
"peerDependencies": {
|
|
56
|
-
"@rootnative/inertia": ">=0.0.
|
|
57
|
-
"react": ">=19.
|
|
58
|
-
"react-native": ">=0.
|
|
65
|
+
"@rootnative/inertia": ">=0.0.20 <0.1.0",
|
|
66
|
+
"react": ">=19.3.0 <20.0.0",
|
|
67
|
+
"react-native": ">=0.88.0 <0.89.0"
|
|
59
68
|
},
|
|
60
69
|
"devDependencies": {
|
|
61
70
|
"@material/material-color-utilities": "^0.4.0",
|
|
62
|
-
"@react-native/babel-preset": "^0.
|
|
63
|
-
"@react-native/jest-preset": "^0.
|
|
64
|
-
"@rootnative/inertia": "0.0.
|
|
71
|
+
"@react-native/babel-preset": "^0.88.0",
|
|
72
|
+
"@react-native/jest-preset": "^0.88.0",
|
|
73
|
+
"@rootnative/inertia": "0.0.20",
|
|
65
74
|
"@testing-library/react-native": "^13.3.3",
|
|
66
75
|
"@types/jest": "^29.5.14",
|
|
67
76
|
"@types/react": "^19.0.0",
|
|
68
77
|
"jest": "^29.7.0",
|
|
69
|
-
"react": "19.
|
|
70
|
-
"react-native": "0.
|
|
71
|
-
"react-test-renderer": "19.
|
|
78
|
+
"react": "19.3.0",
|
|
79
|
+
"react-native": "0.88.0",
|
|
80
|
+
"react-test-renderer": "19.3.0",
|
|
72
81
|
"tsup": "^8.0.0",
|
|
73
82
|
"typescript": "^5.0.0"
|
|
74
83
|
},
|