react-native-theme-transition 1.0.6 → 2.0.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.
Files changed (66) hide show
  1. package/README.md +55 -43
  2. package/README.npm.md +55 -43
  3. package/dist/constants.d.ts +1 -2
  4. package/dist/constants.d.ts.map +1 -1
  5. package/dist/constants.js +4 -0
  6. package/dist/constants.js.map +1 -1
  7. package/dist/createThemeTransition.d.ts +6 -18
  8. package/dist/createThemeTransition.d.ts.map +1 -1
  9. package/dist/createThemeTransition.js +37 -35
  10. package/dist/createThemeTransition.js.map +1 -1
  11. package/dist/index.d.ts +9 -9
  12. package/dist/index.d.ts.map +1 -1
  13. package/dist/index.js +8 -8
  14. package/dist/index.js.map +1 -1
  15. package/dist/overlay/SkiaOverlay.d.ts +17 -0
  16. package/dist/overlay/SkiaOverlay.d.ts.map +1 -0
  17. package/dist/overlay/SkiaOverlay.js +297 -0
  18. package/dist/overlay/SkiaOverlay.js.map +1 -0
  19. package/dist/overlay/captureView.d.ts +7 -0
  20. package/dist/overlay/captureView.d.ts.map +1 -0
  21. package/dist/overlay/captureView.js +31 -0
  22. package/dist/overlay/captureView.js.map +1 -0
  23. package/dist/overlay/resolveOrigin.d.ts +8 -0
  24. package/dist/overlay/resolveOrigin.d.ts.map +1 -0
  25. package/dist/overlay/resolveOrigin.js +68 -0
  26. package/dist/overlay/resolveOrigin.js.map +1 -0
  27. package/dist/overlay/types.d.ts +15 -0
  28. package/dist/overlay/types.d.ts.map +1 -0
  29. package/dist/overlay/types.js +61 -0
  30. package/dist/overlay/types.js.map +1 -0
  31. package/dist/setThemeDecision.d.ts +14 -0
  32. package/dist/setThemeDecision.d.ts.map +1 -0
  33. package/dist/setThemeDecision.js +27 -0
  34. package/dist/setThemeDecision.js.map +1 -0
  35. package/dist/transitionEngine.d.ts +48 -17
  36. package/dist/transitionEngine.d.ts.map +1 -1
  37. package/dist/transitionEngine.js +279 -208
  38. package/dist/transitionEngine.js.map +1 -1
  39. package/dist/transitionMeta.d.ts +136 -0
  40. package/dist/transitionMeta.d.ts.map +1 -0
  41. package/dist/transitionMeta.js +131 -0
  42. package/dist/transitionMeta.js.map +1 -0
  43. package/dist/types.d.ts +254 -193
  44. package/dist/types.d.ts.map +1 -1
  45. package/dist/validateSetThemeOptions.d.ts +15 -0
  46. package/dist/validateSetThemeOptions.d.ts.map +1 -0
  47. package/dist/validateSetThemeOptions.js +54 -0
  48. package/dist/validateSetThemeOptions.js.map +1 -0
  49. package/package.json +14 -6
  50. package/src/constants.ts +6 -0
  51. package/src/createThemeTransition.ts +57 -39
  52. package/src/index.ts +12 -9
  53. package/src/overlay/SkiaOverlay.tsx +629 -0
  54. package/src/overlay/captureView.ts +32 -0
  55. package/src/overlay/resolveOrigin.ts +81 -0
  56. package/src/overlay/types.ts +83 -0
  57. package/src/setThemeDecision.ts +48 -0
  58. package/src/transitionEngine.tsx +390 -247
  59. package/src/transitionMeta.ts +176 -0
  60. package/src/types.ts +272 -193
  61. package/src/validateSetThemeOptions.ts +76 -0
  62. package/dist/hooks/useTheme.d.ts +0 -14
  63. package/dist/hooks/useTheme.d.ts.map +0 -1
  64. package/dist/hooks/useTheme.js +0 -46
  65. package/dist/hooks/useTheme.js.map +0 -1
  66. package/src/hooks/useTheme.ts +0 -72
