react-native-theme-transition 1.0.7 → 2.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -43
- package/README.npm.md +55 -43
- package/dist/constants.d.ts +1 -2
- package/dist/constants.d.ts.map +1 -1
- package/dist/constants.js +4 -0
- package/dist/constants.js.map +1 -1
- package/dist/createThemeTransition.d.ts +6 -18
- package/dist/createThemeTransition.d.ts.map +1 -1
- package/dist/createThemeTransition.js +37 -35
- package/dist/createThemeTransition.js.map +1 -1
- package/dist/index.d.ts +9 -9
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +8 -8
- package/dist/index.js.map +1 -1
- package/dist/overlay/SkiaOverlay.d.ts +17 -0
- package/dist/overlay/SkiaOverlay.d.ts.map +1 -0
- package/dist/overlay/SkiaOverlay.js +297 -0
- package/dist/overlay/SkiaOverlay.js.map +1 -0
- package/dist/overlay/captureView.d.ts +7 -0
- package/dist/overlay/captureView.d.ts.map +1 -0
- package/dist/overlay/captureView.js +31 -0
- package/dist/overlay/captureView.js.map +1 -0
- package/dist/overlay/resolveOrigin.d.ts +8 -0
- package/dist/overlay/resolveOrigin.d.ts.map +1 -0
- package/dist/overlay/resolveOrigin.js +68 -0
- package/dist/overlay/resolveOrigin.js.map +1 -0
- package/dist/overlay/types.d.ts +15 -0
- package/dist/overlay/types.d.ts.map +1 -0
- package/dist/overlay/types.js +61 -0
- package/dist/overlay/types.js.map +1 -0
- package/dist/setThemeDecision.d.ts +14 -0
- package/dist/setThemeDecision.d.ts.map +1 -0
- package/dist/setThemeDecision.js +27 -0
- package/dist/setThemeDecision.js.map +1 -0
- package/dist/transitionEngine.d.ts +48 -17
- package/dist/transitionEngine.d.ts.map +1 -1
- package/dist/transitionEngine.js +273 -210
- package/dist/transitionEngine.js.map +1 -1
- package/dist/transitionMeta.d.ts +136 -0
- package/dist/transitionMeta.d.ts.map +1 -0
- package/dist/transitionMeta.js +131 -0
- package/dist/transitionMeta.js.map +1 -0
- package/dist/types.d.ts +254 -193
- package/dist/types.d.ts.map +1 -1
- package/dist/validateSetThemeOptions.d.ts +15 -0
- package/dist/validateSetThemeOptions.d.ts.map +1 -0
- package/dist/validateSetThemeOptions.js +54 -0
- package/dist/validateSetThemeOptions.js.map +1 -0
- package/package.json +14 -6
- package/src/constants.ts +6 -0
- package/src/createThemeTransition.ts +57 -39
- package/src/index.ts +12 -9
- package/src/overlay/SkiaOverlay.tsx +629 -0
- package/src/overlay/captureView.ts +32 -0
- package/src/overlay/resolveOrigin.ts +81 -0
- package/src/overlay/types.ts +83 -0
- package/src/setThemeDecision.ts +48 -0
- package/src/transitionEngine.tsx +383 -249
- package/src/transitionMeta.ts +176 -0
- package/src/types.ts +272 -193
- package/src/validateSetThemeOptions.ts +76 -0
- package/dist/hooks/useTheme.d.ts +0 -14
- package/dist/hooks/useTheme.d.ts.map +0 -1
- package/dist/hooks/useTheme.js +0 -46
- package/dist/hooks/useTheme.js.map +0 -1
- 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
|
-
*
|
|
5
|
+
* Supported transition names.
|
|
3
6
|
*
|
|
4
|
-
* @
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
27
|
+
* @see https://react-native-theme-transition.vercel.app/docs/types#transitionorigin
|
|
15
28
|
*/
|
|
16
|
-
export
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
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
|
|
27
|
-
*
|
|
28
|
-
*
|
|
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
|
-
* @
|
|
60
|
+
* @see https://react-native-theme-transition.vercel.app/docs/types#systemthememap
|
|
33
61
|
*/
|
|
34
|
-
export type SystemThemeMap<Names extends string> = Record<
|
|
62
|
+
export type SystemThemeMap<Names extends string> = Record<ColorScheme, Names>
|
|
35
63
|
|
|
36
64
|
/**
|
|
37
65
|
* Configuration for {@link createThemeTransition}.
|
|
38
66
|
*
|
|
39
|
-
* @
|
|
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
|
-
*
|
|
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
|
-
*
|
|
54
|
-
*
|
|
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
|
-
|
|
84
|
+
animated?: boolean
|
|
57
85
|
|
|
58
86
|
/**
|
|
59
|
-
*
|
|
87
|
+
* Default transition kind. Override per call via
|
|
88
|
+
* `setTheme(name, { transition })`.
|
|
60
89
|
*
|
|
61
|
-
* @
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
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
|
|
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
|
-
* @
|
|
72
|
-
*
|
|
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
|
-
*
|
|
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 -
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
99
|
-
*
|
|
100
|
-
|
|
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
|
-
*
|
|
103
|
-
*
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
* @
|
|
169
|
+
* @default Easing.out(Easing.cubic)
|
|
108
170
|
*/
|
|
109
|
-
|
|
171
|
+
easing?: (t: number) => number
|
|
110
172
|
|
|
111
173
|
/**
|
|
112
|
-
*
|
|
174
|
+
* Per-call start callback. Fires after
|
|
175
|
+
* {@link ThemeTransitionConfig.onTransitionStart} and only when the
|
|
176
|
+
* change is animated.
|
|
113
177
|
*
|
|
114
|
-
* @
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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 -
|
|
187
|
+
* @param themeName - Theme that is now active.
|
|
120
188
|
*/
|
|
121
|
-
|
|
189
|
+
onTransitionEnd?: (themeName: Names) => void
|
|
122
190
|
}
|
|
123
191
|
|
|
124
192
|
/**
|
|
125
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
132
|
-
*
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
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
|
|
215
|
+
* @default false
|
|
138
216
|
*/
|
|
139
|
-
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
230
|
+
* @default 'right'
|
|
149
231
|
*/
|
|
150
|
-
|
|
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
|
-
*
|
|
244
|
+
* How the screen is divided. `'left-right'` splits vertically;
|
|
245
|
+
* `'top-bottom'` splits horizontally.
|
|
154
246
|
*
|
|
155
|
-
* @
|
|
156
|
-
|
|
157
|
-
|
|
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
|
-
*
|
|
160
|
-
|
|
161
|
-
|
|
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
|
-
* @
|
|
270
|
+
* @default 52
|
|
271
|
+
* @throws Error if not a finite number `>= 2`.
|
|
164
272
|
*/
|
|
165
|
-
|
|
273
|
+
blockSize?: number
|
|
166
274
|
}
|
|
167
275
|
|
|
168
276
|
/**
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
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
|
-
|
|
175
|
-
|
|
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
|
-
*
|
|
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
|
-
* @
|
|
183
|
-
* @
|
|
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
|
-
|
|
188
|
-
/** `true` while a cross-fade transition overlay is visible. */
|
|
189
|
-
isTransitioning: boolean
|
|
292
|
+
noiseSize?: number
|
|
190
293
|
}
|
|
191
294
|
|
|
192
295
|
/**
|
|
193
|
-
*
|
|
194
|
-
*
|
|
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
|
-
* @
|
|
300
|
+
* @see https://react-native-theme-transition.vercel.app/docs/types#setthemeoptions
|
|
197
301
|
*/
|
|
198
|
-
export
|
|
199
|
-
|
|
200
|
-
|
|
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
|
-
*
|
|
203
|
-
*
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
* @
|
|
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
|
-
* @
|
|
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:
|
|
360
|
+
ThemeTransitionProvider: (props: {
|
|
361
|
+
/** Your app tree. */
|
|
229
362
|
children: React.ReactNode
|
|
230
363
|
/**
|
|
231
|
-
* Theme to render on the first frame.
|
|
232
|
-
*
|
|
233
|
-
*
|
|
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
|
|
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
|
-
*
|
|
257
|
-
*
|
|
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
|
+
}
|
package/dist/hooks/useTheme.d.ts
DELETED
|
@@ -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
|