@rootnative/core 0.0.0-alpha.2 → 0.0.0-alpha.20

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/llms.txt CHANGED
@@ -1,8 +1,8 @@
1
1
  # @rootnative/core — Theme System for React Native
2
2
 
3
- > Version: 0.0.0-alpha.2
4
- > Peer deps: react >=18, react-native >=0.72
5
- > Optional: @material/material-color-utilities >=0.4.0 (for createMaterialTheme)
3
+ > Version: 0.0.0-alpha.20
4
+ > Peer deps: react >=19.2.3 <20.0.0, react-native >=0.83.0 <0.87.0, @rootnative/inertia >=0.0.11 <0.1.0 (required — every animation runs on it)
5
+ > createMaterialTheme needs no extra install — its color engine (@material/material-color-utilities) is bundled behind the create-theme subpath
6
6
 
7
7
  ## Quick Start
8
8
 
@@ -20,6 +20,19 @@ export default function App() {
20
20
 
21
21
  ## API
22
22
 
23
+ ### When to pick which — theme paths
24
+
25
+ Ask this first. Every path below ends in the same `<ThemeProvider theme={...}>`.
26
+
27
+ | You want | Reach for |
28
+ | --- | --- |
29
+ | MD3 defaults, no setup | `<ThemeProvider>` alone (light), or `theme={{ light: lightTheme, dark: darkTheme }}` to follow the OS |
30
+ | A full MD3 palette from one brand color | `createMaterialTheme(seed)` from `@rootnative/core/create-theme` |
31
+ | MD3 with a few token overrides | Spread over `lightTheme` / `darkTheme` (see the custom-theme example under ThemeProvider) |
32
+ | MD3 with sharper or rounder corners | The `roundness` option on `createMaterialTheme`, or `applyRoundness()` on an existing theme |
33
+ | A fully custom design system (your own tokens) | `defineTheme<MyTheme>()` + `useTheme<MyTheme>()` |
34
+ | Light/dark switching and persistence | The `{ light, dark }` pair + `useThemeMode()`; add `storage` to persist |
35
+
23
36
  ### ThemeProvider
24
37
 
25
38
  Wrap your app root to supply the theme to all components. Works with any design system — Material Design 3 or custom themes. Defaults to the MD3 light theme when no theme is provided.
@@ -33,8 +46,24 @@ import { ThemeProvider, darkTheme } from '@rootnative/core'
33
46
  // Dark theme
34
47
  <ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
35
48
 
36
- // Custom theme
49
+ // Light/dark, following the OS setting
37
50
  import { lightTheme } from '@rootnative/core'
51
+
52
+ <ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
53
+ {children}
54
+ </ThemeProvider>
55
+
56
+ // ...and remembering the user's override across launches
57
+ import AsyncStorage from '@react-native-async-storage/async-storage'
58
+
59
+ <ThemeProvider
60
+ theme={{ light: lightTheme, dark: darkTheme }}
61
+ storage={AsyncStorage}
62
+ >
63
+ {children}
64
+ </ThemeProvider>
65
+
66
+ // Custom theme
38
67
  import type { Theme } from '@rootnative/core'
39
68
 
40
69
  const custom: Theme = {
@@ -45,9 +74,42 @@ const custom: Theme = {
45
74
  ```
46
75
 
47
76
  Props:
48
- - `theme?: BaseTheme` — Theme object. Default: `lightTheme` (MD3)
77
+ - `theme?: BaseTheme | { light: BaseTheme; dark: BaseTheme }` — A single theme, or a light/dark pair. A pair enables `useThemeMode()`. Default: `lightTheme` (MD3)
78
+ - `mode?: 'system' | 'light' | 'dark'` — Controlled mode. Leave unset and use `setMode()` instead. Pair with `onModeChange`
79
+ - `defaultMode?: 'system' | 'light' | 'dark'` — Initial mode when uncontrolled. Default: `'system'`
80
+ - `onModeChange?: (mode: ThemeMode) => void`
81
+ - `storage?: { getItem, setItem }` — Persists the mode. Any AsyncStorage-shaped object; sync or async. Nothing is persisted unless you pass this
82
+ - `iconResolver?: IconResolver`
49
83
  - `children: ReactNode`
50
84
 
85
+ ### useThemeMode()
86
+
87
+ 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.
88
+
89
+ Returns `{ mode, scheme, setMode, isReady }`:
90
+ - `mode` — what was asked for, including `'system'`
91
+ - `scheme` — the resolved `'light' | 'dark'` actually rendering. Use this to sync anything outside the theme, such as the status bar
92
+ - `setMode(mode)` — switches mode, and persists it when `storage` is set
93
+ - `isReady` — `false` until a persisted mode has loaded. Always `true` without `storage`. Gate a splash screen on it to avoid a launch flash
94
+
95
+ ```tsx
96
+ import { useThemeMode } from '@rootnative/core'
97
+ import { StatusBar } from 'expo-status-bar'
98
+
99
+ function ThemeToggle() {
100
+ const { scheme, setMode } = useThemeMode()
101
+
102
+ return (
103
+ <>
104
+ <StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
105
+ <Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')}>
106
+ Toggle theme
107
+ </Button>
108
+ </>
109
+ )
110
+ }
111
+ ```
112
+
51
113
  ### useTheme()
52
114
 
53
115
  Returns the current theme from the nearest `ThemeProvider`.
@@ -72,10 +134,10 @@ Identity function that validates a custom theme object against `BaseTheme`. Prov
72
134
 
73
135
  ```tsx
74
136
  import { defineTheme } from '@rootnative/core'
75
- import type { BaseTheme, TextStyle } from '@rootnative/core'
137
+ import type { BaseTheme, TypographyToken } from '@rootnative/core'
76
138
 
77
139
  interface MyColors { [key: string]: string; brand: string; background: string; text: string }
78
- interface MyTypography { [key: string]: TextStyle; heading: TextStyle; body: TextStyle }
140
+ interface MyTypography { [key: string]: TypographyToken; heading: TypographyToken; body: TypographyToken }
79
141
  interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography }
80
142
 
81
143
  const myTheme = defineTheme<MyTheme>({
@@ -86,7 +148,7 @@ const myTheme = defineTheme<MyTheme>({
86
148
  },
87
149
  shape: { roundness: 1, cornerNone: 0, cornerExtraSmall: 4, cornerSmall: 8, cornerMedium: 12, cornerLarge: 16, cornerExtraLarge: 28, cornerFull: 9999 },
88
150
  spacing: { xs: 4, sm: 8, md: 16, lg: 24, xl: 32 },
89
- stateLayer: { pressedOpacity: 0.12, focusedOpacity: 0.12, hoveredOpacity: 0.08, disabledOpacity: 0.38 },
151
+ stateLayer: { pressedOpacity: 0.1, focusedOpacity: 0.1, hoveredOpacity: 0.08, draggedOpacity: 0.16, disabledOpacity: 0.38, disabledContainerOpacity: 0.12 },
90
152
  elevation: { ... },
91
153
  motion: { ... },
92
154
  })
@@ -99,9 +161,29 @@ Generates a complete MD3 light and dark theme from a single seed color. Uses Goo
99
161
  Defaults are byte-identical to the upstream MD3 `material-color-utilities` library — pure spec output.
100
162
 
101
163
  **Spec-aligned options:**
102
- - `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.
164
+ - `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. **Two variants move the primary hue away from your seed — see the table below.**
165
+
166
+ **Does the variant keep the seed hue?**
167
+
168
+ Ask this first if the seed is a brand color. `expressive` and `fruitSalad` rotate the primary hue by design — this is correct MD3 behavior, not a defect, but it means the generated `primary` is not your brand color. Example results for the seed `#E07A3F` (a strong orange):
169
+
170
+ | Variant | Light `primary` | Keeps the seed hue? |
171
+ | --- | --- | --- |
172
+ | `tonalSpot` | `#8d4e2a` | Yes |
173
+ | `neutral` | — | Yes (low chroma) |
174
+ | `vibrant` | `#9d4300` | Yes |
175
+ | `expressive` | `#585799` | **No — rotates to blue-violet** |
176
+ | `fidelity` | `#9b450b` | Yes — also returns the seed as `primaryContainer` |
177
+ | `content` | `#9b450b` | Yes |
178
+ | `monochrome` | — | Yes (chroma 0) |
179
+ | `rainbow` | `#984714` | Yes |
180
+ | `fruitSalad` | `#974066` | **No — rotates to magenta** |
181
+
182
+ Use `fidelity`, `content`, or `tonalSpot` to keep the seed hue. Pick `expressive` for colorfulness only when the palette does not have to match a brand color.
183
+
184
+ **`fidelity` pins `primaryContainer` to the seed in both modes.** With `variant: 'fidelity'` the seed is returned as `primaryContainer` in the light theme **and** the dark theme (`onPrimaryContainer` stays dark in both). This is upstream MD3 fidelity behavior: the scheme holds the source color exactly. Every other container role gets darker in dark mode, so a bright container with dark text can break the surface ramp. Override `primaryContainer` / `onPrimaryContainer` for the dark theme if the ramp matters more than seed fidelity.
103
185
  - `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 15 typography styles. When omitted, platform defaults are used (Roboto on Android, System on iOS).
186
+ - `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
187
  - `roundness?: number` — Global corner-radius multiplier. `0` = sharp corners, `1` = default MD3 (default), `2` = double rounding. Does not affect `cornerNone` or `cornerFull`.
106
188
 
107
189
  **Explicit overrides (NOT part of MD3 spec — use only when no built-in `variant` covers your case):**
@@ -135,18 +217,27 @@ createMaterialTheme('#006A6A', { surfaceTone: 'neutral' })
135
217
  // Override: per-palette chroma
136
218
  createMaterialTheme('#006A6A', { seedAdjustments: { primary: 60, secondary: 32 } })
137
219
 
138
- // Use in provider
220
+ // Use in provider — pinned light
139
221
  <ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
140
222
 
141
- // Or with dark mode
142
- <ThemeProvider theme={isDark ? darkTheme : lightTheme}>{children}</ThemeProvider>
223
+ // Or hand both to the provider and let it follow the OS. Rename on
224
+ // destructure so the pair matches the prop's { light, dark } shape.
225
+ const { lightTheme: light, darkTheme: dark } = createMaterialTheme('#006A6A')
226
+
227
+ <ThemeProvider theme={{ light, dark }}>{children}</ThemeProvider>
143
228
  ```
144
229
 
145
230
  Returns: `{ lightTheme: Theme, darkTheme: Theme }`
146
231
 
147
- The generated themes include all 69 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
232
+ The generated themes include all 49 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
148
233
 
149
- Requires `@material/material-color-utilities` as a peer dependency: `npm install @material/material-color-utilities`
234
+ No extra install is needed: `@material/material-color-utilities` is bundled inside `@rootnative/core`, behind the `create-theme` subpath. Projects that never import the subpath never load it.
235
+
236
+ The subpath also imports nothing from `react-native`, so it runs in plain Node — print a palette from a script, check a theme in CI, or feed the roles to a design-token pipeline:
237
+
238
+ ```bash
239
+ node -e "import('@rootnative/core/create-theme').then(({ createMaterialTheme }) => console.log(createMaterialTheme('#006A6A').lightTheme.colors))"
240
+ ```
150
241
 
151
242
  ### applyRoundness(roundness)
152
243
 
@@ -181,32 +272,32 @@ material.defaultTopAppBarTokens
181
272
 
182
273
  ### Theme type hierarchy
183
274
 
184
- - `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TextStyle>`, plus shape, spacing, stateLayer, elevation, motion.
185
- - `Theme` — Material Design 3 theme. Extends `BaseTheme` with 69 MD3 color roles, 15 typography variants, and optional `topAppBar` tokens. `MaterialTheme` is an identical alias (same type) — use it to disambiguate in multi-design-system codebases.
275
+ - `BaseTheme` — Generic base interface. All design systems extend this. Has `colors: Record<string, string>`, `typography: Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
276
+ - `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
277
 
187
278
  ### Theme structure
188
279
 
189
280
  ```
190
281
  BaseTheme {
191
282
  colors: Record<string, string>
192
- typography: Record<string, TextStyle>
283
+ typography: Record<string, TypographyToken>
193
284
  shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
194
285
  spacing: Spacing — xs, sm, md, lg, xl
195
- elevation: Elevation — level0..level3 (shadow properties)
196
- stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, disabledOpacity
197
- motion: Motion — duration, easing, and spring tokens
286
+ elevation: Elevation — level0..level5 (shadow properties)
287
+ stateLayer: StateLayer — pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity
288
+ motion: Motion — duration, easing, and MD3 Expressive spring tokens (springFastSpatial, springDefaultSpatial, springSlowSpatial, springFastEffects, springDefaultEffects, springSlowEffects — each { tension, friction, mass })
198
289
  }
199
290
 
200
291
  Theme extends BaseTheme {
201
- colors: Colors — 69 MD3 color roles
202
- typography: Typography — 15 type scale variants (displayLarge..labelSmall)
292
+ colors: Colors — 49 MD3 color roles
293
+ typography: Typography — 30 type scale variants: 15 base (displayLarge..labelSmall) + 15 MD3 Expressive emphasized (displayLargeEmphasized..labelSmallEmphasized)
203
294
  topAppBar?: TopAppBarTokens
204
295
  }
205
296
  ```
206
297
 
207
298
  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
299
 
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
300
+ 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
301
 
211
302
  ### useBreakpoint()
212
303
 
@@ -232,3 +323,26 @@ const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
232
323
 
233
324
  Type: `useBreakpointValue<T>(values: Partial<Record<Breakpoint, T>> & Record<'compact', T>): T`
234
325
 
326
+ ### useWindowDimensions()
327
+
328
+ Returns the window size, the same as `useWindowDimensions` from `react-native`, but hydration-safe. Use it instead of the `react-native` hook when a layout needs a number rather than a size class: a hero height, a carousel slot, a column count.
329
+
330
+ ```tsx
331
+ import { useWindowDimensions } from '@rootnative/core'
332
+
333
+ const { width } = useWindowDimensions()
334
+ const heroHeight = width * 0.56
335
+ ```
336
+
337
+ Type: `useWindowDimensions(): ScaledSize`
338
+
339
+ ### Breakpoints and static export (web)
340
+
341
+ The three hooks are hydration-safe, so **no `useHydrated` gate is needed at the call site**. The `useWindowDimensions` hook from `react-native` is **not**: on a static export it keeps the layout of a 0 wide window until the reader resizes the window.
342
+
343
+ A static export (`web.output: 'static'`) renders on a server with no DOM, where react-native-web's `Dimensions` is fixed at `width: 0` — so every breakpoint resolves to `compact` and that is what ships in the HTML. React 19 does **not** repair a `className`/`style` mismatch during hydration: it adopts the server DOM, keeps it, and fires no recoverable error, so a tablet would silently keep the phone layout.
344
+
345
+ `useWindowDimensions` therefore reports the server's 0 by 0 window for as long as the client is hydrating, matching that markup, and switches to the measured window on the re-render React schedules once hydration finishes. `useBreakpoint` reads it, so it reports `compact` for the same span, and a breakpoint and a raw width cannot disagree. On native and on a single-page web build there is no hydration, so the measured value is returned from the first render at no cost.
346
+
347
+ The practical consequence: a breakpoint-dependent layout **starts compact and widens a frame later** on a static export. That is unavoidable — the server cannot know the viewport — so design the compact variant to be the honest first paint. `Grid` inherits all of this, which matters because it resolves a `columns` map internally and leaves a consumer nowhere to put a gate of their own.
348
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rootnative/core",
3
- "version": "0.0.0-alpha.2",
3
+ "version": "0.0.0-alpha.20",
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,
@@ -53,32 +53,27 @@
53
53
  "md3"
54
54
  ],
55
55
  "peerDependencies": {
56
- "@material/material-color-utilities": ">=0.4.0",
57
- "@rootnative/inertia": ">=0.0.0-alpha.5",
58
- "react": ">=18.0.0",
59
- "react-native": ">=0.72.0"
60
- },
61
- "peerDependenciesMeta": {
62
- "@material/material-color-utilities": {
63
- "optional": true
64
- }
56
+ "@rootnative/inertia": ">=0.0.11 <0.1.0",
57
+ "react": ">=19.2.3 <20.0.0",
58
+ "react-native": ">=0.83.0 <0.87.0"
65
59
  },
66
60
  "devDependencies": {
67
61
  "@material/material-color-utilities": "^0.4.0",
68
- "@react-native/babel-preset": "^0.81.5",
69
- "@rootnative/inertia": "^0.0.0-alpha.5",
62
+ "@react-native/babel-preset": "^0.86.3",
63
+ "@react-native/jest-preset": "^0.86.3",
64
+ "@rootnative/inertia": "0.0.14",
70
65
  "@testing-library/react-native": "^13.3.3",
71
66
  "@types/jest": "^29.5.14",
72
67
  "@types/react": "^19.0.0",
73
68
  "jest": "^29.7.0",
74
- "react": "19.1.0",
75
- "react-native": "0.81.5",
76
- "react-test-renderer": "19.1.0",
69
+ "react": "19.2.3",
70
+ "react-native": "0.86.3",
71
+ "react-test-renderer": "19.2.3",
77
72
  "tsup": "^8.0.0",
78
73
  "typescript": "^5.0.0"
79
74
  },
80
75
  "scripts": {
81
- "build": "tsup src/index.ts src/create-theme/index.ts --dts --format esm --outDir dist --clean",
76
+ "build": "tsup",
82
77
  "typecheck": "tsc --noEmit",
83
78
  "test": "jest",
84
79
  "lint": "eslint . --max-warnings 0"