package/src/types.ts CHANGED
@@ -1,300 +1,379 @@
1
+ import type { View } from 'react-native'
2
+ import type { TransitionType } from './transitionMeta'
3
+
1
4
  /**
2
- * Map of theme token names to color values.
5
+ * Supported transition names.
3
6
  *
4
- * @remarks
5
- * Each theme is a flat record where keys are token names (e.g. `"background"`,
6
- * `"textPrimary"`) and values are color strings accepted by React Native
7
- * (hex, rgb, rgba, named colors).
7
+ * @see https://react-native-theme-transition.vercel.app/docs/types#transitiontype
8
+ */
9
+ export type { TransitionType }
10
+
11
+ /**
12
+ * A flat record of theme tokens. Keys are token names, values are
13
+ * React Native color strings. Every theme in a configuration must
14
+ * declare the same set of keys.
15
+ *
16
+ * @see https://react-native-theme-transition.vercel.app/docs/types#themedefinition
8
17
  */
9
18
  export type ThemeDefinition = Record<string, string>
10
19
 
11
20
  /**
12
- * Union of theme names available in a theme configuration.
21
+ * Explicit origin point for a reveal transition, in React Native
22
+ * density-independent points relative to the provider's root view.
23
+ * Both `x` and `y` must be finite numbers; the engine throws on `NaN`
24
+ * or `Infinity` to prevent silent geometry corruption inside the
25
+ * overlay's bounding-radius math.
13
26
  *
14
- * @typeParam T - Your application's theme map, keyed by theme name.
27
+ * @see https://react-native-theme-transition.vercel.app/docs/types#transitionorigin
15
28
  */
16
- export type ThemeNames<T extends Record<string, ThemeDefinition>> = keyof T & string
29
+ export interface TransitionOrigin {
30
+ /** Horizontal offset from the left edge of the provider, in points. Must be finite. */
31
+ x: number
32
+ /** Vertical offset from the top edge of the provider, in points. Must be finite. */
33
+ y: number
34
+ }
17
35
 
18
36
  /**
19
- * Union of token names shared across all themes in a configuration.
37
+ * Origin for a reveal transition. Either an explicit
38
+ * {@link TransitionOrigin} or a React ref whose center is measured
39
+ * just before the animation starts. A ref that has unmounted or
40
+ * returns no coordinates falls back to the center of the screen.
20
41
  *
21
- * @typeParam T - Your application's theme map, keyed by theme name.
42
+ * @see https://react-native-theme-transition.vercel.app/docs/types#originspec
22
43
  */
44
+ export type OriginSpec = TransitionOrigin | React.RefObject<View | null>
45
+
46
+ /** Union of the theme names declared in `T`. */
47
+ export type ThemeNames<T extends Record<string, ThemeDefinition>> = keyof T & string
48
+
49
+ /** Union of the token names shared across every theme in `T`. */
23
50
  export type TokenNames<T extends Record<string, ThemeDefinition>> = keyof T[ThemeNames<T>] & string
24
51
 
52
+ /** Binary OS color scheme. Never `'unspecified'`. */
53
+ export type ColorScheme = 'light' | 'dark'
54
+
25
55
  /**
26
- * Maps OS color schemes (`'light'` / `'dark'`) to theme names.
27
- *
28
- * @remarks
29
- * Required when your themes are not named `'light'` and `'dark'`.
30
- * Both keys must be provided.
56
+ * Maps OS color schemes to theme names. Required when your themes are
57
+ * not literally named `'light'` and `'dark'` and you want to use
58
+ * `initialTheme="system"` or `setTheme('system')`.
31
59
  *
32
- * @typeParam Names - Union of theme name strings.
60
+ * @see https://react-native-theme-transition.vercel.app/docs/types#systemthememap
33
61
  */
34
- export type SystemThemeMap<Names extends string> = Record<'light' | 'dark', Names>
62
+ export type SystemThemeMap<Names extends string> = Record<ColorScheme, Names>
35
63
 
36
64
  /**
37
65
  * Configuration for {@link createThemeTransition}.
38
66
  *
39
- * @typeParam T - Your application's theme map, keyed by theme name.
67
+ * @see https://react-native-theme-transition.vercel.app/docs/api/create-theme-transition
40
68
  */
