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

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/dist/index.d.mts CHANGED
@@ -1,8 +1,9 @@
1
- import { T as Theme, a as TopAppBarTokens, B as BaseTheme, M as Motion, S as Shape } from './types-xq2X5AuN.mjs';
2
- export { C as Colors, E as Elevation, b as ElevationLevel, F as FontWeight, c as MaterialTheme, d as MotionSpring, e as ShadowOffset, f as Spacing, g as StateLayer, h as TextStyle, i as Typography } from './types-xq2X5AuN.mjs';
1
+ import { T as Theme, a as TopAppBarTokens, B as BaseTheme, M as Motion, S as Shape } from './types-NiRbh4dM.mjs';
2
+ export { C as Colors, E as Elevation, b as ElevationLevel, F as FontWeight, c as MaterialTheme, d as MotionSpring, e as ShadowOffset, f as Spacing, g as StateLayer, h as Typography, i as TypographyToken } from './types-NiRbh4dM.mjs';
3
3
  import { TransitionConfig, NamedTransitions } from '@rootnative/inertia';
4
4
  import * as react_jsx_runtime from 'react/jsx-runtime';
5
5
  import * as React from 'react';
6
+ import { ScaledSize } from 'react-native';
6
7
 
7
8
  declare const lightTheme: Theme;
8
9
 
@@ -34,6 +35,10 @@ declare module '@rootnative/inertia' {
34
35
  'state-focus': TransitionConfig;
35
36
  'spring-fast-spatial': TransitionConfig;
36
37
  'spring-default-spatial': TransitionConfig;
38
+ 'spring-slow-spatial': TransitionConfig;
39
+ 'spring-fast-effects': TransitionConfig;
40
+ 'spring-default-effects': TransitionConfig;
41
+ 'spring-slow-effects': TransitionConfig;
37
42
  }
38
43
  }
39
44
  /**
@@ -43,10 +48,10 @@ declare module '@rootnative/inertia' {
43
48
  * reference by name instead of hand-rolling `withTiming`/`withSpring`
44
49
  * configs.
45
50
  *
46
- * The state-layer names encode the library's interaction timing policy —
47
- * hover `durationShort3` (150ms), press `durationShort2` (100ms), focus
48
- * `durationShort4` (200ms), all on the standard easing curve. The spring
49
- * names expose the theme's `MotionSpring` tokens verbatim.
51
+ * The state-layer names encode the library's interaction motion policy —
52
+ * per MD3 Expressive, state-layer color/opacity feedback rides the
53
+ * fast-effects spring (small-element effects, critically damped). The
54
+ * spring names expose the theme's `MotionSpring` tokens verbatim.
50
55
  */
51
56
  declare function motionTransitions(motion: Motion): NamedTransitions;
52
57
 
