@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
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
# @rootnative/core
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
The theme engine of [Root Native UI](https://github.com/rootnative/ui), a React Native component library. It ships with Material Design 3, and it takes the tokens of your own design system too.
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -14,17 +14,19 @@ Design-system agnostic theme engine for [RootNative UI](https://github.com/rootn
|
|
|
14
14
|
pnpm add @rootnative/core @rootnative/inertia
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
Peer dependencies: `react >=
|
|
17
|
+
Peer dependencies: `react >=19.3.0`, `react-native >=0.88.0 <0.89.0`, `@rootnative/inertia >=0.0.26 <0.1.0`
|
|
18
18
|
|
|
19
|
-
`@rootnative/inertia` is required
|
|
20
|
-
npm and pnpm install required peers
|
|
19
|
+
`@rootnative/inertia` is required. Every animation in the library runs on it.
|
|
20
|
+
npm and pnpm install the required peers for you. Yarn classic doesn't, so add
|
|
21
21
|
it by hand there.
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
`createMaterialTheme` needs no extra install. Its MD3 color engine
|
|
24
|
+
(`@material/material-color-utilities`) is bundled behind the
|
|
25
|
+
`@rootnative/core/create-theme` subpath.
|
|
24
26
|
|
|
25
27
|
## Quick start (Material Design 3)
|
|
26
28
|
|
|
27
|
-
Wrap your app root
|
|
29
|
+
Wrap your app root in `ThemeProvider`:
|
|
28
30
|
|
|
29
31
|
```tsx
|
|
30
32
|
import { ThemeProvider } from '@rootnative/core'
|
|
@@ -42,13 +44,13 @@ export default function App() {
|
|
|
42
44
|
|
|
43
45
|
### ThemeProvider
|
|
44
46
|
|
|
45
|
-
Provides the theme context to all child components.
|
|
47
|
+
Provides the theme context to all child components. It takes an MD3 theme or a theme with your own roles. The default is the MD3 light theme.
|
|
46
48
|
|
|
47
49
|
| Prop | Type | Default | Description |
|
|
48
50
|
|------|------|---------|-------------|
|
|
49
|
-
| `theme` | `BaseTheme` | `lightTheme` (MD3) |
|
|
50
|
-
| `iconResolver` | `IconResolver` |
|
|
51
|
-
| `children` | `ReactNode` | — |
|
|
51
|
+
| `theme` | `BaseTheme` | `lightTheme` (MD3) | The theme object |
|
|
52
|
+
| `iconResolver` | `IconResolver` | none | Resolves a string icon name (`leadingIcon="check"`) to an icon node. Set it once at the app root to use Lucide, SF Symbols, custom SVGs, and so on. Pre-built adapters: [`@rootnative/icons`](https://www.npmjs.com/package/@rootnative/icons). A nested provider without it uses the resolver of its parent |
|
|
53
|
+
| `children` | `ReactNode` | — | The app content |
|
|
52
54
|
|
|
53
55
|
### useTheme()
|
|
54
56
|
|
|
@@ -66,26 +68,44 @@ const theme = useTheme<MyTheme>()
|
|
|
66
68
|
|
|
67
69
|
### defineTheme(theme)
|
|
68
70
|
|
|
69
|
-
|
|
71
|
+
A helper that makes a custom theme with full type checks.
|
|
72
|
+
|
|
73
|
+
A theme with your own role names is for your own components. It needs
|
|
74
|
+
`colors` and `typography`, and it can carry token groups of your own:
|
|
70
75
|
|
|
71
76
|
```tsx
|
|
72
77
|
import { defineTheme } from '@rootnative/core'
|
|
73
|
-
import type { BaseTheme } from '@rootnative/core'
|
|
74
78
|
|
|
75
79
|
const myTheme = defineTheme({
|
|
76
80
|
colors: { brand: '#FF6B00', background: '#FFF', text: '#1A1A1A' },
|
|
77
|
-
typography: {
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
81
|
+
typography: {
|
|
82
|
+
body: {
|
|
83
|
+
fontFamily: 'Inter',
|
|
84
|
+
fontSize: 16,
|
|
85
|
+
fontWeight: '400',
|
|
86
|
+
lineHeight: 24,
|
|
87
|
+
letterSpacing: 0,
|
|
88
|
+
},
|
|
89
|
+
},
|
|
90
|
+
radius: { control: 8, card: 16 },
|
|
91
|
+
})
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
The components of `@rootnative/components` read the MD3 color and typography
|
|
95
|
+
roles. For them, keep the MD3 theme and add your tokens beside it:
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
import { defineTheme, lightTheme } from '@rootnative/core'
|
|
99
|
+
|
|
100
|
+
const appTheme = defineTheme({
|
|
101
|
+
...lightTheme,
|
|
102
|
+
status: { success: '#388E3C', onSuccess: '#FFFFFF' },
|
|
83
103
|
})
|
|
84
104
|
```
|
|
85
105
|
|
|
86
106
|
### createMaterialTheme(seedColor)
|
|
87
107
|
|
|
88
|
-
|
|
108
|
+
Makes a complete MD3 light and dark theme from one seed color, with Google's HCT color space.
|
|
89
109
|
|
|
90
110
|
```tsx
|
|
91
111
|
import { createMaterialTheme } from '@rootnative/core/create-theme'
|
|
@@ -96,11 +116,13 @@ const { lightTheme, darkTheme } = createMaterialTheme('#006A6A')
|
|
|
96
116
|
<ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
|
|
97
117
|
```
|
|
98
118
|
|
|
99
|
-
|
|
119
|
+
You need no extra install, and the subpath imports nothing from
|
|
120
|
+
`react-native`, so it also runs in plain Node. Print a palette from a script,
|
|
121
|
+
or check a theme in CI.
|
|
100
122
|
|
|
101
123
|
### applyRoundness(roundness)
|
|
102
124
|
|
|
103
|
-
Scales the MD3 corner radius tokens by a multiplier
|
|
125
|
+
Scales the MD3 corner radius tokens by a multiplier: `0` = sharp corners, `1` = the MD3 default, `2` = double rounding. `cornerNone` stays `0` and `cornerFull` stays `999`.
|
|
104
126
|
|
|
105
127
|
```tsx
|
|
106
128
|
import { lightTheme, applyRoundness } from '@rootnative/core'
|
|
@@ -110,7 +132,7 @@ const sharp: Theme = { ...lightTheme, shape: applyRoundness(0.5) }
|
|
|
110
132
|
|
|
111
133
|
### material preset
|
|
112
134
|
|
|
113
|
-
|
|
135
|
+
One grouped object with all MD3 theme values:
|
|
114
136
|
|
|
115
137
|
```tsx
|
|
116
138
|
import { material } from '@rootnative/core'
|
|
@@ -122,19 +144,19 @@ material.defaultTopAppBarTokens
|
|
|
122
144
|
|
|
123
145
|
### Theme type hierarchy
|
|
124
146
|
|
|
125
|
-
- `BaseTheme
|
|
126
|
-
- `Theme
|
|
147
|
+
- `BaseTheme`: the generic base. Colors as `Record<string, string>`, typography as `Record<string, TypographyToken>`, and room for token groups of your own.
|
|
148
|
+
- `Theme`: the MD3 theme. It extends `BaseTheme` with 49 color roles, 30 typography variants (15 base + 15 emphasized), the shape, spacing, stateLayer, elevation and motion groups, and the optional `topAppBar` tokens. `MaterialTheme` is an identical alias. Use it to tell the themes apart in a codebase with more than one design system.
|
|
127
149
|
|
|
128
150
|
### Theme structure
|
|
129
151
|
|
|
130
152
|
| Token group | Description |
|
|
131
153
|
|-------------|-------------|
|
|
132
|
-
| `colors` |
|
|
133
|
-
| `typography` |
|
|
134
|
-
| `shape` | `roundness` multiplier plus corner radius tokens (`cornerNone` through `cornerFull`) |
|
|
135
|
-
| `spacing` |
|
|
136
|
-
| `elevation` |
|
|
137
|
-
| `stateLayer` |
|
|
154
|
+
| `colors` | The color roles of the design system (`Record<string, string>`) |
|
|
155
|
+
| `typography` | The type scale variants (`Record<string, TypographyToken>`) |
|
|
156
|
+
| `shape` | The `roundness` multiplier plus the corner radius tokens (`cornerNone` through `cornerFull`) |
|
|
157
|
+
| `spacing` | The spacing scale (xs, sm, md, lg, xl) |
|
|
158
|
+
| `elevation` | The shadow levels `level0` through `level5` |
|
|
159
|
+
| `stateLayer` | The opacity values: `pressedOpacity`, `focusedOpacity`, `hoveredOpacity`, `draggedOpacity`, `disabledOpacity`, `disabledContainerOpacity` |
|
|
138
160
|
| `motion` | 16 `duration*`, 7 `easing*` and 6 `spring*` tokens |
|
|
139
161
|
|
|
140
162
|
### Custom MD3 theme
|
|
@@ -159,39 +181,88 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
|
|
|
159
181
|
<ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
|
|
160
182
|
```
|
|
161
183
|
|
|
184
|
+
### Nested providers
|
|
185
|
+
|
|
186
|
+
A second `ThemeProvider` inside the root one gives one part of the app its own
|
|
187
|
+
theme. It takes the icon resolver of its parent when it gets no
|
|
188
|
+
`iconResolver`. With a `{ light, dark }` pair and none of `mode`,
|
|
189
|
+
`defaultMode` and `storage`, it follows the mode of its parent, and its
|
|
190
|
+
`setMode()` sets the mode of the parent. An overlay (`Dialog`, `Menu`, ...)
|
|
191
|
+
renders its content at the `PortalHost`, so the components inside it take the
|
|
192
|
+
theme of the provider above the host. The
|
|
193
|
+
[theming guide](https://rootnative.github.io/ui/theming#nested-providers)
|
|
194
|
+
shows the two fixes.
|
|
195
|
+
|
|
196
|
+
### Static export: the dark first paint
|
|
197
|
+
|
|
198
|
+
The HTML of a static web export holds the light theme, so a reader with a dark
|
|
199
|
+
system setting sees the light page until hydration ends. The
|
|
200
|
+
`@rootnative/core/static-export` subpath hides it. Put both in the HTML shell
|
|
201
|
+
(`app/+html.tsx` with Expo Router), before the body:
|
|
202
|
+
|
|
203
|
+
```tsx
|
|
204
|
+
import { darkTheme } from '@rootnative/core'
|
|
205
|
+
import {
|
|
206
|
+
schemeGuardCss,
|
|
207
|
+
schemeGuardScript,
|
|
208
|
+
} from '@rootnative/core/static-export'
|
|
209
|
+
|
|
210
|
+
<script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
|
|
211
|
+
<style
|
|
212
|
+
dangerouslySetInnerHTML={{
|
|
213
|
+
__html: schemeGuardCss({ background: darkTheme.colors.background }),
|
|
214
|
+
}}
|
|
215
|
+
/>
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
A reader with a dark scheme then sees the dark background until
|
|
219
|
+
`ThemeProvider` shows the dark theme. A reader with a light scheme sees no
|
|
220
|
+
change.
|
|
221
|
+
|
|
162
222
|
### useBreakpoint()
|
|
163
223
|
|
|
164
224
|
Returns the current MD3 window size class: `'compact'` | `'medium'` | `'expanded'` | `'large'` | `'extraLarge'`.
|
|
165
225
|
|
|
166
226
|
### useBreakpointValue(values)
|
|
167
227
|
|
|
168
|
-
Returns
|
|
228
|
+
Returns the value of the current breakpoint. A missing breakpoint falls back to the nearest smaller entry.
|
|
169
229
|
|
|
170
230
|
```tsx
|
|
171
231
|
const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
|
|
172
232
|
```
|
|
173
233
|
|
|
234
|
+
### useWindowDimensions()
|
|
235
|
+
|
|
236
|
+
Returns the window size, the same as the `react-native` hook, but safe in a static web export. Use it when a layout needs the raw width or height.
|
|
237
|
+
|
|
238
|
+
```tsx
|
|
239
|
+
const { width } = useWindowDimensions()
|
|
240
|
+
```
|
|
241
|
+
|
|
174
242
|
## Exports
|
|
175
243
|
|
|
176
|
-
- `ThemeProvider
|
|
177
|
-
- `useTheme
|
|
178
|
-
- `useIconResolver
|
|
179
|
-
- `
|
|
180
|
-
- `
|
|
181
|
-
- `
|
|
182
|
-
- `
|
|
183
|
-
- `
|
|
184
|
-
- `
|
|
185
|
-
- `
|
|
186
|
-
- `
|
|
187
|
-
- `
|
|
188
|
-
- `
|
|
244
|
+
- `ThemeProvider`: the theme context provider (works with any design system, defaults to MD3)
|
|
245
|
+
- `useTheme`: reads the current theme (generic)
|
|
246
|
+
- `useIconResolver`: reads the configured icon resolver
|
|
247
|
+
- `useThemeScope` / `ThemeScopeProvider`: read the providers of one place as one value, and provide them again at another place, for content rendered through a portal
|
|
248
|
+
- `defineTheme`: makes a custom theme with full type checks
|
|
249
|
+
- `createMaterialTheme`: makes MD3 themes from a seed color (import from `@rootnative/core/create-theme`)
|
|
250
|
+
- `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`)
|
|
251
|
+
- `applyRoundness`: scales the MD3 corner radius tokens by a multiplier
|
|
252
|
+
- `material`: the MD3 preset object (`lightTheme`, `darkTheme`, `defaultTopAppBarTokens`)
|
|
253
|
+
- `useBreakpoint` / `breakpoints`: the current window size class
|
|
254
|
+
- `useBreakpointValue`: responsive values
|
|
255
|
+
- `useWindowDimensions`: the window size, safe to hydrate from a static export
|
|
256
|
+
- `lightTheme` / `darkTheme`: the built-in MD3 themes
|
|
257
|
+
- `defaultTopAppBarTokens`: the MD3 top app bar defaults
|
|
258
|
+
- `motionTransitions`: the named-transition registry that `ThemeProvider` mounts
|
|
259
|
+
- `BaseTheme`, `Theme`, `MaterialTheme`, `Colors`, `Typography`, `TypographyToken`, `FontWeight`, `Shape`, `Spacing`, `Elevation`, `ElevationLevel`, `ShadowOffset`, `StateLayer`, `Motion`, `MotionSpring`, `TopAppBarTokens`, `IconResolver`, `IconRenderProps`, `IconSource`, `ThemeProviderProps`, `ThemeScope`, `ThemeScopeProviderProps`, `Breakpoint`, `BreakpointValues`: types
|
|
189
260
|
|
|
190
261
|
## Docs
|
|
191
262
|
|
|
192
263
|
Full docs: https://rootnative.github.io/ui/
|
|
193
264
|
|
|
194
|
-
LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt
|
|
265
|
+
LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt. Or read `node_modules/@rootnative/core/llms.txt` for the exact installed version.
|
|
195
266
|
|
|
196
267
|
## License
|
|
197
268
|
|
|
@@ -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,3 +1,7 @@
|
|
|
1
|
+
import {
|
|
2
|
+
__require
|
|
3
|
+
} from "./chunk-Y6FXYEAI.mjs";
|
|
4
|
+
|
|
1
5
|
// src/theme/topAppBar.ts
|
|
2
6
|
var defaultTopAppBarTokens = {
|
|
3
7
|
horizontalPadding: 4,
|
|
@@ -13,13 +17,31 @@ var defaultTopAppBarTokens = {
|
|
|
13
17
|
};
|
|
14
18
|
|
|
15
19
|
// src/theme/typography.ts
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
var webFontFamily = '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif';
|
|
21
|
+
function resolveDefaultFontFamily() {
|
|
22
|
+
var _a;
|
|
23
|
+
if (typeof process !== "undefined" && ((_a = process.env) == null ? void 0 : _a.EXPO_OS)) {
|
|
24
|
+
return process.env.EXPO_OS === "web" ? webFontFamily : "System";
|
|
25
|
+
}
|
|
26
|
+
try {
|
|
27
|
+
if (typeof __require === "function") {
|
|
28
|
+
const { Platform } = __require("react-native");
|
|
29
|
+
const selected = Platform.select({
|
|
30
|
+
android: "Roboto",
|
|
31
|
+
ios: "System",
|
|
32
|
+
web: webFontFamily,
|
|
33
|
+
default: "System"
|
|
34
|
+
});
|
|
35
|
+
if (selected) return selected;
|
|
36
|
+
}
|
|
37
|
+
} catch {
|
|
38
|
+
}
|
|
39
|
+
if (typeof navigator !== "undefined" && navigator.product === "ReactNative") {
|
|
40
|
+
return "System";
|
|
41
|
+
}
|
|
42
|
+
return webFontFamily;
|
|
43
|
+
}
|
|
44
|
+
var defaultFontFamily = resolveDefaultFontFamily();
|
|
23
45
|
var defaultTypography = {
|
|
24
46
|
displayLarge: {
|
|
25
47
|
fontFamily: defaultFontFamily,
|
|
@@ -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
|
+
};
|