react-native-theme-transition 1.0.5 → 1.0.7

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.
@@ -9,33 +9,37 @@
9
9
  * @module
10
10
  */
11
11
 
12
- import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
13
- import { Appearance, AppState, Image, View } from 'react-native';
14
- import Animated, {
15
- useAnimatedProps,
16
- useSharedValue,
17
- withTiming,
18
- } from 'react-native-reanimated';
19
- import { captureRef } from 'react-native-view-shot';
20
- import { scheduleOnRN } from 'react-native-worklets';
12
+ import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react'
13
+ import { Appearance, AppState, Image, View } from 'react-native'
14
+ import Animated, { useAnimatedProps, useSharedValue, withTiming } from 'react-native-reanimated'
15
+ import { captureRef } from 'react-native-view-shot'
16
+ import { scheduleOnRN } from 'react-native-worklets'
17
+ import { TAG } from './constants'
21
18
  import type {
22
- ThemeTransitionConfig,
23
- UseThemeResult,
24
19
  SetThemeOptions,
25
20
  SystemThemeMap,
26
21
  ThemeDefinition,
27
22
  ThemeNames,
23
+ ThemeTransitionConfig,
28
24
  TokenNames,
29
- } from './types';
30
- import { TAG } from './constants';
25
+ UseThemeResult,
26
+ } from './types'
31
27
 
32
- const ABSOLUTE_FILL = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 } as const;
28
+ const ABSOLUTE_FILL = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 } as const
33
29
  // Avoids layout clipping on certain Android API levels.
34
- const ROOT_STYLE = { flex: 1 } as const;
30
+ const ROOT_STYLE = { flex: 1 } as const
35
31
 
36
32
  /** Calls `fn` and swallows errors with a console.warn tagged by `label`. */
37
- function safeCall<A extends unknown[]>(label: string, fn: ((...args: A) => void) | undefined, ...args: A): void {
38
- try { fn?.(...args); } catch (e) { console.warn(`${TAG} ${label} threw:`, e); }
33
+ function safeCall<A extends unknown[]>(
34
+ label: string,
35
+ fn: ((...args: A) => void) | undefined,
36
+ ...args: A
37
+ ): void {
38
+ try {
39
+ fn?.(...args)
40
+ } catch (e) {
41
+ console.warn(`${TAG} ${label} threw:`, e)
42
+ }
39
43
  }
40
44
 
41
45
  /**
@@ -55,13 +59,13 @@ function safeCall<A extends unknown[]>(label: string, fn: ((...args: A) => void)
55
59
  */
56
60
  function waitFrames(n: number): Promise<void> {
57
61
  return new Promise((resolve) => {
58
- let remaining = n;
62
+ let remaining = n
59
63
  const tick = () => {
60
- if (--remaining <= 0) resolve();
61
- else requestAnimationFrame(tick);
62
- };
63
- requestAnimationFrame(tick);
64
- });
64
+ if (--remaining <= 0) resolve()
65
+ else requestAnimationFrame(tick)
66
+ }
67
+ requestAnimationFrame(tick)
68
+ })
65
69
  }
66
70
 
67
71
  /**
@@ -74,10 +78,13 @@ function waitFrames(n: number): Promise<void> {
74
78
  *
75
79
  * @internal
76
80
  */