41
69
  export interface ThemeTransitionConfig<T extends Record<string, ThemeDefinition>> {
42
70
  /**
43
- * All available themes keyed by name.
44
- *
45
- * @remarks
46
- * Every theme must share the exact same token keys. Mismatched keys
47
- * cause a runtime error at initialization.
48
- * The name `'system'` is reserved and cannot be used as a theme name.
71
+ * All available themes keyed by name. Every theme must share the
72
+ * same token keys; mismatches throw at initialization. The name
73
+ * `'system'` is reserved.
49
74
  */
50
75
  themes: T
51
76
 
52
77
  /**
53
- * Cross-fade duration in milliseconds.
54
- * @default 350
78
+ * Whether theme changes animate by default. When `false`, every
79
+ * `setTheme` call switches instantly unless the caller passes
80
+ * `{ animated: true }`.
81
+ *
82
+ * @default true
55
83
  */
56
- duration?: number
84
+ animated?: boolean
57
85
 
58
86
  /**
59
- * Maps OS appearance (`'light'` / `'dark'`) to theme names.
87
+ * Default transition kind. Override per call via
88
+ * `setTheme(name, { transition })`.
60
89
  *
61
- * @remarks
62
- * Required when your themes are not named `'light'` and `'dark'`
63
- * and you want to use `initialTheme="system"` or `setTheme('system')`.
64
- * Both `light` and `dark` must be provided.
90
+ * @default 'fade'
91
+ */
92
+ transition?: TransitionType
93
+
94
+ /**
95
+ * Maps OS appearance to your theme names. Required when your themes
96
+ * are not named `'light'` and `'dark'` and you want to use
97
+ * `'system'` mode. Complements
98
+ * {@link ThemeTransitionConfig.darkThemes}.
65
99
  */
66
100
  systemThemeMap?: SystemThemeMap<ThemeNames<T>>
67
101
 
68
102
  /**
69
- * Theme names that use a dark color scheme.
103
+ * Theme names that should register as a dark color scheme with the
104
+ * OS via `Appearance.setColorScheme`. Only needed with two or more
105
+ * dark themes; otherwise derived from
106
+ * {@link ThemeTransitionConfig.systemThemeMap} (or `['dark']` if
107
+ * neither is provided). Must contain at least one entry when
108
+ * supplied; the engine throws on an empty array. Omit the field to
109
+ * fall back to the default.
70
110
  *
71
- * @remarks
72
- * The library automatically calls `Appearance.setColorScheme` to keep
73
- * native UI elements (alerts, date pickers, keyboards) in sync with
74
- * the active theme. Themes listed here get `'dark'`; all others get `'light'`.
75
- * In system mode, `'unspecified'` is used so the OS drives the appearance.
76
- *
77
- * **Do not call `Appearance.setColorScheme` yourself** — the library manages
78
- * it internally. Calling it manually can corrupt state on Android.
79
- *
80
- * @default `[systemThemeMap.dark]` if `systemThemeMap` is provided, otherwise `['dark']`.
111
+ * @see https://react-native-theme-transition.vercel.app/docs/api/create-theme-transition#darkthemes
112
+ * @throws Error if supplied as an empty array, or if any entry is not a known theme name.
81
113
  */
82
114
  darkThemes?: ThemeNames<T>[]
83
115
 
84
116
  /**
85
- * Called when an animated transition begins, before the screenshot capture.
86
- *
87
- * @remarks
88
- * Fires for all animated transitions, including system-driven ones.
89
- * Does not fire for instant switches (`animated: false`).
117
+ * Fires when an animated transition begins, before snapshot capture.
90
118
  *
91
- * @param themeName - The target theme name.
119
+ * @param themeName - Theme becoming active.
120
+ * @see https://react-native-theme-transition.vercel.app/docs/guides/callbacks
92
121
  */
93
122
  onTransitionStart?: (themeName: ThemeNames<T>) => void
94
123
 
95
124
  /**
96
- * Called after an animated transition completes and the overlay is removed.
125
+ * Fires after an animated transition completes and the overlay is
126
+ * removed.
127
+ *
128
+ * @param themeName - Theme that is now active.
129
+ * @see https://react-native-theme-transition.vercel.app/docs/guides/callbacks
130
+ */
131
+ onTransitionEnd?: (themeName: ThemeNames<T>) => void
132
+
133
+ /**
134
+ * Fires whenever the active theme changes, regardless of path. The
135
+ * only callback guaranteed to fire on every code path. In `'system'`
136
+ * mode it can fire twice for a single `setTheme` call if the OS
137
+ * appearance changes while the transition is still in flight.
97
138
  *
98
- * @remarks
99
- * Fires for all animated transitions, including system-driven ones.
100
- * Does not fire for instant switches (`animated: false`).
139
+ * @param themeName - Theme that is now active.
140
+ * @see https://react-native-theme-transition.vercel.app/docs/guides/callbacks
141
+ */
142
+ onThemeChange?: (themeName: ThemeNames<T>) => void
143
+ }
144
+
145
+ /** Common fields shared by every variant in {@link SetThemeOptions}. */
146
+ interface BaseSetThemeOptions<Names extends string> {
147
+ /**
148
+ * Whether to animate this specific change. `false` switches
149
+ * instantly, with no snapshot or overlay. When omitted, inherits
150
+ * {@link ThemeTransitionConfig.animated} (which itself defaults to
151
+ * `true`).
152
+ */
153
+ animated?: boolean
154
+
155
+ /**
156
+ * Duration in milliseconds. Overrides the per-transition default.
157
+ * Must be a non-negative finite number; the engine throws on `NaN`,
158
+ * `Infinity`, or negative values.
101
159
  *
102
- * Not called if the screenshot capture fails mid-transition, even when
103
- * `onTransitionStart` has already fired. In that case the library falls back to an
104
- * instant switch and only `onThemeChange` fires. Design `onTransitionStart` handlers
105
- * to be resilient to a missing matching `onTransitionEnd`.
160
+ * @default 350 for `fade`, `circularReveal`, `wipe`, `slide`, `split`; 800 for `heart`, `star`; 750 for `pixelize`, `dissolve`
161
+ * @throws Error if not a non-negative finite number.
162
+ */
163
+ duration?: number
164
+
165
+ /**
166
+ * Easing function. Accepts any Reanimated `EasingFunction`, a
167
+ * worklet-safe `(t: number) => number`.
106
168
  *
107
- * @param themeName - The newly active theme name.
169
+ * @default Easing.out(Easing.cubic)
108
170
  */
109
- onTransitionEnd?: (themeName: ThemeNames<T>) => void
171
+ easing?: (t: number) => number
110
172
 
111
173
  /**
112
- * Called whenever the active theme changes.
174
+ * Per-call start callback. Fires after
175
+ * {@link ThemeTransitionConfig.onTransitionStart} and only when the
176
+ * change is animated.
113
177
  *
114
- * @remarks
115
- * Fires for all theme changes: animated transitions, instant switches,
116
- * and system-driven appearance changes. For animated transitions,
117
- * fires after `onTransitionEnd`.
178
+ * @param themeName - Theme becoming active.
179
+ */
180
+ onTransitionStart?: (themeName: Names) => void
181
+
182
+ /**
183
+ * Per-call end callback. Fires after
184
+ * {@link ThemeTransitionConfig.onTransitionEnd}. Skipped on
185
+ * capture-failure fallbacks.
118
186
  *
119
- * @param themeName - The newly active theme name.
187
+ * @param themeName - Theme that is now active.
120
188
  */
121
- onThemeChange?: (themeName: ThemeNames<T>) => void
189
+ onTransitionEnd?: (themeName: Names) => void
122
190
  }
