@rootnative/core 0.0.0-alpha.35 → 0.0.0-alpha.36
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 +41 -41
- package/llms.txt +1 -1
- package/package.json +1 -1
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 works with any design system, and ships with Material Design 3.
|
|
10
10
|
|
|
11
11
|
## Install
|
|
12
12
|
|
|
@@ -16,17 +16,17 @@ pnpm add @rootnative/core @rootnative/inertia
|
|
|
16
16
|
|
|
17
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
|
-
`createMaterialTheme` needs no extra install
|
|
23
|
+
`createMaterialTheme` needs no extra install. Its MD3 color engine
|
|
24
24
|
(`@material/material-color-utilities`) is bundled behind the
|
|
25
25
|
`@rootnative/core/create-theme` subpath.
|
|
26
26
|
|
|
27
27
|
## Quick start (Material Design 3)
|
|
28
28
|
|
|
29
|
-
Wrap your app root
|
|
29
|
+
Wrap your app root in `ThemeProvider`:
|
|
30
30
|
|
|
31
31
|
```tsx
|
|
32
32
|
import { ThemeProvider } from '@rootnative/core'
|
|
@@ -44,13 +44,13 @@ export default function App() {
|
|
|
44
44
|
|
|
45
45
|
### ThemeProvider
|
|
46
46
|
|
|
47
|
-
Provides the theme context to all child components.
|
|
47
|
+
Provides the theme context to all child components. It works with any design system: Material Design 3 or a custom theme. The default is the MD3 light theme.
|
|
48
48
|
|
|
49
49
|
| Prop | Type | Default | Description |
|
|
50
50
|
|------|------|---------|-------------|
|
|
51
|
-
| `theme` | `BaseTheme` | `lightTheme` (MD3) |
|
|
52
|
-
| `iconResolver` | `IconResolver` | none | Resolves string icon
|
|
53
|
-
| `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 |
|
|
54
54
|
|
|
55
55
|
### useTheme()
|
|
56
56
|
|
|
@@ -68,7 +68,7 @@ const theme = useTheme<MyTheme>()
|
|
|
68
68
|
|
|
69
69
|
### defineTheme(theme)
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
A helper that makes a custom theme with full type checks:
|
|
72
72
|
|
|
73
73
|
```tsx
|
|
74
74
|
import { defineTheme } from '@rootnative/core'
|
|
@@ -87,7 +87,7 @@ const myTheme = defineTheme({
|
|
|
87
87
|
|
|
88
88
|
### createMaterialTheme(seedColor)
|
|
89
89
|
|
|
90
|
-
|
|
90
|
+
Makes a complete MD3 light and dark theme from one seed color, with Google's HCT color space.
|
|
91
91
|
|
|
92
92
|
```tsx
|
|
93
93
|
import { createMaterialTheme } from '@rootnative/core/create-theme'
|
|
@@ -98,13 +98,13 @@ const { lightTheme, darkTheme } = createMaterialTheme('#006A6A')
|
|
|
98
98
|
<ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
|
|
99
99
|
```
|
|
100
100
|
|
|
101
|
-
|
|
102
|
-
`react-native`, so it also runs in plain Node
|
|
101
|
+
You need no extra install, and the subpath imports nothing from
|
|
102
|
+
`react-native`, so it also runs in plain Node. Print a palette from a script,
|
|
103
103
|
or check a theme in CI.
|
|
104
104
|
|
|
105
105
|
### applyRoundness(roundness)
|
|
106
106
|
|
|
107
|
-
Scales the MD3 corner radius tokens by a multiplier
|
|
107
|
+
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`.
|
|
108
108
|
|
|
109
109
|
```tsx
|
|
110
110
|
import { lightTheme, applyRoundness } from '@rootnative/core'
|
|
@@ -114,7 +114,7 @@ const sharp: Theme = { ...lightTheme, shape: applyRoundness(0.5) }
|
|
|
114
114
|
|
|
115
115
|
### material preset
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
One grouped object with all MD3 theme values:
|
|
118
118
|
|
|
119
119
|
```tsx
|
|
120
120
|
import { material } from '@rootnative/core'
|
|
@@ -126,19 +126,19 @@ material.defaultTopAppBarTokens
|
|
|
126
126
|
|
|
127
127
|
### Theme type hierarchy
|
|
128
128
|
|
|
129
|
-
- `BaseTheme
|
|
130
|
-
- `Theme
|
|
129
|
+
- `BaseTheme`: the generic base. Colors as `Record<string, string>`, typography as `Record<string, TypographyToken>`, plus shape, spacing, stateLayer, elevation, motion.
|
|
130
|
+
- `Theme`: the MD3 theme. It extends `BaseTheme` with 49 color roles, 30 typography variants (15 base + 15 emphasized), 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.
|
|
131
131
|
|
|
132
132
|
### Theme structure
|
|
133
133
|
|
|
134
134
|
| Token group | Description |
|
|
135
135
|
|-------------|-------------|
|
|
136
|
-
| `colors` |
|
|
137
|
-
| `typography` |
|
|
138
|
-
| `shape` | `roundness` multiplier plus corner radius tokens (`cornerNone` through `cornerFull`) |
|
|
139
|
-
| `spacing` |
|
|
140
|
-
| `elevation` |
|
|
141
|
-
| `stateLayer` |
|
|
136
|
+
| `colors` | The color roles of the design system (`Record<string, string>`) |
|
|
137
|
+
| `typography` | The type scale variants (`Record<string, TypographyToken>`) |
|
|
138
|
+
| `shape` | The `roundness` multiplier plus the corner radius tokens (`cornerNone` through `cornerFull`) |
|
|
139
|
+
| `spacing` | The spacing scale (xs, sm, md, lg, xl) |
|
|
140
|
+
| `elevation` | The shadow levels `level0` through `level5` |
|
|
141
|
+
| `stateLayer` | The opacity values: `pressedOpacity`, `focusedOpacity`, `hoveredOpacity`, `draggedOpacity`, `disabledOpacity`, `disabledContainerOpacity` |
|
|
142
142
|
| `motion` | 16 `duration*`, 7 `easing*` and 6 `spring*` tokens |
|
|
143
143
|
|
|
144
144
|
### Custom MD3 theme
|
|
@@ -207,7 +207,7 @@ Returns the current MD3 window size class: `'compact'` | `'medium'` | `'expanded
|
|
|
207
207
|
|
|
208
208
|
### useBreakpointValue(values)
|
|
209
209
|
|
|
210
|
-
Returns
|
|
210
|
+
Returns the value of the current breakpoint. A missing breakpoint falls back to the nearest smaller entry.
|
|
211
211
|
|
|
212
212
|
```tsx
|
|
213
213
|
const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
|
|
@@ -223,28 +223,28 @@ const { width } = useWindowDimensions()
|
|
|
223
223
|
|
|
224
224
|
## Exports
|
|
225
225
|
|
|
226
|
-
- `ThemeProvider
|
|
227
|
-
- `useTheme
|
|
228
|
-
- `useIconResolver
|
|
229
|
-
- `useThemeScope` / `ThemeScopeProvider
|
|
230
|
-
- `defineTheme
|
|
231
|
-
- `createMaterialTheme
|
|
232
|
-
- `schemeGuardScript` / `schemeGuardCss
|
|
233
|
-
- `applyRoundness
|
|
234
|
-
- `material
|
|
235
|
-
- `useBreakpoint` / `breakpoints
|
|
236
|
-
- `useBreakpointValue
|
|
237
|
-
- `useWindowDimensions
|
|
238
|
-
- `lightTheme` / `darkTheme
|
|
239
|
-
- `defaultTopAppBarTokens
|
|
240
|
-
- `motionTransitions
|
|
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
|
|
226
|
+
- `ThemeProvider`: the theme context provider (works with any design system, defaults to MD3)
|
|
227
|
+
- `useTheme`: reads the current theme (generic)
|
|
228
|
+
- `useIconResolver`: reads 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
|
|
230
|
+
- `defineTheme`: makes a custom theme with full type checks
|
|
231
|
+
- `createMaterialTheme`: makes 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`)
|
|
233
|
+
- `applyRoundness`: scales the MD3 corner radius tokens by a multiplier
|
|
234
|
+
- `material`: the MD3 preset object (`lightTheme`, `darkTheme`, `defaultTopAppBarTokens`)
|
|
235
|
+
- `useBreakpoint` / `breakpoints`: the current window size class
|
|
236
|
+
- `useBreakpointValue`: responsive values
|
|
237
|
+
- `useWindowDimensions`: the window size, safe to hydrate from a static export
|
|
238
|
+
- `lightTheme` / `darkTheme`: the built-in MD3 themes
|
|
239
|
+
- `defaultTopAppBarTokens`: the MD3 top app bar defaults
|
|
240
|
+
- `motionTransitions`: the named-transition registry that `ThemeProvider` mounts
|
|
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
|
|
242
242
|
|
|
243
243
|
## Docs
|
|
244
244
|
|
|
245
245
|
Full docs: https://rootnative.github.io/ui/
|
|
246
246
|
|
|
247
|
-
LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt
|
|
247
|
+
LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt. Or read `node_modules/@rootnative/core/llms.txt` for the exact installed version.
|
|
248
248
|
|
|
249
249
|
## License
|
|
250
250
|
|
package/llms.txt
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @rootnative/core — Theme System for React Native
|
|
2
2
|
|
|
3
|
-
> Version: 0.0.0-alpha.
|
|
3
|
+
> Version: 0.0.0-alpha.36
|
|
4
4
|
> Peer deps: react >=19.3.0 <20.0.0, react-native >=0.88.0 <0.89.0, @rootnative/inertia >=0.0.26 <0.1.0 (required — every animation runs on it)
|
|
5
5
|
> createMaterialTheme needs no extra install — its color engine (@material/material-color-utilities) is bundled behind the create-theme subpath
|
|
6
6
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rootnative/core",
|
|
3
|
-
"version": "0.0.0-alpha.
|
|
3
|
+
"version": "0.0.0-alpha.36",
|
|
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,
|