77
- function normalizeScheme(colorScheme?: string | null, fallback: 'light' | 'dark' = 'light'): 'light' | 'dark' {
78
- if (colorScheme === 'dark') return 'dark';
79
- if (colorScheme === 'light') return 'light';
80
- return fallback;
81
+ function normalizeScheme(
82
+ colorScheme?: string | null,
83
+ fallback: 'light' | 'dark' = 'light',
84
+ ): 'light' | 'dark' {
85
+ if (colorScheme === 'dark') return 'dark'
86
+ if (colorScheme === 'light') return 'light'
87
+ return fallback
81
88
  }
82
89
 
83
90
  /**
@@ -96,7 +103,7 @@ function mapSchemeToTheme<Names extends string>(
96
103
  scheme: 'light' | 'dark',
97
104
  mapping?: SystemThemeMap<Names>,
98
105
  ): Names {
99
- return mapping?.[scheme] ?? (scheme as Names);
106
+ return mapping?.[scheme] ?? (scheme as Names)
100
107
  }
101
108
 
102
109
  /**
@@ -108,7 +115,10 @@ function resolveSystemTheme<Names extends string>(
108
115
  mapping?: SystemThemeMap<Names>,
109
116
  fallbackScheme?: 'light' | 'dark',
110
117
  ): Names {
111
- return mapSchemeToTheme<Names>(normalizeScheme(Appearance.getColorScheme(), fallbackScheme), mapping);
118
+ return mapSchemeToTheme<Names>(
119
+ normalizeScheme(Appearance.getColorScheme(), fallbackScheme),
120
+ mapping,
121
+ )
112
122
  }
113
123
 
114
124
  /**
@@ -116,334 +126,372 @@ function resolveSystemTheme<Names extends string>(
116
126
  *
117
127
  * @internal Used by {@link createThemeTransition}; not part of the public API.
118
128
  */
119
- export function createProviderAndContext<
120
- T extends Record<string, ThemeDefinition>,
121
- >(config: ThemeTransitionConfig<T>) {
129
+ export function createProviderAndContext<T extends Record<string, ThemeDefinition>>(
130
+ config: ThemeTransitionConfig<T>,
131
+ ) {
122
132
  const {
123
- themes, duration = 350, systemThemeMap, darkThemes: darkThemesConfig,
133
+ themes,
134
+ duration = 350,
135
+ systemThemeMap,
136
+ darkThemes: darkThemesConfig,
124
137
  onTransitionStart: configOnTransitionStart,
125
138
  onTransitionEnd: configOnTransitionEnd,
126
139
  onThemeChange,
127
- } = config;
140
+ } = config
128
141
 
129
142
  const darkThemeSet = new Set<string>(
130
143
  darkThemesConfig ?? (systemThemeMap ? [systemThemeMap.dark] : ['dark']),
131
- );
144
+ )
132
145
 
133
- const schemeOf = (name: string): 'light' | 'dark' => darkThemeSet.has(name) ? 'dark' : 'light';
146
+ const schemeOf = (name: string): 'light' | 'dark' => (darkThemeSet.has(name) ? 'dark' : 'light')
134
147
 
135
- type Names = ThemeNames<T>;
136
- type Tokens = TokenNames<T>;
148
+ type Names = ThemeNames<T>
149
+ type Tokens = TokenNames<T>
137
150
 
138
- const Context = createContext<UseThemeResult<Tokens, Names> | null>(null);
151
+ const Context = createContext<UseThemeResult<Tokens, Names> | null>(null)
139
152
 
140
153
  function getColors(name: Names): Record<Tokens, string> {
141
- return { ...themes[name] } as Record<Tokens, string>;
154
+ return { ...themes[name] } as Record<Tokens, string>
142
155
  }
143
156
 
144
157
  function ThemeTransitionProvider({
145
158
  children,
146
159
  initialTheme,
147
160
  }: {
148
- children: React.ReactNode;
149
- initialTheme: Names | 'system';
161
+ children: React.ReactNode
162
+ initialTheme: Names | 'system'
150
163
  }) {
151
- const [activeTheme, setActiveTheme] = useState<{ colors: Record<Tokens, string>; name: Names }>(() => {
152
- const isInitialSystem = initialTheme === 'system';
153
- const startTheme = isInitialSystem
154
- ? resolveSystemTheme<Names>(systemThemeMap)
155
- : initialTheme;
156
-
157
- if (!(startTheme in themes)) {
158
- throw new Error(
159
- `${TAG} initialTheme resolved to "${startTheme}" which does not exist in themes.${
160
- isInitialSystem ? ' Provide `systemThemeMap` in the config to map OS appearance to your theme names.' : ''
161
- }`,
162
- );
163
- }
164
+ const [activeTheme, setActiveTheme] = useState<{ colors: Record<Tokens, string>; name: Names }>(
165
+ () => {
166
+ const isInitialSystem = initialTheme === 'system'
167
+ const startTheme = isInitialSystem
168
+ ? resolveSystemTheme<Names>(systemThemeMap)
169
+ : initialTheme
170
+
171
+ if (!(startTheme in themes)) {
172
+ throw new Error(
173
+ `${TAG} initialTheme resolved to "${startTheme}" which does not exist in themes.${
174
+ isInitialSystem
175
+ ? ' Provide `systemThemeMap` in the config to map OS appearance to your theme names.'
176
+ : ''
177
+ }`,
178
+ )
179
+ }
164
180
 
165
- return { colors: getColors(startTheme), name: startTheme };
166
- });
181
+ return { colors: getColors(startTheme), name: startTheme }
182
+ },
183
+ )
167
184
 
168
- const targetThemeRef = useRef(activeTheme.name);
169
- const rootRef = useRef<View>(null);
170
- const transitioningRef = useRef(false);
185
+ const targetThemeRef = useRef(activeTheme.name)
186
+ const rootRef = useRef<View>(null)
187
+ const transitioningRef = useRef(false)
171
188
  // Guards async callbacks against running after unmount.
172
- const mountedRef = useRef(true);
173
- const [isTransitioning, setIsTransitioning] = useState(false);
189
+ const mountedRef = useRef(true)
190
+ const [isTransitioning, setIsTransitioning] = useState(false)
174
191
 
175
- const systemModeRef = useRef(initialTheme === 'system');
192
+ const systemModeRef = useRef(initialTheme === 'system')
176
193
  // State mirror of systemModeRef — drives the Appearance.setColorScheme effect.
177
- const [isSystemMode, setIsSystemMode] = useState(initialTheme === 'system');
178
- const appStateRef = useRef(AppState.currentState);
179
- // Pending OS scheme change that arrived mid-transition. Applied by finishTransition.
180
- const pendingSchemeRef = useRef<'light' | 'dark' | null>(null);
181
- // Last observed OS scheme — lets manual→system resolve without calling
182
- // setColorScheme('unspecified') (which flashes the Android status bar).
194
+ const [isSystemMode, setIsSystemMode] = useState(initialTheme === 'system')
195
+ const appStateRef = useRef(AppState.currentState)
196
+ // OS scheme change that arrived while the overlay was animating.
197
+ const pendingSchemeRef = useRef<'light' | 'dark' | null>(null)
198
+ // Avoids calling setColorScheme('unspecified') pre-overlay (Android status bar flash).
183
199
  const lastKnownOsSchemeRef = useRef<'light' | 'dark'>(
184
200
  normalizeScheme(Appearance.getColorScheme()),
185
- );
186
- // Manual override scheme while a deferred setColorScheme('unspecified') is pending.
187
- // finishTransition uses this to correct the theme if the OS scheme diverged.
188
- const deferredSystemRestoreRef = useRef<'light' | 'dark' | null>(null);
201
+ )
202
+ // Non-null while setColorScheme('unspecified') is deferred behind the overlay.
203
+ const deferredSystemRestoreRef = useRef<'light' | 'dark' | null>(null)
189
204
 
190
205
  // SharedValue (not state) so touch blocking takes effect on the native thread
191
206
  // within one frame, without waiting for a React re-render cycle.
192
- const isBlocking = useSharedValue(false);
207
+ const isBlocking = useSharedValue(false)
193
208
  const blockerProps = useAnimatedProps(() => ({
194
- pointerEvents: isBlocking.value ? 'auto' as const : 'none' as const,
195
- }));
209
+ pointerEvents: isBlocking.value ? ('auto' as const) : ('none' as const),
210
+ }))
196
211
 
