react-native-theme-transition 1.0.2 → 1.0.4

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/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
+ }