react-native-theme-transition 1.0.2 → 1.0.3
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/LICENSE +9 -9
- package/README.md +111 -113
- package/README.npm.md +111 -0
- package/package.json +90 -87
- package/src/createThemeTransition.ts +92 -92
- package/src/hooks/useTheme.ts +88 -88
- package/src/index.ts +29 -29
- package/src/transitionEngine.tsx +445 -445
- package/src/types.ts +304 -304
package/src/types.ts
CHANGED
|
@@ -1,304 +1,304 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Map of theme token names to color values.
|
|
3
|
-
*
|
|
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).
|
|
8
|
-
*/
|
|
9
|
-
export type ThemeDefinition = Record<string, string>;
|
|
10
|
-
|
|
11
|
-
/**
|
|
12
|
-
* Union of theme names available in a theme configuration.
|
|
13
|
-
*
|
|
14
|
-
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
15
|
-
*/
|
|
16
|
-
export type ThemeNames<T extends Record<string, ThemeDefinition>> =
|
|
17
|
-
keyof T & string;
|
|
18
|
-
|
|
19
|
-
/**
|
|
20
|
-
* Union of token names shared across all themes in a configuration.
|
|
21
|
-
*
|
|
22
|
-
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
23
|
-
*/
|
|
24
|
-
export type TokenNames<T extends Record<string, ThemeDefinition>> =
|
|
25
|
-
keyof T[ThemeNames<T>] & string;
|
|
26
|
-
|
|
27
|
-
/**
|
|
28
|
-
* Maps OS color schemes (`'light'` / `'dark'`) to theme names.
|
|
29
|
-
*
|
|
30
|
-
* @remarks
|
|
31
|
-
* Required when your themes are not named `'light'` and `'dark'`.
|
|
32
|
-
* Both keys must be provided.
|
|
33
|
-
*
|
|
34
|
-
* @typeParam Names - Union of theme name strings.
|
|
35
|
-
*/
|
|
36
|
-
export type SystemThemeMap<Names extends string> =
|
|
37
|
-
Record<'light' | 'dark', Names>;
|
|
38
|
-
|
|
39
|
-
/**
|
|
40
|
-
* Configuration for {@link createThemeTransition}.
|
|
41
|
-
*
|
|
42
|
-
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
43
|
-
*/
|
|
44
|
-
export interface ThemeTransitionConfig<T extends Record<string, ThemeDefinition>> {
|
|
45
|
-
/**
|
|
46
|
-
* All available themes keyed by name.
|
|
47
|
-
*
|
|
48
|
-
* @remarks
|
|
49
|
-
* Every theme must share the exact same token keys. Mismatched keys
|
|
50
|
-
* cause a runtime error at initialization.
|
|
51
|
-
* The name `'system'` is reserved and cannot be used as a theme name.
|
|
52
|
-
*/
|
|
53
|
-
themes: T;
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* Cross-fade duration in milliseconds.
|
|
57
|
-
* @default 350
|
|
58
|
-
*/
|
|
59
|
-
duration?: number;
|
|
60
|
-
|
|
61
|
-
/**
|
|
62
|
-
* Maps OS appearance (`'light'` / `'dark'`) to theme names.
|
|
63
|
-
*
|
|
64
|
-
* @remarks
|
|
65
|
-
* Required when your themes are not named `'light'` and `'dark'`
|
|
66
|
-
* and you want to use `initialTheme="system"` or `setTheme('system')`.
|
|
67
|
-
* Both `light` and `dark` must be provided.
|
|
68
|
-
*/
|
|
69
|
-
systemThemeMap?: SystemThemeMap<ThemeNames<T>>;
|
|
70
|
-
|
|
71
|
-
/**
|
|
72
|
-
* Theme names that use a dark color scheme.
|
|
73
|
-
*
|
|
74
|
-
* @remarks
|
|
75
|
-
* The library automatically calls `Appearance.setColorScheme` to keep
|
|
76
|
-
* native UI elements (alerts, date pickers, keyboards) in sync with
|
|
77
|
-
* the active theme. Themes listed here get `'dark'`; all others get `'light'`.
|
|
78
|
-
* In system mode, `'unspecified'` is used so the OS drives the appearance.
|
|
79
|
-
*
|
|
80
|
-
* **Do not call `Appearance.setColorScheme` yourself** — the library manages
|
|
81
|
-
* it internally. Calling it manually can corrupt state on Android.
|
|
82
|
-
*
|
|
83
|
-
* @default `[systemThemeMap.dark]` if `systemThemeMap` is provided, otherwise `['dark']`.
|
|
84
|
-
*/
|
|
85
|
-
darkThemes?: ThemeNames<T>[];
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* Called when an animated transition begins, before the screenshot capture.
|
|
89
|
-
*
|
|
90
|
-
* @remarks
|
|
91
|
-
* Fires for all animated transitions, including system-driven ones.
|
|
92
|
-
* Does not fire for instant switches (`animated: false`).
|
|
93
|
-
*
|
|
94
|
-
* @param themeName - The target theme name.
|
|
95
|
-
*/
|
|
96
|
-
onTransitionStart?: (themeName: ThemeNames<T>) => void;
|
|
97
|
-
|
|
98
|
-
/**
|
|
99
|
-
* Called after an animated transition completes and the overlay is removed.
|
|
100
|
-
*
|
|
101
|
-
* @remarks
|
|
102
|
-
* Fires for all animated transitions, including system-driven ones.
|
|
103
|
-
* Does not fire for instant switches (`animated: false`).
|
|
104
|
-
*
|
|
105
|
-
* Not called if the screenshot capture fails mid-transition, even when
|
|
106
|
-
* `onTransitionStart` has already fired. In that case the library falls back to an
|
|
107
|
-
* instant switch and only `onThemeChange` fires. Design `onTransitionStart` handlers
|
|
108
|
-
* to be resilient to a missing matching `onTransitionEnd`.
|
|
109
|
-
*
|
|
110
|
-
* @param themeName - The newly active theme name.
|
|
111
|
-
*/
|
|
112
|
-
onTransitionEnd?: (themeName: ThemeNames<T>) => void;
|
|
113
|
-
|
|
114
|
-
/**
|
|
115
|
-
* Called whenever the active theme changes.
|
|
116
|
-
*
|
|
117
|
-
* @remarks
|
|
118
|
-
* Fires for all theme changes: animated transitions, instant switches,
|
|
119
|
-
* and system-driven appearance changes. For animated transitions,
|
|
120
|
-
* fires after `onTransitionEnd`.
|
|
121
|
-
*
|
|
122
|
-
* @param themeName - The newly active theme name.
|
|
123
|
-
*/
|
|
124
|
-
onThemeChange?: (themeName: ThemeNames<T>) => void;
|
|
125
|
-
}
|
|
126
|
-
|
|
127
|
-
/**
|
|
128
|
-
* Options for {@link ThemeTransitionAPI.useTheme | setTheme}.
|
|
129
|
-
*
|
|
130
|
-
* @typeParam Names - Union of theme name strings.
|
|
131
|
-
*/
|
|
132
|
-
export interface SetThemeOptions<Names extends string = string> {
|
|
133
|
-
/**
|
|
134
|
-
* Whether to use the screenshot-overlay cross-fade animation.
|
|
135
|
-
*
|
|
136
|
-
* @remarks
|
|
137
|
-
* When `false`, the theme switches instantly without capturing a screenshot
|
|
138
|
-
* or showing an overlay.
|
|
139
|
-
*
|
|
140
|
-
* @default true
|
|
141
|
-
*/
|
|
142
|
-
animated?: boolean;
|
|
143
|
-
|
|
144
|
-
/**
|
|
145
|
-
* Called when the animated transition begins, before the screenshot capture.
|
|
146
|
-
*
|
|
147
|
-
* @remarks
|
|
148
|
-
* Only called when `animated` is `true` (the default).
|
|
149
|
-
* Fires after the config-level `onTransitionStart` (if provided).
|
|
150
|
-
*
|
|
151
|
-
* @param themeName - The target theme name.
|
|
152
|
-
*/
|
|
153
|
-
onTransitionStart?: (themeName: Names) => void;
|
|
154
|
-
|
|
155
|
-
/**
|
|
156
|
-
* Called after the animated transition completes and the overlay is removed.
|
|
157
|
-
*
|
|
158
|
-
* @remarks
|
|
159
|
-
* Only called when `animated` is `true` (the default).
|
|
160
|
-
* Fires after the config-level `onTransitionEnd` (if provided).
|
|
161
|
-
*
|
|
162
|
-
* Not called if the screenshot capture fails mid-transition, even when
|
|
163
|
-
* `onTransitionStart` has already fired. In that case the library falls back to an
|
|
164
|
-
* instant switch and only `onThemeChange` fires.
|
|
165
|
-
*
|
|
166
|
-
* @param themeName - The newly active theme name.
|
|
167
|
-
*/
|
|
168
|
-
onTransitionEnd?: (themeName: Names) => void;
|
|
169
|
-
}
|
|
170
|
-
|
|
171
|
-
/**
|
|
172
|
-
* Base return type of the {@link ThemeTransitionAPI.useTheme | useTheme} hook.
|
|
173
|
-
*
|
|
174
|
-
* @typeParam Tokens - Union of token name strings.
|
|
175
|
-
* @typeParam Names - Union of theme name strings.
|
|
176
|
-
*/
|
|
177
|
-
export interface UseThemeResult<
|
|
178
|
-
Tokens extends string,
|
|
179
|
-
Names extends string,
|
|
180
|
-
> {
|
|
181
|
-
/** Current resolved color values for all tokens. */
|
|
182
|
-
colors: Record<Tokens, string>;
|
|
183
|
-
/** Name of the currently active theme (resolved, never `'system'`). */
|
|
184
|
-
name: Names;
|
|
185
|
-
/**
|
|
186
|
-
* Switch to a new theme or enter system mode.
|
|
187
|
-
*
|
|
188
|
-
* @param name - Target theme name or `'system'`.
|
|
189
|
-
* @param options - Optional transition configuration.
|
|
190
|
-
* @returns `true` if the theme change was accepted, `false` if rejected
|
|
191
|
-
* (already transitioning or same theme).
|
|
192
|
-
*/
|
|
193
|
-
setTheme: (name: Names | 'system', options?: SetThemeOptions<Names>) => boolean;
|
|
194
|
-
/** `true` while a cross-fade transition overlay is visible. */
|
|
195
|
-
isTransitioning: boolean;
|
|
196
|
-
}
|
|
197
|
-
|
|
198
|
-
/**
|
|
199
|
-
* Selection state returned by {@link ThemeTransitionAPI.useTheme | useTheme}
|
|
200
|
-
* when called with `{ initialSelection }`.
|
|
201
|
-
*
|
|
202
|
-
* @typeParam Names - Union of theme name strings.
|
|
203
|
-
*/
|
|
204
|
-
export interface ThemeSelectionResult<Names extends string> {
|
|
205
|
-
/** The currently selected option (may be `'system'`). */
|
|
206
|
-
selected: Names | 'system';
|
|
207
|
-
/**
|
|
208
|
-
* Select a theme with transition-safe timing.
|
|
209
|
-
*
|
|
210
|
-
* @remarks
|
|
211
|
-
* Updates the selection highlight immediately, then defers `setTheme`
|
|
212
|
-
* to the next animation frame so the selection is painted before
|
|
213
|
-
* the library captures the screenshot. Rapid presses during an
|
|
214
|
-
* ongoing transition are silently ignored.
|
|
215
|
-
*
|
|
216
|
-
* @param option - Theme name or `'system'`.
|
|
217
|
-
*/
|
|
218
|
-
select: (option: Names | 'system') => void;
|
|
219
|
-
}
|
|
220
|
-
|
|
221
|
-
/**
|
|
222
|
-
* Public API returned by {@link createThemeTransition}.
|
|
223
|
-
*
|
|
224
|
-
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
225
|
-
*/
|
|
226
|
-
export interface ThemeTransitionAPI<T extends Record<string, ThemeDefinition>> {
|
|
227
|
-
/**
|
|
228
|
-
* Provider that supplies animated theme colors via context.
|
|
229
|
-
*
|
|
230
|
-
* @remarks
|
|
231
|
-
* Place this as high as possible in the component tree (ideally wrapping
|
|
232
|
-
* navigation) so the screenshot can capture the entire screen.
|
|
233
|
-
*/
|
|
234
|
-
ThemeTransitionProvider: React.FC<{
|
|
235
|
-
children: React.ReactNode;
|
|
236
|
-
/**
|
|
237
|
-
* Theme to render on the first frame.
|
|
238
|
-
*
|
|
239
|
-
* @remarks
|
|
240
|
-
* Pass `'system'` to read the OS appearance synchronously (zero-flash)
|
|
241
|
-
* and subscribe to changes. For custom theme names, provide
|
|
242
|
-
* {@link ThemeTransitionConfig.systemThemeMap | systemThemeMap} in the config.
|
|
243
|
-
*/
|
|
244
|
-
initialTheme: ThemeNames<T> | 'system';
|
|
245
|
-
}>;
|
|
246
|
-
|
|
247
|
-
/**
|
|
248
|
-
* Hook returning the current theme state and transition controls.
|
|
249
|
-
*
|
|
250
|
-
* @remarks
|
|
251
|
-
* **Without arguments** — returns theme colors, name, `setTheme`, and
|
|
252
|
-
* `isTransitioning`. Use this in any component that reads or changes the theme.
|
|
253
|
-
*
|
|
254
|
-
* **With `{ initialSelection }`** — also returns `selected` and `select` for
|
|
255
|
-
* building theme selection UIs (button groups, toggles, checkmark lists) with
|
|
256
|
-
* transition-safe timing. On iOS (especially 120Hz ProMotion), calling
|
|
257
|
-
* `setTheme` synchronously after a UI state update can cause the screenshot
|
|
258
|
-
* to capture the old state, producing visible flickering. The `select`
|
|
259
|
-
* function handles this automatically by deferring `setTheme` to the next
|
|
260
|
-
* animation frame.
|
|
261
|
-
*
|
|
262
|
-
* `initialSelection` sets the starting value of `selected` (read once, like
|
|
263
|
-
* `useState`). When omitted, defaults to the current theme name from context.
|
|
264
|
-
*
|
|
265
|
-
* @throws If called outside a `ThemeTransitionProvider`.
|
|
266
|
-
*
|
|
267
|
-
* @example
|
|
268
|
-
* ```tsx
|
|
269
|
-
* // Reading theme colors in any component
|
|
270
|
-
* const { colors, name } = useTheme();
|
|
271
|
-
* ```
|
|
272
|
-
*
|
|
273
|
-
* @example
|
|
274
|
-
* ```tsx
|
|
275
|
-
* // Building a theme selection UI
|
|
276
|
-
* function ThemePicker() {
|
|
277
|
-
* const { selected, select, colors, isTransitioning } = useTheme({ initialSelection: 'system' });
|
|
278
|
-
* return (
|
|
279
|
-
* <View style={{ flexDirection: 'row', gap: 8 }}>
|
|
280
|
-
* {(['system', 'light', 'dark'] as const).map((option) => (
|
|
281
|
-
* <Pressable
|
|
282
|
-
* key={option}
|
|
283
|
-
* onPress={() => select(option)}
|
|
284
|
-
* disabled={isTransitioning}
|
|
285
|
-
* style={{ backgroundColor: option === selected ? colors.primary : 'transparent' }}
|
|
286
|
-
* >
|
|
287
|
-
* <Text>{option}</Text>
|
|
288
|
-
* </Pressable>
|
|
289
|
-
* ))}
|
|
290
|
-
* </View>
|
|
291
|
-
* );
|
|
292
|
-
* }
|
|
293
|
-
* ```
|
|
294
|
-
*/
|
|
295
|
-
useTheme: {
|
|
296
|
-
/** Returns current theme state and controls. */
|
|
297
|
-
(): UseThemeResult<TokenNames<T>, ThemeNames<T>>;
|
|
298
|
-
/**
|
|
299
|
-
* Returns theme state, controls, and selection tracking with transition-safe timing.
|
|
300
|
-
* @param options.initialSelection - Starting value for `selected`. Defaults to the current theme name.
|
|
301
|
-
*/
|
|
302
|
-
(options: { initialSelection?: ThemeNames<T> | 'system' }): UseThemeResult<TokenNames<T>, ThemeNames<T>> & ThemeSelectionResult<ThemeNames<T>>;
|
|
303
|
-
};
|
|
304
|
-
}
|
|
1
|
+
/**
|
|
2
|
+
* Map of theme token names to color values.
|
|
3
|
+
*
|
|
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).
|
|
8
|
+
*/
|
|
9
|
+
export type ThemeDefinition = Record<string, string>;
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Union of theme names available in a theme configuration.
|
|
13
|
+
*
|
|
14
|
+
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
15
|
+
*/
|
|
16
|
+
export type ThemeNames<T extends Record<string, ThemeDefinition>> =
|
|
17
|
+
keyof T & string;
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Union of token names shared across all themes in a configuration.
|
|
21
|
+
*
|
|
22
|
+
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
23
|
+
*/
|
|
24
|
+
export type TokenNames<T extends Record<string, ThemeDefinition>> =
|
|
25
|
+
keyof T[ThemeNames<T>] & string;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Maps OS color schemes (`'light'` / `'dark'`) to theme names.
|
|
29
|
+
*
|
|
30
|
+
* @remarks
|
|
31
|
+
* Required when your themes are not named `'light'` and `'dark'`.
|
|
32
|
+
* Both keys must be provided.
|
|
33
|
+
*
|
|
34
|
+
* @typeParam Names - Union of theme name strings.
|
|
35
|
+
*/
|
|
36
|
+
export type SystemThemeMap<Names extends string> =
|
|
37
|
+
Record<'light' | 'dark', Names>;
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Configuration for {@link createThemeTransition}.
|
|
41
|
+
*
|
|
42
|
+
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
43
|
+
*/
|
|
44
|
+
export interface ThemeTransitionConfig<T extends Record<string, ThemeDefinition>> {
|
|
45
|
+
/**
|
|
46
|
+
* All available themes keyed by name.
|
|
47
|
+
*
|
|
48
|
+
* @remarks
|
|
49
|
+
* Every theme must share the exact same token keys. Mismatched keys
|
|
50
|
+
* cause a runtime error at initialization.
|
|
51
|
+
* The name `'system'` is reserved and cannot be used as a theme name.
|
|
52
|
+
*/
|
|
53
|
+
themes: T;
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Cross-fade duration in milliseconds.
|
|
57
|
+
* @default 350
|
|
58
|
+
*/
|
|
59
|
+
duration?: number;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Maps OS appearance (`'light'` / `'dark'`) to theme names.
|
|
63
|
+
*
|
|
64
|
+
* @remarks
|
|
65
|
+
* Required when your themes are not named `'light'` and `'dark'`
|
|
66
|
+
* and you want to use `initialTheme="system"` or `setTheme('system')`.
|
|
67
|
+
* Both `light` and `dark` must be provided.
|
|
68
|
+
*/
|
|
69
|
+
systemThemeMap?: SystemThemeMap<ThemeNames<T>>;
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Theme names that use a dark color scheme.
|
|
73
|
+
*
|
|
74
|
+
* @remarks
|
|
75
|
+
* The library automatically calls `Appearance.setColorScheme` to keep
|
|
76
|
+
* native UI elements (alerts, date pickers, keyboards) in sync with
|
|
77
|
+
* the active theme. Themes listed here get `'dark'`; all others get `'light'`.
|
|
78
|
+
* In system mode, `'unspecified'` is used so the OS drives the appearance.
|
|
79
|
+
*
|
|
80
|
+
* **Do not call `Appearance.setColorScheme` yourself** — the library manages
|
|
81
|
+
* it internally. Calling it manually can corrupt state on Android.
|
|
82
|
+
*
|
|
83
|
+
* @default `[systemThemeMap.dark]` if `systemThemeMap` is provided, otherwise `['dark']`.
|
|
84
|
+
*/
|
|
85
|
+
darkThemes?: ThemeNames<T>[];
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Called when an animated transition begins, before the screenshot capture.
|
|
89
|
+
*
|
|
90
|
+
* @remarks
|
|
91
|
+
* Fires for all animated transitions, including system-driven ones.
|
|
92
|
+
* Does not fire for instant switches (`animated: false`).
|
|
93
|
+
*
|
|
94
|
+
* @param themeName - The target theme name.
|
|
95
|
+
*/
|
|
96
|
+
onTransitionStart?: (themeName: ThemeNames<T>) => void;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Called after an animated transition completes and the overlay is removed.
|
|
100
|
+
*
|
|
101
|
+
* @remarks
|
|
102
|
+
* Fires for all animated transitions, including system-driven ones.
|
|
103
|
+
* Does not fire for instant switches (`animated: false`).
|
|
104
|
+
*
|
|
105
|
+
* Not called if the screenshot capture fails mid-transition, even when
|
|
106
|
+
* `onTransitionStart` has already fired. In that case the library falls back to an
|
|
107
|
+
* instant switch and only `onThemeChange` fires. Design `onTransitionStart` handlers
|
|
108
|
+
* to be resilient to a missing matching `onTransitionEnd`.
|
|
109
|
+
*
|
|
110
|
+
* @param themeName - The newly active theme name.
|
|
111
|
+
*/
|
|
112
|
+
onTransitionEnd?: (themeName: ThemeNames<T>) => void;
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Called whenever the active theme changes.
|
|
116
|
+
*
|
|
117
|
+
* @remarks
|
|
118
|
+
* Fires for all theme changes: animated transitions, instant switches,
|
|
119
|
+
* and system-driven appearance changes. For animated transitions,
|
|
120
|
+
* fires after `onTransitionEnd`.
|
|
121
|
+
*
|
|
122
|
+
* @param themeName - The newly active theme name.
|
|
123
|
+
*/
|
|
124
|
+
onThemeChange?: (themeName: ThemeNames<T>) => void;
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Options for {@link ThemeTransitionAPI.useTheme | setTheme}.
|
|
129
|
+
*
|
|
130
|
+
* @typeParam Names - Union of theme name strings.
|
|
131
|
+
*/
|
|
132
|
+
export interface SetThemeOptions<Names extends string = string> {
|
|
133
|
+
/**
|
|
134
|
+
* Whether to use the screenshot-overlay cross-fade animation.
|
|
135
|
+
*
|
|
136
|
+
* @remarks
|
|
137
|
+
* When `false`, the theme switches instantly without capturing a screenshot
|
|
138
|
+
* or showing an overlay.
|
|
139
|
+
*
|
|
140
|
+
* @default true
|
|
141
|
+
*/
|
|
142
|
+
animated?: boolean;
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Called when the animated transition begins, before the screenshot capture.
|
|
146
|
+
*
|
|
147
|
+
* @remarks
|
|
148
|
+
* Only called when `animated` is `true` (the default).
|
|
149
|
+
* Fires after the config-level `onTransitionStart` (if provided).
|
|
150
|
+
*
|
|
151
|
+
* @param themeName - The target theme name.
|
|
152
|
+
*/
|
|
153
|
+
onTransitionStart?: (themeName: Names) => void;
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Called after the animated transition completes and the overlay is removed.
|
|
157
|
+
*
|
|
158
|
+
* @remarks
|
|
159
|
+
* Only called when `animated` is `true` (the default).
|
|
160
|
+
* Fires after the config-level `onTransitionEnd` (if provided).
|
|
161
|
+
*
|
|
162
|
+
* Not called if the screenshot capture fails mid-transition, even when
|
|
163
|
+
* `onTransitionStart` has already fired. In that case the library falls back to an
|
|
164
|
+
* instant switch and only `onThemeChange` fires.
|
|
165
|
+
*
|
|
166
|
+
* @param themeName - The newly active theme name.
|
|
167
|
+
*/
|
|
168
|
+
onTransitionEnd?: (themeName: Names) => void;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* Base return type of the {@link ThemeTransitionAPI.useTheme | useTheme} hook.
|
|
173
|
+
*
|
|
174
|
+
* @typeParam Tokens - Union of token name strings.
|
|
175
|
+
* @typeParam Names - Union of theme name strings.
|
|
176
|
+
*/
|
|
177
|
+
export interface UseThemeResult<
|
|
178
|
+
Tokens extends string,
|
|
179
|
+
Names extends string,
|
|
180
|
+
> {
|
|
181
|
+
/** Current resolved color values for all tokens. */
|
|
182
|
+
colors: Record<Tokens, string>;
|
|
183
|
+
/** Name of the currently active theme (resolved, never `'system'`). */
|
|
184
|
+
name: Names;
|
|
185
|
+
/**
|
|
186
|
+
* Switch to a new theme or enter system mode.
|
|
187
|
+
*
|
|
188
|
+
* @param name - Target theme name or `'system'`.
|
|
189
|
+
* @param options - Optional transition configuration.
|
|
190
|
+
* @returns `true` if the theme change was accepted, `false` if rejected
|
|
191
|
+
* (already transitioning or same theme).
|
|
192
|
+
*/
|
|
193
|
+
setTheme: (name: Names | 'system', options?: SetThemeOptions<Names>) => boolean;
|
|
194
|
+
/** `true` while a cross-fade transition overlay is visible. */
|
|
195
|
+
isTransitioning: boolean;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Selection state returned by {@link ThemeTransitionAPI.useTheme | useTheme}
|
|
200
|
+
* when called with `{ initialSelection }`.
|
|
201
|
+
*
|
|
202
|
+
* @typeParam Names - Union of theme name strings.
|
|
203
|
+
*/
|
|
204
|
+
export interface ThemeSelectionResult<Names extends string> {
|
|
205
|
+
/** The currently selected option (may be `'system'`). */
|
|
206
|
+
selected: Names | 'system';
|
|
207
|
+
/**
|
|
208
|
+
* Select a theme with transition-safe timing.
|
|
209
|
+
*
|
|
210
|
+
* @remarks
|
|
211
|
+
* Updates the selection highlight immediately, then defers `setTheme`
|
|
212
|
+
* to the next animation frame so the selection is painted before
|
|
213
|
+
* the library captures the screenshot. Rapid presses during an
|
|
214
|
+
* ongoing transition are silently ignored.
|
|
215
|
+
*
|
|
216
|
+
* @param option - Theme name or `'system'`.
|
|
217
|
+
*/
|
|
218
|
+
select: (option: Names | 'system') => void;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/**
|
|
222
|
+
* Public API returned by {@link createThemeTransition}.
|
|
223
|
+
*
|
|
224
|
+
* @typeParam T - Your application's theme map, keyed by theme name.
|
|
225
|
+
*/
|
|
226
|
+
export interface ThemeTransitionAPI<T extends Record<string, ThemeDefinition>> {
|
|
227
|
+
/**
|
|
228
|
+
* Provider that supplies animated theme colors via context.
|
|
229
|
+
*
|
|
230
|
+
* @remarks
|
|
231
|
+
* Place this as high as possible in the component tree (ideally wrapping
|
|
232
|
+
* navigation) so the screenshot can capture the entire screen.
|
|
233
|
+
*/
|
|
234
|
+
ThemeTransitionProvider: React.FC<{
|
|
235
|
+
children: React.ReactNode;
|
|
236
|
+
/**
|
|
237
|
+
* Theme to render on the first frame.
|
|
238
|
+
*
|
|
239
|
+
* @remarks
|
|
240
|
+
* Pass `'system'` to read the OS appearance synchronously (zero-flash)
|
|
241
|
+
* and subscribe to changes. For custom theme names, provide
|
|
242
|
+
* {@link ThemeTransitionConfig.systemThemeMap | systemThemeMap} in the config.
|
|
243
|
+
*/
|
|
244
|
+
initialTheme: ThemeNames<T> | 'system';
|
|
245
|
+
}>;
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* Hook returning the current theme state and transition controls.
|
|
249
|
+
*
|
|
250
|
+
* @remarks
|
|
251
|
+
* **Without arguments** — returns theme colors, name, `setTheme`, and
|
|
252
|
+
* `isTransitioning`. Use this in any component that reads or changes the theme.
|
|
253
|
+
*
|
|
254
|
+
* **With `{ initialSelection }`** — also returns `selected` and `select` for
|
|
255
|
+
* building theme selection UIs (button groups, toggles, checkmark lists) with
|
|
256
|
+
* transition-safe timing. On iOS (especially 120Hz ProMotion), calling
|
|
257
|
+
* `setTheme` synchronously after a UI state update can cause the screenshot
|
|
258
|
+
* to capture the old state, producing visible flickering. The `select`
|
|
259
|
+
* function handles this automatically by deferring `setTheme` to the next
|
|
260
|
+
* animation frame.
|
|
261
|
+
*
|
|
262
|
+
* `initialSelection` sets the starting value of `selected` (read once, like
|
|
263
|
+
* `useState`). When omitted, defaults to the current theme name from context.
|
|
264
|
+
*
|
|
265
|
+
* @throws If called outside a `ThemeTransitionProvider`.
|
|
266
|
+
*
|
|
267
|
+
* @example
|
|
268
|
+
* ```tsx
|
|
269
|
+
* // Reading theme colors in any component
|
|
270
|
+
* const { colors, name } = useTheme();
|
|
271
|
+
* ```
|
|
272
|
+
*
|
|
273
|
+
* @example
|
|
274
|
+
* ```tsx
|
|
275
|
+
* // Building a theme selection UI
|
|
276
|
+
* function ThemePicker() {
|
|
277
|
+
* const { selected, select, colors, isTransitioning } = useTheme({ initialSelection: 'system' });
|
|
278
|
+
* return (
|
|
279
|
+
* <View style={{ flexDirection: 'row', gap: 8 }}>
|
|
280
|
+
* {(['system', 'light', 'dark'] as const).map((option) => (
|
|
281
|
+
* <Pressable
|
|
282
|
+
* key={option}
|
|
283
|
+
* onPress={() => select(option)}
|
|
284
|
+
* disabled={isTransitioning}
|
|
285
|
+
* style={{ backgroundColor: option === selected ? colors.primary : 'transparent' }}
|
|
286
|
+
* >
|
|
287
|
+
* <Text>{option}</Text>
|
|
288
|
+
* </Pressable>
|
|
289
|
+
* ))}
|
|
290
|
+
* </View>
|
|
291
|
+
* );
|
|
292
|
+
* }
|
|
293
|
+
* ```
|
|
294
|
+
*/
|
|
295
|
+
useTheme: {
|
|
296
|
+
/** Returns current theme state and controls. */
|
|
297
|
+
(): UseThemeResult<TokenNames<T>, ThemeNames<T>>;
|
|
298
|
+
/**
|
|
299
|
+
* Returns theme state, controls, and selection tracking with transition-safe timing.
|
|
300
|
+
* @param options.initialSelection - Starting value for `selected`. Defaults to the current theme name.
|
|
301
|
+
*/
|
|
302
|
+
(options: { initialSelection?: ThemeNames<T> | 'system' }): UseThemeResult<TokenNames<T>, ThemeNames<T>> & ThemeSelectionResult<ThemeNames<T>>;
|
|
303
|
+
};
|
|
304
|
+
}
|