197
212
  // State (not ref) so unsetting it unmounts the Image, freeing the captured bitmap.
198
- const [overlayUri, setOverlayUri] = useState<string | null>(null);
199
- const overlayOpacity = useSharedValue(0);
213
+ const [overlayUri, setOverlayUri] = useState<string | null>(null)
214
+ const overlayOpacity = useSharedValue(0)
200
215
  // Stable ref so Reanimated doesn't re-process the style on every render.
201
- const overlayStyle = useMemo(() => ({ opacity: overlayOpacity }), [overlayOpacity]);
202
- const overlayDecodeRef = useRef<{ resolve: () => void; reject: () => void } | null>(null);
203
- const overlaySource = useMemo(() => overlayUri ? { uri: overlayUri } : undefined, [overlayUri]);
216
+ const overlayStyle = useMemo(() => ({ opacity: overlayOpacity }), [overlayOpacity])
217
+ const overlayDecodeRef = useRef<{ resolve: () => void; reject: () => void } | null>(null)
218
+ const overlaySource = useMemo(
219
+ () => (overlayUri ? { uri: overlayUri } : undefined),
220
+ [overlayUri],
221
+ )
204
222
  const onOverlayLoad = useCallback(() => {
205
- overlayDecodeRef.current?.resolve();
206
- }, []);
223
+ overlayDecodeRef.current?.resolve()
224
+ }, [])
207
225
  const onOverlayError = useCallback(() => {
208
- overlayDecodeRef.current?.reject();
209
- }, []);
226
+ overlayDecodeRef.current?.reject()
227
+ }, [])
210
228
 