@@ -80,15 +85,126 @@ interface IconRenderProps {
80
85
  * etc. without forking components.
81
86
  */
82
87
  type IconResolver = (name: string, props: IconRenderProps) => React.ReactNode;
83
- declare const IconResolverContext: React.Context<IconResolver | null>;
88
+ /**
89
+ * Anything a component will accept for an icon prop:
90
+ *
91
+ * - **string** — a name resolved via the `iconResolver` registered on
92
+ * `ThemeProvider`. Falls back to `MaterialCommunityIcons` when no
93
+ * resolver is set, preserving the legacy default.
94
+ * - **ReactElement** — a pre-rendered icon. The caller is responsible for
95
+ * passing size and color; the component will not override them.
96
+ * - **(props) => ReactNode** — a render function that receives the
97
+ * component's resolved size and color. Useful for plugging in Lucide,
98
+ * SF Symbols, or custom SVGs without losing theme integration.
99
+ */
100
+ type IconSource = string | React.ReactElement | ((props: IconRenderProps) => React.ReactNode);
101
+
102
+ /**
103
+ * What the app asks for. `'system'` follows the OS setting and keeps
104
+ * following it as the OS changes; `'light'` / `'dark'` pin the scheme.
105
+ */
106
+ type ThemeMode = 'system' | 'light' | 'dark';
107
+ /** What the app actually renders. `'system'` is always resolved away. */
108
+ type ColorScheme = 'light' | 'dark';
109
+ /**
110
+ * Persists the user's mode choice across launches. Deliberately structural
111
+ * rather than a dependency on any one storage library: pass an
112
+ * AsyncStorage-shaped object, MMKV, `localStorage`, SecureStore, or your own
113
+ * wrapper. `@rootnative/core` takes no storage dependency of its own.
114
+ *
115
+ * Both methods may be sync or async — the provider awaits either.
116
+ *
117
+ * @example
118
+ * import AsyncStorage from '@react-native-async-storage/async-storage'
119
+ *
120
+ * <ThemeProvider theme={{ light, dark }} storage={AsyncStorage}>
121
+ */
122
+ interface ThemeModeStorage {
123
+ getItem: (key: string) => string | null | Promise<string | null>;
124
+ setItem: (key: string, value: string) => unknown | Promise<unknown>;
125
+ }
126
+ interface ThemeModeContextValue {
127
+ /** The requested mode, including `'system'`. */
128
+ mode: ThemeMode;
129
+ /**
130
+ * The resolved scheme actually in use. `mode: 'system'` resolves this from
131
+ * the OS; `'light'` / `'dark'` pass straight through. Use this to sync
132
+ * anything outside the theme — most commonly the status bar.
133
+ */
134
+ scheme: ColorScheme;
135
+ /** Sets the mode, and persists it when a `storage` is configured. */
136
+ setMode: (mode: ThemeMode) => void;
137
+ /**
138
+ * `false` until a persisted mode has been read back from `storage`. Always
139
+ * `true` when no `storage` is configured, since there is nothing to wait
140
+ * for. Gate a splash screen on this to avoid a light-to-dark flash on
141
+ * launch.
142
+ */
143
+ isReady: boolean;
144
+ }
84
145
 
146
+ /**
147
+ * A light/dark pair. Matches what `createMaterialTheme()` returns, so its
148
+ * result can be renamed straight into the prop:
149
+ * `const { lightTheme: light, darkTheme: dark } = createMaterialTheme(seed)`.
150
+ */
151
+ interface ThemePair {
152
+ light: BaseTheme;
153
+ dark: BaseTheme;
154
+ }
155
+ /** Storage key for the persisted mode. Namespaced to avoid app collisions. */
156
+ declare const THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
85
157
  interface ThemeProviderProps {
86
158
  /**
87
159
  * Theme object to provide to all child components via context.
88
160
  * Accepts any theme extending `BaseTheme` — Material, Apple, or custom.
161
+ *
162
+ * Pass a `{ light, dark }` pair to enable light/dark switching: the provider
163
+ * then resolves which one to use from `mode` plus the OS setting, and
164
+ * `useThemeMode()` becomes available to descendants.
165
+ *
89
166
  * @default lightTheme (Material Design 3)
90
167
  */
91
- theme?: BaseTheme;
168
+ theme?: BaseTheme | ThemePair;
169
+ /**
170
+ * Which theme of the pair to use. `'system'` follows the OS and keeps
171
+ * following it; `'light'` / `'dark'` pin it. Ignored when `theme` is a
172
+ * single theme.
173
+ *
174
+ * Leave uncontrolled (the default) and drive it with `setMode()` from
175
+ * `useThemeMode()`. Pass it to control the mode from your own state — the
176
+ * provider then never changes it on its own, so pair it with `onModeChange`.
177
+ *
178
+ * On a static web export, `'system'` renders light on the server and while
179
+ * the client hydrates, then switches to the OS scheme on the next render.
180
+ * The server cannot know the scheme, so the light theme is the first paint.
181
+ *
182
+ * @default 'system'
183
+ */
184
+ mode?: ThemeMode;
185
+ /**
186
+ * Initial mode for the uncontrolled case. A persisted value from `storage`
187
+ * wins over this once it loads.
188
+ *
189
+ * @default 'system'
190
+ */
191
+ defaultMode?: ThemeMode;
192
+ /** Called whenever `setMode()` runs, controlled or not. */
193
+ onModeChange?: (mode: ThemeMode) => void;
194
+ /**
195
+ * Persists the mode across launches. Any object with `getItem`/`setItem` —
196
+ * AsyncStorage, MMKV, `localStorage`. `@rootnative/core` takes no storage
197
+ * dependency of its own, so nothing is persisted unless you pass this.
198
+ *
199
+ * Ignored when `mode` is controlled: your own state is then the source of
200
+ * truth and persisting behind it would fight it.
201
+ *
202
+ * @example
203
+ * import AsyncStorage from '@react-native-async-storage/async-storage'
204
+ *
205
+ * <ThemeProvider theme={{ light, dark }} storage={AsyncStorage}>
206
+ */
207
+ storage?: ThemeModeStorage;
92
208
  /**
93
209
  * Resolves string icon names (e.g. `leadingIcon="check"`) to icon nodes.
94
210
  * Set this once at the app root to use SF Symbols, Lucide, custom SVGs,
@@ -124,6 +240,14 @@ interface ThemeProviderProps {
124
240
  * </ThemeProvider>
125
241
  *
126
242
  * @example
243
+ * // Light/dark, following the OS
244
+ * import { ThemeProvider, lightTheme, darkTheme } from '@rootnative/core'
245
+ *
246
+ * <ThemeProvider theme={{ light: lightTheme, dark: darkTheme }}>
247
+ * <App />
248
+ * </ThemeProvider>
249
+ *
250
+ * @example
127
251
  * // Custom or Apple theme
128
252
  * import { ThemeProvider } from '@rootnative/core'
129
253
  *
@@ -131,7 +255,7 @@ interface ThemeProviderProps {
131
255
  * <App />
132
256
  * </ThemeProvider>
133
257
  */
134
- declare function ThemeProvider({ theme, iconResolver, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
258
+ declare function ThemeProvider({ theme, mode: controlledMode, defaultMode, onModeChange, storage, iconResolver, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
135
259
 
136
260
  /**
137
261
  * Returns the current theme from the nearest `ThemeProvider`.
@@ -150,6 +274,21 @@ declare function ThemeProvider({ theme, iconResolver, children, }: ThemeProvider
150
274
  */
151
275
  declare function useTheme<T extends BaseTheme = Theme>(): T;
152
276
 
277
+ /**
278
+ * Reads and controls the light/dark mode of the nearest `ThemeProvider`.
279
+ *
280
+ * Requires a provider configured with a theme *pair* — `theme={{ light, dark }}`.
281
+ * A provider given a single theme has no mode to report, so this throws rather
282
+ * than inventing one.
283
+ *
284
+ * @example
285
+ * const { mode, scheme, setMode } = useThemeMode()
286
+ *
287
+ * <StatusBar style={scheme === 'dark' ? 'light' : 'dark'} />
288
+ * <Button onPress={() => setMode(scheme === 'dark' ? 'light' : 'dark')} />
289
+ */
290
+ declare function useThemeMode(): ThemeModeContextValue;
291
+
153
292
  /**
154
293
  * Returns the icon resolver registered on the nearest `ThemeProvider`,
155
294
  * or `null` if none was provided. Components fall back to
@@ -173,6 +312,30 @@ declare const breakpoints: {
173
312
  * Returns the current Material Design 3 window size class based on viewport width.
174
313
  * Reactively updates when the window is resized.
175
314
  *
315
+ * **Hydration-safe by construction.** A static export renders on a server with
316
+ * no DOM, where react-native-web's `Dimensions` is hard-wired to `width: 0`,
317
+ * so every breakpoint resolves to `compact` and that is what ships in the
318
+ * HTML. On the client `Dimensions` reports the real width immediately, so
319
+ * without care the first client render disagrees with the markup it is
320
+ * hydrating — and **React does not repair that**. Measured against React
321
+ * 19.2.3: a `className` / `style` mismatch is adopted from the server DOM,
322
+ * left on screen, and reported through *zero* recoverable errors. A tablet
323
+ * gets the phone layout, permanently, with no console signal.
324
+ *
325
+ * So this hook reports `compact` for as long as the client is hydrating,
326
+ * matching the markup exactly, and switches to the measured breakpoint on the
327
+ * re-render React schedules once hydration finishes. The correction is an
328
+ * ordinary update, which *does* patch the DOM. The guard lives in this
329
+ * package's `useWindowDimensions`, which this hook reads. Use that hook, not
330
+ * the `react-native` one, when a layout needs the raw width.
331
+ *
332
+ * **It costs nothing where there is no hydration.** On native, and on a
333
+ * single-page web build, `getServerSnapshot` is never called, so the measured
334
+ * breakpoint is returned from the first render with no extra pass. Consumers
335
+ * need no `useHydrated` gate of their own, and neither does `Grid`, which
336
+ * resolves a breakpoint map internally and gives a consumer nowhere to put
337
+ * one.
338
+ *
176
339
  * @example
177
340
  * const breakpoint = useBreakpoint()
178
341
  * const columns = breakpoint === 'compact' ? 2 : 4
@@ -191,6 +354,34 @@ type BreakpointValues<T> = Partial<Record<Breakpoint, T>> & Record<'compact', T>
191
354
  */
192
355
  declare function useBreakpointValue<T>(values: BreakpointValues<T>): T;
193
356
 
357
+ /**
358
+ * Returns the window size, the same as `useWindowDimensions` from
359
+ * `react-native`, but safe to use in a static web export.
360
+ *
361
+ * **Use this instead of the `react-native` hook for any value that reaches a
362
+ * style or the tree.** A static export (`web.output: 'static'`) renders on a
363
+ * server with no DOM, where react-native-web measures a 0 by 0 window. The
364
+ * client measures the real window on its first render, so the `react-native`
365
+ * hook disagrees with the markup it hydrates, and React 19 keeps the server's
366
+ * style with no error. A carousel slot sized from the width, or a hero height
367
+ * set as a fraction of it, then keeps the layout of a 0 wide window until the
368
+ * reader resizes the window.
369
+ *
370
+ * This hook returns the server's 0 by 0 window while the client hydrates, and
371
+ * the measured window on the re-render React schedules after hydration. That
372
+ * re-render is an ordinary update, which does patch the DOM. On native, and on
373
+ * a single-page web build, nothing hydrates, so the measured window comes back
374
+ * from the first render with no extra pass.
375
+ *
376
+ * `useBreakpoint` reads this hook, so a breakpoint and a raw width cannot
377
+ * disagree during hydration.
378
+ *
379
+ * @example
380
+ * const { width } = useWindowDimensions()
381
+ * const heroHeight = width * 0.56
382
+ */
383
+ declare function useWindowDimensions(): ScaledSize;
384
+
194
385
  /**
195
386
  * Material Design 3 preset — groups all MD3-specific theme values.
196
387
  *
@@ -207,4 +398,4 @@ declare const material: {
207
398
  readonly defaultTopAppBarTokens: TopAppBarTokens;
208
399
  };
209
400
 
210
- export { BaseTheme, type Breakpoint, type BreakpointValues, type IconRenderProps, type IconResolver, IconResolverContext, Motion, Shape, Theme, ThemeProvider, type ThemeProviderProps, TopAppBarTokens, applyRoundness, breakpoints, darkTheme, defaultTopAppBarTokens, defineTheme, lightTheme, material, motionTransitions, useBreakpoint, useBreakpointValue, useIconResolver, useTheme };
401
+ export { BaseTheme, type Breakpoint, type BreakpointValues, type ColorScheme, type IconRenderProps, type IconResolver, type IconSource, Motion, Shape, THEME_MODE_STORAGE_KEY, Theme, type ThemeMode, type ThemeModeContextValue, type ThemeModeStorage, type ThemePair, ThemeProvider, type ThemeProviderProps, TopAppBarTokens, applyRoundness, breakpoints, darkTheme, defaultTopAppBarTokens, defineTheme, lightTheme, material, motionTransitions, useBreakpoint, useBreakpointValue, useIconResolver, useTheme, useThemeMode, useWindowDimensions };
package/dist/index.mjs CHANGED
@@ -3,7 +3,7 @@ import {
3
3
  defaultTopAppBarTokens,
4
4
  defaultTypography,
5
5
  lightTheme
6
- } from "./chunk-67NS34RT.mjs";
6
+ } from "./chunk-HMQZLDPN.mjs";
7
7
 
8
8
  // src/theme/dark.ts
9
9
  var darkTheme = {
@@ -171,8 +171,14 @@ var darkTheme = {
171
171
  easingEmphasized: "cubic-bezier(0.2, 0, 0, 1)",
172
172
  easingEmphasizedAccelerate: "cubic-bezier(0.3, 0, 0.8, 0.15)",
173
173
  easingEmphasizedDecelerate: "cubic-bezier(0.05, 0.7, 0.1, 1)",
174
- springFastSpatial: { tension: 380, friction: 33, mass: 1 },
175
- springDefaultSpatial: { tension: 380, friction: 26, mass: 1 }
174
+ // MD3 Expressive scheme, androidx ExpressiveMotionTokens.kt v0_14_0.
175
+ // tension = Compose stiffness; friction = dampingRatio * 2 * sqrt(tension).
176
+ springFastSpatial: { tension: 800, friction: 33.94, mass: 1 },
177
+ springDefaultSpatial: { tension: 380, friction: 31.19, mass: 1 },
178
+ springSlowSpatial: { tension: 200, friction: 22.63, mass: 1 },
179
+ springFastEffects: { tension: 3800, friction: 123.29, mass: 1 },
180
+ springDefaultEffects: { tension: 1600, friction: 80, mass: 1 },
181
+ springSlowEffects: { tension: 800, friction: 56.57, mass: 1 }
176
182
  }
177
183
  };
178
184
 
@@ -182,38 +188,44 @@ function defineTheme(theme) {
182
188
  }
183
189
 
184
190
  // src/theme/motionAdapter.ts
185
- import {
186
- cubicBezier
187
- } from "@rootnative/inertia";
188
191
  function motionTransitions(motion) {
189
- const standard = cubicBezier(motion.easingStandard);
190
192
  return {
191
- "state-hover": {
192
- type: "timing",
193
- duration: motion.durationShort3,
194
- easing: standard
195
- },
196
- "state-press": {
197
- type: "timing",
198
- duration: motion.durationShort2,
199
- easing: standard
200
- },
201
- "state-focus": {
202
- type: "timing",
203
- duration: motion.durationShort4,
204
- easing: standard
205
- },
193
+ "state-hover": { type: "spring", ...motion.springFastEffects },
194
+ "state-press": { type: "spring", ...motion.springFastEffects },
195
+ "state-focus": { type: "spring", ...motion.springFastEffects },
206
196
  "spring-fast-spatial": { type: "spring", ...motion.springFastSpatial },
207
197
  "spring-default-spatial": {
208
198
  type: "spring",
209
199
  ...motion.springDefaultSpatial
210
- }
200
+ },
201
+ "spring-slow-spatial": { type: "spring", ...motion.springSlowSpatial },
202
+ "spring-fast-effects": { type: "spring", ...motion.springFastEffects },
203
+ "spring-default-effects": {
204
+ type: "spring",
205
+ ...motion.springDefaultEffects
206
+ },
207
+ "spring-slow-effects": { type: "spring", ...motion.springSlowEffects }
211
208
  };
212
209
  }
213
210
 
214
211
  // src/provider/ThemeProvider.tsx
215
212
  import { MotionConfig } from "@rootnative/inertia";
216
- import * as React3 from "react";
213
+ import * as React4 from "react";
214
+ import { useColorScheme } from "react-native";
215
+
216
+ // src/internal/useIsHydrating.ts
217
+ import { useSyncExternalStore } from "react";
218
+ var subscribeToNothing = () => () => {
219
+ };
220
+ var notHydrating = () => false;
221
+ var isHydratingOnServer = () => true;
222
+ function useIsHydrating() {
223
+ return useSyncExternalStore(
224
+ subscribeToNothing,
225
+ notHydrating,
226
+ isHydratingOnServer
227
+ );
228
+ }
217
229
 
218
230
  // src/provider/IconResolverContext.ts
219
231
  import * as React from "react";
@@ -225,19 +237,99 @@ var IconResolverContext = React.createContext(
225
237
  import * as React2 from "react";
226
238
  var ThemeContext = React2.createContext(lightTheme);
227
239
 
240
+ // src/provider/ThemeModeContext.ts
241
+ import * as React3 from "react";
242
+ var ThemeModeContext = React3.createContext(null);
243
+
228
244
  // src/provider/ThemeProvider.tsx
229
245
  import { jsx } from "react/jsx-runtime";
246
+ var THEME_MODE_STORAGE_KEY = "rootnative.theme-mode";
247
+ function isThemePair(theme) {
248
+ return !("colors" in theme);
249
+ }
250
+ function isThemeMode(value) {
251
+ return value === "system" || value === "light" || value === "dark";
252
+ }
230
253
  function ThemeProvider({
231
254
  theme,
255
+ mode: controlledMode,
256
+ defaultMode = "system",
257
+ onModeChange,
258
+ storage,
232
259
  iconResolver,
233
260
  children
234
261
  }) {
235
- const resolvedTheme = theme != null ? theme : lightTheme;
236
- const transitions = React3.useMemo(
262
+ const pair = theme && isThemePair(theme) ? theme : null;
263
+ const measuredScheme = useColorScheme();
264
+ const systemScheme = useIsHydrating() ? "light" : measuredScheme;
265
+ const [uncontrolledMode, setUncontrolledMode] = React4.useState(defaultMode);
266
+ const isControlled = controlledMode !== void 0;
267
+ const mode = isControlled ? controlledMode : uncontrolledMode;
268
+ const [isReady, setIsReady] = React4.useState(
269
+ () => !storage || isControlled || !pair
270
+ );
271
+ const storageRef = React4.useRef(storage);
272
+ React4.useEffect(() => {
273
+ storageRef.current = storage;
274
+ });
275
+ const shouldLoad = Boolean(storage) && !isControlled && Boolean(pair);
276
+ React4.useEffect(() => {
277
+ if (!shouldLoad) {
278
+ setIsReady(true);
279
+ return;
280
+ }
281
+ let cancelled = false;
282
+ const load = async () => {
283
+ var _a;
284
+ try {
285
+ const stored = await ((_a = storageRef.current) == null ? void 0 : _a.getItem(THEME_MODE_STORAGE_KEY));
286
+ if (!cancelled && isThemeMode(stored)) {
287
+ setUncontrolledMode(stored);
288
+ }
289
+ } catch {
290
+ } finally {
291
+ if (!cancelled) {
292
+ setIsReady(true);
293
+ }
294
+ }
295
+ };
296
+ void load();
297
+ return () => {
298
+ cancelled = true;
299
+ };
300
+ }, [shouldLoad]);
301
+ const setMode = React4.useCallback(
302
+ (nextMode) => {
303
+ var _a;
304
+ if (!isControlled) {
305
+ setUncontrolledMode(nextMode);
306
+ }
307
+ onModeChange == null ? void 0 : onModeChange(nextMode);
308
+ if (!isControlled) {
309
+ try {
310
+ const result = (_a = storageRef.current) == null ? void 0 : _a.setItem(
311
+ THEME_MODE_STORAGE_KEY,
312
+ nextMode
313
+ );
314
+ void Promise.resolve(result).catch(() => {
315
+ });
316
+ } catch {
317
+ }
318
+ }
319
+ },
320
+ [isControlled, onModeChange]
321
+ );
322
+ const scheme = mode === "system" ? systemScheme === "dark" ? "dark" : "light" : mode;
323
+ const resolvedTheme = pair ? scheme === "dark" ? pair.dark : pair.light : theme != null ? theme : lightTheme;
324
+ const modeValue = React4.useMemo(
325
+ () => pair ? { mode, scheme, setMode, isReady } : null,
326
+ [pair, mode, scheme, setMode, isReady]
327
+ );
328
+ const transitions = React4.useMemo(
237
329
  () => motionTransitions(resolvedTheme.motion),
238
330
  [resolvedTheme.motion]
239
331
  );
240
- return /* @__PURE__ */ jsx(ThemeContext.Provider, { value: resolvedTheme, children: /* @__PURE__ */ jsx(IconResolverContext.Provider, { value: iconResolver != null ? iconResolver : null, children: /* @__PURE__ */ jsx(MotionConfig, { transitions, children }) }) });
332
+ return /* @__PURE__ */ jsx(ThemeContext.Provider, { value: resolvedTheme, children: /* @__PURE__ */ jsx(ThemeModeContext.Provider, { value: modeValue, children: /* @__PURE__ */ jsx(IconResolverContext.Provider, { value: iconResolver != null ? iconResolver : null, children: /* @__PURE__ */ jsx(MotionConfig, { transitions, children }) }) }) });
241
333
  }
242
334
 
243
335
  // src/provider/useTheme.ts
@@ -246,14 +338,38 @@ function useTheme() {
246
338
  return useContext(ThemeContext);
247
339
  }
248
340
 
249
- // src/provider/useIconResolver.ts
341
+ // src/provider/useThemeMode.ts
250
342
  import { useContext as useContext2 } from "react";
343
+ function useThemeMode() {
344
+ const value = useContext2(ThemeModeContext);
345
+ if (value === null) {
346
+ throw new Error(
347
+ "useThemeMode() requires a <ThemeProvider theme={{ light, dark }}>. A provider with a single theme has no light/dark mode to control."
348
+ );
349
+ }
350
+ return value;
351
+ }
352
+
353
+ // src/provider/useIconResolver.ts
354
+ import { useContext as useContext3 } from "react";
251
355
  function useIconResolver() {
252
- return useContext2(IconResolverContext);
356
+ return useContext3(IconResolverContext);
357
+ }
358
+
359
+ // src/responsive/useWindowDimensions.ts
360
+ import { useWindowDimensions as useMeasuredWindowDimensions } from "react-native";
361
+ var SERVER_WINDOW = Object.freeze({
362
+ width: 0,
363
+ height: 0,
364
+ scale: 1,
365
+ fontScale: 1
366
+ });
367
+ function useWindowDimensions() {
368
+ const measured = useMeasuredWindowDimensions();
369
+ return useIsHydrating() ? SERVER_WINDOW : measured;
253
370
  }
254
371
 
255
372
  // src/responsive/useBreakpoint.ts
256
- import { useWindowDimensions } from "react-native";
257
373
  var breakpoints = {
258
374
  compact: 0,
259
375
  medium: 600,
@@ -298,7 +414,7 @@ var material = {
298
414
  defaultTopAppBarTokens
299
415
  };
300
416
  export {
301
- IconResolverContext,
417
+ THEME_MODE_STORAGE_KEY,
302
418
  ThemeProvider,
303
419
  applyRoundness,
304
420
  breakpoints,
@@ -311,5 +427,7 @@ export {
311
427
  useBreakpoint,
312
428
  useBreakpointValue,
313
429
  useIconResolver,
314
- useTheme
430
+ useTheme,
431
+ useThemeMode,
432
+ useWindowDimensions
315
433
  };
@@ -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,28 +87,49 @@ interface Colors {
88
87
  inverseSurface: string;
89
88
  inverseOnSurface: string;
90
89
  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
- }
90
+ };
91
+ /**
92
+ * Material Design 3 type scale with 15 roles across 5 categories (display,
93
+ * headline, title, body, label), plus the 15 MD3 Expressive emphasized
94
+ * variants. Emphasized styles keep the base size/line-height and step the
95
+ * weight up (regular→medium, medium→bold); a few also adjust tracking. The
96
+ * spec additionally varies width/grade on variable fonts, which React Native
97
+ * cannot express — weight (+tracking) is the documented approximation.
98
+ */
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
+ };
111
131
  type FontWeight = 'normal' | 'bold' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
112
- interface TextStyle {
132
+ interface TypographyToken {
113
133
  fontFamily: string;
114
134
  fontSize: number;
115
135
  fontWeight: FontWeight;
@@ -216,17 +236,41 @@ interface Motion {
216
236
  easingEmphasizedAccelerate: string;
217
237
  easingEmphasizedDecelerate: string;
218
238
  /**
219
- * Spring for fast spatial transitions — selection morphs that track user
220
- * input snappily (Switch thumb, Slider press-grow). Slight overshoot,
221
- * ~0.85 damping ratio. Named after the MD3 Expressive motion-physics token
222
- * scheme (fast/default/slow × spatial/effects).
239
+ * Spring for fast spatial transitions — small-element position/size/corner
240
+ * morphs that track user input snappily (Switch thumb, Slider press-grow,
241
+ * press shape-morphs). Pronounced overshoot (damping ratio 0.6). Named
242
+ * after the MD3 Expressive motion-physics token scheme
243
+ * (fast/default/slow × spatial/effects).
223
244
  */
224
245
  springFastSpatial: MotionSpring;
225
246
  /**
226
- * Spring for default spatial transitions — selection morphs with a softer,
227
- * bouncier settle (Checkbox and Radio marks).
247
+ * Spring for default spatial transitions — standard-size element morphs
248
+ * with a softer, bouncier settle (Checkbox and Radio marks). Damping
249
+ * ratio 0.8.
228
250
  */
229
251
  springDefaultSpatial: MotionSpring;
252
+ /**
253
+ * Spring for slow spatial transitions — large-element position/size/corner
254
+ * morphs (full-screen or container-scale movement). Damping ratio 0.8 at
255
+ * low stiffness.
256
+ */
257
+ springSlowSpatial: MotionSpring;
258
+ /**
259
+ * Spring for fast effects transitions — small-element color/opacity
260
+ * feedback (state layers). Critically damped (damping ratio 1.0) — effects
261
+ * springs never overshoot.
262
+ */
263
+ springFastEffects: MotionSpring;
264
+ /**
265
+ * Spring for default effects transitions — standard color/opacity changes.
266
+ * Critically damped.
267
+ */
268
+ springDefaultEffects: MotionSpring;
269
+ /**
270
+ * Spring for slow effects transitions — large-surface color/opacity
271
+ * changes. Critically damped.
272
+ */
273
+ springSlowEffects: MotionSpring;
230
274
  }
231
275
 
232
- 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 };
276
+ 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 };