@rootnative/core 0.0.0-alpha.27 → 0.0.0-alpha.28
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 +40 -1
- 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 +28 -5
- package/dist/index.mjs +52 -17
- package/dist/static-export/index.d.mts +119 -0
- package/dist/static-export/index.mjs +55 -0
- package/llms.txt +64 -6
- package/package.json +10 -1
package/README.md
CHANGED
|
@@ -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'`.
|
|
@@ -190,6 +228,7 @@ const { width } = useWindowDimensions()
|
|
|
190
228
|
- `useIconResolver` — Access the configured icon resolver
|
|
191
229
|
- `defineTheme` — Type-safe theme creation helper
|
|
192
230
|
- `createMaterialTheme` — Generate MD3 themes from a seed color (import from `@rootnative/core/create-theme`)
|
|
231
|
+
- `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
232
|
- `applyRoundness` — Scale MD3 corner radius tokens by a multiplier
|
|
194
233
|
- `material` — MD3 preset object (`lightTheme`, `darkTheme`, `defaultTopAppBarTokens`)
|
|
195
234
|
- `useBreakpoint` / `breakpoints` — Current window size class
|
|
@@ -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
|
@@ -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
|
*
|
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,9 @@ 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);
|
|
357
392
|
}
|
|
358
393
|
|
|
359
394
|
// src/responsive/useWindowDimensions.ts
|
|
@@ -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,6 +1,6 @@
|
|
|
1
1
|
# @rootnative/core — Theme System for React Native
|
|
2
2
|
|
|
3
|
-
> Version: 0.0.0-alpha.
|
|
3
|
+
> Version: 0.0.0-alpha.28
|
|
4
4
|
> Peer deps: react >=19.2.3 <20.0.0, react-native >=0.83.0 <0.87.0, @rootnative/inertia >=0.0.19 <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
|
|
|
@@ -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,30 @@ 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 does not carry the whole 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. The overlay surface reads the theme where you write the overlay, so it takes the nested colors. The components in the overlay content read the theme at the `PortalHost`, so a `Button` in a `Dialog` takes the root colors. To give the content the nested theme, wrap it in a nested provider with the same theme (for `Dialog`, inside the slot: `<Dialog.Content><ThemeProvider theme={themes}>…</ThemeProvider></Dialog.Content>`), or, for `Menu`, `Tooltip`, `BottomSheet` and the modal `NavigationDrawer`, put a named `PortalHost` inside the nested provider and pass its name as `hostName`.
|
|
138
|
+
|
|
113
139
|
### useTheme()
|
|
114
140
|
|
|
115
141
|
Returns the current theme from the nearest `ThemeProvider`.
|
|
@@ -348,5 +374,37 @@ A static export (`web.output: 'static'`) renders on a server with no DOM, where
|
|
|
348
374
|
|
|
349
375
|
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
376
|
|
|
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
|
|
377
|
+
`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.
|
|
378
|
+
|
|
379
|
+
### Static export: the dark first paint (web)
|
|
380
|
+
|
|
381
|
+
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.
|
|
382
|
+
|
|
383
|
+
`@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:
|
|
384
|
+
|
|
385
|
+
```tsx
|
|
386
|
+
import { darkTheme } from '@rootnative/core'
|
|
387
|
+
import {
|
|
388
|
+
schemeGuardCss,
|
|
389
|
+
schemeGuardScript,
|
|
390
|
+
} from '@rootnative/core/static-export'
|
|
391
|
+
|
|
392
|
+
const SCHEME_GUARD_CSS = schemeGuardCss({
|
|
393
|
+
background: darkTheme.colors.background,
|
|
394
|
+
})
|
|
395
|
+
|
|
396
|
+
// inside <head>
|
|
397
|
+
<script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
|
|
398
|
+
<style dangerouslySetInnerHTML={{ __html: SCHEME_GUARD_CSS }} />
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
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.
|
|
402
|
+
2. For the dark scheme, the CSS hides `#root` and paints `background` under it.
|
|
403
|
+
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.
|
|
404
|
+
|
|
405
|
+
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).
|
|
406
|
+
|
|
407
|
+
Options:
|
|
408
|
+
- `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`
|
|
409
|
+
- `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
410
|
|
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.28",
|
|
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
|
},
|