211
229
  useEffect(() => {
212
- mountedRef.current = true;
230
+ mountedRef.current = true
213
231
  return () => {
214
- mountedRef.current = false;
215
- };
216
- }, []);
232
+ mountedRef.current = false
233
+ }
234
+ }, [])
217
235
 
218
- // Sync native UI (alerts, keyboards) with theme. Skipped in system mode
219
- // where the OS drives appearance via 'unspecified'.
236
+ // Keeps native Appearance (alerts, keyboards, status bar) in sync with mode.
220
237
  useEffect(() => {
221
- if (isSystemMode) return;
222
- if (isTransitioning) return;
223
- Appearance.setColorScheme(schemeOf(activeTheme.name));
224
- }, [isSystemMode, activeTheme.name, isTransitioning]);
238
+ if (isSystemMode) {
239
+ // Explicit mode masks the real OS scheme from the Appearance listener.
240
+ if (!transitioningRef.current) {
241
+ deferredSystemRestoreRef.current = null
242
+ Appearance.setColorScheme('unspecified')
243
+ }
244
+ return
245
+ }
246
+ if (isTransitioning) return
247
+ Appearance.setColorScheme(schemeOf(activeTheme.name))
248
+ }, [isSystemMode, activeTheme.name, isTransitioning])
225
249
 
