@rootnative/core 0.0.0-alpha.3 → 0.0.0-alpha.31

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,119 @@
1
+ /** Options for `schemeGuardScript`. */
2
+ interface SchemeGuardScriptOptions {
3
+ /**
4
+ * The `localStorage` key that holds the mode the reader chose. A stored
5
+ * `'light'` or `'dark'` wins over the OS scheme, as it does in
6
+ * `ThemeProvider`. Pass `null` when the app does not keep the mode in
7
+ * `localStorage` under one key: the script then reads the OS scheme only.
8
+ *
9
+ * @default THEME_MODE_STORAGE_KEY ('rootnative.theme-mode'), the key that
10
+ * `ThemeProvider` writes through `storage`
11
+ */
12
+ storageKey?: string | null;
13
+ }
14
+ /** Options for `schemeGuardCss`. */
15
+ interface SchemeGuardCssOptions {
16
+ /**
17
+ * The CSS color that a dark-scheme reader sees while the page is hidden.
18
+ * Use the background color of the dark theme, for example
19
+ * `darkTheme.colors.background`.
20
+ */
21
+ background: string;
22
+ /**
23
+ * The element that holds the app. The guard hides it until the theme is
24
+ * ready.
25
+ *
26
+ * @default '#root', the element Expo hydrates into
27
+ */
28
+ rootSelector?: string;
29
+ /**
30
+ * How long to wait for the theme before the page shows anyway, in
31
+ * milliseconds. This is for a bundle that fails to load. A short value
32
+ * shows the light page to a dark-scheme reader on a slow connection; a long
33
+ * value keeps a reader with a failed bundle on an empty page.
34
+ *
35
+ * @default 8000
36
+ */
37
+ timeoutMs?: number;
38
+ }
39
+
40
+ /**
41
+ * The source of an inline script for the `<head>` of a static export. It
42
+ * finds the scheme the reader will get after hydration and writes it to
43
+ * `<html>` as `SCHEME_ATTRIBUTE`, before the body paints.
44
+ *
45
+ * ## The problem it solves
46
+ *
47
+ * The export server cannot know the color scheme of the reader, so the HTML
48
+ * holds the light theme. react-native-web writes each theme color into the
49
+ * HTML as an inline style, and shell CSS cannot change an inline style. So a
50
+ * reader with a dark scheme sees the light page until the bundle downloads
51
+ * and hydrates: about 1.3 s on a fast computer, and more than 5 s on a slow
52
+ * phone. A mode stored with `storage` loads after hydration, so a reader who
53
+ * chose dark sees the same light page.
54
+ *
55
+ * This script and `schemeGuardCss` hide the page from a dark-scheme reader
56
+ * until `ThemeProvider` shows the final theme. A light-scheme reader sees no
57
+ * change. Without JavaScript the script does not run, so nothing is hidden.
58
+ *
59
+ * ## How to use it
60
+ *
61
+ * Put both in the HTML shell — for Expo Router that is `app/+html.tsx`. The
62
+ * script must come before the body:
63
+ *
64
+ * ```tsx
65
+ * import { darkTheme } from '@rootnative/core'
66
+ * import {
67
+ * schemeGuardCss,
68
+ * schemeGuardScript,
69
+ * } from '@rootnative/core/static-export'
70
+ *
71
+ * <head>
72
+ * <script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
73
+ * <style
74
+ * dangerouslySetInnerHTML={{
75
+ * __html: schemeGuardCss({ background: darkTheme.colors.background }),
76
+ * }}
77
+ * />
78
+ * </head>
79
+ * ```
80
+ *
81
+ * The scheme comes from the same sources as `ThemeProvider` uses: a stored
82
+ * `'light'` or `'dark'` first, then the OS scheme. The script cannot see a
83
+ * mode that the app controls with `mode`. It then reads the OS scheme, and
84
+ * the page can stay hidden until hydration for a reader who will see light.
85
+ */
86
+ declare function schemeGuardScript(options?: SchemeGuardScriptOptions): string;
87
+ /**
88
+ * CSS for the HTML shell of a static export. For a reader whose scheme is
89
+ * dark, it hides the app element and paints `background` until
90
+ * `ThemeProvider` marks the theme as ready. See `schemeGuardScript` for the
91
+ * problem, and for the script that this CSS needs.
92
+ *
93
+ * The hidden page keeps its layout, so nothing moves when it shows. The cost
94
+ * is time: a dark-scheme reader sees content when hydration ends, not when the
95
+ * HTML arrives, so the Largest Contentful Paint is later for that reader.
96
+ *
97
+ * If the theme is not ready after `timeoutMs`, the page shows anyway. That is
98
+ * for a bundle that fails to load.
99
+ */
100
+ declare function schemeGuardCss(options: SchemeGuardCssOptions): string;
101
+
102
+ /**
103
+ * The two `<html>` attributes the scheme guard is built on. The shell script
104
+ * and `ThemeProvider` write them, and `schemeGuardCss` reads them, so the
105
+ * writers and the CSS share one spelling.
106
+ */
107
+ /**
108
+ * Set on `<html>` by `schemeGuardScript`, before the body paints, to the
109
+ * scheme the reader will get after hydration: `'dark'` or `'light'`.
110
+ */
111
+ declare const SCHEME_ATTRIBUTE = "data-rootnative-scheme";
112
+ /**
113
+ * Set on `<html>` by `ThemeProvider` on web, on the first render after
114
+ * hydration with the stored mode loaded. From then on the theme on screen is
115
+ * the final one, so the guard stands down.
116
+ */
117
+ declare const THEME_READY_ATTRIBUTE = "data-rootnative-theme-ready";
118
+
119
+ export { SCHEME_ATTRIBUTE, type SchemeGuardCssOptions, type SchemeGuardScriptOptions, THEME_READY_ATTRIBUTE, schemeGuardCss, schemeGuardScript };
@@ -0,0 +1,55 @@
1
+ import {
2
+ SCHEME_ATTRIBUTE,
3
+ THEME_MODE_STORAGE_KEY,
4
+ THEME_READY_ATTRIBUTE
5
+ } from "../chunk-OK7DBCK4.mjs";
6
+ import "../chunk-Y6FXYEAI.mjs";
7
+
8
+ // src/static-export/schemeGuard.ts
9
+ var KEYFRAMES = "rootnative-scheme-guard";
10
+ var DEFAULT_ROOT_SELECTOR = "#root";
11
+ var DEFAULT_TIMEOUT_MS = 8e3;
12
+ function scriptLiteral(value) {
13
+ return JSON.stringify(value).replace(/</g, "\\u003c");
14
+ }
15
+ function schemeGuardScript(options) {
16
+ const storageKey = (options == null ? void 0 : options.storageKey) === void 0 ? THEME_MODE_STORAGE_KEY : options.storageKey;
17
+ const readStored = storageKey === null ? "" : `try { stored = window.localStorage.getItem(${scriptLiteral(storageKey)}) } catch (e) {}
18
+ `;
19
+ return `(function () {
20
+ try {
21
+ var stored = null
22
+ ${readStored}var scheme = stored === 'dark' || stored === 'light'
23
+ ? stored
24
+ : window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
25
+ ? 'dark'
26
+ : 'light'
27
+ document.documentElement.setAttribute(${scriptLiteral(SCHEME_ATTRIBUTE)}, scheme)
28
+ } catch (e) {}
29
+ })()
30
+ `;
31
+ }
32
+ function schemeGuardCss(options) {
33
+ var _a, _b;
34
+ const root = (_a = options.rootSelector) != null ? _a : DEFAULT_ROOT_SELECTOR;
35
+ const timeout = (_b = options.timeoutMs) != null ? _b : DEFAULT_TIMEOUT_MS;
36
+ const guarded = `html[${SCHEME_ATTRIBUTE}='dark']:not([${THEME_READY_ATTRIBUTE}])`;
37
+ return `@keyframes ${KEYFRAMES} {
38
+ to { visibility: visible; }
39
+ }
40
+ ${guarded},
41
+ ${guarded} body {
42
+ background-color: ${options.background};
43
+ }
44
+ ${guarded} ${root} {
45
+ visibility: hidden;
46
+ animation: ${KEYFRAMES} 0s ${timeout}ms forwards;
47
+ }
48
+ `;
49
+ }
50
+ export {
51
+ SCHEME_ATTRIBUTE,
52
+ THEME_READY_ATTRIBUTE,
53
+ schemeGuardCss,
54
+ schemeGuardScript
55
+ };
@@ -6,12 +6,12 @@
6
6
  * @example
