@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 RootNative
3
+ Copyright (c) 2025 Root Native
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  # @rootnative/core
8
8
 
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.
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 >=18`, `react-native >=0.72`, `@rootnative/inertia >=0.0.6 <0.1.0`
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 — every animation in the library runs on it.
20
- npm and pnpm install required peers automatically; Yarn classic does not, so add
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
- 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.
24
26
 
25
27
  ## Quick start (Material Design 3)
26
28
 
27
- Wrap your app root with `ThemeProvider`:
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. Works with any design system — Material Design 3 or custom themes. Defaults to the MD3 light theme.
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) | Theme object |
50
- | `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) |
51
- | `children` | `ReactNode` | — | App content |
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
- Type-safe helper for creating custom themes:
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: { heading: { ... }, body: { ... } },
78
- shape: { ... },
79
- spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
80
- stateLayer: { ... },
81
- elevation: { ... },
82
- motion: { ... },
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
- Generates a complete MD3 light and dark theme from a single seed color using Google's HCT color space.
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
- Requires: `npm install @material/material-color-utilities`
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 — `0` = sharp corners, `1` = default MD3, `2` = double rounding. `cornerNone` stays `0` and `cornerFull` stays `999`.
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
- Grouped object with all MD3 theme values:
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` — 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.
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` | Design-system specific color roles (`Record<string, string>`) |
133
- | `typography` | Type scale variants (`Record<string, TypographyToken>`) |
134
- | `shape` | `roundness` multiplier plus corner radius tokens (`cornerNone` through `cornerFull`) |
135
- | `spacing` | Spacing scale (xs, sm, md, lg, xl) |
136
- | `elevation` | Shadow levels `level0` through `level5` |
137
- | `stateLayer` | Opacity values: `pressedOpacity`, `focusedOpacity`, `hoveredOpacity`, `draggedOpacity`, `disabledOpacity`, `disabledContainerOpacity` |
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 a value based on the current breakpoint with cascade fallback.
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` — Theme context provider (works with any design system, defaults to MD3)
177
- - `useTheme` — Access current theme (generic)
178
- - `useIconResolver` — Access the configured icon resolver
179
- - `defineTheme` — Type-safe theme creation helper
180
- - `createMaterialTheme` — Generate MD3 themes from a seed color (import from `@rootnative/core/create-theme`)
181
- - `applyRoundness` — Scale MD3 corner radius tokens by a multiplier
182
- - `material` — MD3 preset object (`lightTheme`, `darkTheme`, `defaultTopAppBarTokens`)
183
- - `useBreakpoint` / `breakpoints` — Current window size class
184
- - `useBreakpointValue` — Responsive values
185
- - `lightTheme` / `darkTheme` — Built-in MD3 themes
186
- - `defaultTopAppBarTokens` — MD3 top app bar defaults
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
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 — or read `node_modules/@rootnative/core/llms.txt` for the exact installed version.
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
- 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-NiRbh4dM.mjs';
1
+ import { T as Theme } from '../types-DbJZ6AOd.mjs';
2
2
 
3
3
  /**
4
4
  * MD3 scheme variant. Each is a spec-defined recipe for deriving the palette