123
191
 
124
192
  /**
125
- * Options for {@link ThemeTransitionAPI.useTheme | setTheme}.
126
- *
127
- * @typeParam Names - Union of theme name strings.
193
+ * Fade. The old snapshot's opacity drops to zero, revealing the new
194
+ * theme. Default transition; the `transition` field can be omitted.
128
195
  */
129
- export interface SetThemeOptions<Names extends string = string> {
196
+ interface FadeVariant {
197
+ transition?: 'fade'
198
+ }
199
+
200
+ /**
201
+ * Reveal. A shape (circle, heart, star) grows from a point,
202
+ * uncovering the new theme.
203
+ */
204
+ interface RevealVariant {
205
+ transition: 'circularReveal' | 'heart' | 'star'
130
206
  /**
131
- * Whether to use the screenshot-overlay cross-fade animation.
132
- *
133
- * @remarks
134
- * When `false`, the theme switches instantly without capturing a screenshot
135
- * or showing an overlay.
207
+ * Point or ref where the shape expands from (or shrinks into when
208
+ * `inverted`). Falls back to the center of the screen.
209
+ */
210
+ origin?: OriginSpec
211
+ /**
212
+ * Reverse the direction. The new theme fills the screen and the old
213
+ * theme shrinks inside the shape until it vanishes.
136
214
  *
137
- * @default true
215
+ * @default false
138
216
  */
139
- animated?: boolean
217
+ inverted?: boolean
218
+ }
140
219
 
220
+ /**
221
+ * Wipe and slide. Directional reveal; `direction` names where the
222
+ * motion is heading. The new theme always enters from the opposite
223
+ * edge and moves toward `direction`.
224
+ */
225
+ interface WipeVariant {
226
+ transition: 'wipe' | 'slide'
141
227
  /**
142
- * Called when the animated transition begins, before the screenshot capture.
143
- *
144
- * @remarks
145
- * Only called when `animated` is `true` (the default).
146
- * Fires after the config-level `onTransitionStart` (if provided).
228
+ * Cardinal direction the motion is heading.
147
229
  *
148
- * @param themeName - The target theme name.
230
+ * @default 'right'
149
231
  */
150
- onTransitionStart?: (themeName: Names) => void
232
+ direction?: 'left' | 'right' | 'up' | 'down'
233
+ }
151
234
 
235
+ /**
236
+ * Split. The screen splits in two and each half animates. With
237
+ * `inverted: false` the halves part outward from the centerline like
238
+ * curtains. With `inverted: true` they close inward from the edges
239
+ * like shutters.
240
+ */
241
+ interface SplitVariant {
242
+ transition: 'split'
152
243
  /**
153
- * Called after the animated transition completes and the overlay is removed.
244
+ * How the screen is divided. `'left-right'` splits vertically;
245
+ * `'top-bottom'` splits horizontally.
154
246
  *
155
- * @remarks
156
- * Only called when `animated` is `true` (the default).
157
- * Fires after the config-level `onTransitionEnd` (if provided).
247
+ * @default 'left-right'
248
+ */
249
+ mode?: 'left-right' | 'top-bottom'
250
+ /**
251
+ * Reverse the animation. `false` parts outward from the center;
252
+ * `true` closes inward from the edges.
158
253
  *
159
- * Not called if the screenshot capture fails mid-transition, even when
160
- * `onTransitionStart` has already fired. In that case the library falls back to an
161
- * instant switch and only `onThemeChange` fires.
254
+ * @default false
255
+ */
256
+ inverted?: boolean
257
+ }
258
+
259
+ /**
260
+ * Pixelize. Both old and new snapshots crossfade through a shared
261
+ * pixel grid that peaks at the midpoint.
262
+ */
263
+ interface PixelizeVariant {
264
+ transition: 'pixelize'
265
+ /**
266
+ * Maximum pixel block size in points at the animation's midpoint.
267
+ * Higher values give a chunkier mosaic. Must be a finite number
268
+ * `>= 2`; the engine throws on smaller, `NaN`, or `Infinity` values.
162
269
  *
163
- * @param themeName - The newly active theme name.
270
+ * @default 52
271
+ * @throws Error if not a finite number `>= 2`.
164
272
  */
165
- onTransitionEnd?: (themeName: Names) => void
273
+ blockSize?: number
166
274
  }
167
275
 
168
276
  /**
169
- * Base return type of the {@link ThemeTransitionAPI.useTheme | useTheme} hook.
170
- *
171
- * @typeParam Tokens - Union of token name strings.
172
- * @typeParam Names - Union of theme name strings.
277
+ * Dissolve. The old snapshot disintegrates via a noise threshold; as
278
+ * `progress` rises, more cells turn transparent until the new theme is
279
+ * fully visible.
173
280
  */
174
- export interface UseThemeResult<Tokens extends string, Names extends string> {
175
- /** Current resolved color values for all tokens. */
176
- colors: Record<Tokens, string>
177
- /** Name of the currently active theme (resolved, never `'system'`). */
178
- name: Names
281
+ interface DissolveVariant {
282
+ transition: 'dissolve'
179
283
  /**
180
- * Switch to a new theme or enter system mode.
284
+ * Noise cell size in points. Higher values give bigger, more
285
+ * visible specks; lower values give finer sand. Must be a finite
286
+ * number `>= 1`; the engine throws on smaller, `NaN`, or `Infinity`
287
+ * values.
181
288
  *
182
- * @param name - Target theme name or `'system'`.
183
- * @param options - Optional transition configuration.
184
- * @returns `true` if the theme change was accepted, `false` if rejected
185
- * (already transitioning or same theme).
289
+ * @default 5
290
+ * @throws Error if not a finite number `>= 1`.
186
291
  */
187
- setTheme: (name: Names | 'system', options?: SetThemeOptions<Names>) => boolean
188
- /** `true` while a cross-fade transition overlay is visible. */
189
- isTransitioning: boolean
292
+ noiseSize?: number
190
293
  }
191
294
 
192
295
  /**
193
- * Selection state returned by {@link ThemeTransitionAPI.useTheme | useTheme}
194
- * when called with `{ initialSelection }`.
296
+ * Options for {@link UseThemeResult.setTheme}. The `transition` field
297
+ * selects a variant and determines which extra fields are valid for
298
+ * that variant.
195
299
  *
196
- * @typeParam Names - Union of theme name strings.
300
+ * @see https://react-native-theme-transition.vercel.app/docs/types#setthemeoptions
197
301
  */
198
- export interface ThemeSelectionResult<Names extends string> {
199
- /** The currently selected option (may be `'system'`). */
200
- selected: Names | 'system'
302
+ export type SetThemeOptions<Names extends string = string> = BaseSetThemeOptions<Names> &
303
+ (FadeVariant | RevealVariant | WipeVariant | SplitVariant | PixelizeVariant | DissolveVariant)
304
+
305
+ /**
306
+ * Return value of {@link ThemeTransitionAPI.useTheme}. Two orthogonal
307
+ * concepts: `theme` (what is currently painted, always concrete) and
308
+ * `preference` (what the user explicitly picked, can be `'system'`).
309
+ *
310
+ * @see https://react-native-theme-transition.vercel.app/docs/api/use-theme
311
+ */
312
+ export interface UseThemeResult<Tokens extends string, Names extends string> {
201
313
  /**
202
- * Select a theme with transition-safe timing.
203
- *
204
- * @remarks
205
- * Updates the selection highlight immediately, then defers `setTheme`
206
- * to the next animation frame so the selection is painted before
207
- * the library captures the screenshot. Rapid presses during an
208
- * ongoing transition are silently ignored.
314
+ * The theme currently painted on screen. Always a concrete theme,
315
+ * never `'system'`.
316
+ */
317
+ theme: {
318
+ /** Name of the painted theme. Always concrete. */
319
+ name: Names
320
+ /** Resolved color tokens for the painted theme. */
321
+ colors: Record<Tokens, string>
322
+ /**
323
+ * Binary light or dark classification, derived from
324
+ * {@link ThemeTransitionConfig.darkThemes}.
325
+ */
326
+ scheme: ColorScheme
327
+ }
328
+
329
+ /**
330
+ * The theme the user explicitly picked. May be `'system'`. Mirrors
331
+ * the last argument passed to {@link UseThemeResult.setTheme}.
332
+ */
333
+ preference: Names | 'system'
334
+
335
+ /** `true` while a transition overlay is visible. */
336
+ isTransitioning: boolean
337
+
338
+ /**
339
+ * Change the user's {@link UseThemeResult.preference}.
209
340
  *
210
- * @param option - Theme name or `'system'`.
341
+ * @param name - Concrete theme name, or `'system'` to follow the OS.
342
+ * @param options - Per-call transition configuration.
343
+ * @returns `'accepted'` if the change will apply, `'ignored'` if rejected (same preference or transition in flight).
344
+ * @see https://react-native-theme-transition.vercel.app/docs/api/use-theme#settheme
211
345
  */
212
- select: (option: Names | 'system') => void
346
+ setTheme: (name: Names | 'system', options?: SetThemeOptions<Names>) => 'accepted' | 'ignored'
213
347
  }
214
348
 
215
349
  /**
216
350
  * Public API returned by {@link createThemeTransition}.
217
351
  *
218
- * @typeParam T - Your application's theme map, keyed by theme name.
352
+ * @see https://react-native-theme-transition.vercel.app/docs/api/create-theme-transition
219
353
  */
220
354
  export interface ThemeTransitionAPI<T extends Record<string, ThemeDefinition>> {
221
355
  /**
222
356
  * Provider that supplies animated theme colors via context.
223
357
  *
224
- * @remarks
225
- * Place this as high as possible in the component tree (ideally wrapping
226
- * navigation) so the screenshot can capture the entire screen.
358
+ * @see https://react-native-theme-transition.vercel.app/docs/api/provider
227
359
  */
228
- ThemeTransitionProvider: React.FC<{
360
+ ThemeTransitionProvider: (props: {
361
+ /** Your app tree. */
229
362
  children: React.ReactNode
230
363
  /**
231
- * Theme to render on the first frame.
232
- *
233
- * @remarks
234
- * Pass `'system'` to read the OS appearance synchronously (zero-flash)
235
- * and subscribe to changes. For custom theme names, provide
236
- * {@link ThemeTransitionConfig.systemThemeMap | systemThemeMap} in the config.
364
+ * Theme to render on the first frame. Read once on mount, like
365
+ * the initializer of `useState`; later changes to this prop are
366
+ * ignored.
237
367
  */
238
368
  initialTheme: ThemeNames<T> | 'system'
239
- }>
369
+ }) => React.ReactNode
240
370
 
241
371
  /**
242
- * Hook returning the current theme state and transition controls.
243
- *
244
- * @remarks
245
- * **Without arguments** — returns theme colors, name, `setTheme`, and
246
- * `isTransitioning`. Use this in any component that reads or changes the theme.
247
- *
248
- * **With `{ initialSelection }`** — also returns `selected` and `select` for
249
- * building theme selection UIs (button groups, toggles, checkmark lists) with
250
- * transition-safe timing. On iOS (especially 120Hz ProMotion), calling
251
- * `setTheme` synchronously after a UI state update can cause the screenshot
252
- * to capture the old state, producing visible flickering. The `select`
253
- * function handles this automatically by deferring `setTheme` to the next
254
- * animation frame.
372
+ * Hook that returns the {@link UseThemeResult} for the nearest
373
+ * provider.
255
374
  *
256
- * `initialSelection` sets the starting value of `selected` (read once, like
257
- * `useState`). When omitted, defaults to the current theme name from context.
258
- *
259
- * @throws If called outside a `ThemeTransitionProvider`.
260
- *
261
- * @example
262
- * ```tsx
263
- * // Reading theme colors in any component
264
- * const { colors, name } = useTheme();
265
- * ```
266
- *
267
- * @example
268
- * ```tsx
269
- * // Building a theme selection UI
270
- * function ThemePicker() {
271
- * const { selected, select, colors, isTransitioning } = useTheme({ initialSelection: 'system' });
272
- * return (
273
- * <View style={{ flexDirection: 'row', gap: 8 }}>
274
- * {(['system', 'light', 'dark'] as const).map((option) => (
275
- * <Pressable
276
- * key={option}
277
- * onPress={() => select(option)}
278
- * disabled={isTransitioning}
279
- * style={{ backgroundColor: option === selected ? colors.primary : 'transparent' }}
280
- * >
281
- * <Text>{option}</Text>
282
- * </Pressable>
283
- * ))}
284
- * </View>
285
- * );
286
- * }
287
- * ```
375
+ * @throws Error if called outside a `ThemeTransitionProvider`.
376
+ * @see https://react-native-theme-transition.vercel.app/docs/api/use-theme
288
377
  */
289
- useTheme: {
290
- /** Returns current theme state and controls. */
291
- (): UseThemeResult<TokenNames<T>, ThemeNames<T>>
292
- /**
293
- * Returns theme state, controls, and selection tracking with transition-safe timing.
294
- * @param options.initialSelection - Starting value for `selected`. Defaults to the current theme name.
295
- */
296
- (options: {
297
- initialSelection?: ThemeNames<T> | 'system'
298
- }): UseThemeResult<TokenNames<T>, ThemeNames<T>> & ThemeSelectionResult<ThemeNames<T>>
299
- }
378
+ useTheme: () => UseThemeResult<TokenNames<T>, ThemeNames<T>>
300
379
  }
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Pure runtime validator for the per-call options passed to `setTheme`.
3
+ * Throws a descriptive `Error` if any numeric option falls outside its
4
+ * supported range, so user-visible failure modes (silent NaN propagation
5
+ * into shaders, negative-duration timers, etc.) surface immediately at
6
+ * the call site instead of producing broken animations.
7
+ *
8
+ * Extracted as a pure helper so the bounds can be unit-tested without
9
+ * mounting the provider.
10
+ *
11
+ * @module
12
+ * @internal
13
+ */
14
+
15
+ import { TAG } from './constants'
16
+ import { isOriginRef } from './overlay/resolveOrigin'
17
+ import type { OriginSpec } from './types'
18
+
19
+ /** @internal The subset of {@link SetThemeOptions} this helper checks. */
20
+ interface ValidatableOptions {
21
+ duration?: number
22
+ blockSize?: number
23
+ noiseSize?: number
24
+ origin?: OriginSpec
25
+ }
26
+
27
+ /** @internal */
28
+ function isValidNumber(value: unknown): value is number {
29
+ return typeof value === 'number' && Number.isFinite(value)
30
+ }
31
+
32
+ /**
33
+ * Throws if any numeric option in `options` is out of range. Returns
34
+ * silently otherwise. Safe to call with `undefined`.
35
+ *
36
+ * @throws Error if any numeric option is `NaN`, `Infinity`, or outside its supported range.
37
+ * @internal
38
+ */
39
+ export function validateSetThemeOptions(options: ValidatableOptions | undefined): void {
40
+ if (!options) return
41
+
42
+ if (options.duration !== undefined) {
43
+ if (!isValidNumber(options.duration) || options.duration < 0) {
44
+ throw new Error(
45
+ `${TAG} \`duration\` must be a non-negative finite number. Got ${String(options.duration)}.`,
46
+ )
47
+ }
48
+ }
49
+
50
+ if (options.blockSize !== undefined) {
51
+ if (!isValidNumber(options.blockSize) || options.blockSize < 2) {
52
+ throw new Error(
53
+ `${TAG} \`blockSize\` must be a finite number >= 2. Got ${String(options.blockSize)}.`,
54
+ )
55
+ }
56
+ }
57
+
58
+ if (options.noiseSize !== undefined) {
59
+ if (!isValidNumber(options.noiseSize) || options.noiseSize < 1) {
60
+ throw new Error(
61
+ `${TAG} \`noiseSize\` must be a finite number >= 1. Got ${String(options.noiseSize)}.`,
62
+ )
63
+ }
64
+ }
65
+
66
+ // Refs are validated at measurement time inside `resolveOrigin`,
67
+ // which falls back to the screen center if measurement fails. Only
68
+ // explicit coordinate pairs are checked here.
69
+ if (options.origin && !isOriginRef(options.origin)) {
70
+ if (!isValidNumber(options.origin.x) || !isValidNumber(options.origin.y)) {
71
+ throw new Error(
72
+ `${TAG} \`origin\` coordinates must be finite numbers. Got {x: ${String(options.origin.x)}, y: ${String(options.origin.y)}}.`,
73
+ )
74
+ }
75
+ }
76
+ }
@@ -1,14 +0,0 @@
1
- import type { Context } from 'react';
2
- import type { ThemeDefinition, ThemeNames, ThemeSelectionResult, TokenNames, UseThemeResult } from '../types';
3
- /**
4
- * Factory that produces the `useTheme` hook bound to a specific context.
5
- *
6
- * @internal Used by {@link createThemeTransition}; not part of the public API.
7
- */
8
- export declare function createUseTheme<T extends Record<string, ThemeDefinition>>(Ctx: Context<UseThemeResult<TokenNames<T>, ThemeNames<T>> | null>): {
9
- (): UseThemeResult<TokenNames<T>, ThemeNames<T>>;
10
- (options: {
11
- initialSelection?: ThemeNames<T> | "system";
12
- }): UseThemeResult<TokenNames<T>, ThemeNames<T>> & ThemeSelectionResult<ThemeNames<T>>;
13
- };
14
- //# sourceMappingURL=useTheme.d.ts.map