@rootnative/core 0.0.0-alpha.1 → 0.0.0-alpha.10
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 +24 -11
- package/dist/{chunk-DC35U5WG.mjs → chunk-QQ3ME6R7.mjs} +118 -1
- package/dist/create-theme/index.d.mts +1 -1
- package/dist/create-theme/index.mjs +1 -1
- package/dist/index.d.mts +164 -6
- package/dist/index.mjs +137 -7
- package/dist/{types-GiXhVyob.d.mts → types-NiRbh4dM.d.mts} +93 -26
- package/llms.txt +73 -21
- package/package.json +3 -1
package/README.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
Absolute URL, not a relative path: this README is the npm package page, and
|
|
3
|
+
npm does not resolve repository-relative image paths.
|
|
4
|
+
-->
|
|
5
|
+
<img src="https://raw.githubusercontent.com/rootnative/ui/main/assets/brand/rootnative-mark.png" alt="" width="88" height="88" />
|
|
6
|
+
|
|
1
7
|
# @rootnative/core
|
|
2
8
|
|
|
3
9
|
Design-system agnostic theme engine for [RootNative UI](https://github.com/rootnative/ui) — a React Native component library. Ships with Material Design 3 out of the box.
|
|
@@ -5,10 +11,14 @@ Design-system agnostic theme engine for [RootNative UI](https://github.com/rootn
|
|
|
5
11
|
## Install
|
|
6
12
|
|
|
7
13
|
```bash
|
|
8
|
-
pnpm add @rootnative/core
|
|
14
|
+
pnpm add @rootnative/core @rootnative/inertia
|
|
9
15
|
```
|
|
10
16
|
|
|
11
|
-
Peer dependencies: `react >=18`, `react-native >=0.72`
|
|
17
|
+
Peer dependencies: `react >=18`, `react-native >=0.72`, `@rootnative/inertia >=0.0.6 <0.1.0`
|
|
18
|
+
|
|
19
|
+
`@rootnative/inertia` is required — every animation in the library runs on it.
|
|
20
|
+
npm and pnpm install required peers automatically; Yarn classic does not, so add
|
|
21
|
+
it by hand there.
|
|
12
22
|
|
|
13
23
|
Optional: `@material/material-color-utilities >=0.4` — only needed for `createMaterialTheme`.
|
|
14
24
|
|
|
@@ -112,20 +122,20 @@ material.defaultTopAppBarTokens
|
|
|
112
122
|
|
|
113
123
|
### Theme type hierarchy
|
|
114
124
|
|
|
115
|
-
- `BaseTheme` — Generic base. Colors as `Record<string, string>`, typography as `Record<string,
|
|
116
|
-
- `Theme` — MD3 theme. Extends `BaseTheme` with
|
|
125
|
+
- `BaseTheme` — Generic base. Colors as `Record<string, string>`, typography as `Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
|
|
126
|
+
- `Theme` — MD3 theme. Extends `BaseTheme` with 49 color roles, 30 typography variants (15 base + 15 emphasized), optional `topAppBar` tokens. `MaterialTheme` is an identical alias — use it to disambiguate in multi-design-system codebases.
|
|
117
127
|
|
|
118
128
|
### Theme structure
|
|
119
129
|
|
|
120
130
|
| Token group | Description |
|
|
121
131
|
|-------------|-------------|
|
|
122
132
|
| `colors` | Design-system specific color roles (`Record<string, string>`) |
|
|
123
|
-
| `typography` | Type scale variants (`Record<string,
|
|
124
|
-
| `shape` |
|
|
133
|
+
| `typography` | Type scale variants (`Record<string, TypographyToken>`) |
|
|
134
|
+
| `shape` | `roundness` multiplier plus corner radius tokens (`cornerNone` through `cornerFull`) |
|
|
125
135
|
| `spacing` | Spacing scale (xs, sm, md, lg, xl) |
|
|
126
|
-
| `elevation` | Shadow levels
|
|
127
|
-
| `stateLayer` | Opacity values
|
|
128
|
-
| `motion` |
|
|
136
|
+
| `elevation` | Shadow levels `level0` through `level5` |
|
|
137
|
+
| `stateLayer` | Opacity values: `pressedOpacity`, `focusedOpacity`, `hoveredOpacity`, `draggedOpacity`, `disabledOpacity`, `disabledContainerOpacity` |
|
|
138
|
+
| `motion` | 16 `duration*`, 7 `easing*` and 6 `spring*` tokens |
|
|
129
139
|
|
|
130
140
|
### Custom MD3 theme
|
|
131
141
|
|
|
@@ -174,11 +184,14 @@ const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
|
|
|
174
184
|
- `useBreakpointValue` — Responsive values
|
|
175
185
|
- `lightTheme` / `darkTheme` — Built-in MD3 themes
|
|
176
186
|
- `defaultTopAppBarTokens` — MD3 top app bar defaults
|
|
177
|
-
- `
|
|
187
|
+
- `motionTransitions` — The named-transition registry mounted by `ThemeProvider`
|
|
188
|
+
- `BaseTheme`, `Theme`, `MaterialTheme`, `Colors`, `Typography`, `TypographyToken`, `FontWeight`, `Shape`, `Spacing`, `Elevation`, `ElevationLevel`, `ShadowOffset`, `StateLayer`, `Motion`, `MotionSpring`, `TopAppBarTokens`, `IconResolver`, `IconRenderProps`, `IconSource`, `ThemeProviderProps`, `Breakpoint`, `BreakpointValues` — Types
|
|
178
189
|
|
|
179
190
|
## Docs
|
|
180
191
|
|
|
181
|
-
https://rootnative.github.io/ui/
|
|
192
|
+
Full docs: https://rootnative.github.io/ui/
|
|
193
|
+
|
|
194
|
+
LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt — or read `node_modules/@rootnative/core/llms.txt` for the exact installed version.
|
|
182
195
|
|
|
183
196
|
## License
|
|
184
197
|
|
|
@@ -125,6 +125,115 @@ var defaultTypography = {
|
|
|
125
125
|
fontWeight: "500",
|
|
126
126
|
lineHeight: 16,
|
|
127
127
|
letterSpacing: 0.5
|
|
128
|
+
},
|
|
129
|
+
// MD3 Expressive emphasized styles — androidx TypeScaleTokens.kt v0_103.
|
|
130
|
+
// Same size/line-height as the base style, weight one step heavier
|
|
131
|
+
// (400→500, 500→700); displayLarge/titleMedium/bodyLarge/bodyMedium also
|
|
132
|
+
// adjust tracking per the Compose tokens.
|
|
133
|
+
displayLargeEmphasized: {
|
|
134
|
+
fontFamily: defaultFontFamily,
|
|
135
|
+
fontSize: 57,
|
|
136
|
+
fontWeight: "500",
|
|
137
|
+
lineHeight: 64,
|
|
138
|
+
letterSpacing: 0
|
|
139
|
+
},
|
|
140
|
+
displayMediumEmphasized: {
|
|
141
|
+
fontFamily: defaultFontFamily,
|
|
142
|
+
fontSize: 45,
|
|
143
|
+
fontWeight: "500",
|
|
144
|
+
lineHeight: 52,
|
|
145
|
+
letterSpacing: 0
|
|
146
|
+
},
|
|
147
|
+
displaySmallEmphasized: {
|
|
148
|
+
fontFamily: defaultFontFamily,
|
|
149
|
+
fontSize: 36,
|
|
150
|
+
fontWeight: "500",
|
|
151
|
+
lineHeight: 44,
|
|
152
|
+
letterSpacing: 0
|
|
153
|
+
},
|
|
154
|
+
headlineLargeEmphasized: {
|
|
155
|
+
fontFamily: defaultFontFamily,
|
|
156
|
+
fontSize: 32,
|
|
157
|
+
fontWeight: "500",
|
|
158
|
+
lineHeight: 40,
|
|
159
|
+
letterSpacing: 0
|
|
160
|
+
},
|
|
161
|
+
headlineMediumEmphasized: {
|
|
162
|
+
fontFamily: defaultFontFamily,
|
|
163
|
+
fontSize: 28,
|
|
164
|
+
fontWeight: "500",
|
|
165
|
+
lineHeight: 36,
|
|
166
|
+
letterSpacing: 0
|
|
167
|
+
},
|
|
168
|
+
headlineSmallEmphasized: {
|
|
169
|
+
fontFamily: defaultFontFamily,
|
|
170
|
+
fontSize: 24,
|
|
171
|
+
fontWeight: "500",
|
|
172
|
+
lineHeight: 32,
|
|
173
|
+
letterSpacing: 0
|
|
174
|
+
},
|
|
175
|
+
titleLargeEmphasized: {
|
|
176
|
+
fontFamily: defaultFontFamily,
|
|
177
|
+
fontSize: 22,
|
|
178
|
+
fontWeight: "500",
|
|
179
|
+
lineHeight: 28,
|
|
180
|
+
letterSpacing: 0
|
|
181
|
+
},
|
|
182
|
+
titleMediumEmphasized: {
|
|
183
|
+
fontFamily: defaultFontFamily,
|
|
184
|
+
fontSize: 16,
|
|
185
|
+
fontWeight: "700",
|
|
186
|
+
lineHeight: 24,
|
|
187
|
+
letterSpacing: 0.15
|
|
188
|
+
},
|
|
189
|
+
titleSmallEmphasized: {
|
|
190
|
+
fontFamily: defaultFontFamily,
|
|
191
|
+
fontSize: 14,
|
|
192
|
+
fontWeight: "700",
|
|
193
|
+
lineHeight: 20,
|
|
194
|
+
letterSpacing: 0.1
|
|
195
|
+
},
|
|
196
|
+
bodyLargeEmphasized: {
|
|
197
|
+
fontFamily: defaultFontFamily,
|
|
198
|
+
fontSize: 16,
|
|
199
|
+
fontWeight: "500",
|
|
200
|
+
lineHeight: 24,
|
|
201
|
+
letterSpacing: 0.15
|
|
202
|
+
},
|
|
203
|
+
bodyMediumEmphasized: {
|
|
204
|
+
fontFamily: defaultFontFamily,
|
|
205
|
+
fontSize: 14,
|
|
206
|
+
fontWeight: "500",
|
|
207
|
+
lineHeight: 20,
|
|
208
|
+
letterSpacing: 0.25
|
|
209
|
+
},
|
|
210
|
+
bodySmallEmphasized: {
|
|
211
|
+
fontFamily: defaultFontFamily,
|
|
212
|
+
fontSize: 12,
|
|
213
|
+
fontWeight: "500",
|
|
214
|
+
lineHeight: 16,
|
|
215
|
+
letterSpacing: 0.4
|
|
216
|
+
},
|
|
217
|
+
labelLargeEmphasized: {
|
|
218
|
+
fontFamily: defaultFontFamily,
|
|
219
|
+
fontSize: 14,
|
|
220
|
+
fontWeight: "700",
|
|
221
|
+
lineHeight: 20,
|
|
222
|
+
letterSpacing: 0.1
|
|
223
|
+
},
|
|
224
|
+
labelMediumEmphasized: {
|
|
225
|
+
fontFamily: defaultFontFamily,
|
|
226
|
+
fontSize: 12,
|
|
227
|
+
fontWeight: "700",
|
|
228
|
+
lineHeight: 16,
|
|
229
|
+
letterSpacing: 0.5
|
|
230
|
+
},
|
|
231
|
+
labelSmallEmphasized: {
|
|
232
|
+
fontFamily: defaultFontFamily,
|
|
233
|
+
fontSize: 11,
|
|
234
|
+
fontWeight: "700",
|
|
235
|
+
lineHeight: 16,
|
|
236
|
+
letterSpacing: 0.5
|
|
128
237
|
}
|
|
129
238
|
};
|
|
130
239
|
|
|
@@ -293,7 +402,15 @@ var lightTheme = {
|
|
|
293
402
|
easingStandardDecelerate: "cubic-bezier(0, 0, 0, 1)",
|
|
294
403
|
easingEmphasized: "cubic-bezier(0.2, 0, 0, 1)",
|
|
295
404
|
easingEmphasizedAccelerate: "cubic-bezier(0.3, 0, 0.8, 0.15)",
|
|
296
|
-
easingEmphasizedDecelerate: "cubic-bezier(0.05, 0.7, 0.1, 1)"
|
|
405
|
+
easingEmphasizedDecelerate: "cubic-bezier(0.05, 0.7, 0.1, 1)",
|
|
406
|
+
// MD3 Expressive scheme, androidx ExpressiveMotionTokens.kt v0_14_0.
|
|
407
|
+
// tension = Compose stiffness; friction = dampingRatio * 2 * sqrt(tension).
|
|
408
|
+
springFastSpatial: { tension: 800, friction: 33.94, mass: 1 },
|
|
409
|
+
springDefaultSpatial: { tension: 380, friction: 31.19, mass: 1 },
|
|
410
|
+
springSlowSpatial: { tension: 200, friction: 22.63, mass: 1 },
|
|
411
|
+
springFastEffects: { tension: 3800, friction: 123.29, mass: 1 },
|
|
412
|
+
springDefaultEffects: { tension: 1600, friction: 80, mass: 1 },
|
|
413
|
+
springSlowEffects: { tension: 800, friction: 56.57, mass: 1 }
|
|
297
414
|
}
|
|
298
415
|
};
|
|
299
416
|
|
package/dist/index.d.mts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import { T as Theme, a as TopAppBarTokens, B as BaseTheme, S as Shape } from './types-
|
|
2
|
-
export { C as Colors, E as Elevation, b as ElevationLevel, F as FontWeight,
|
|
1
|
+
import { T as Theme, a as TopAppBarTokens, B as BaseTheme, M as Motion, S as Shape } from './types-NiRbh4dM.mjs';
|
|
2
|
+
export { C as Colors, E as Elevation, b as ElevationLevel, F as FontWeight, c as MaterialTheme, d as MotionSpring, e as ShadowOffset, f as Spacing, g as StateLayer, h as Typography, i as TypographyToken } from './types-NiRbh4dM.mjs';
|
|
3
|
+
import { TransitionConfig, NamedTransitions } from '@rootnative/inertia';
|
|
3
4
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
4
5
|
import * as React from 'react';
|
|
5
6
|
|
|
@@ -26,6 +27,33 @@ declare const defaultTopAppBarTokens: TopAppBarTokens;
|
|
|
26
27
|
*/
|
|
27
28
|
declare function defineTheme<T extends BaseTheme>(theme: T): T;
|
|
28
29
|
|
|
30
|
+
declare module '@rootnative/inertia' {
|
|
31
|
+
interface RegisteredTransitions {
|
|
32
|
+
'state-hover': TransitionConfig;
|
|
33
|
+
'state-press': TransitionConfig;
|
|
34
|
+
'state-focus': TransitionConfig;
|
|
35
|
+
'spring-fast-spatial': TransitionConfig;
|
|
36
|
+
'spring-default-spatial': TransitionConfig;
|
|
37
|
+
'spring-slow-spatial': TransitionConfig;
|
|
38
|
+
'spring-fast-effects': TransitionConfig;
|
|
39
|
+
'spring-default-effects': TransitionConfig;
|
|
40
|
+
'spring-slow-effects': TransitionConfig;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Map a theme's motion tokens into inertia's named-transition registry.
|
|
45
|
+
* `ThemeProvider` feeds the result to `<MotionConfig transitions>`, making
|
|
46
|
+
* `theme.motion.*` the single source of truth components (and consumers)
|
|
47
|
+
* reference by name instead of hand-rolling `withTiming`/`withSpring`
|
|
48
|
+
* configs.
|
|
49
|
+
*
|
|
50
|
+
* The state-layer names encode the library's interaction motion policy —
|
|
51
|
+
* per MD3 Expressive, state-layer color/opacity feedback rides the
|
|
52
|
+
* fast-effects spring (small-element effects, critically damped). The
|
|
53
|
+
* spring names expose the theme's `MotionSpring` tokens verbatim.
|
|
54
|
+
*/
|
|
55
|
+
declare function motionTransitions(motion: Motion): NamedTransitions;
|
|
56
|
+
|
|
29
57
|
/**
|
|
30
58
|
* Scales the intermediate corner radius tokens by a `roundness` multiplier.
|
|
31
59
|
* `cornerNone` always stays `0` and `cornerFull` always stays `999`.
|
|
@@ -56,15 +84,122 @@ interface IconRenderProps {
|
|
|
56
84
|
* etc. without forking components.
|
|
57
85
|
*/
|
|
58
86
|
type IconResolver = (name: string, props: IconRenderProps) => React.ReactNode;
|
|
59
|
-
|
|
87
|
+
/**
|
|
88
|
+
* Anything a component will accept for an icon prop:
|
|
89
|
+
*
|
|
90
|
+
* - **string** — a name resolved via the `iconResolver` registered on
|
|
91
|
+
* `ThemeProvider`. Falls back to `MaterialCommunityIcons` when no
|
|
92
|
+
* resolver is set, preserving the legacy default.
|
|
93
|
+
* - **ReactElement** — a pre-rendered icon. The caller is responsible for
|
|
94
|
+
* passing size and color; the component will not override them.
|
|
95
|
+
* - **(props) => ReactNode** — a render function that receives the
|
|
96
|
+
* component's resolved size and color. Useful for plugging in Lucide,
|
|
97
|
+
* SF Symbols, or custom SVGs without losing theme integration.
|
|
98
|
+
*/
|
|
99
|
+
type IconSource = string | React.ReactElement | ((props: IconRenderProps) => React.ReactNode);
|
|
60
100
|
|
|
101
|
+
/**
|
|
102
|
+
* What the app asks for. `'system'` follows the OS setting and keeps
|
|
103
|
+
* following it as the OS changes; `'light'` / `'dark'` pin the scheme.
|
|
104
|
+
*/
|
|
105
|
+
type ThemeMode = 'system' | 'light' | 'dark';
|
|
106
|
+
/** What the app actually renders. `'system'` is always resolved away. */
|
|
107
|
+
type ColorScheme = 'light' | 'dark';
|
|
108
|
+
/**
|
|
109
|
+
* Persists the user's mode choice across launches. Deliberately structural
|
|
110
|
+
* rather than a dependency on any one storage library: pass an
|
|
111
|
+
* AsyncStorage-shaped object, MMKV, `localStorage`, SecureStore, or your own
|
|
112
|
+
* wrapper. `@rootnative/core` takes no storage dependency of its own.
|
|
113
|
+
*
|
|
114
|
+
* Both methods may be sync or async — the provider awaits either.
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* import AsyncStorage from '@react-native-async-storage/async-storage'
|
|
118
|
+
*
|
|
119
|
+
* <ThemeProvider theme={{ light, dark }} storage={AsyncStorage}>
|
|
120
|
+
*/
|
|
121
|
+
interface ThemeModeStorage {
|
|
122
|
+
getItem: (key: string) => string | null | Promise<string | null>;
|
|
123
|
+
setItem: (key: string, value: string) => unknown | Promise<unknown>;
|
|
124
|
+
}
|
|
125
|
+
interface ThemeModeContextValue {
|
|
126
|
+
/** The requested mode, including `'system'`. */
|
|
127
|
+
mode: ThemeMode;
|
|
128
|
+
/**
|
|
129
|
+
* The resolved scheme actually in use. `mode: 'system'` resolves this from
|
|
130
|
+
* the OS; `'light'` / `'dark'` pass straight through. Use this to sync
|
|
131
|
+
* anything outside the theme — most commonly the status bar.
|
|
132
|
+
*/
|
|
133
|
+
scheme: ColorScheme;
|
|
134
|
+
/** Sets the mode, and persists it when a `storage` is configured. */
|
|
135
|
+
setMode: (mode: ThemeMode) => void;
|
|
136
|
+
/**
|
|
137
|
+
* `false` until a persisted mode has been read back from `storage`. Always
|
|
138
|
+
* `true` when no `storage` is configured, since there is nothing to wait
|
|
139
|
+
* for. Gate a splash screen on this to avoid a light-to-dark flash on
|
|
140
|
+
* launch.
|
|
141
|
+
*/
|
|
142
|
+
isReady: boolean;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/**
|
|
146
|
+
* A light/dark pair. Matches what `createMaterialTheme()` returns, so its
|
|
147
|
+
* result can be renamed straight into the prop:
|
|
148
|
+
* `const { lightTheme: light, darkTheme: dark } = createMaterialTheme(seed)`.
|
|
149
|
+
*/
|
|
150
|
+
interface ThemePair {
|
|
151
|
+
light: BaseTheme;
|
|
152
|
+
dark: BaseTheme;
|
|
153
|
+
}
|
|
154
|
+
/** Storage key for the persisted mode. Namespaced to avoid app collisions. */
|
|
155
|
+
declare const THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
|
|
61
156
|
interface ThemeProviderProps {
|
|
62
157
|
/**
|
|
63
158
|
* Theme object to provide to all child components via context.
|
|
64
159
|
* Accepts any theme extending `BaseTheme` — Material, Apple, or custom.
|
|
160
|
+
*
|
|
161
|
+
* Pass a `{ light, dark }` pair to enable light/dark switching: the provider
|
|
162
|
+
* then resolves which one to use from `mode` plus the OS setting, and
|
|
163
|
+
* `useThemeMode()` becomes available to descendants.
|
|
164
|
+
*
|
|
65
165
|
* @default lightTheme (Material Design 3)
|
|
66
166
|
*/
|
|
67
|
-
theme?: BaseTheme;
|
|
167
|
+
theme?: BaseTheme | ThemePair;
|
|
168
|
+
/**
|
|
169
|
+
* Which theme of the pair to use. `'system'` follows the OS and keeps
|
|
170
|
+
* following it; `'light'` / `'dark'` pin it. Ignored when `theme` is a
|
|
171
|
+
* single theme.
|
|
172
|
+
*
|
|
173
|
+
* Leave uncontrolled (the default) and drive it with `setMode()` from
|
|
174
|
+
* `useThemeMode()`. Pass it to control the mode from your own state — the
|
|
175
|
+
* provider then never changes it on its own, so pair it with `onModeChange`.
|
|
176
|
+
*
|
|
177
|
+
* @default 'system'
|
|
178
|
+
*/
|
|
179
|
+
mode?: ThemeMode;
|
|
180
|
+
/**
|
|
181
|
+
* Initial mode for the uncontrolled case. A persisted value from `storage`
|
|
182
|
+
* wins over this once it loads.
|
|
183
|
+
*
|
|
184
|
+
* @default 'system'
|
|
185
|
+
*/
|
|
186
|
+
defaultMode?: ThemeMode;
|
|
187
|
+
/** Called whenever `setMode()` runs, controlled or not. */
|
|
188
|
+
onModeChange?: (mode: ThemeMode) => void;
|
|
189
|
+
/**
|
|
190
|
+
* Persists the mode across launches. Any object with `getItem`/`setItem` —
|
|
191
|
+
* AsyncStorage, MMKV, `localStorage`. `@rootnative/core` takes no storage
|
|
192
|
+
* dependency of its own, so nothing is persisted unless you pass this.
|
|
193
|
+
*
|
|
194
|
+
* Ignored when `mode` is controlled: your own state is then the source of
|
|
195
|
+
* truth and persisting behind it would fight it.
|
|
196
|
+
*
|
|
197
|
+
* @example
|
|
198
|
+
* import AsyncStorage from '@react-native-async-storage/async-storage'
|
|
199
|
+
*
|
|
200
|
+
* <ThemeProvider theme={{ light, dark }} storage={AsyncStorage}>
|
|
201
|
+
*/
|
|
202
|
+
storage?: ThemeModeStorage;
|
|
68
203
|
/**
|
|
69
204
|
* Resolves string icon names (e.g. `leadingIcon="check"`) to icon nodes.
|
|
70
205
|
* Set this once at the app root to use SF Symbols, Lucide, custom SVGs,
|
|
@@ -100,6 +235,14 @@ interface ThemeProviderProps {
|
|
|
100
235
|
* </ThemeProvider>
|
|
101
236
|
*
|
|
102
237
|
* @example
|
|
238
|
+
* // Light/dark, following the OS
|
|
239
|
+
* import { ThemeProvider, lightTheme, darkTheme } from '@rootnative/core'
|
|
240
|
+
*
|
|
241
|
+
* <ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
|
|
242
|
+
* <App />
|
|
243
|
+
* </ThemeProvider>
|
|
244
|
+
*
|
|
245
|
+
* @example
|
|
103
246
|
* // Custom or Apple theme
|
|
104
247
|
* import { ThemeProvider } from '@rootnative/core'
|
|
105
248
|
*
|
|
@@ -107,7 +250,7 @@ interface ThemeProviderProps {
|
|
|
107
250
|
* <App />
|
|
108
251
|
* </ThemeProvider>
|
|
109
252
|
*/
|
|
110
|
-
declare function ThemeProvider({ theme, iconResolver, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
|
|
253
|
+
declare function ThemeProvider({ theme, mode: controlledMode, defaultMode, onModeChange, storage, iconResolver, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
|
|
111
254
|
|
|
112
255
|
/**
|
|
113
256
|
* Returns the current theme from the nearest `ThemeProvider`.
|
|
@@ -126,6 +269,21 @@ declare function ThemeProvider({ theme, iconResolver, children, }: ThemeProvider
|
|
|
126
269
|
*/
|
|
127
270
|
declare function useTheme<T extends BaseTheme = Theme>(): T;
|
|
128
271
|
|
|
272
|
+
/**
|
|
273
|
+
* Reads and controls the light/dark mode of the nearest `ThemeProvider`.
|
|
274
|
+
*
|
|
275
|
+
* Requires a provider configured with a theme *pair* — `theme={{ light, dark }}`.
|
|
276
|
+
* A provider given a single theme has no mode to report, so this throws rather
|
|
277
|
+
* than inventing one.
|
|
278
|
+
*
|
|
279
|
+
* @example
|
|
280
|
+
* const { mode, scheme, setMode } = useThemeMode()
|
|
281
|
+
*
|
|
282
|
+
* <StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
|
|
283
|
+
* <Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')} />
|
|
284
|
+
*/
|
|
285
|
+
declare function useThemeMode(): ThemeModeContextValue;
|
|
286
|
+
|
|
129
287
|
/**
|
|
130
288
|
* Returns the icon resolver registered on the nearest `ThemeProvider`,
|
|
131
289
|
* or `null` if none was provided. Components fall back to
|
|
@@ -183,4 +341,4 @@ declare const material: {
|
|
|
183
341
|
readonly defaultTopAppBarTokens: TopAppBarTokens;
|
|
184
342
|
};
|
|
185
343
|
|
|
186
|
-
export { BaseTheme, type Breakpoint, type BreakpointValues, type IconRenderProps, type IconResolver,
|
|
344
|
+
export { BaseTheme, type Breakpoint, type BreakpointValues, type ColorScheme, type IconRenderProps, type IconResolver, type IconSource, Motion, Shape, THEME_MODE_STORAGE_KEY, Theme, type ThemeMode, type ThemeModeContextValue, type ThemeModeStorage, type ThemePair, ThemeProvider, type ThemeProviderProps, TopAppBarTokens, applyRoundness, breakpoints, darkTheme, defaultTopAppBarTokens, defineTheme, lightTheme, material, motionTransitions, useBreakpoint, useBreakpointValue, useIconResolver, useTheme, useThemeMode };
|
package/dist/index.mjs
CHANGED
|
@@ -3,7 +3,7 @@ import {
|
|
|
3
3
|
defaultTopAppBarTokens,
|
|
4
4
|
defaultTypography,
|
|
5
5
|
lightTheme
|
|
6
|
-
} from "./chunk-
|
|
6
|
+
} from "./chunk-QQ3ME6R7.mjs";
|
|
7
7
|
|
|
8
8
|
// src/theme/dark.ts
|
|
9
9
|
var darkTheme = {
|
|
@@ -170,7 +170,15 @@ var darkTheme = {
|
|
|
170
170
|
easingStandardDecelerate: "cubic-bezier(0, 0, 0, 1)",
|
|
171
171
|
easingEmphasized: "cubic-bezier(0.2, 0, 0, 1)",
|
|
172
172
|
easingEmphasizedAccelerate: "cubic-bezier(0.3, 0, 0.8, 0.15)",
|
|
173
|
-
easingEmphasizedDecelerate: "cubic-bezier(0.05, 0.7, 0.1, 1)"
|
|
173
|
+
easingEmphasizedDecelerate: "cubic-bezier(0.05, 0.7, 0.1, 1)",
|
|
174
|
+
// MD3 Expressive scheme, androidx ExpressiveMotionTokens.kt v0_14_0.
|
|
175
|
+
// tension = Compose stiffness; friction = dampingRatio * 2 * sqrt(tension).
|
|
176
|
+
springFastSpatial: { tension: 800, friction: 33.94, mass: 1 },
|
|
177
|
+
springDefaultSpatial: { tension: 380, friction: 31.19, mass: 1 },
|
|
178
|
+
springSlowSpatial: { tension: 200, friction: 22.63, mass: 1 },
|
|
179
|
+
springFastEffects: { tension: 3800, friction: 123.29, mass: 1 },
|
|
180
|
+
springDefaultEffects: { tension: 1600, friction: 80, mass: 1 },
|
|
181
|
+
springSlowEffects: { tension: 800, friction: 56.57, mass: 1 }
|
|
174
182
|
}
|
|
175
183
|
};
|
|
176
184
|
|
|
@@ -179,6 +187,32 @@ function defineTheme(theme) {
|
|
|
179
187
|
return theme;
|
|
180
188
|
}
|
|
181
189
|
|
|
190
|
+
// src/theme/motionAdapter.ts
|
|
191
|
+
function motionTransitions(motion) {
|
|
192
|
+
return {
|
|
193
|
+
"state-hover": { type: "spring", ...motion.springFastEffects },
|
|
194
|
+
"state-press": { type: "spring", ...motion.springFastEffects },
|
|
195
|
+
"state-focus": { type: "spring", ...motion.springFastEffects },
|
|
196
|
+
"spring-fast-spatial": { type: "spring", ...motion.springFastSpatial },
|
|
197
|
+
"spring-default-spatial": {
|
|
198
|
+
type: "spring",
|
|
199
|
+
...motion.springDefaultSpatial
|
|
200
|
+
},
|
|
201
|
+
"spring-slow-spatial": { type: "spring", ...motion.springSlowSpatial },
|
|
202
|
+
"spring-fast-effects": { type: "spring", ...motion.springFastEffects },
|
|
203
|
+
"spring-default-effects": {
|
|
204
|
+
type: "spring",
|
|
205
|
+
...motion.springDefaultEffects
|
|
206
|
+
},
|
|
207
|
+
"spring-slow-effects": { type: "spring", ...motion.springSlowEffects }
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
// src/provider/ThemeProvider.tsx
|
|
212
|
+
import { MotionConfig } from "@rootnative/inertia";
|
|
213
|
+
import * as React4 from "react";
|
|
214
|
+
import { useColorScheme } from "react-native";
|
|
215
|
+
|
|
182
216
|
// src/provider/IconResolverContext.ts
|
|
183
217
|
import * as React from "react";
|
|
184
218
|
var IconResolverContext = React.createContext(
|
|
@@ -189,14 +223,96 @@ var IconResolverContext = React.createContext(
|
|
|
189
223
|
import * as React2 from "react";
|
|
190
224
|
var ThemeContext = React2.createContext(lightTheme);
|
|
191
225
|
|
|
226
|
+
// src/provider/ThemeModeContext.ts
|
|
227
|
+
import * as React3 from "react";
|
|
228
|
+
var ThemeModeContext = React3.createContext(null);
|
|
229
|
+
|
|
192
230
|
// src/provider/ThemeProvider.tsx
|
|
193
231
|
import { jsx } from "react/jsx-runtime";
|
|
232
|
+
var THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
|
|
233
|
+
function isThemePair(theme) {
|
|
234
|
+
return !("colors" in theme);
|
|
235
|
+
}
|
|
236
|
+
function isThemeMode(value) {
|
|
237
|
+
return value === "system" || value === "light" || value === "dark";
|
|
238
|
+
}
|
|
194
239
|
function ThemeProvider({
|
|
195
240
|
theme,
|
|
241
|
+
mode: controlledMode,
|
|
242
|
+
defaultMode = "system",
|
|
243
|
+
onModeChange,
|
|
244
|
+
storage,
|
|
196
245
|
iconResolver,
|
|
197
246
|
children
|
|
198
247
|
}) {
|
|
199
|
-
|
|
248
|
+
const pair = theme && isThemePair(theme) ? theme : null;
|
|
249
|
+
const systemScheme = useColorScheme();
|
|
250
|
+
const [uncontrolledMode, setUncontrolledMode] = React4.useState(defaultMode);
|
|
251
|
+
const isControlled = controlledMode !== void 0;
|
|
252
|
+
const mode = isControlled ? controlledMode : uncontrolledMode;
|
|
253
|
+
const [isReady, setIsReady] = React4.useState(
|
|
254
|
+
() => !storage || isControlled || !pair
|
|
255
|
+
);
|
|
256
|
+
const storageRef = React4.useRef(storage);
|
|
257
|
+
storageRef.current = storage;
|
|
258
|
+
const shouldLoad = Boolean(storage) && !isControlled && Boolean(pair);
|
|
259
|
+
React4.useEffect(() => {
|
|
260
|
+
if (!shouldLoad) {
|
|
261
|
+
setIsReady(true);
|
|
262
|
+
return;
|
|
263
|
+
}
|
|
264
|
+
let cancelled = false;
|
|
265
|
+
const load = async () => {
|
|
266
|
+
var _a;
|
|
267
|
+
try {
|
|
268
|
+
const stored = await ((_a = storageRef.current) == null ? void 0 : _a.getItem(THEME_MODE_STORAGE_KEY));
|
|
269
|
+
if (!cancelled && isThemeMode(stored)) {
|
|
270
|
+
setUncontrolledMode(stored);
|
|
271
|
+
}
|
|
272
|
+
} catch {
|
|
273
|
+
} finally {
|
|
274
|
+
if (!cancelled) {
|
|
275
|
+
setIsReady(true);
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
};
|
|
279
|
+
void load();
|
|
280
|
+
return () => {
|
|
281
|
+
cancelled = true;
|
|
282
|
+
};
|
|
283
|
+
}, [shouldLoad]);
|
|
284
|
+
const setMode = React4.useCallback(
|
|
285
|
+
(nextMode) => {
|
|
286
|
+
var _a;
|
|
287
|
+
if (!isControlled) {
|
|
288
|
+
setUncontrolledMode(nextMode);
|
|
289
|
+
}
|
|
290
|
+
onModeChange == null ? void 0 : onModeChange(nextMode);
|
|
291
|
+
if (!isControlled) {
|
|
292
|
+
try {
|
|
293
|
+
const result = (_a = storageRef.current) == null ? void 0 : _a.setItem(
|
|
294
|
+
THEME_MODE_STORAGE_KEY,
|
|
295
|
+
nextMode
|
|
296
|
+
);
|
|
297
|
+
void Promise.resolve(result).catch(() => {
|
|
298
|
+
});
|
|
299
|
+
} catch {
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
},
|
|
303
|
+
[isControlled, onModeChange]
|
|
304
|
+
);
|
|
305
|
+
const scheme = mode === "system" ? systemScheme === "dark" ? "dark" : "light" : mode;
|
|
306
|
+
const resolvedTheme = pair ? scheme === "dark" ? pair.dark : pair.light : theme != null ? theme : lightTheme;
|
|
307
|
+
const modeValue = React4.useMemo(
|
|
308
|
+
() => pair ? { mode, scheme, setMode, isReady } : null,
|
|
309
|
+
[pair, mode, scheme, setMode, isReady]
|
|
310
|
+
);
|
|
311
|
+
const transitions = React4.useMemo(
|
|
312
|
+
() => motionTransitions(resolvedTheme.motion),
|
|
313
|
+
[resolvedTheme.motion]
|
|
314
|
+
);
|
|
315
|
+
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 }) }) }) });
|
|
200
316
|
}
|
|
201
317
|
|
|
202
318
|
// src/provider/useTheme.ts
|
|
@@ -205,10 +321,22 @@ function useTheme() {
|
|
|
205
321
|
return useContext(ThemeContext);
|
|
206
322
|
}
|
|
207
323
|
|
|
208
|
-
// src/provider/
|
|
324
|
+
// src/provider/useThemeMode.ts
|
|
209
325
|
import { useContext as useContext2 } from "react";
|
|
326
|
+
function useThemeMode() {
|
|
327
|
+
const value = useContext2(ThemeModeContext);
|
|
328
|
+
if (value === null) {
|
|
329
|
+
throw new Error(
|
|
330
|
+
"useThemeMode() requires a <ThemeProvider theme={{ light, dark }}>. A provider with a single theme has no light/dark mode to control."
|
|
331
|
+
);
|
|
332
|
+
}
|
|
333
|
+
return value;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
// src/provider/useIconResolver.ts
|
|
337
|
+
import { useContext as useContext3 } from "react";
|
|
210
338
|
function useIconResolver() {
|
|
211
|
-
return
|
|
339
|
+
return useContext3(IconResolverContext);
|
|
212
340
|
}
|
|
213
341
|
|
|
214
342
|
// src/responsive/useBreakpoint.ts
|
|
@@ -257,7 +385,7 @@ var material = {
|
|
|
257
385
|
defaultTopAppBarTokens
|
|
258
386
|
};
|
|
259
387
|
export {
|
|
260
|
-
|
|
388
|
+
THEME_MODE_STORAGE_KEY,
|
|
261
389
|
ThemeProvider,
|
|
262
390
|
applyRoundness,
|
|
263
391
|
breakpoints,
|
|
@@ -266,8 +394,10 @@ export {
|
|
|
266
394
|
defineTheme,
|
|
267
395
|
lightTheme,
|
|
268
396
|
material,
|
|
397
|
+
motionTransitions,
|
|
269
398
|
useBreakpoint,
|
|
270
399
|
useBreakpointValue,
|
|
271
400
|
useIconResolver,
|
|
272
|
-
useTheme
|
|
401
|
+
useTheme,
|
|
402
|
+
useThemeMode
|
|
273
403
|
};
|
|
@@ -6,12 +6,12 @@
|
|
|
6
6
|
* @example
|
|
7
7
|
* interface MyTheme extends BaseTheme {
|
|
8
8
|
* colors: { brand: string; background: string; text: string }
|
|
9
|
-
* typography: { heading:
|
|
9
|
+
* typography: { heading: TypographyToken; body: TypographyToken }
|
|
10
10
|
* }
|
|
11
11
|
*/
|
|
12
12
|
interface BaseTheme {
|
|
13
13
|
colors: Record<string, string>;
|
|
14
|
-
typography: Record<string,
|
|
14
|
+
typography: Record<string, TypographyToken>;
|
|
15
15
|
shape: Shape;
|
|
16
16
|
spacing: Spacing;
|
|
17
17
|
stateLayer: StateLayer;
|
|
@@ -37,8 +37,7 @@ interface Theme extends BaseTheme {
|
|
|
37
37
|
*/
|
|
38
38
|
type MaterialTheme = Theme;
|
|
39
39
|
/** Material Design 3 color roles. All values are CSS color strings (hex, rgb, etc.). */
|
|
40
|
-
|
|
41
|
-
[key: string]: string;
|
|
40
|
+
type Colors = {
|
|
42
41
|
primary: string;
|
|
43
42
|
onPrimary: string;
|
|
44
43
|
primaryContainer: string;
|
|
@@ -88,28 +87,49 @@ interface Colors {
|
|
|
88
87
|
inverseSurface: string;
|
|
89
88
|
inverseOnSurface: string;
|
|
90
89
|
inversePrimary: string;
|
|
91
|
-
}
|
|
92
|
-
/**
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* Material Design 3 type scale with 15 roles across 5 categories (display,
|
|
93
|
+
* headline, title, body, label), plus the 15 MD3 Expressive emphasized
|
|
94
|
+
* variants. Emphasized styles keep the base size/line-height and step the
|
|
95
|
+
* weight up (regular→medium, medium→bold); a few also adjust tracking. The
|
|
96
|
+
* spec additionally varies width/grade on variable fonts, which React Native
|
|
97
|
+
* cannot express — weight (+tracking) is the documented approximation.
|
|
98
|
+
*/
|
|
99
|
+
type Typography = {
|
|
100
|
+
displayLarge: TypographyToken;
|
|
101
|
+
displayMedium: TypographyToken;
|
|
102
|
+
displaySmall: TypographyToken;
|
|
103
|
+
headlineLarge: TypographyToken;
|
|
104
|
+
headlineMedium: TypographyToken;
|
|
105
|
+
headlineSmall: TypographyToken;
|
|
106
|
+
titleLarge: TypographyToken;
|
|
107
|
+
titleMedium: TypographyToken;
|
|
108
|
+
titleSmall: TypographyToken;
|
|
109
|
+
bodyLarge: TypographyToken;
|
|
110
|
+
bodyMedium: TypographyToken;
|
|
111
|
+
bodySmall: TypographyToken;
|
|
112
|
+
labelLarge: TypographyToken;
|
|
113
|
+
labelMedium: TypographyToken;
|
|
114
|
+
labelSmall: TypographyToken;
|
|
115
|
+
displayLargeEmphasized: TypographyToken;
|
|
116
|
+
displayMediumEmphasized: TypographyToken;
|
|
117
|
+
displaySmallEmphasized: TypographyToken;
|
|
118
|
+
headlineLargeEmphasized: TypographyToken;
|
|
119
|
+
headlineMediumEmphasized: TypographyToken;
|
|
120
|
+
headlineSmallEmphasized: TypographyToken;
|
|
121
|
+
titleLargeEmphasized: TypographyToken;
|
|
122
|
+
titleMediumEmphasized: TypographyToken;
|
|
123
|
+
titleSmallEmphasized: TypographyToken;
|
|
124
|
+
bodyLargeEmphasized: TypographyToken;
|
|
125
|
+
bodyMediumEmphasized: TypographyToken;
|
|
126
|
+
bodySmallEmphasized: TypographyToken;
|
|
127
|
+
labelLargeEmphasized: TypographyToken;
|
|
128
|
+
labelMediumEmphasized: TypographyToken;
|
|
129
|
+
labelSmallEmphasized: TypographyToken;
|
|
130
|
+
};
|
|
111
131
|
type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
|
|
112
|
-
interface
|
|
132
|
+
interface TypographyToken {
|
|
113
133
|
fontFamily: string;
|
|
114
134
|
fontSize: number;
|
|
115
135
|
fontWeight: FontWeight;
|
|
@@ -179,6 +199,17 @@ interface ShadowOffset {
|
|
|
179
199
|
width: number;
|
|
180
200
|
height: number;
|
|
181
201
|
}
|
|
202
|
+
/**
|
|
203
|
+
* Physics config for spring-driven transitions. Uses the react-spring
|
|
204
|
+
* vocabulary (`tension`/`friction`/`mass`) — the same surface
|
|
205
|
+
* `@rootnative/inertia` springs accept, mapped 1:1 onto Reanimated's
|
|
206
|
+
* `stiffness`/`damping`/`mass`.
|
|
207
|
+
*/
|
|
208
|
+
interface MotionSpring {
|
|
209
|
+
tension: number;
|
|
210
|
+
friction: number;
|
|
211
|
+
mass: number;
|
|
212
|
+
}
|
|
182
213
|
/** Duration (in ms) and easing tokens for animations following MD3 motion guidelines. */
|
|
183
214
|
interface Motion {
|
|
184
215
|
durationShort1: number;
|
|
@@ -204,6 +235,42 @@ interface Motion {
|
|
|
204
235
|
easingEmphasized: string;
|
|
205
236
|
easingEmphasizedAccelerate: string;
|
|
206
237
|
easingEmphasizedDecelerate: string;
|
|
238
|
+
/**
|
|
239
|
+
* Spring for fast spatial transitions — small-element position/size/corner
|
|
240
|
+
* morphs that track user input snappily (Switch thumb, Slider press-grow,
|
|
241
|
+
* press shape-morphs). Pronounced overshoot (damping ratio 0.6). Named
|
|
242
|
+
* after the MD3 Expressive motion-physics token scheme
|
|
243
|
+
* (fast/default/slow × spatial/effects).
|
|
244
|
+
*/
|
|
245
|
+
springFastSpatial: MotionSpring;
|
|
246
|
+
/**
|
|
247
|
+
* Spring for default spatial transitions — standard-size element morphs
|
|
248
|
+
* with a softer, bouncier settle (Checkbox and Radio marks). Damping
|
|
249
|
+
* ratio 0.8.
|
|
250
|
+
*/
|
|
251
|
+
springDefaultSpatial: MotionSpring;
|
|
252
|
+
/**
|
|
253
|
+
* Spring for slow spatial transitions — large-element position/size/corner
|
|
254
|
+
* morphs (full-screen or container-scale movement). Damping ratio 0.8 at
|
|
255
|
+
* low stiffness.
|
|
256
|
+
*/
|
|
257
|
+
springSlowSpatial: MotionSpring;
|
|
258
|
+
/**
|
|
259
|
+
* Spring for fast effects transitions — small-element color/opacity
|
|
260
|
+
* feedback (state layers). Critically damped (damping ratio 1.0) — effects
|
|
261
|
+
* springs never overshoot.
|
|
262
|
+
*/
|
|
263
|
+
springFastEffects: MotionSpring;
|
|
264
|
+
/**
|
|
265
|
+
* Spring for default effects transitions — standard color/opacity changes.
|
|
266
|
+
* Critically damped.
|
|
267
|
+
*/
|
|
268
|
+
springDefaultEffects: MotionSpring;
|
|
269
|
+
/**
|
|
270
|
+
* Spring for slow effects transitions — large-surface color/opacity
|
|
271
|
+
* changes. Critically damped.
|
|
272
|
+
*/
|
|
273
|
+
springSlowEffects: MotionSpring;
|
|
207
274
|
}
|
|
208
275
|
|
|
209
|
-
export type { BaseTheme as B, Colors as C, Elevation as E, FontWeight as F,
|
|
276
|
+
export type { BaseTheme as B, Colors as C, Elevation as E, FontWeight as F, Motion as M, Shape as S, Theme as T, TopAppBarTokens as a, ElevationLevel as b, MaterialTheme as c, MotionSpring as d, ShadowOffset as e, Spacing as f, StateLayer as g, Typography as h, TypographyToken as i };
|
package/llms.txt
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# @rootnative/core — Theme System for React Native
|
|
2
2
|
|
|
3
|
-
> Version: 0.0.0-alpha.
|
|
4
|
-
> Peer deps: react >=18, react-native >=0.72
|
|
3
|
+
> Version: 0.0.0-alpha.10
|
|
4
|
+
> Peer deps: react >=18, react-native >=0.72, @rootnative/inertia >=0.0.7 <0.1.0 (required — every animation runs on it)
|
|
5
5
|
> Optional: @material/material-color-utilities >=0.4.0 (for createMaterialTheme)
|
|
6
6
|
|
|
7
7
|
## Quick Start
|
|
@@ -33,8 +33,24 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
|
|
|
33
33
|
// Dark theme
|
|
34
34
|
<ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
|
|
35
35
|
|
|
36
|
-
//
|
|
36
|
+
// Light/dark, following the OS setting
|
|
37
37
|
import { lightTheme } from '@rootnative/core'
|
|
38
|
+
|
|
39
|
+
<ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
|
|
40
|
+
{children}
|
|
41
|
+
</ThemeProvider>
|
|
42
|
+
|
|
43
|
+
// ...and remembering the user's override across launches
|
|
44
|
+
import AsyncStorage from '@react-native-async-storage/async-storage'
|
|
45
|
+
|
|
46
|
+
<ThemeProvider
|
|
47
|
+
theme={{ light: lightTheme, dark: darkTheme }}
|
|
48
|
+
storage={AsyncStorage}
|
|
49
|
+
>
|
|
50
|
+
{children}
|
|
51
|
+
</ThemeProvider>
|
|
52
|
+
|
|
53
|
+
// Custom theme
|
|
38
54
|
import type { Theme } from '@rootnative/core'
|
|
39
55
|
|
|
40
56
|
const custom: Theme = {
|
|
@@ -45,9 +61,42 @@ const custom: Theme = {
|
|
|
45
61
|
```
|
|
46
62
|
|
|
47
63
|
Props:
|
|
48
|
-
- `theme?: BaseTheme` —
|
|
64
|
+
- `theme?: BaseTheme | { light: BaseTheme; dark: BaseTheme }` — A single theme, or a light/dark pair. A pair enables `useThemeMode()`. Default: `lightTheme` (MD3)
|
|
65
|
+
- `mode?: 'system' | 'light' | 'dark'` — Controlled mode. Leave unset and use `setMode()` instead. Pair with `onModeChange`
|
|
66
|
+
- `defaultMode?: 'system' | 'light' | 'dark'` — Initial mode when uncontrolled. Default: `'system'`
|
|
67
|
+
- `onModeChange?: (mode: ThemeMode) => void`
|
|
68
|
+
- `storage?: { getItem, setItem }` — Persists the mode. Any AsyncStorage-shaped object; sync or async. Nothing is persisted unless you pass this
|
|
69
|
+
- `iconResolver?: IconResolver`
|
|
49
70
|
- `children: ReactNode`
|
|
50
71
|
|
|
72
|
+
### useThemeMode()
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
Returns `{ mode, scheme, setMode, isReady }`:
|
|
77
|
+
- `mode` — what was asked for, including `'system'`
|
|
78
|
+
- `scheme` — the resolved `'light' | 'dark'` actually rendering. Use this to sync anything outside the theme, such as the status bar
|
|
79
|
+
- `setMode(mode)` — switches mode, and persists it when `storage` is set
|
|
80
|
+
- `isReady` — `false` until a persisted mode has loaded. Always `true` without `storage`. Gate a splash screen on it to avoid a launch flash
|
|
81
|
+
|
|
82
|
+
```tsx
|
|
83
|
+
import { useThemeMode } from '@rootnative/core'
|
|
84
|
+
import { StatusBar } from 'expo-status-bar'
|
|
85
|
+
|
|
86
|
+
function ThemeToggle() {
|
|
87
|
+
const { scheme, setMode } = useThemeMode()
|
|
88
|
+
|
|
89
|
+
return (
|
|
90
|
+
<>
|
|
91
|
+
<StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
|
|
92
|
+
<Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')}>
|
|
93
|
+
Toggle theme
|
|
94
|
+
</Button>
|
|
95
|
+
</>
|
|
96
|
+
)
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
51
100
|
### useTheme()
|
|
52
101
|
|
|
53
102
|
Returns the current theme from the nearest `ThemeProvider`.
|
|
@@ -72,10 +121,10 @@ Identity function that validates a custom theme object against `BaseTheme`. Prov
|
|
|
72
121
|
|
|
73
122
|
```tsx
|
|
74
123
|
import { defineTheme } from '@rootnative/core'
|
|
75
|
-
import type { BaseTheme,
|
|
124
|
+
import type { BaseTheme, TypographyToken } from '@rootnative/core'
|
|
76
125
|
|
|
77
126
|
interface MyColors { [key: string]: string; brand: string; background: string; text: string }
|
|
78
|
-
interface MyTypography { [key: string]:
|
|
127
|
+
interface MyTypography { [key: string]: TypographyToken; heading: TypographyToken; body: TypographyToken }
|
|
79
128
|
interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography }
|
|
80
129
|
|
|
81
130
|
const myTheme = defineTheme<MyTheme>({
|
|
@@ -86,7 +135,7 @@ const myTheme = defineTheme<MyTheme>({
|
|
|
86
135
|
},
|
|
87
136
|
shape: { roundness: 1, cornerNone: 0, cornerExtraSmall: 4, cornerSmall: 8, cornerMedium: 12, cornerLarge: 16, cornerExtraLarge: 28, cornerFull: 9999 },
|
|
88
137
|
spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
|
|
89
|
-
stateLayer: { pressedOpacity: 0.
|
|
138
|
+
stateLayer: { pressedOpacity: 0.1, focusedOpacity: 0.1, hoveredOpacity: 0.08, draggedOpacity: 0.16, disabledOpacity: 0.38, disabledContainerOpacity: 0.12 },
|
|
90
139
|
elevation: { ... },
|
|
91
140
|
motion: { ... },
|
|
92
141
|
})
|
|
@@ -101,7 +150,7 @@ Defaults are byte-identical to the upstream MD3 `material-color-utilities` libra
|
|
|
101
150
|
**Spec-aligned options:**
|
|
102
151
|
- `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.
|
|
103
152
|
- `contrastLevel?: 'standard' | 'medium' | 'high'` — MD3 contrast preset (default `'standard'`). Maps to MD3 contrast values `0 / 0.5 / 1.0`. Use `'medium'` or `'high'` for WCAG AAA / low-vision modes.
|
|
104
|
-
- `fontFamily?: string` — Custom font family applied to all
|
|
153
|
+
- `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
154
|
- `roundness?: number` — Global corner-radius multiplier. `0` = sharp corners, `1` = default MD3 (default), `2` = double rounding. Does not affect `cornerNone` or `cornerFull`.
|
|
106
155
|
|
|
107
156
|
**Explicit overrides (NOT part of MD3 spec — use only when no built-in `variant` covers your case):**
|
|
@@ -135,16 +184,19 @@ createMaterialTheme('#006A6A', { surfaceTone: 'neutral' })
|
|
|
135
184
|
// Override: per-palette chroma
|
|
136
185
|
createMaterialTheme('#006A6A', { seedAdjustments: { primary: 60, secondary: 32 } })
|
|
137
186
|
|
|
138
|
-
// Use in provider
|
|
187
|
+
// Use in provider — pinned light
|
|
139
188
|
<ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
|
|
140
189
|
|
|
141
|
-
// Or
|
|
142
|
-
|
|
190
|
+
// Or hand both to the provider and let it follow the OS. Rename on
|
|
191
|
+
// destructure so the pair matches the prop's { light, dark } shape.
|
|
192
|
+
const { lightTheme: light, darkTheme: dark } = createMaterialTheme('#006A6A')
|
|
193
|
+
|
|
194
|
+
<ThemeProvider theme={{ light, dark }}>{children}</ThemeProvider>
|
|
143
195
|
```
|
|
144
196
|
|
|
145
197
|
Returns: `{ lightTheme: Theme, darkTheme: Theme }`
|
|
146
198
|
|
|
147
|
-
The generated themes include all
|
|
199
|
+
The generated themes include all 49 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
|
|
148
200
|
|
|
149
201
|
Requires `@material/material-color-utilities` as a peer dependency: `npm install @material/material-color-utilities`
|
|
150
202
|
|
|
@@ -181,32 +233,32 @@ material.defaultTopAppBarTokens
|
|
|
181
233
|
|
|
182
234
|
### Theme type hierarchy
|
|
183
235
|
|
|
184
|
-
- `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string,
|
|
185
|
-
- `Theme` — Material Design 3 theme. Extends `BaseTheme` with
|
|
236
|
+
- `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
|
|
237
|
+
- `Theme` — Material Design 3 theme. Extends `BaseTheme` with 49 MD3 color roles, 30 typography variants (15 base + 15 emphasized), and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
|
|
186
238
|
|
|
187
239
|
### Theme structure
|
|
188
240
|
|
|
189
241
|
```
|
|
190
242
|
BaseTheme {
|
|
191
243
|
colors: Record<string, string>
|
|
192
|
-
typography: Record<string,
|
|
244
|
+
typography: Record<string, TypographyToken>
|
|
193
245
|
shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
|
|
194
246
|
spacing: Spacing — xs, sm, md, lg, xl
|
|
195
|
-
elevation: Elevation — level0..
|
|
196
|
-
stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, disabledOpacity
|
|
197
|
-
motion: Motion — duration and
|
|
247
|
+
elevation: Elevation — level0..level5 (shadow properties)
|
|
248
|
+
stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
|
|
249
|
+
motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
|
|
198
250
|
}
|
|
199
251
|
|
|
200
252
|
Theme extends BaseTheme {
|
|
201
|
-
colors: Colors —
|
|
202
|
-
typography: Typography —
|
|
253
|
+
colors: Colors — 49 MD3 color roles
|
|
254
|
+
typography: Typography — 30 type scale variants: 15 base (displayLarge..labelSmall) + 15 MD3 Expressive emphasized (displayLargeEmphasized..labelSmallEmphasized)
|
|
203
255
|
topAppBar?: TopAppBarTokens
|
|
204
256
|
}
|
|
205
257
|
```
|
|
206
258
|
|
|
207
259
|
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
260
|
|
|
209
|
-
Typography variants: displayLarge, displayMedium, displaySmall, headlineLarge, headlineMedium, headlineSmall, titleLarge, titleMedium, titleSmall, bodyLarge, bodyMedium, bodySmall, labelLarge, labelMedium, labelSmall — each with fontFamily, fontSize, fontWeight, lineHeight, letterSpacing
|
|
261
|
+
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).
|
|
210
262
|
|
|
211
263
|
### useBreakpoint()
|
|
212
264
|
|
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.10",
|
|
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,
|
|
@@ -54,6 +54,7 @@
|
|
|
54
54
|
],
|
|
55
55
|
"peerDependencies": {
|
|
56
56
|
"@material/material-color-utilities": ">=0.4.0",
|
|
57
|
+
"@rootnative/inertia": ">=0.0.7 <0.1.0",
|
|
57
58
|
"react": ">=18.0.0",
|
|
58
59
|
"react-native": ">=0.72.0"
|
|
59
60
|
},
|
|
@@ -65,6 +66,7 @@
|
|
|
65
66
|
"devDependencies": {
|
|
66
67
|
"@material/material-color-utilities": "^0.4.0",
|
|
67
68
|
"@react-native/babel-preset": "^0.81.5",
|
|
69
|
+
"@rootnative/inertia": "0.0.7",
|
|
68
70
|
"@testing-library/react-native": "^13.3.3",
|
|
69
71
|
"@types/jest": "^29.5.14",
|
|
70
72
|
"@types/react": "^19.0.0",
|