226
250
  const resetTransition = useCallback(() => {
227
- transitioningRef.current = false;
228
- isBlocking.value = false;
229
- setIsTransitioning(false);
230
- setOverlayUri(null);
231
- }, [isBlocking]);
232
-
233
- const runTransition = useCallback(async (initialName: Names, options?: SetThemeOptions<Names>) => {
234
- let name: Names = initialName;
235
- try {
236
- // 2 frames for JS → Shadow Tree → Native UI to paint before capture.
237
- // useTheme's requestAnimationFrame adds a 3rd — enough for 120Hz.
238
- await waitFrames(2);
239
- if (!mountedRef.current) return;
240
-
241
- // jpg 0.8: ~30% smaller than png, no visible degradation during a cross-fade.
242
- const uri = await captureRef(rootRef, { format: 'jpg', quality: 0.8 });
243
- if (!mountedRef.current) return;
244
-
245
- overlayOpacity.set(1);
246
-
247
- await new Promise<void>((resolve, reject) => {
248
- overlayDecodeRef.current = { resolve, reject };
249
- setOverlayUri(uri);
250
- });
251
- if (!mountedRef.current) return;
252
-
253
- await waitFrames(1);
254
- if (!mountedRef.current) return;
255
-
256
- // Deferred: setting this earlier would re-render under the overlay,
257
- // flashing state-dependent visuals before the screenshot hides them.
258
- setIsTransitioning(true);
259
-
260
- setActiveTheme({ colors: getColors(name), name });
261
-
262
- // Deferred setColorScheme('unspecified') — done now while the overlay is
263
- // opaque so any theme correction (OS scheme diverged) is invisible to the user.
264
- if (deferredSystemRestoreRef.current !== null) {
265
- const manualScheme = deferredSystemRestoreRef.current;
266
-
267
- let resolved = false;
268
- const realScheme = await new Promise<'light' | 'dark'>((resolve) => {
269
- const sub = Appearance.addChangeListener(({ colorScheme }) => {
270
- if (resolved) return;
271
- resolved = true;
272
- sub.remove();
273
- resolve(normalizeScheme(colorScheme));
274
- });
275
- Appearance.setColorScheme('unspecified');
276
- // No event → OS scheme already matches the manual override.
277
- requestAnimationFrame(() => {
278
- if (resolved) return;
279
- resolved = true;
280
- sub.remove();
281
- resolve(manualScheme);
282
- });
283
- });
284
- if (!mountedRef.current) return;
285
-
286
- deferredSystemRestoreRef.current = null;
287
- lastKnownOsSchemeRef.current = realScheme;
288
-
289
- const corrected = mapSchemeToTheme<Names>(realScheme, systemThemeMap);
290
- if (corrected in themes && corrected !== name) {
291
- name = corrected as Names;
292
- targetThemeRef.current = corrected;
293
- setActiveTheme({ colors: getColors(corrected), name: corrected });
251
+ transitioningRef.current = false
252
+ isBlocking.value = false
253
+ setIsTransitioning(false)
254
+ setOverlayUri(null)
255
+ }, [isBlocking])
256
+
257
+ const runTransition = useCallback(
258
+ async (initialName: Names, options?: SetThemeOptions<Names>) => {
259
+ let name: Names = initialName
260
+ try {
261
+ // 2 frames for JS → Shadow Tree → Native UI to paint before capture.
262
+ // useTheme's requestAnimationFrame adds a 3rd — enough for 120Hz.
263
+ await waitFrames(2)
264
+ if (!mountedRef.current) return
265
+
266
+ // jpg 0.8: ~30% smaller than png, no visible degradation during a cross-fade.
267
+ const uri = await captureRef(rootRef, { format: 'jpg', quality: 0.8 })
268
+ if (!mountedRef.current) return
269
+
270
+ overlayOpacity.set(1)
271
+
272
+ await new Promise<void>((resolve, reject) => {
273
+ overlayDecodeRef.current = { resolve, reject }
274
+ setOverlayUri(uri)
275
+ })
276
+ if (!mountedRef.current) return
277
+
278
+ await waitFrames(1)
279
+ if (!mountedRef.current) return
280
+
281
+ // Deferred: setting this earlier would re-render under the overlay,
282
+ // flashing state-dependent visuals before the screenshot hides them.
283
+ setIsTransitioning(true)
284
+
285
+ setActiveTheme({ colors: getColors(name), name })
286
+
287
+ // Deferred setColorScheme('unspecified') — done now while the overlay is
288
+ // opaque so any theme correction (OS scheme diverged) is invisible to the user.
289
+ if (deferredSystemRestoreRef.current !== null) {
290
+ const manualScheme = deferredSystemRestoreRef.current
291
+
292
+ let resolved = false
293
+ const realScheme = await new Promise<'light' | 'dark'>((resolve) => {
294
+ const sub = Appearance.addChangeListener(({ colorScheme }) => {
295
+ if (resolved) return
296
+ resolved = true
297
+ sub.remove()
298
+ resolve(normalizeScheme(colorScheme))
299
+ })
300
+ Appearance.setColorScheme('unspecified')
301
+ // No event → OS scheme already matches the manual override.
302
+ requestAnimationFrame(() => {
303
+ if (resolved) return
304
+ resolved = true
305
+ sub.remove()
306
+ resolve(manualScheme)
307
+ })
308
+ })
309
+ if (!mountedRef.current) return
310
+
311
+ deferredSystemRestoreRef.current = null
312
+ lastKnownOsSchemeRef.current = realScheme
313
+
314
+ const corrected = mapSchemeToTheme<Names>(realScheme, systemThemeMap)
315
+ if (corrected in themes && corrected !== name) {
316
+ name = corrected as Names
317
+ targetThemeRef.current = corrected
318
+ setActiveTheme({ colors: getColors(corrected), name: corrected })
319
+ }
294
320
  }
295
- }
296
321
 
297
- await waitFrames(1);
298
- if (!mountedRef.current) return;
299
-
300
- const finishTransition = () => {
301
- if (!mountedRef.current) return;
302
- resetTransition();
303
- safeCall('config onTransitionEnd', configOnTransitionEnd, name);
304
- safeCall('per-call onTransitionEnd', options?.onTransitionEnd, name);
305
- safeCall('config onThemeChange', onThemeChange, name);
306
-
307
- // Apply any OS scheme change that arrived mid-transition.
308
- if (systemModeRef.current && pendingSchemeRef.current !== null) {
309
- const resolved = mapSchemeToTheme<Names>(pendingSchemeRef.current, systemThemeMap);
310
- pendingSchemeRef.current = null;
311
- if (resolved in themes && resolved !== name) {
312
- targetThemeRef.current = resolved;
313
- setActiveTheme({ colors: getColors(resolved), name: resolved });
314
- safeCall('config onThemeChange', onThemeChange, resolved);
322
+ await waitFrames(1)
323
+ if (!mountedRef.current) return
324
+
325
+ const finishTransition = () => {
326
+ if (!mountedRef.current) return
327
+ resetTransition()
328
+ safeCall('config onTransitionEnd', configOnTransitionEnd, name)
329
+ safeCall('per-call onTransitionEnd', options?.onTransitionEnd, name)
330
+ safeCall('config onThemeChange', onThemeChange, name)
331
+
332
+ // OS may have changed while the overlay was up.
333
+ if (systemModeRef.current && pendingSchemeRef.current !== null) {
334
+ const resolved = mapSchemeToTheme<Names>(pendingSchemeRef.current, systemThemeMap)
335
+ pendingSchemeRef.current = null
336
+ if (resolved in themes && resolved !== name) {
337
+ targetThemeRef.current = resolved
338
+ setActiveTheme({ colors: getColors(resolved), name: resolved })
339
+ safeCall('config onThemeChange', onThemeChange, resolved)
340
+ }
315
341
  }
316
342
  }
317
- };
318
-
319
- overlayOpacity.set(withTiming(0, { duration }, (finished) => {
320
- 'worklet';
321
- if (finished) scheduleOnRN(finishTransition);
322
- }));
323
- } catch (error) {
324
- // If capture fails, apply theme instantly — no animation beats a stuck overlay.
325
- console.warn(
326
- `${TAG} Failed to capture screenshot. Falling back to instant theme switch.`,
327
- error,
328
- );
329
- if (!mountedRef.current) return;
330
- setActiveTheme({ colors: getColors(name), name });
331
- overlayOpacity.set(0);
332
- resetTransition();
333
- safeCall('config onThemeChange', onThemeChange, name);
334
- }
335
- }, [overlayOpacity, resetTransition]);
336
-
337
- const setTheme = useCallback((name: Names | 'system', options?: SetThemeOptions<Names>): boolean => {
338
- // Manual→system: resolve from cached OS scheme to avoid the Android
339
- // status bar flash that setColorScheme('unspecified') causes pre-overlay.
340
- if (name === 'system' && !systemModeRef.current) {
341
- if (transitioningRef.current) return false;
342
-
343
- setIsSystemMode(true);
344
- systemModeRef.current = true;
345
- deferredSystemRestoreRef.current = schemeOf(targetThemeRef.current);
346
- return setTheme('system', options);
347
- }
348
343
 
349
- const resolvedTheme = name === 'system'
350
- ? mapSchemeToTheme<Names>(lastKnownOsSchemeRef.current, systemThemeMap)
351
- : name;
352
- if (!(resolvedTheme in themes)) {
353
- const resolutionHint = name === 'system'
354
- ? ' Provide `systemThemeMap` in the config to map OS appearance to your theme names.'
355
- : '';
356
- throw new Error(
357
- `${TAG} setTheme("${name}") resolved to "${resolvedTheme}" which does not exist in themes.${resolutionHint}`,
358
- );
359
- }
344
+ overlayOpacity.set(
345
+ withTiming(0, { duration }, (finished) => {
346
+ 'worklet'
347
+ if (finished) scheduleOnRN(finishTransition)
348
+ }),
349
+ )
350
+ } catch (error) {
351
+ // If capture fails, apply theme instantly — no animation beats a stuck overlay.
352
+ console.warn(
353
+ `${TAG} Failed to capture screenshot. Falling back to instant theme switch.`,
354
+ error,
355
+ )
356
+ if (!mountedRef.current) return
357
+ setActiveTheme({ colors: getColors(name), name })
358
+ overlayOpacity.set(0)
359
+ resetTransition()
360
+ safeCall('config onThemeChange', onThemeChange, name)
361
+ }
362
+ },
363
+ [overlayOpacity, resetTransition],
364
+ )
365
+
366
+ const setTheme = useCallback(
367
+ (name: Names | 'system', options?: SetThemeOptions<Names>): boolean => {
368
+ // Calling setColorScheme('unspecified') pre-overlay flashes the Android status bar.
369
+ if (name === 'system' && !systemModeRef.current) {
370
+ if (transitioningRef.current) return false
371
+
372
+ setIsSystemMode(true)
373
+ systemModeRef.current = true
374
+ deferredSystemRestoreRef.current = schemeOf(targetThemeRef.current)
375
+ // Entering system mode is always a valid change for select().
376
+ setTheme('system', options)
377
+ return true
378
+ }
360
379
 
361
- if (transitioningRef.current) return false;
380
+ const resolvedTheme =
381
+ name === 'system'
382
+ ? mapSchemeToTheme<Names>(lastKnownOsSchemeRef.current, systemThemeMap)
383
+ : name
384
+ if (!(resolvedTheme in themes)) {
385
+ const resolutionHint =
386
+ name === 'system'
387
+ ? ' Provide `systemThemeMap` in the config to map OS appearance to your theme names.'
388
+ : ''
389
+ throw new Error(
390
+ `${TAG} setTheme("${name}") resolved to "${resolvedTheme}" which does not exist in themes.${resolutionHint}`,
391
+ )
392
+ }
362
393
 
363
- // After transition guard — a rejected call must not activate system mode.
364
- const wasSystemMode = systemModeRef.current;
365
- systemModeRef.current = name === 'system';
394
+ if (transitioningRef.current) return false
366
395
 
367
- if (systemModeRef.current !== wasSystemMode) {
368
- setIsSystemMode(systemModeRef.current);
369
- }
396
+ // After transition guard — a rejected call must not activate system mode.
397
+ const wasSystemMode = systemModeRef.current
398
+ systemModeRef.current = name === 'system'
370
399
 
371
- if (resolvedTheme === targetThemeRef.current) {
372
- // Manual↔system mode switch is valid even when the resolved theme matches —
373
- // returning true prevents select() from reverting the user's selection.
374
- return wasSystemMode !== systemModeRef.current;
375
- }
400
+ if (systemModeRef.current !== wasSystemMode) {
401
+ setIsSystemMode(systemModeRef.current)
402
+ // Stale deferred ref would override the user's explicit choice.
403
+ if (!systemModeRef.current) {
404
+ deferredSystemRestoreRef.current = null
405
+ }
406
+ }
376
407
 
377
- targetThemeRef.current = resolvedTheme;
408
+ if (resolvedTheme === targetThemeRef.current) {
409
+ // Manual↔system mode switch is valid even when the resolved theme matches —
410
+ // returning true prevents select() from reverting the user's selection.
411
+ return wasSystemMode !== systemModeRef.current
412
+ }
378
413
 
379
- if (options?.animated === false) {
380
- setActiveTheme({ colors: getColors(resolvedTheme), name: resolvedTheme });
381
- safeCall('config onThemeChange', onThemeChange, resolvedTheme);
382
- return true;
383
- }
414
+ targetThemeRef.current = resolvedTheme
384
415
 
385
- // Block before user callbacks to prevent re-entrant setTheme.
386
- transitioningRef.current = true;
387
- isBlocking.value = true;
388
-
389
- try {
390
- configOnTransitionStart?.(resolvedTheme);
391
- options?.onTransitionStart?.(resolvedTheme);
392
- } catch (e) {
393
- // Reset guards so a callback error doesn't permanently block transitions.
394
- resetTransition();
395
- throw e;
396
- }
397
- runTransition(resolvedTheme, options).catch(() => {});
398
- return true;
399
- }, [isBlocking, resetTransition, runTransition]);
416
+ if (options?.animated === false) {
417
+ setActiveTheme({ colors: getColors(resolvedTheme), name: resolvedTheme })
418
+ safeCall('config onThemeChange', onThemeChange, resolvedTheme)
419
+ return true
420
+ }
421
+
422
+ // Block before user callbacks to prevent re-entrant setTheme.
423
+ transitioningRef.current = true
424
+ isBlocking.value = true
425
+
426
+ try {
427
+ configOnTransitionStart?.(resolvedTheme)
428
+ options?.onTransitionStart?.(resolvedTheme)
429
+ } catch (e) {
430
+ // Reset guards so a callback error doesn't permanently block transitions.
431
+ resetTransition()
432
+ throw e
433
+ }
434
+ runTransition(resolvedTheme, options).catch(() => {})
435
+ return true
436
+ },
437
+ [isBlocking, resetTransition, runTransition],
438
+ )
400
439
 
401
440
  useEffect(() => {
402
441
  const appearanceSub = Appearance.addChangeListener(({ colorScheme }) => {
403
- if (!systemModeRef.current) return;
404
- lastKnownOsSchemeRef.current = normalizeScheme(colorScheme);
442
+ if (!systemModeRef.current) return
443
+ lastKnownOsSchemeRef.current = normalizeScheme(colorScheme)
405
444
  // Deferred restore listener in runTransition handles these.
406
- if (deferredSystemRestoreRef.current !== null) return;
445
+ if (deferredSystemRestoreRef.current !== null) return
407
446
  if (transitioningRef.current) {
408
- pendingSchemeRef.current = normalizeScheme(colorScheme);
409
- return;
447
+ pendingSchemeRef.current = normalizeScheme(colorScheme)
448
+ return
410
449
  }
411
450
  if (appStateRef.current === 'active') {
412
- setTheme('system');
451
+ setTheme('system')
413
452
  } else {
414
453
  // Background: apply directly. iOS may defer — AppState handler re-applies on foreground.
415
- const resolved = mapSchemeToTheme<Names>(normalizeScheme(colorScheme), systemThemeMap);
416
- if (!(resolved in themes) || resolved === targetThemeRef.current) return;
417
- targetThemeRef.current = resolved;
418
- setActiveTheme({ colors: getColors(resolved), name: resolved });
419
- safeCall('config onThemeChange', onThemeChange, resolved);
454
+ const resolved = mapSchemeToTheme<Names>(normalizeScheme(colorScheme), systemThemeMap)
455
+ if (!(resolved in themes) || resolved === targetThemeRef.current) return
456
+ targetThemeRef.current = resolved
457
+ setActiveTheme({ colors: getColors(resolved), name: resolved })
458
+ safeCall('config onThemeChange', onThemeChange, resolved)
420
459
  }
421
- });
460
+ })
422
461
 
423
462
  // Re-read OS scheme on foreground return — iOS may not deliver
424
463
  // Appearance events while suspended, or may defer the React commit.
425
464
  const appSub = AppState.addEventListener('change', (next) => {
426
465
  if (appStateRef.current !== 'active' && next === 'active' && systemModeRef.current) {
427
- const resolved = resolveSystemTheme<Names>(systemThemeMap, schemeOf(targetThemeRef.current));
466
+ const resolved = resolveSystemTheme<Names>(
467
+ systemThemeMap,
468
+ schemeOf(targetThemeRef.current),
469
+ )
428
470
  if (resolved in themes) {
429
- const changed = resolved !== targetThemeRef.current;
430
- targetThemeRef.current = resolved;
431
- setActiveTheme({ colors: getColors(resolved), name: resolved });
432
- if (changed) safeCall('config onThemeChange', onThemeChange, resolved);
471
+ const changed = resolved !== targetThemeRef.current
472
+ targetThemeRef.current = resolved
473
+ setActiveTheme({ colors: getColors(resolved), name: resolved })
474
+ if (changed) safeCall('config onThemeChange', onThemeChange, resolved)
433
475
  }
434
476
  }
435
- appStateRef.current = next;
436
- });
477
+ appStateRef.current = next
478
+ })
437
479
 
