@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 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 >=18`, `react-native >=0.72`
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
- Optional: `@material/material-color-utilities >=0.4` — only needed for `createMaterialTheme`.
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` | MaterialCommunityIcons | Resolves string icon names (`leadingIcon="check"`) to icon nodes. Set once at the app root to use Lucide, SF Symbols, custom SVGs, etc. Pre-built adapters: [`@rootnative/icons`](https://www.npmjs.com/package/@rootnative/icons) |
52
+ | `iconResolver` | `IconResolver` | none | Resolves string icon names (`leadingIcon="check"`) to icon nodes. Set once at the app root to use Lucide, SF Symbols, custom SVGs, etc. Pre-built adapters: [`@rootnative/icons`](https://www.npmjs.com/package/@rootnative/icons). A nested provider without it uses the resolver of its parent |
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
- Requires: `npm install @material/material-color-utilities`
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, TextStyle>`, plus shape, spacing, stateLayer, elevation, motion.
116
- - `Theme` — MD3 theme. Extends `BaseTheme` with 69 color roles, 15 typography variants, optional `topAppBar` tokens. `MaterialTheme` is an identical alias — use it to disambiguate in multi-design-system codebases.
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, TextStyle>`) |
124
- | `shape` | Corner radius tokens (none through full) |
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 0–3 |
127
- | `stateLayer` | Opacity values for pressed, focused, hovered, disabled |
128
- | `motion` | Duration and easing tokens |
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
- - `BaseTheme`, `Theme`, `MaterialTheme`, `Colors`, `Typography`, `Shape`, `Spacing`, `Elevation`, `StateLayer`, `Motion`, `TopAppBarTokens`, `IconResolver`, `IconRenderProps`, `ThemeProviderProps`, `Breakpoint`, `BreakpointValues` — Types
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
- import { Platform } from "react-native";
17
- var defaultFontFamily = Platform.select({
18
- android: "Roboto",
19
- ios: "System",
20
- web: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
21
- default: "System"
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
+ };
@@ -1,4 +1,4 @@
1
- import { T as Theme } from '../types-C8j9GvU_.mjs';
1
+ import { T as Theme } from '../types-BQpoSlhx.mjs';
2
2
 
3
3
  /**
4
4
  * MD3 scheme variant. Each is a spec-defined recipe for deriving the palette