@rootnative/core 0.0.0-alpha.26 → 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 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
- 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
- });
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-HMQZLDPN.mjs";
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 next render.
180
- * The server cannot know the scheme, so the light theme is the first paint.
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-HMQZLDPN.mjs";
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 = "system",
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 systemScheme = useIsHydrating() ? "light" : measuredScheme;
265
- const [uncontrolledMode, setUncontrolledMode] = React4.useState(defaultMode);
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 mode = isControlled ? controlledMode : uncontrolledMode;
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 scheme = mode === "system" ? systemScheme === "dark" ? "dark" : "light" : mode;
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, isReady]
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(IconResolverContext.Provider, { value: iconResolver != null ? iconResolver : null, children: /* @__PURE__ */ jsx(MotionConfig, { transitions, children }) }) }) });
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 useContext(ThemeContext);
373
+ return useContext2(ThemeContext);
339
374
  }
340
375
 
341
376
  // src/provider/useThemeMode.ts
342
- import { useContext as useContext2 } from "react";
377
+ import { useContext as useContext3 } from "react";
343
378
  function useThemeMode() {
344
- const value = useContext2(ThemeModeContext);
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 useContext3 } from "react";
389
+ import { useContext as useContext4 } from "react";
355
390
  function useIconResolver() {
356
- return useContext3(IconResolverContext);
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,7 +1,7 @@
1
1
  # @rootnative/core — Theme System for React Native
2
2
 
3
- > Version: 0.0.0-alpha.26
4
- > Peer deps: react >=19.2.3 <20.0.0, react-native >=0.83.0 <0.87.0, @rootnative/inertia >=0.0.17 <0.1.0 (required — every animation runs on it)
3
+ > Version: 0.0.0-alpha.28
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
 
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 next render. No hydration gate is needed around it
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 one light frame first. The `useColorScheme` hook from `react-native` is **not** hydration-safe: a theme chosen from it stays light in a dark browser.
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.26",
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
  },
@@ -53,7 +62,7 @@
53
62
  "md3"
54
63
  ],
55
64
  "peerDependencies": {
56
- "@rootnative/inertia": ">=0.0.17 <0.1.0",
65
+ "@rootnative/inertia": ">=0.0.19 <0.1.0",
57
66
  "react": ">=19.2.3 <20.0.0",
58
67
  "react-native": ">=0.83.0 <0.87.0"
59
68
  },
@@ -61,7 +70,7 @@
61
70
  "@material/material-color-utilities": "^0.4.0",
62
71
  "@react-native/babel-preset": "^0.86.3",
63
72
  "@react-native/jest-preset": "^0.86.3",
64
- "@rootnative/inertia": "0.0.18",
73
+ "@rootnative/inertia": "0.0.19",
65
74
  "@testing-library/react-native": "^13.3.3",
66
75
  "@types/jest": "^29.5.14",
67
76
  "@types/react": "^19.0.0",