@rootnative/core 0.0.0-alpha.9 → 0.0.2
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/LICENSE +1 -1
- package/README.md +116 -45
- package/dist/chunk-OK7DBCK4.mjs +12 -0
- package/dist/{chunk-QQ3ME6R7.mjs → chunk-Y5CU4C2C.mjs} +29 -7
- package/dist/chunk-Y6FXYEAI.mjs +10 -0
- package/dist/create-theme/index.d.mts +1 -1
- package/dist/create-theme/index.mjs +5152 -19
- package/dist/index.d.mts +276 -20
- package/dist/index.mjs +214 -13
- package/dist/static-export/index.d.mts +119 -0
- package/dist/static-export/index.mjs +55 -0
- package/dist/{types-NiRbh4dM.d.mts → types-DbJZ6AOd.d.mts} +43 -9
- package/llms.txt +216 -26
- package/package.json +21 -17
|
@@ -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
|
+
};
|
|
@@ -1,22 +1,23 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Base theme interface that all design systems must implement
|
|
3
|
-
*
|
|
4
|
-
*
|
|
2
|
+
* Base theme interface that all design systems must implement: color roles
|
|
3
|
+
* and typography roles, with any role names. Extend this to create a custom
|
|
4
|
+
* design system theme, and add token groups of your own on the theme root.
|
|
5
|
+
*
|
|
6
|
+
* It has no Material Design group. `shape`, `spacing`, `stateLayer`,
|
|
7
|
+
* `elevation` and `motion` belong to {@link Theme}. The components of
|
|
8
|
+
* `@rootnative/components` read the MD3 roles and groups, so they need a
|
|
9
|
+
* {@link Theme}.
|
|
5
10
|
*
|
|
6
11
|
* @example
|
|
7
12
|
* interface MyTheme extends BaseTheme {
|
|
8
13
|
* colors: { brand: string; background: string; text: string }
|
|
9
14
|
* typography: { heading: TypographyToken; body: TypographyToken }
|
|
15
|
+
* radius: { card: number; control: number }
|
|
10
16
|
* }
|
|
11
17
|
*/
|
|
12
18
|
interface BaseTheme {
|
|
13
19
|
colors: Record<string, string>;
|
|
14
20
|
typography: Record<string, TypographyToken>;
|
|
15
|
-
shape: Shape;
|
|
16
|
-
spacing: Spacing;
|
|
17
|
-
stateLayer: StateLayer;
|
|
18
|
-
elevation: Elevation;
|
|
19
|
-
motion: Motion;
|
|
20
21
|
[key: string]: unknown;
|
|
21
22
|
}
|
|
22
23
|
/**
|
|
@@ -28,6 +29,11 @@ interface BaseTheme {
|
|
|
28
29
|
interface Theme extends BaseTheme {
|
|
29
30
|
colors: Colors;
|
|
30
31
|
typography: Typography;
|
|
32
|
+
shape: Shape;
|
|
33
|
+
spacing: Spacing;
|
|
34
|
+
stateLayer: StateLayer;
|
|
35
|
+
elevation: Elevation;
|
|
36
|
+
motion: Motion;
|
|
31
37
|
topAppBar?: TopAppBarTokens;
|
|
32
38
|
}
|
|
33
39
|
/**
|
|
@@ -136,7 +142,7 @@ interface TypographyToken {
|
|
|
136
142
|
lineHeight: number;
|
|
137
143
|
letterSpacing: number;
|
|
138
144
|
}
|
|
139
|
-
/** Corner radius tokens from none (0) to full (
|
|
145
|
+
/** Corner radius tokens from none (0) to full (999 for pill shapes). */
|
|
140
146
|
interface Shape {
|
|
141
147
|
/** Global multiplier for corner radii. `0` = sharp, `1` = default MD3, `2` = double rounding. Does not affect `cornerNone` or `cornerFull`. */
|
|
142
148
|
roundness: number;
|
|
@@ -156,16 +162,44 @@ interface Spacing {
|
|
|
156
162
|
lg: number;
|
|
157
163
|
xl: number;
|
|
158
164
|
}
|
|
165
|
+
/**
|
|
166
|
+
* Layout tokens of the MD3 top app bar, in dp. `AppBar` follows the Compose
|
|
167
|
+
* `TopAppBarLayout` geometry: each side slot and the title carry
|
|
168
|
+
* `horizontalPadding`. So the title starts at
|
|
169
|
+
* `max(titleStartInset, horizontalPadding + leading width) + horizontalPadding`
|
|
170
|
+
* from the start edge (16 with no leading content, 56 after a 48dp navigation
|
|
171
|
+
* icon), and the last action ends `horizontalPadding` (4) from the end edge.
|
|
172
|
+
* No pair of values puts the title and the actions on one wider gutter. Pad
|
|
173
|
+
* the bar with `style` for that (AppBar docs, "Align with a Page Gutter").
|
|
174
|
+
*/
|
|
159
175
|
interface TopAppBarTokens {
|
|
176
|
+
/** Padding at each end of the top row, and on each side of the title. Default 4. */
|
|
160
177
|
horizontalPadding: number;
|
|
178
|
+
/**
|
|
179
|
+
* Smallest start position of the title's own padding, used when the
|
|
180
|
+
* leading slot is narrower. With `horizontalPadding`, also the start inset
|
|
181
|
+
* of the title row of a `medium` or `large` bar. Default 12.
|
|
182
|
+
*/
|
|
161
183
|
titleStartInset: number;
|
|
184
|
+
/** Height of a `small` or `center-aligned` bar, and of a collapsed `medium` or `large` bar. Default 64. */
|
|
162
185
|
smallContainerHeight: number;
|
|
186
|
+
/** Height of a `medium` bar with no subtitle. A subtitle adds 24. Default 112. */
|
|
163
187
|
mediumContainerHeight: number;
|
|
188
|
+
/** Height of a `large` bar with no subtitle. A subtitle adds 32. Default 152. */
|
|
164
189
|
largeContainerHeight: number;
|
|
190
|
+
/** Height of the row that holds the navigation icon and the actions. Default 64. */
|
|
165
191
|
topRowHeight: number;
|
|
192
|
+
/** Smallest height of the leading and trailing slots. Default 48. */
|
|
166
193
|
sideSlotMinHeight: number;
|
|
194
|
+
/**
|
|
195
|
+
* Width of the frame around the navigation icon, and the smallest width of
|
|
196
|
+
* custom slot content, so a 40dp `IconButton` takes the 48dp footprint of
|
|
197
|
+
* an MD3 icon button. Default 48.
|
|
198
|
+
*/
|
|
167
199
|
iconFrameSize: number;
|
|
200
|
+
/** Space under the title of a `medium` bar. Default 24. */
|
|
168
201
|
mediumTitleBottomPadding: number;
|
|
202
|
+
/** Space under the title of a `large` bar. Default 28. */
|
|
169
203
|
largeTitleBottomPadding: number;
|
|
170
204
|
}
|
|
171
205
|
/** Opacity values for interactive state feedback (press, hover, focus, drag, disabled). */
|
package/llms.txt
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# @rootnative/core — Theme System for React Native
|
|
2
2
|
|
|
3
|
-
> Version: 0.0.
|
|
4
|
-
> Peer deps: react >=
|
|
5
|
-
>
|
|
3
|
+
> Version: 0.0.2
|
|
4
|
+
> Peer deps: react >=19.3.0 <20.0.0, react-native >=0.88.0 <0.89.0, @rootnative/inertia >=0.0.26 <0.1.0 (required — every animation runs on it)
|
|
5
|
+
> createMaterialTheme needs no extra install — its color engine (@material/material-color-utilities) is bundled behind the create-theme subpath
|
|
6
6
|
|
|
7
7
|
## Quick Start
|
|
8
8
|
|
|
@@ -20,9 +20,25 @@ export default function App() {
|
|
|
20
20
|
|
|
21
21
|
## API
|
|
22
22
|
|
|
23
|
+
### When to pick which — theme paths
|
|
24
|
+
|
|
25
|
+
Ask this first. Every path below ends in the same `<ThemeProvider theme={...}>`.
|
|
26
|
+
|
|
27
|
+
| You want | Reach for |
|
|
28
|
+
| --- | --- |
|
|
29
|
+
| MD3 defaults, no setup | `<ThemeProvider>` alone (light), or `theme={{ light: lightTheme, dark: darkTheme }}` to follow the OS |
|
|
30
|
+
| A full MD3 palette from one brand color | `createMaterialTheme(seed)` from `@rootnative/core/create-theme` |
|
|
31
|
+
| MD3 with a few token overrides | Spread over `lightTheme` / `darkTheme` (see the custom-theme example under ThemeProvider) |
|
|
32
|
+
| MD3 with sharper or rounder corners | The `roundness` option on `createMaterialTheme`, or `applyRoundness()` on an existing theme |
|
|
33
|
+
| MD3 components plus your own tokens | Spread `lightTheme` in `defineTheme<AppTheme>()` and add a token group on the theme root |
|
|
34
|
+
| Your own role names, for your own components only (the library components need the MD3 roles) | `defineTheme<MyTheme>()` + `useTheme<MyTheme>()` |
|
|
35
|
+
| Light/dark switching and persistence | The `{ light, dark }` pair + `useThemeMode()`; add `storage` to persist |
|
|
36
|
+
| One part of the app with its own colors | A nested `ThemeProvider` with its own pair (see Nested providers) |
|
|
37
|
+
| No light flash for dark readers of a static web export | `schemeGuardScript` + `schemeGuardCss` from `@rootnative/core/static-export` in the HTML shell |
|
|
38
|
+
|
|
23
39
|
### ThemeProvider
|
|
24
40
|
|
|
25
|
-
Wrap your app root to supply the theme to all components.
|
|
41
|
+
Wrap your app root to supply the theme to all components. Takes an MD3 theme, or a theme with your own role names for your own components. The components of `@rootnative/components` read the MD3 color and typography roles, so they need a theme that keeps them. Defaults to the MD3 light theme when no theme is provided.
|
|
26
42
|
|
|
27
43
|
```tsx
|
|
28
44
|
import { ThemeProvider, darkTheme } from '@rootnative/core'
|
|
@@ -33,8 +49,24 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
|
|
|
33
49
|
// Dark theme
|
|
34
50
|
<ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
|
|
35
51
|
|
|
36
|
-
//
|
|
52
|
+
// Light/dark, following the OS setting
|
|
37
53
|
import { lightTheme } from '@rootnative/core'
|
|
54
|
+
|
|
55
|
+
<ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
|
|
56
|
+
{children}
|
|
57
|
+
</ThemeProvider>
|
|
58
|
+
|
|
59
|
+
// ...and remembering the user's override across launches
|
|
60
|
+
import AsyncStorage from '@react-native-async-storage/async-storage'
|
|
61
|
+
|
|
62
|
+
<ThemeProvider
|
|
63
|
+
theme={{ light: lightTheme, dark: darkTheme }}
|
|
64
|
+
storage={AsyncStorage}
|
|
65
|
+
>
|
|
66
|
+
{children}
|
|
67
|
+
</ThemeProvider>
|
|
68
|
+
|
|
69
|
+
// Custom theme
|
|
38
70
|
import type { Theme } from '@rootnative/core'
|
|
39
71
|
|
|
40
72
|
const custom: Theme = {
|
|
@@ -45,9 +77,82 @@ const custom: Theme = {
|
|
|
45
77
|
```
|
|
46
78
|
|
|
47
79
|
Props:
|
|
48
|
-
- `theme?: BaseTheme` —
|
|
80
|
+
- `theme?: BaseTheme | { light: BaseTheme; dark: BaseTheme }` — A single theme, or a light/dark pair. A pair enables `useThemeMode()`. Default: `lightTheme` (MD3)
|
|
81
|
+
- `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"
|
|
82
|
+
- `defaultMode?: 'system' | 'light' | 'dark'` — Initial mode when uncontrolled. Default: `'system'`. On a nested provider, setting it gives the provider a mode of its own
|
|
83
|
+
- `onModeChange?: (mode: ThemeMode) => void`
|
|
84
|
+
- `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'`)
|
|
85
|
+
- `iconResolver?: IconResolver` — Renders string icon names. Pass `mdiResolver` from `@rootnative/components/mdi` for MaterialDesignIcons, or your own. Without it a string name renders nothing and logs one warning. A nested provider without it uses the resolver of its parent
|
|
49
86
|
- `children: ReactNode`
|
|
50
87
|
|
|
88
|
+
### useThemeMode()
|
|
89
|
+
|
|
90
|
+
Reads and controls light/dark mode. Requires a provider given a `{ light, dark }` pair — it throws otherwise, since a single-theme provider has no mode to control.
|
|
91
|
+
|
|
92
|
+
Returns `{ mode, scheme, setMode, isReady }`:
|
|
93
|
+
- `mode` — what was asked for, including `'system'`
|
|
94
|
+
- `scheme` — the resolved `'light' | 'dark'` actually rendering. Use this to sync anything outside the theme, such as the status bar
|
|
95
|
+
- `setMode(mode)` — switches mode, and persists it when `storage` is set
|
|
96
|
+
- `isReady` — `false` until a persisted mode has loaded. Always `true` without `storage`. Gate a splash screen on it to avoid a launch flash
|
|
97
|
+
|
|
98
|
+
```tsx
|
|
99
|
+
import { useThemeMode } from '@rootnative/core'
|
|
100
|
+
import { StatusBar } from 'expo-status-bar'
|
|
101
|
+
|
|
102
|
+
function ThemeToggle() {
|
|
103
|
+
const { scheme, setMode } = useThemeMode()
|
|
104
|
+
|
|
105
|
+
return (
|
|
106
|
+
<>
|
|
107
|
+
<StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
|
|
108
|
+
<Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')}>
|
|
109
|
+
Toggle theme
|
|
110
|
+
</Button>
|
|
111
|
+
</>
|
|
112
|
+
)
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Nested providers
|
|
117
|
+
|
|
118
|
+
A second `ThemeProvider` inside the root one gives one part of the app its own theme, for example the colors of an image:
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
import { createMaterialTheme } from '@rootnative/core/create-theme'
|
|
122
|
+
|
|
123
|
+
const themes = useMemo(() => {
|
|
124
|
+
const { lightTheme: light, darkTheme: dark } = createMaterialTheme(seed)
|
|
125
|
+
return { light, dark }
|
|
126
|
+
}, [seed])
|
|
127
|
+
|
|
128
|
+
<ThemeProvider theme={themes}>{children}</ThemeProvider>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
What a nested provider takes from its parent:
|
|
132
|
+
- **Icon resolver** — with no `iconResolver`, it uses the resolver of its parent.
|
|
133
|
+
- **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.
|
|
134
|
+
- **Named transitions** — its `MotionConfig` merges with the one above, so the named transitions of the app stay.
|
|
135
|
+
|
|
136
|
+
A nested provider with a single theme has no mode, so `useThemeMode()` throws below it.
|
|
137
|
+
|
|
138
|
+
**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.
|
|
139
|
+
|
|
140
|
+
### useThemeScope() and ThemeScopeProvider
|
|
141
|
+
|
|
142
|
+
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.
|
|
143
|
+
|
|
144
|
+
```tsx
|
|
145
|
+
import { ThemeScopeProvider, useThemeScope } from '@rootnative/core'
|
|
146
|
+
|
|
147
|
+
function MyPortal({ children }) {
|
|
148
|
+
const scope = useThemeScope()
|
|
149
|
+
return createPortal(
|
|
150
|
+
<ThemeScopeProvider scope={scope}>{children}</ThemeScopeProvider>,
|
|
151
|
+
host,
|
|
152
|
+
)
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
51
156
|
### useTheme()
|
|
52
157
|
|
|
53
158
|
Returns the current theme from the nearest `ThemeProvider`.
|
|
@@ -68,7 +173,7 @@ const theme = useTheme<MyTheme>()
|
|
|
68
173
|
|
|
69
174
|
### defineTheme(theme)
|
|
70
175
|
|
|
71
|
-
Identity function that validates a custom theme object against `BaseTheme`. Provides type-checking and autocompletion.
|
|
176
|
+
Identity function that validates a custom theme object against `BaseTheme`. Provides type-checking and autocompletion. The theme below has its own role names, so it is for your own components. `BaseTheme` needs only `colors` and `typography`; the other token groups of such a theme are your own. For the library components, spread `lightTheme` and add your tokens beside the MD3 roles.
|
|
72
177
|
|
|
73
178
|
```tsx
|
|
74
179
|
import { defineTheme } from '@rootnative/core'
|
|
@@ -76,7 +181,7 @@ import type { BaseTheme, TypographyToken } from '@rootnative/core'
|
|
|
76
181
|
|
|
77
182
|
interface MyColors { [key: string]: string; brand: string; background: string; text: string }
|
|
78
183
|
interface MyTypography { [key: string]: TypographyToken; heading: TypographyToken; body: TypographyToken }
|
|
79
|
-
interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography }
|
|
184
|
+
interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography; radius: { control: number; card: number } }
|
|
80
185
|
|
|
81
186
|
const myTheme = defineTheme<MyTheme>({
|
|
82
187
|
colors: { brand: '#FF6B00', background: '#FFFFFF', text: '#1A1A1A' },
|
|
@@ -84,11 +189,7 @@ const myTheme = defineTheme<MyTheme>({
|
|
|
84
189
|
heading: { fontFamily: 'Inter', fontSize: 24, fontWeight: '700', lineHeight: 32, letterSpacing: 0 },
|
|
85
190
|
body: { fontFamily: 'Inter', fontSize: 16, fontWeight: '400', lineHeight: 24, letterSpacing: 0.5 },
|
|
86
191
|
},
|
|
87
|
-
|
|
88
|
-
spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
|
|
89
|
-
stateLayer: { pressedOpacity: 0.1, focusedOpacity: 0.1, hoveredOpacity: 0.08, draggedOpacity: 0.16, disabledOpacity: 0.38, disabledContainerOpacity: 0.12 },
|
|
90
|
-
elevation: { ... },
|
|
91
|
-
motion: { ... },
|
|
192
|
+
radius: { control: 8, card: 16 },
|
|
92
193
|
})
|
|
93
194
|
```
|
|
94
195
|
|
|
@@ -99,7 +200,27 @@ Generates a complete MD3 light and dark theme from a single seed color. Uses Goo
|
|
|
99
200
|
Defaults are byte-identical to the upstream MD3 `material-color-utilities` library — pure spec output.
|
|
100
201
|
|
|
101
202
|
**Spec-aligned options:**
|
|
102
|
-
- `variant?: 'tonalSpot' | 'neutral' | 'vibrant' | 'expressive' | 'fidelity' | 'content' | 'monochrome' | 'rainbow' | 'fruitSalad'` — MD3 scheme variant (default `'tonalSpot'`, the Material You default on Android 12+). Each is a spec-defined recipe for deriving the palette. Use `'monochrome'` for spec-legal pure-grey themes, `'vibrant'` for high-colorfulness, etc.
|
|
203
|
+
- `variant?: 'tonalSpot' | 'neutral' | 'vibrant' | 'expressive' | 'fidelity' | 'content' | 'monochrome' | 'rainbow' | 'fruitSalad'` — MD3 scheme variant (default `'tonalSpot'`, the Material You default on Android 12+). Each is a spec-defined recipe for deriving the palette. Use `'monochrome'` for spec-legal pure-grey themes, `'vibrant'` for high-colorfulness, etc. **Two variants move the primary hue away from your seed — see the table below.**
|
|
204
|
+
|
|
205
|
+
**Does the variant keep the seed hue?**
|
|
206
|
+
|
|
207
|
+
Ask this first if the seed is a brand color. `expressive` and `fruitSalad` rotate the primary hue by design — this is correct MD3 behavior, not a defect, but it means the generated `primary` is not your brand color. Example results for the seed `#E07A3F` (a strong orange):
|
|
208
|
+
|
|
209
|
+
| Variant | Light `primary` | Keeps the seed hue? |
|
|
210
|
+
| --- | --- | --- |
|
|
211
|
+
| `tonalSpot` | `#8d4e2a` | Yes |
|
|
212
|
+
| `neutral` | — | Yes (low chroma) |
|
|
213
|
+
| `vibrant` | `#9d4300` | Yes |
|
|
214
|
+
| `expressive` | `#585799` | **No — rotates to blue-violet** |
|
|
215
|
+
| `fidelity` | `#9b450b` | Yes — also returns the seed as `primaryContainer` |
|
|
216
|
+
| `content` | `#9b450b` | Yes |
|
|
217
|
+
| `monochrome` | — | Yes (chroma 0) |
|
|
218
|
+
| `rainbow` | `#984714` | Yes |
|
|
219
|
+
| `fruitSalad` | `#974066` | **No — rotates to magenta** |
|
|
220
|
+
|
|
221
|
+
Use `fidelity`, `content`, or `tonalSpot` to keep the seed hue. Pick `expressive` for colorfulness only when the palette does not have to match a brand color.
|
|
222
|
+
|
|
223
|
+
**`fidelity` pins `primaryContainer` to the seed in both modes.** With `variant: 'fidelity'` the seed is returned as `primaryContainer` in the light theme **and** the dark theme (`onPrimaryContainer` stays dark in both). This is upstream MD3 fidelity behavior: the scheme holds the source color exactly. Every other container role gets darker in dark mode, so a bright container with dark text can break the surface ramp. Override `primaryContainer` / `onPrimaryContainer` for the dark theme if the ramp matters more than seed fidelity.
|
|
103
224
|
- `contrastLevel?: 'standard' | 'medium' | 'high'` — MD3 contrast preset (default `'standard'`). Maps to MD3 contrast values `0 / 0.5 / 1.0`. Use `'medium'` or `'high'` for WCAG AAA / low-vision modes.
|
|
104
225
|
- `fontFamily?: string` — Custom font family applied to all 30 typography styles (15 base + 15 emphasized). When omitted, platform defaults are used (Roboto on Android, System on iOS).
|
|
105
226
|
- `roundness?: number` — Global corner-radius multiplier. `0` = sharp corners, `1` = default MD3 (default), `2` = double rounding. Does not affect `cornerNone` or `cornerFull`.
|
|
@@ -135,18 +256,27 @@ createMaterialTheme('#006A6A', { surfaceTone: 'neutral' })
|
|
|
135
256
|
// Override: per-palette chroma
|
|
136
257
|
createMaterialTheme('#006A6A', { seedAdjustments: { primary: 60, secondary: 32 } })
|
|
137
258
|
|
|
138
|
-
// Use in provider
|
|
259
|
+
// Use in provider — pinned light
|
|
139
260
|
<ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
|
|
140
261
|
|
|
141
|
-
// Or
|
|
142
|
-
|
|
262
|
+
// Or hand both to the provider and let it follow the OS. Rename on
|
|
263
|
+
// destructure so the pair matches the prop's { light, dark } shape.
|
|
264
|
+
const { lightTheme: light, darkTheme: dark } = createMaterialTheme('#006A6A')
|
|
265
|
+
|
|
266
|
+
<ThemeProvider theme={{ light, dark }}>{children}</ThemeProvider>
|
|
143
267
|
```
|
|
144
268
|
|
|
145
269
|
Returns: `{ lightTheme: Theme, darkTheme: Theme }`
|
|
146
270
|
|
|
147
271
|
The generated themes include all 49 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
|
|
148
272
|
|
|
149
|
-
|
|
273
|
+
No extra install is needed: `@material/material-color-utilities` is bundled inside `@rootnative/core`, behind the `create-theme` subpath. Projects that never import the subpath never load it.
|
|
274
|
+
|
|
275
|
+
The subpath also imports nothing from `react-native`, so it runs in plain Node — print a palette from a script, check a theme in CI, or feed the roles to a design-token pipeline:
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
node -e "import('@rootnative/core/create-theme').then(({ createMaterialTheme }) => console.log(createMaterialTheme('#006A6A').lightTheme.colors))"
|
|
279
|
+
```
|
|
150
280
|
|
|
151
281
|
### applyRoundness(roundness)
|
|
152
282
|
|
|
@@ -181,8 +311,8 @@ material.defaultTopAppBarTokens
|
|
|
181
311
|
|
|
182
312
|
### Theme type hierarchy
|
|
183
313
|
|
|
184
|
-
- `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`,
|
|
185
|
-
- `Theme` — Material Design 3 theme. Extends `BaseTheme` with 49 MD3 color roles, 30 typography variants (15 base + 15 emphasized), and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
|
|
314
|
+
- `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`, and an index signature for token groups of your own. It has no MD3 group.
|
|
315
|
+
- `Theme` — Material Design 3 theme. Extends `BaseTheme` with 49 MD3 color roles, 30 typography variants (15 base + 15 emphasized), the `shape`, `spacing`, `stateLayer`, `elevation` and `motion` groups, and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
|
|
186
316
|
|
|
187
317
|
### Theme structure
|
|
188
318
|
|
|
@@ -190,20 +320,23 @@ material.defaultTopAppBarTokens
|
|
|
190
320
|
BaseTheme {
|
|
191
321
|
colors: Record<string, string>
|
|
192
322
|
typography: Record<string, TypographyToken>
|
|
193
|
-
|
|
194
|
-
spacing: Spacing — xs, sm, md, lg, xl
|
|
195
|
-
elevation: Elevation — level0..level5 (shadow properties)
|
|
196
|
-
stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
|
|
197
|
-
motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
|
|
323
|
+
[key: string]: unknown — token groups of your own
|
|
198
324
|
}
|
|
199
325
|
|
|
200
326
|
Theme extends BaseTheme {
|
|
201
327
|
colors: Colors — 49 MD3 color roles
|
|
202
328
|
typography: Typography — 30 type scale variants: 15 base (displayLarge..labelSmall) + 15 MD3 Expressive emphasized (displayLargeEmphasized..labelSmallEmphasized)
|
|
203
|
-
|
|
329
|
+
shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
|
|
330
|
+
spacing: Spacing — xs, sm, md, lg, xl
|
|
331
|
+
elevation: Elevation — level0..level5 (shadow properties)
|
|
332
|
+
stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
|
|
333
|
+
motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
|
|
334
|
+
topAppBar?: TopAppBarTokens — horizontalPadding, titleStartInset, smallContainerHeight, mediumContainerHeight, largeContainerHeight, topRowHeight, sideSlotMinHeight, iconFrameSize, mediumTitleBottomPadding, largeTitleBottomPadding (AppBar geometry in dp)
|
|
204
335
|
}
|
|
205
336
|
```
|
|
206
337
|
|
|
338
|
+
`TopAppBarTokens`: `AppBar` follows the Compose `TopAppBarLayout` geometry. The title starts at `max(titleStartInset, horizontalPadding + leading width) + horizontalPadding` from the start edge (16dp with no leading content, 56dp after a 48dp navigation icon), and the last action ends `horizontalPadding` (4dp) from the end edge. No pair of token values puts both on one wider gutter: keep the tokens and pad the bar with `style` (`paddingStart: gutter - horizontalPadding - titleStartInset`, `paddingEnd: gutter - horizontalPadding`).
|
|
339
|
+
|
|
207
340
|
Colors: primary, onPrimary, primaryContainer, onPrimaryContainer, primaryFixed, onPrimaryFixed, primaryFixedDim, onPrimaryFixedVariant, secondary (same pattern), tertiary (same pattern), error, onError, errorContainer, onErrorContainer, background, onBackground, surface, surfaceDim, surfaceBright, surfaceContainerLowest, surfaceContainerLow, surfaceContainer, surfaceContainerHigh, surfaceContainerHighest, onSurface, surfaceVariant, onSurfaceVariant, outline, outlineVariant, surfaceTint, shadow, scrim, inverseSurface, inverseOnSurface, inversePrimary
|
|
208
341
|
|
|
209
342
|
Typography variants: displayLarge, displayMedium, displaySmall, headlineLarge, headlineMedium, headlineSmall, titleLarge, titleMedium, titleSmall, bodyLarge, bodyMedium, bodySmall, labelLarge, labelMedium, labelSmall — each with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing. Each also has an MD3 Expressive `<name>Emphasized` variant (same size/line height, weight one step heavier: 400→500, 500→700).
|
|
@@ -232,3 +365,60 @@ const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
|
|
|
232
365
|
|
|
233
366
|
Type: `useBreakpointValue<T>(values: Partial<Record<Breakpoint, T>> & Record<'compact', T>): T`
|
|
234
367
|
|
|
368
|
+
### useWindowDimensions()
|
|
369
|
+
|
|
370
|
+
Returns the window size, the same as `useWindowDimensions` from `react-native`, but hydration-safe. Use it instead of the `react-native` hook when a layout needs a number rather than a size class: a hero height, a carousel slot, a column count.
|
|
371
|
+
|
|
372
|
+
```tsx
|
|
373
|
+
import { useWindowDimensions } from '@rootnative/core'
|
|
374
|
+
|
|
375
|
+
const { width } = useWindowDimensions()
|
|
376
|
+
const heroHeight = width * 0.56
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
Type: `useWindowDimensions(): ScaledSize`
|
|
380
|
+
|
|
381
|
+
### Breakpoints and static export (web)
|
|
382
|
+
|
|
383
|
+
The three hooks are hydration-safe, so **no `useHydrated` gate is needed at the call site**. The `useWindowDimensions` hook from `react-native` is **not**: on a static export it keeps the layout of a 0 wide window until the reader resizes the window.
|
|
384
|
+
|
|
385
|
+
A static export (`web.output: 'static'`) renders on a server with no DOM, where react-native-web's `Dimensions` is fixed at `width: 0` — so every breakpoint resolves to `compact` and that is what ships in the HTML. React 19 does **not** repair a `className`/`style` mismatch during hydration: it adopts the server DOM, keeps it, and fires no recoverable error, so a tablet would silently keep the phone layout.
|
|
386
|
+
|
|
387
|
+
`useWindowDimensions` therefore reports the server's 0 by 0 window for as long as the client is hydrating, matching that markup, and switches to the measured window on the re-render React schedules once hydration finishes. `useBreakpoint` reads it, so it reports `compact` for the same span, and a breakpoint and a raw width cannot disagree. On native and on a single-page web build there is no hydration, so the measured value is returned from the first render at no cost.
|
|
388
|
+
|
|
389
|
+
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.
|
|
390
|
+
|
|
391
|
+
`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.
|
|
392
|
+
|
|
393
|
+
### Static export: the dark first paint (web)
|
|
394
|
+
|
|
395
|
+
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.
|
|
396
|
+
|
|
397
|
+
`@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:
|
|
398
|
+
|
|
399
|
+
```tsx
|
|
400
|
+
import { darkTheme } from '@rootnative/core'
|
|
401
|
+
import {
|
|
402
|
+
schemeGuardCss,
|
|
403
|
+
schemeGuardScript,
|
|
404
|
+
} from '@rootnative/core/static-export'
|
|
405
|
+
|
|
406
|
+
const SCHEME_GUARD_CSS = schemeGuardCss({
|
|
407
|
+
background: darkTheme.colors.background,
|
|
408
|
+
})
|
|
409
|
+
|
|
410
|
+
// inside <head>
|
|
411
|
+
<script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
|
|
412
|
+
<style dangerouslySetInnerHTML={{ __html: SCHEME_GUARD_CSS }} />
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
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.
|
|
416
|
+
2. For the dark scheme, the CSS hides `#root` and paints `background` under it.
|
|
417
|
+
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.
|
|
418
|
+
|
|
419
|
+
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).
|
|
420
|
+
|
|
421
|
+
Options:
|
|
422
|
+
- `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`
|
|
423
|
+
- `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`
|
|
424
|
+
|