7
7
  * interface MyTheme extends BaseTheme {
8
8
  * colors: { brand: string; background: string; text: string }
9
- * typography: { heading: TextStyle; body: TextStyle }
9
+ * typography: { heading: TypographyToken; body: TypographyToken }
10
10
  * }
11
11
  */
12
12
  interface BaseTheme {
13
13
  colors: Record<string, string>;
14
- typography: Record<string, TextStyle>;
14
+ typography: Record<string, TypographyToken>;
15
15
  shape: Shape;
16
16
  spacing: Spacing;
17
17
  stateLayer: StateLayer;
@@ -37,8 +37,7 @@ interface Theme extends BaseTheme {
37
37
  */
38
38
  type MaterialTheme = Theme;
39
39
  /** Material Design 3 color roles. All values are CSS color strings (hex, rgb, etc.). */
40
- interface Colors {
41
- [key: string]: string;
40
+ type Colors = {
42
41
  primary: string;
43
42
  onPrimary: string;
44
43
  primaryContainer: string;
@@ -88,7 +87,7 @@ interface Colors {
88
87
  inverseSurface: string;
89
88
  inverseOnSurface: string;
90
89
  inversePrimary: string;
91
- }
90
+ };
92
91
  /**
93
92
  * Material Design 3 type scale with 15 roles across 5 categories (display,
94
93
  * headline, title, body, label), plus the 15 MD3 Expressive emphasized
@@ -97,48 +96,47 @@ interface Colors {
97
96
  * spec additionally varies width/grade on variable fonts, which React Native
98
97
  * cannot express — weight (+tracking) is the documented approximation.
99
98
  */
100
- interface Typography {
101
- [key: string]: TextStyle;
102
- displayLarge: TextStyle;
103
- displayMedium: TextStyle;
104
- displaySmall: TextStyle;
105
- headlineLarge: TextStyle;
106
- headlineMedium: TextStyle;
107
- headlineSmall: TextStyle;
108
- titleLarge: TextStyle;
109
- titleMedium: TextStyle;
110
- titleSmall: TextStyle;
111
- bodyLarge: TextStyle;
112
- bodyMedium: TextStyle;
113
- bodySmall: TextStyle;
114
- labelLarge: TextStyle;
115
- labelMedium: TextStyle;
116
- labelSmall: TextStyle;
117
- displayLargeEmphasized: TextStyle;
118
- displayMediumEmphasized: TextStyle;
119
- displaySmallEmphasized: TextStyle;
120
- headlineLargeEmphasized: TextStyle;
121
- headlineMediumEmphasized: TextStyle;
122
- headlineSmallEmphasized: TextStyle;
123
- titleLargeEmphasized: TextStyle;
124
- titleMediumEmphasized: TextStyle;
125
- titleSmallEmphasized: TextStyle;
126
- bodyLargeEmphasized: TextStyle;
127
- bodyMediumEmphasized: TextStyle;
128
- bodySmallEmphasized: TextStyle;
129
- labelLargeEmphasized: TextStyle;
130
- labelMediumEmphasized: TextStyle;
131
- labelSmallEmphasized: TextStyle;
132
- }
99
+ type Typography = {
100
+ displayLarge: TypographyToken;
101
+ displayMedium: TypographyToken;
102
+ displaySmall: TypographyToken;
103
+ headlineLarge: TypographyToken;
104
+ headlineMedium: TypographyToken;
105
+ headlineSmall: TypographyToken;
106
+ titleLarge: TypographyToken;
107
+ titleMedium: TypographyToken;
108
+ titleSmall: TypographyToken;
109
+ bodyLarge: TypographyToken;
110
+ bodyMedium: TypographyToken;
111
+ bodySmall: TypographyToken;
112
+ labelLarge: TypographyToken;
113
+ labelMedium: TypographyToken;
114
+ labelSmall: TypographyToken;
115
+ displayLargeEmphasized: TypographyToken;
116
+ displayMediumEmphasized: TypographyToken;
117
+ displaySmallEmphasized: TypographyToken;
118
+ headlineLargeEmphasized: TypographyToken;
119
+ headlineMediumEmphasized: TypographyToken;
120
+ headlineSmallEmphasized: TypographyToken;
121
+ titleLargeEmphasized: TypographyToken;
122
+ titleMediumEmphasized: TypographyToken;
123
+ titleSmallEmphasized: TypographyToken;
124
+ bodyLargeEmphasized: TypographyToken;
125
+ bodyMediumEmphasized: TypographyToken;
126
+ bodySmallEmphasized: TypographyToken;
127
+ labelLargeEmphasized: TypographyToken;
128
+ labelMediumEmphasized: TypographyToken;
129
+ labelSmallEmphasized: TypographyToken;
130
+ };
133
131
  type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
134
- interface TextStyle {
132
+ interface TypographyToken {
135
133
  fontFamily: string;
136
134
  fontSize: number;
137
135
  fontWeight: FontWeight;
138
136
  lineHeight: number;
139
137
  letterSpacing: number;
140
138
  }
141
- /** Corner radius tokens from none (0) to full (9999 for pill shapes). */
139
+ /** Corner radius tokens from none (0) to full (999 for pill shapes). */
142
140
  interface Shape {
143
141
  /** Global multiplier for corner radii. `0` = sharp, `1` = default MD3, `2` = double rounding. Does not affect `cornerNone` or `cornerFull`. */
144
142
  roundness: number;
@@ -158,16 +156,44 @@ interface Spacing {
158
156
  lg: number;
159
157
  xl: number;
160
158
  }
159
+ /**
160
+ * Layout tokens of the MD3 top app bar, in dp. `AppBar` follows the Compose
161
+ * `TopAppBarLayout` geometry: each side slot and the title carry
162
+ * `horizontalPadding`. So the title starts at
163
+ * `max(titleStartInset, horizontalPadding + leading width) + horizontalPadding`
164
+ * from the start edge (16 with no leading content, 56 after a 48dp navigation
165
+ * icon), and the last action ends `horizontalPadding` (4) from the end edge.
166
+ * No pair of values puts the title and the actions on one wider gutter. Pad
167
+ * the bar with `style` for that (AppBar docs, "Align with a Page Gutter").
168
+ */
161
169
  interface TopAppBarTokens {
170
+ /** Padding at each end of the top row, and on each side of the title. Default 4. */
162
171
  horizontalPadding: number;
172
+ /**
173
+ * Smallest start position of the title's own padding, used when the
174
+ * leading slot is narrower. With `horizontalPadding`, also the start inset
175
+ * of the title row of a `medium` or `large` bar. Default 12.
176
+ */
163
177
  titleStartInset: number;
178
+ /** Height of a `small` or `center-aligned` bar, and of a collapsed `medium` or `large` bar. Default 64. */
164
179
  smallContainerHeight: number;
180
+ /** Height of a `medium` bar with no subtitle. A subtitle adds 24. Default 112. */
165
181
  mediumContainerHeight: number;
182
+ /** Height of a `large` bar with no subtitle. A subtitle adds 32. Default 152. */
166
183
  largeContainerHeight: number;
184
+ /** Height of the row that holds the navigation icon and the actions. Default 64. */
167
185
  topRowHeight: number;
186
+ /** Smallest height of the leading and trailing slots. Default 48. */
168
187
  sideSlotMinHeight: number;
188
+ /**
189
+ * Width of the frame around the navigation icon, and the smallest width of
190
+ * custom slot content, so a 40dp `IconButton` takes the 48dp footprint of
191
+ * an MD3 icon button. Default 48.
192
+ */
169
193
  iconFrameSize: number;
194
+ /** Space under the title of a `medium` bar. Default 24. */
170
195
  mediumTitleBottomPadding: number;
196
+ /** Space under the title of a `large` bar. Default 28. */
171
197
  largeTitleBottomPadding: number;
172
198
  }
173
199
  /** Opacity values for interactive state feedback (press, hover, focus, drag, disabled). */
@@ -275,4 +301,4 @@ interface Motion {
275
301
  springSlowEffects: MotionSpring;
276
302
  }
277
303
 
278
- export type { BaseTheme as B, Colors as C, Elevation as E, FontWeight as F, Motion as M, Shape as S, Theme as T, TopAppBarTokens as a, ElevationLevel as b, MaterialTheme as c, MotionSpring as d, ShadowOffset as e, Spacing as f, StateLayer as g, TextStyle as h, Typography as i };
304
+ export type { BaseTheme as B, Colors as C, Elevation as E, FontWeight as F, Motion as M, Shape as S, Theme as T, TopAppBarTokens as a, ElevationLevel as b, MaterialTheme as c, MotionSpring as d, ShadowOffset as e, Spacing as f, StateLayer as g, Typography as h, TypographyToken as i };