@rootnative/core 0.0.0-alpha.0

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.
@@ -0,0 +1,209 @@
1
+ /**
2
+ * Base theme interface that all design systems must implement.
3
+ * Provides a generic contract for colors, typography, and shared tokens.
4
+ * Extend this to create a custom design system theme.
5
+ *
6
+ * @example
7
+ * interface MyTheme extends BaseTheme {
8
+ * colors: { brand: string; background: string; text: string }
9
+ * typography: { heading: TextStyle; body: TextStyle }
10
+ * }
11
+ */
12
+ interface BaseTheme {
13
+ colors: Record<string, string>;
14
+ typography: Record<string, TextStyle>;
15
+ shape: Shape;
16
+ spacing: Spacing;
17
+ stateLayer: StateLayer;
18
+ elevation: Elevation;
19
+ motion: Motion;
20
+ [key: string]: unknown;
21
+ }
22
+ /**
23
+ * Material Design 3 theme object containing all design tokens.
24
+ * Access via `useTheme()` hook or pass to `ThemeProvider`.
25
+ *
26
+ * @see https://m3.material.io/foundations/design-tokens
27
+ */
28
+ interface Theme extends BaseTheme {
29
+ colors: Colors;
30
+ typography: Typography;
31
+ topAppBar?: TopAppBarTokens;
32
+ }
33
+ /**
34
+ * Alias for {@link Theme}. Both reference the same MD3 type — use
35
+ * `MaterialTheme` when you need to distinguish from a custom `BaseTheme`
36
+ * in codebases that support multiple design systems.
37
+ */
38
+ type MaterialTheme = Theme;
39
+ /** Material Design 3 color roles. All values are CSS color strings (hex, rgb, etc.). */
40
+ interface Colors {
41
+ [key: string]: string;
42
+ primary: string;
43
+ onPrimary: string;
44
+ primaryContainer: string;
45
+ onPrimaryContainer: string;
46
+ primaryFixed: string;
47
+ onPrimaryFixed: string;
48
+ primaryFixedDim: string;
49
+ onPrimaryFixedVariant: string;
50
+ secondary: string;
51
+ onSecondary: string;
52
+ secondaryContainer: string;
53
+ onSecondaryContainer: string;
54
+ secondaryFixed: string;
55
+ onSecondaryFixed: string;
56
+ secondaryFixedDim: string;
57
+ onSecondaryFixedVariant: string;
58
+ tertiary: string;
59
+ onTertiary: string;
60
+ tertiaryContainer: string;
61
+ onTertiaryContainer: string;
62
+ tertiaryFixed: string;
63
+ onTertiaryFixed: string;
64
+ tertiaryFixedDim: string;
65
+ onTertiaryFixedVariant: string;
66
+ error: string;
67
+ onError: string;
68
+ errorContainer: string;
69
+ onErrorContainer: string;
70
+ background: string;
71
+ onBackground: string;
72
+ surface: string;
73
+ surfaceDim: string;
74
+ surfaceBright: string;
75
+ surfaceContainerLowest: string;
76
+ surfaceContainerLow: string;
77
+ surfaceContainer: string;
78
+ surfaceContainerHigh: string;
79
+ surfaceContainerHighest: string;
80
+ onSurface: string;
81
+ surfaceVariant: string;
82
+ onSurfaceVariant: string;
83
+ outline: string;
84
+ outlineVariant: string;
85
+ surfaceTint: string;
86
+ shadow: string;
87
+ scrim: string;
88
+ inverseSurface: string;
89
+ inverseOnSurface: string;
90
+ inversePrimary: string;
91
+ }
92
+ /** Material Design 3 type scale with 15 roles across 5 categories (display, headline, title, body, label). */
93
+ interface Typography {
94
+ [key: string]: TextStyle;
95
+ displayLarge: TextStyle;
96
+ displayMedium: TextStyle;
97
+ displaySmall: TextStyle;
98
+ headlineLarge: TextStyle;
99
+ headlineMedium: TextStyle;
100
+ headlineSmall: TextStyle;
101
+ titleLarge: TextStyle;
102
+ titleMedium: TextStyle;
103
+ titleSmall: TextStyle;
104
+ bodyLarge: TextStyle;
105
+ bodyMedium: TextStyle;
106
+ bodySmall: TextStyle;
107
+ labelLarge: TextStyle;
108
+ labelMedium: TextStyle;
109
+ labelSmall: TextStyle;
110
+ }
111
+ type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
112
+ interface TextStyle {
113
+ fontFamily: string;
114
+ fontSize: number;
115
+ fontWeight: FontWeight;
116
+ lineHeight: number;
117
+ letterSpacing: number;
118
+ }
119
+ /** Corner radius tokens from none (0) to full (9999 for pill shapes). */
120
+ interface Shape {
121
+ /** Global multiplier for corner radii. `0` = sharp, `1` = default MD3, `2` = double rounding. Does not affect `cornerNone` or `cornerFull`. */
122
+ roundness: number;
123
+ cornerNone: number;
124
+ cornerExtraSmall: number;
125
+ cornerSmall: number;
126
+ cornerMedium: number;
127
+ cornerLarge: number;
128
+ cornerExtraLarge: number;
129
+ cornerFull: number;
130
+ }
131
+ /** Spacing scale in density-independent pixels (dp). Use as `theme.spacing.md` or with layout components. */
132
+ interface Spacing {
133
+ xs: number;
134
+ sm: number;
135
+ md: number;
136
+ lg: number;
137
+ xl: number;
138
+ }
139
+ interface TopAppBarTokens {
140
+ horizontalPadding: number;
141
+ titleStartInset: number;
142
+ smallContainerHeight: number;
143
+ mediumContainerHeight: number;
144
+ largeContainerHeight: number;
145
+ topRowHeight: number;
146
+ sideSlotMinHeight: number;
147
+ iconFrameSize: number;
148
+ mediumTitleBottomPadding: number;
149
+ largeTitleBottomPadding: number;
150
+ }
151
+ /** Opacity values for interactive state feedback (press, hover, focus, drag, disabled). */
152
+ interface StateLayer {
153
+ pressedOpacity: number;
154
+ focusedOpacity: number;
155
+ hoveredOpacity: number;
156
+ draggedOpacity: number;
157
+ /** Opacity applied to content (text, icons) in disabled components. MD3: 38% onSurface. */
158
+ disabledOpacity: number;
159
+ /** Opacity applied to container fills of disabled components. MD3: 12% onSurface. */
160
+ disabledContainerOpacity: number;
161
+ }
162
+ /** Shadow/elevation levels (0–5) for surface hierarchy. */
163
+ interface Elevation {
164
+ level0: ElevationLevel;
165
+ level1: ElevationLevel;
166
+ level2: ElevationLevel;
167
+ level3: ElevationLevel;
168
+ level4: ElevationLevel;
169
+ level5: ElevationLevel;
170
+ }
171
+ interface ElevationLevel {
172
+ shadowColor: string;
173
+ shadowOffset: ShadowOffset;
174
+ shadowOpacity: number;
175
+ shadowRadius: number;
176
+ elevation: number;
177
+ }
178
+ interface ShadowOffset {
179
+ width: number;
180
+ height: number;
181
+ }
182
+ /** Duration (in ms) and easing tokens for animations following MD3 motion guidelines. */
183
+ interface Motion {
184
+ durationShort1: number;
185
+ durationShort2: number;
186
+ durationShort3: number;
187
+ durationShort4: number;
188
+ durationMedium1: number;
189
+ durationMedium2: number;
190
+ durationMedium3: number;
191
+ durationMedium4: number;
192
+ durationLong1: number;
193
+ durationLong2: number;
194
+ durationLong3: number;
195
+ durationLong4: number;
196
+ durationExtraLong1: number;
197
+ durationExtraLong2: number;
198
+ durationExtraLong3: number;
199
+ durationExtraLong4: number;
200
+ easingLinear: string;
201
+ easingStandard: string;
202
+ easingStandardAccelerate: string;
203
+ easingStandardDecelerate: string;
204
+ easingEmphasized: string;
205
+ easingEmphasizedAccelerate: string;
206
+ easingEmphasizedDecelerate: string;
207
+ }
208
+
209
+ export type { BaseTheme as B, Colors as C, Elevation as E, FontWeight as F, MaterialTheme as M, Shape as S, Theme as T, TopAppBarTokens as a, ElevationLevel as b, Motion as c, ShadowOffset as d, Spacing as e, StateLayer as f, TextStyle as g, Typography as h };
package/llms.txt ADDED
@@ -0,0 +1,234 @@
1
+ # @rootnative/core — Theme System for React Native
2
+
3
+ > Version: 0.0.0-alpha.0
4
+ > Peer deps: react >=18, react-native >=0.72
5
+ > Optional: @material/material-color-utilities >=0.4.0 (for createMaterialTheme)
6
+
7
+ ## Quick Start
8
+
9
+ ```tsx
10
+ import { ThemeProvider } from '@rootnative/core'
11
+
12
+ export default function App() {
13
+ return (
14
+ <ThemeProvider>
15
+ {/* Your app */}
16
+ </ThemeProvider>
17
+ )
18
+ }
19
+ ```
20
+
21
+ ## API
22
+
23
+ ### ThemeProvider
24
+
25
+ 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.
26
+
27
+ ```tsx
28
+ import { ThemeProvider, darkTheme } from '@rootnative/core'
29
+
30
+ // Light theme (default)
31
+ <ThemeProvider>{children}</ThemeProvider>
32
+
33
+ // Dark theme
34
+ <ThemeProvider theme={darkTheme}>{children}</ThemeProvider>
35
+
36
+ // Custom theme
37
+ import { lightTheme } from '@rootnative/core'
38
+ import type { Theme } from '@rootnative/core'
39
+
40
+ const custom: Theme = {
41
+ ...lightTheme,
42
+ colors: { ...lightTheme.colors, primary: '#006A6A', onPrimary: '#FFFFFF' },
43
+ }
44
+ <ThemeProvider theme={custom}>{children}</ThemeProvider>
45
+ ```
46
+
47
+ Props:
48
+ - `theme?: BaseTheme` — Theme object. Default: `lightTheme` (MD3)
49
+ - `children: ReactNode`
50
+
51
+ ### useTheme()
52
+
53
+ Returns the current theme from the nearest `ThemeProvider`.
54
+
55
+ Without a type parameter, returns the Material Design 3 `Theme`. Pass a custom theme type for typed access to your design system's tokens.
56
+
57
+ ```tsx
58
+ import { useTheme } from '@rootnative/core'
59
+
60
+ // Material Design 3 (default)
61
+ const theme = useTheme()
62
+ // theme.colors.primary, theme.typography.bodyMedium, theme.spacing.md, etc.
63
+
64
+ // Custom design system
65
+ const theme = useTheme<MyTheme>()
66
+ // theme.colors.brand, theme.typography.heading, etc.
67
+ ```
68
+
69
+ ### defineTheme(theme)
70
+
71
+ Identity function that validates a custom theme object against `BaseTheme`. Provides type-checking and autocompletion.
72
+
73
+ ```tsx
74
+ import { defineTheme } from '@rootnative/core'
75
+ import type { BaseTheme, TextStyle } from '@rootnative/core'
76
+
77
+ interface MyColors { [key: string]: string; brand: string; background: string; text: string }
78
+ interface MyTypography { [key: string]: TextStyle; heading: TextStyle; body: TextStyle }
79
+ interface MyTheme extends BaseTheme { colors: MyColors; typography: MyTypography }
80
+
81
+ const myTheme = defineTheme<MyTheme>({
82
+ colors: { brand: '#FF6B00', background: '#FFFFFF', text: '#1A1A1A' },
83
+ typography: {
84
+ heading: { fontFamily: 'Inter', fontSize: 24, fontWeight: '700', lineHeight: 32, letterSpacing: 0 },
85
+ body: { fontFamily: 'Inter', fontSize: 16, fontWeight: '400', lineHeight: 24, letterSpacing: 0.5 },
86
+ },
87
+ shape: { roundness: 1, cornerNone: 0, cornerExtraSmall: 4, cornerSmall: 8, cornerMedium: 12, cornerLarge: 16, cornerExtraLarge: 28, cornerFull: 9999 },
88
+ 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 },
90
+ elevation: { ... },
91
+ motion: { ... },
92
+ })
93
+ ```
94
+
95
+ ### createMaterialTheme(seedColor, options?)
96
+
97
+ Generates a complete MD3 light and dark theme from a single seed color. Uses Google's HCT color space via `@material/material-color-utilities` for spec-compliant palette generation.
98
+
99
+ Defaults are byte-identical to the upstream MD3 `material-color-utilities` library — pure spec output.
100
+
101
+ **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.
103
+ - `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).
105
+ - `roundness?: number` — Global corner-radius multiplier. `0` = sharp corners, `1` = default MD3 (default), `2` = double rounding. Does not affect `cornerNone` or `cornerFull`.
106
+
107
+ **Explicit overrides (NOT part of MD3 spec — use only when no built-in `variant` covers your case):**
108
+ - `surfaceTone?: 'spec' | 'neutral'` — Default `'spec'` keeps the variant's neutral palette as-is. `'neutral'` rebuilds the neutral and neutralVariant palettes with chroma `0` while leaving primary/secondary/tertiary untouched. Use this for a colorful brand + OLED-near-black surfaces. For a fully spec-legal monochrome theme prefer `variant: 'monochrome'`.
109
+ - `seedAdjustments?: { primary?: number, secondary?: number }` — Per-palette HCT chroma overrides. Same hue, fresh chroma. The variant defaults are spec-defined (TonalSpot uses `primary: 36` / `secondary: 16`); only override when no `variant` matches your brand. Try `variant: 'vibrant'` first.
110
+
111
+ **Separate entry point** — keeps the ~60 kB dependency out of the main bundle:
112
+
113
+ ```tsx
114
+ import { createMaterialTheme } from '@rootnative/core/create-theme'
115
+ import { ThemeProvider } from '@rootnative/core'
116
+
117
+ // Pure MD3 default (TonalSpot variant)
118
+ const { lightTheme, darkTheme } = createMaterialTheme('#006A6A')
119
+
120
+ // Switch MD3 variant
121
+ createMaterialTheme('#006A6A', { variant: 'vibrant' })
122
+
123
+ // Spec-legal monochrome theme
124
+ createMaterialTheme('#006A6A', { variant: 'monochrome' })
125
+
126
+ // High-contrast accessibility preset
127
+ createMaterialTheme('#006A6A', { contrastLevel: 'high' })
128
+
129
+ // Custom font + sharp corners
130
+ createMaterialTheme('#006A6A', { fontFamily: 'Inter', roundness: 0 })
131
+
132
+ // Override: keep colorful primary/secondary, flatten surfaces to pure grey
133
+ createMaterialTheme('#006A6A', { surfaceTone: 'neutral' })
134
+
135
+ // Override: per-palette chroma
136
+ createMaterialTheme('#006A6A', { seedAdjustments: { primary: 60, secondary: 32 } })
137
+
138
+ // Use in provider
139
+ <ThemeProvider theme={lightTheme}>{children}</ThemeProvider>
140
+
141
+ // Or with dark mode
142
+ <ThemeProvider theme={isDark ? darkTheme : lightTheme}>{children}</ThemeProvider>
143
+ ```
144
+
145
+ Returns: `{ lightTheme: Theme, darkTheme: Theme }`
146
+
147
+ The generated themes include all 69 MD3 color roles plus shared tokens (typography, shape, spacing, stateLayer, elevation, motion, topAppBar).
148
+
149
+ Requires `@material/material-color-utilities` as a peer dependency: `npm install @material/material-color-utilities`
150
+
151
+ ### applyRoundness(roundness)
152
+
153
+ Scales the MD3 corner radius tokens by a multiplier. Returns a complete `Shape` object. `cornerNone` (0) and `cornerFull` (999) are never affected.
154
+
155
+ - `roundness: 0` — sharp corners (all intermediate tokens become 0)
156
+ - `roundness: 1` — default MD3 values
157
+ - `roundness: 2` — double the rounding
158
+
159
+ ```tsx
160
+ import { applyRoundness, lightTheme } from '@rootnative/core'
161
+
162
+ // Use with spread to override shape on an existing theme
163
+ const sharpTheme = { ...lightTheme, shape: applyRoundness(0) }
164
+
165
+ // Or with defineTheme
166
+ import { defineTheme } from '@rootnative/core'
167
+ const theme = defineTheme({ ...lightTheme, shape: applyRoundness(0.5) })
168
+ ```
169
+
170
+ ### material preset
171
+
172
+ Grouped object containing all Material Design 3 theme values.
173
+
174
+ ```tsx
175
+ import { material } from '@rootnative/core'
176
+
177
+ material.lightTheme // MD3 light theme
178
+ material.darkTheme // MD3 dark theme
179
+ material.defaultTopAppBarTokens
180
+ ```
181
+
182
+ ### Theme type hierarchy
183
+
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.
186
+
187
+ ### Theme structure
188
+
189
+ ```
190
+ BaseTheme {
191
+ colors: Record<string, string>
192
+ typography: Record<string, TextStyle>
193
+ shape: Shape — roundness, cornerNone, cornerExtraSmall, cornerSmall, cornerMedium, cornerLarge, cornerExtraLarge, cornerFull
194
+ 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 and easing tokens
198
+ }
199
+
200
+ Theme extends BaseTheme {
201
+ colors: Colors — 69 MD3 color roles
202
+ typography: Typography — 15 type scale variants (displayLarge..labelSmall)
203
+ topAppBar?: TopAppBarTokens
204
+ }
205
+ ```
206
+
207
+ 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
+
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
210
+
211
+ ### useBreakpoint()
212
+
213
+ Returns the current MD3 window size class. Reactively updates on resize.
214
+
215
+ ```tsx
216
+ import { useBreakpoint } from '@rootnative/core'
217
+
218
+ const bp = useBreakpoint()
219
+ // 'compact' (0-599) | 'medium' (600-839) | 'expanded' (840-1199) | 'large' (1200-1599) | 'extraLarge' (1600+)
220
+ ```
221
+
222
+ ### useBreakpointValue(values)
223
+
224
+ Returns a value based on the current breakpoint with cascade fallback.
225
+
226
+ ```tsx
227
+ import { useBreakpointValue } from '@rootnative/core'
228
+
229
+ const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })
230
+ // compact → 1, medium → 2, expanded/large/extraLarge → 4
231
+ ```
232
+
233
+ Type: `useBreakpointValue<T>(values: Partial<Record<Breakpoint, T>> & Record<'compact', T>): T`
234
+
package/package.json ADDED
@@ -0,0 +1,83 @@
1
+ {
2
+ "name": "@rootnative/core",
3
+ "version": "0.0.0-alpha.0",
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
+ "private": false,
6
+ "sideEffects": false,
7
+ "main": "dist/index.mjs",
8
+ "module": "dist/index.mjs",
9
+ "types": "dist/index.d.mts",
10
+ "react-native": "dist/index.mjs",
11
+ "source": "src/index.ts",
12
+ "exports": {
13
+ ".": {
14
+ "types": "./dist/index.d.mts",
15
+ "react-native": "./dist/index.mjs",
16
+ "import": "./dist/index.mjs",
17
+ "default": "./dist/index.mjs"
18
+ },
19
+ "./create-theme": {
20
+ "types": "./dist/create-theme/index.d.mts",
21
+ "react-native": "./dist/create-theme/index.mjs",
22
+ "import": "./dist/create-theme/index.mjs",
23
+ "default": "./dist/create-theme/index.mjs"
24
+ }
25
+ },
26
+ "typesVersions": {
27
+ "*": {
28
+ "create-theme": [
29
+ "dist/create-theme/index.d.mts"
30
+ ]
31
+ }
32
+ },
33
+ "publishConfig": {
34
+ "access": "public"
35
+ },
36
+ "files": [
37
+ "dist",
38
+ "llms.txt"
39
+ ],
40
+ "license": "MIT",
41
+ "repository": {
42
+ "type": "git",
43
+ "url": "https://github.com/rootnative/ui.git",
44
+ "directory": "packages/core"
45
+ },
46
+ "homepage": "https://github.com/rootnative/ui",
47
+ "keywords": [
48
+ "react-native",
49
+ "material-design-3",
50
+ "theme",
51
+ "ui",
52
+ "md3"
53
+ ],
54
+ "peerDependencies": {
55
+ "@material/material-color-utilities": ">=0.4.0",
56
+ "react": ">=18.0.0",
57
+ "react-native": ">=0.72.0"
58
+ },
59
+ "peerDependenciesMeta": {
60
+ "@material/material-color-utilities": {
61
+ "optional": true
62
+ }
63
+ },
64
+ "devDependencies": {
65
+ "@material/material-color-utilities": "^0.4.0",
66
+ "@react-native/babel-preset": "^0.81.5",
67
+ "@testing-library/react-native": "^13.3.3",
68
+ "@types/jest": "^29.5.14",
69
+ "@types/react": "^19.0.0",
70
+ "jest": "^29.7.0",
71
+ "react": "19.1.0",
72
+ "react-native": "0.81.5",
73
+ "react-test-renderer": "19.1.0",
74
+ "tsup": "^8.0.0",
75
+ "typescript": "^5.0.0"
76
+ },
77
+ "scripts": {
78
+ "build": "tsup src/index.ts src/create-theme/index.ts --dts --format esm --outDir dist --clean",
79
+ "typecheck": "tsc --noEmit",
80
+ "test": "jest",
81
+ "lint": "eslint . --max-warnings 0"
82
+ }
83
+ }