@rootnative/core 0.0.0-alpha.3 → 0.0.0-alpha.30
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 +77 -13
- 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 +267 -10
- package/dist/index.mjs +198 -12
- package/dist/static-export/index.d.mts +119 -0
- package/dist/static-export/index.mjs +55 -0
- package/dist/{types-C8j9GvU_.d.mts → types-BQpoSlhx.d.mts} +67 -41
- package/llms.txt +215 -23
- package/package.json +20 -16
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,12 +11,18 @@ 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 >=
|
|
17
|
+
Peer dependencies: `react >=19.3.0`, `react-native >=0.88.0 <0.89.0`, `@rootnative/inertia >=0.0.20 <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
|
+
`createMaterialTheme` needs no extra install — its MD3 color engine
|
|
24
|
+
(`@material/material-color-utilities`) is bundled behind the
|
|
25
|
+
`@rootnative/core/create-theme` subpath.
|
|
14
26
|
|
|
15
27
|
## Quick start (Material Design 3)
|
|
16
28
|
|
|
@@ -37,7 +49,7 @@ Provides the theme context to all child components. Works with any design system
|
|
|
37
49
|
| Prop | Type | Default | Description |
|
|
38
50
|
|------|------|---------|-------------|
|
|
39
51
|
| `theme` | `BaseTheme` | `lightTheme` (MD3) | Theme object |
|
|
40
|
-
| `iconResolver` | `IconResolver` |
|
|
52
|
+
| `iconResolver` | `IconResolver` | none | Resolves string icon names (`leadingIcon="check"`) to icon nodes. Set once at the app root to use Lucide, SF Symbols, custom SVGs, etc. Pre-built adapters: [`@rootnative/icons`](https://www.npmjs.com/package/@rootnative/icons). A nested provider without it uses the resolver of its parent |
|
|
41
53
|
| `children` | `ReactNode` | — | App content |
|
|
42
54
|
|
|
43
55
|
### useTheme()
|
|
@@ -86,7 +98,9 @@ const { lightTheme, darkTheme } = createMaterialTheme('#006A6A')
|
|
|
86
98
|
<ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
|
|
87
99
|
```
|
|
88
100
|
|
|
89
|
-
|
|
101
|
+
No extra install is needed, and the subpath imports nothing from
|
|
102
|
+
`react-native`, so it also runs in plain Node — print a palette from a script
|
|
103
|
+
or check a theme in CI.
|
|
90
104
|
|
|
91
105
|
### applyRoundness(roundness)
|
|
92
106
|
|
|
@@ -112,20 +126,20 @@ material.defaultTopAppBarTokens
|
|
|
112
126
|
|
|
113
127
|
### Theme type hierarchy
|
|
114
128
|
|
|
115
|
-
- `BaseTheme` — Generic base. Colors as `Record<string, string>`, typography as `Record<string,
|
|
116
|
-
- `Theme` — MD3 theme. Extends `BaseTheme` with
|
|
129
|
+
- `BaseTheme` — Generic base. Colors as `Record<string, string>`, typography as `Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
|
|
130
|
+
- `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
131
|
|
|
118
132
|
### Theme structure
|
|
119
133
|
|
|
120
134
|
| Token group | Description |
|
|
121
135
|
|-------------|-------------|
|
|
122
136
|
| `colors` | Design-system specific color roles (`Record<string, string>`) |
|
|
123
|
-
| `typography` | Type scale variants (`Record<string,
|
|
124
|
-
| `shape` |
|
|
137
|
+
| `typography` | Type scale variants (`Record<string, TypographyToken>`) |
|
|
138
|
+
| `shape` | `roundness` multiplier plus corner radius tokens (`cornerNone` through `cornerFull`) |
|
|
125
139
|
| `spacing` | Spacing scale (xs, sm, md, lg, xl) |
|
|
126
|
-
| `elevation` | Shadow levels
|
|
127
|
-
| `stateLayer` | Opacity values
|
|
128
|
-
| `motion` |
|
|
140
|
+
| `elevation` | Shadow levels `level0` through `level5` |
|
|
141
|
+
| `stateLayer` | Opacity values: `pressedOpacity`, `focusedOpacity`, `hoveredOpacity`, `draggedOpacity`, `disabledOpacity`, `disabledContainerOpacity` |
|
|
142
|
+
| `motion` | 16 `duration*`, 7 `easing*` and 6 `spring*` tokens |
|
|
129
143
|
|
|
130
144
|
### Custom MD3 theme
|
|
131
145
|
|
|
@@ -149,6 +163,44 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
|
|
|
149
163
|
<ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
|
|
150
164
|
```
|
|
151
165
|
|
|
166
|
+
### Nested providers
|
|
167
|
+
|
|
168
|
+
A second `ThemeProvider` inside the root one gives one part of the app its own
|
|
169
|
+
theme. It takes the icon resolver of its parent when it gets no
|
|
170
|
+
`iconResolver`. With a `{ light, dark }` pair and none of `mode`,
|
|
171
|
+
`defaultMode` and `storage`, it follows the mode of its parent, and its
|
|
172
|
+
`setMode()` sets the mode of the parent. An overlay (`Dialog`, `Menu`, ...)
|
|
173
|
+
renders its content at the `PortalHost`, so the components inside it take the
|
|
174
|
+
theme of the provider above the host. The
|
|
175
|
+
[theming guide](https://rootnative.github.io/ui/theming#nested-providers)
|
|
176
|
+
shows the two fixes.
|
|
177
|
+
|
|
178
|
+
### Static export: the dark first paint
|
|
179
|
+
|
|
180
|
+
The HTML of a static web export holds the light theme, so a reader with a dark
|
|
181
|
+
system setting sees the light page until hydration ends. The
|
|
182
|
+
`@rootnative/core/static-export` subpath hides it. Put both in the HTML shell
|
|
183
|
+
(`app/+html.tsx` with Expo Router), before the body:
|
|
184
|
+
|
|
185
|
+
```tsx
|
|
186
|
+
import { darkTheme } from '@rootnative/core'
|
|
187
|
+
import {
|
|
188
|
+
schemeGuardCss,
|
|
189
|
+
schemeGuardScript,
|
|
190
|
+
} from '@rootnative/core/static-export'
|
|
191
|
+
|
|
192
|
+
<script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
|
|
193
|
+
<style
|
|
194
|
+
dangerouslySetInnerHTML={{
|
|
195
|
+
__html: schemeGuardCss({ background: darkTheme.colors.background }),
|
|
196
|
+
}}
|
|
197
|
+
/>
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
A reader with a dark scheme then sees the dark background until
|
|
201
|
+
`ThemeProvider` shows the dark theme. A reader with a light scheme sees no
|
|
202
|
+
change.
|
|
203
|
+
|
|
152
204
|
### useBreakpoint()
|
|
153
205
|
|
|
154
206
|
Returns the current MD3 window size class: `'compact'` | `'medium'` | `'expanded'` | `'large'` | `'extraLarge'`.
|
|
@@ -161,20 +213,32 @@ Returns a value based on the current breakpoint with cascade fallback.
|
|
|
161
213
|
const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
|
|
162
214
|
```
|
|
163
215
|
|
|
216
|
+
### useWindowDimensions()
|
|
217
|
+
|
|
218
|
+
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.
|
|
219
|
+
|
|
220
|
+
```tsx
|
|
221
|
+
const { width } = useWindowDimensions()
|
|
222
|
+
```
|
|
223
|
+
|
|
164
224
|
## Exports
|
|
165
225
|
|
|
166
226
|
- `ThemeProvider` — Theme context provider (works with any design system, defaults to MD3)
|
|
167
227
|
- `useTheme` — Access current theme (generic)
|
|
168
228
|
- `useIconResolver` — Access the configured icon resolver
|
|
229
|
+
- `useThemeScope` / `ThemeScopeProvider` — Read the providers of one place as one value, and provide them again at another place, for content rendered through a portal
|
|
169
230
|
- `defineTheme` — Type-safe theme creation helper
|
|
170
231
|
- `createMaterialTheme` — Generate MD3 themes from a seed color (import from `@rootnative/core/create-theme`)
|
|
232
|
+
- `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`)
|
|
171
233
|
- `applyRoundness` — Scale MD3 corner radius tokens by a multiplier
|
|
172
234
|
- `material` — MD3 preset object (`lightTheme`, `darkTheme`, `defaultTopAppBarTokens`)
|
|
173
235
|
- `useBreakpoint` / `breakpoints` — Current window size class
|
|
174
236
|
- `useBreakpointValue` — Responsive values
|
|
237
|
+
- `useWindowDimensions` — Window size that is safe to hydrate from a static export
|
|
175
238
|
- `lightTheme` / `darkTheme` — Built-in MD3 themes
|
|
176
239
|
- `defaultTopAppBarTokens` — MD3 top app bar defaults
|
|
177
|
-
- `
|
|
240
|
+
- `motionTransitions` — The named-transition registry mounted by `ThemeProvider`
|
|
241
|
+
- `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
|
|
178
242
|
|
|
179
243
|
## Docs
|
|
180
244
|
|
|
@@ -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
|
+
};
|