438
480
  return () => {
439
- appearanceSub.remove();
440
- appSub.remove();
441
- };
442
- }, [setTheme]);
443
-
444
- const contextValue = useMemo(() => ({
445
- colors: activeTheme.colors, name: activeTheme.name, setTheme, isTransitioning,
446
- }), [activeTheme, setTheme, isTransitioning]);
481
+ appearanceSub.remove()
482
+ appSub.remove()
483
+ }
484
+ }, [setTheme])
485
+
486
+ const contextValue = useMemo(
487
+ () => ({
488
+ colors: activeTheme.colors,
489
+ name: activeTheme.name,
490
+ setTheme,
491
+ isTransitioning,
492
+ }),
493
+ [activeTheme, setTheme, isTransitioning],
494
+ )
447
495
 
448
496
  return (
449
497
  <Context.Provider value={contextValue}>
@@ -454,13 +502,20 @@ export function createProviderAndContext<
454
502
  {/* Always mounted — avoids shared-value race on conditional mount. */}
455
503
  <Animated.View style={[ABSOLUTE_FILL, overlayStyle]} pointerEvents="none">
456
504
  {overlayUri != null ? (
457
- <Image source={overlaySource} style={ABSOLUTE_FILL} resizeMode="cover" fadeDuration={0} onLoad={onOverlayLoad} onError={onOverlayError} />
505
+ <Image
506
+ source={overlaySource}
507
+ style={ABSOLUTE_FILL}
508
+ resizeMode="cover"
509
+ fadeDuration={0}
510
+ onLoad={onOverlayLoad}
511
+ onError={onOverlayError}
512
+ />
458
513
  ) : null}
459
514
  </Animated.View>
460
515
  </View>
461
516
  </Context.Provider>
462
- );
517
+ )
463
518
  }
464
519
 
465
- return { Context, ThemeTransitionProvider };
520
+ return { Context, ThemeTransitionProvider }
466
521
  }