uitheme-rn 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +402 -2
- package/SCREEN-TRANSITION-CHECKS.md +22 -0
- package/STYLING-CHECKS.md +44 -0
- package/dist/core.cjs +154 -0
- package/dist/core.d.cts +19 -0
- package/dist/core.d.ts +19 -0
- package/dist/core.js +126 -0
- package/dist/expo.cjs +148 -0
- package/dist/expo.d.cts +22 -0
- package/dist/expo.d.ts +22 -0
- package/dist/expo.js +121 -0
- package/dist/index.cjs +361 -0
- package/dist/index.d.cts +149 -0
- package/dist/index.d.ts +149 -0
- package/dist/index.js +333 -0
- package/dist/nativewind.cjs +133 -0
- package/dist/nativewind.d.cts +11 -0
- package/dist/nativewind.d.ts +11 -0
- package/dist/nativewind.js +117 -0
- package/dist/reanimated.cjs +60 -0
- package/dist/reanimated.d.cts +11 -0
- package/dist/reanimated.d.ts +11 -0
- package/dist/reanimated.js +35 -0
- package/dist/styling-types-IxVh-sYQ.d.cts +7 -0
- package/dist/styling-types-IxVh-sYQ.d.ts +7 -0
- package/dist/transitions.cjs +401 -0
- package/dist/transitions.d.cts +49 -0
- package/dist/transitions.d.ts +49 -0
- package/dist/transitions.js +394 -0
- package/dist/types-BkuOLauF.d.cts +25 -0
- package/dist/types-BkuOLauF.d.ts +25 -0
- package/dist/uniwind.cjs +88 -0
- package/dist/uniwind.d.cts +11 -0
- package/dist/uniwind.d.ts +11 -0
- package/dist/uniwind.js +68 -0
- package/package.json +159 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 tonyedgal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,403 @@
|
|
|
1
|
-
#
|
|
1
|
+
# uitheme-rn
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Native appearance and independent color palettes for React Native. The provider
|
|
4
|
+
and hooks have no Expo, DOM, CSS, Reanimated, or storage dependency. Optional
|
|
5
|
+
controls in `uitheme-rn/expo` use SwiftUI on iOS and Jetpack Compose on Android.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
pnpm add uitheme-rn@alpha
|
|
11
|
+
# Optional native controls in an Expo SDK 56 or 57 app:
|
|
12
|
+
npx expo install @expo/ui
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Version `0.1.0-alpha` is intended for early testing. Device validation is still
|
|
16
|
+
in progress.
|
|
17
|
+
The reference app uses SDK 57, React 19.2.3, and React Native 0.86.3. The declared
|
|
18
|
+
React Native range begins at 0.83; older versions in that range still need device
|
|
19
|
+
verification. Expo is required only for the `/expo` entry point.
|
|
20
|
+
|
|
21
|
+
Animation peers are restricted to Reanimated 4.5.x, Worklets 0.10.x, and Skia
|
|
22
|
+
2.11.x. These ranges prevent npm from selecting incompatible animation engines.
|
|
23
|
+
NativeWind support targets exactly `5.0.0-rc.0`. Newer engine versions need a
|
|
24
|
+
separate compatibility check. See
|
|
25
|
+
[the release review](https://github.com/tonyedgal/ui-theme/blob/main/docs/native-stable-release-readiness.md) for the current
|
|
26
|
+
validation scope and remaining gates.
|
|
27
|
+
|
|
28
|
+
## Provider
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
import { UIThemeProvider, useUITheme } from 'uitheme-rn';
|
|
32
|
+
import { UIThemeSelector, UIColorThemeSelector } from 'uitheme-rn/expo';
|
|
33
|
+
import Storage from 'expo-sqlite/kv-store';
|
|
34
|
+
|
|
35
|
+
export default function App() {
|
|
36
|
+
return (
|
|
37
|
+
<UIThemeProvider storage={Storage} fallback={null}>
|
|
38
|
+
<Settings />
|
|
39
|
+
</UIThemeProvider>
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function Settings() {
|
|
44
|
+
return (
|
|
45
|
+
<>
|
|
46
|
+
<UIThemeSelector />
|
|
47
|
+
<UIColorThemeSelector />
|
|
48
|
+
</>
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Install example storage with `npx expo install expo-sqlite`. Storage is optional.
|
|
54
|
+
Without an adapter, preferences remain in memory. An adapter needs `getItem`
|
|
55
|
+
and `setItem`; each may be synchronous or asynchronous. AsyncStorage also
|
|
56
|
+
implements this contract. For MMKV, map `getString(key) ?? null` and `set(key, value)`.
|
|
57
|
+
Theme preferences are not secrets and do not need SecureStore.
|
|
58
|
+
|
|
59
|
+
`fallback` is optional. Omit it to render defaults during restoration; pass
|
|
60
|
+
`null` to delay the app and retain your launch screen until preferences restore.
|
|
61
|
+
Call `SplashScreen.hideAsync()` in a mounted descendant after `isHydrated` is
|
|
62
|
+
true, as the reference app does. A failed storage read also completes hydration.
|
|
63
|
+
|
|
64
|
+
Provider options are captured on mount. Change the provider's `key` to replace
|
|
65
|
+
palettes, storage, defaults, or the error handler. Each provider owns its state.
|
|
66
|
+
The package never overrides the app-wide `Appearance` setting.
|
|
67
|
+
|
|
68
|
+
## State and actions
|
|
69
|
+
|
|
70
|
+
```tsx
|
|
71
|
+
const {
|
|
72
|
+
theme, // 'system' | 'light' | 'dark': user preference
|
|
73
|
+
resolvedTheme, // 'light' | 'dark': currently displayed mode
|
|
74
|
+
systemTheme,
|
|
75
|
+
colorTheme,
|
|
76
|
+
colors,
|
|
77
|
+
palettes,
|
|
78
|
+
colorThemes,
|
|
79
|
+
isHydrated,
|
|
80
|
+
setTheme,
|
|
81
|
+
setColorTheme,
|
|
82
|
+
toggleTheme,
|
|
83
|
+
toggleColorTheme,
|
|
84
|
+
flush,
|
|
85
|
+
} = useUITheme();
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`setTheme('system')` follows React Native Appearance updates. `toggleTheme()`
|
|
89
|
+
selects the opposite of the resolved mode and leaves system mode. Palettes do
|
|
90
|
+
not change when appearance changes. Setters update synchronously and reject
|
|
91
|
+
unknown choices. `flush()` waits for restoration and queued writes; storage
|
|
92
|
+
failures reach `onStorageError` while in-memory changes stay usable. Setters do
|
|
93
|
+
not await disk or pretend to run a browser-style transition.
|
|
94
|
+
|
|
95
|
+
The store persists a versioned record under `uitheme-rn:preferences`, configurable
|
|
96
|
+
with `storageKey`. Unknown versions and invalid fields fall back to defaults.
|
|
97
|
+
User input wins over a late read, independently for each preference. Writes
|
|
98
|
+
are serialized. Call `flush()` before an app-owned shutdown flow when possible;
|
|
99
|
+
JavaScript cannot guarantee a write completes after the OS kills the process.
|
|
100
|
+
|
|
101
|
+
## Palettes and tokens
|
|
102
|
+
|
|
103
|
+
```tsx
|
|
104
|
+
import { defaultPalettes, type ThemePalette } from 'uitheme-rn';
|
|
105
|
+
|
|
106
|
+
const palettes = {
|
|
107
|
+
...defaultPalettes,
|
|
108
|
+
forest: {
|
|
109
|
+
label: 'Forest',
|
|
110
|
+
light: { ...defaultPalettes.default.light, accent: '#216E46' },
|
|
111
|
+
dark: { ...defaultPalettes.default.dark, accent: '#80D6A5' },
|
|
112
|
+
},
|
|
113
|
+
} satisfies Record<string, ThemePalette>;
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Pass `palettes` and optionally `defaultColorTheme` to the provider. Without an
|
|
117
|
+
explicit default, the first palette is used. Each palette supplies `background`,
|
|
118
|
+
`surface`, `text`, `secondaryText`, `separator`, `accent`, and `onAccent` in both
|
|
119
|
+
modes. Values are React Native `ColorValue`; opaque platform colors are accepted.
|
|
120
|
+
Explicit mode colors are useful when the app's mode differs from the OS.
|
|
121
|
+
Platform semantic colors follow the native host's appearance, so coordinate
|
|
122
|
+
them with app-wide appearance if using them outside an Expo UI Host.
|
|
123
|
+
|
|
124
|
+
`themeTokens` supplies a 4-point spacing scale, continuous corner radii, and
|
|
125
|
+
system-font text styles. Text still scales with the device. `useThemeColors()`
|
|
126
|
+
returns the active palette. Custom app-specific tokens belong in the app's
|
|
127
|
+
theme module, composed with these tokens.
|
|
128
|
+
|
|
129
|
+
## Native controls
|
|
130
|
+
|
|
131
|
+
Each control owns an Expo UI Host with the resolved color scheme:
|
|
132
|
+
|
|
133
|
+
- `UIThemeSelector`: appearance picker; supports `label`, translated `labels`,
|
|
134
|
+
`disabled`, and `testID`.
|
|
135
|
+
- `UIColorThemeSelector`: palette picker with palette labels; supports `label`,
|
|
136
|
+
`disabled`, and `testID`.
|
|
137
|
+
- `UIThemeSwitcher`: native button for light/dark; supports `label` and `disabled`.
|
|
138
|
+
|
|
139
|
+
For custom settings composition, use `useUITheme()` with your own `@expo/ui`
|
|
140
|
+
controls. Native control feedback and navigation transitions stay platform-owned.
|
|
141
|
+
The root and Expo entries do not mount snapshots or duplicate screen trees.
|
|
142
|
+
Screen snapshots are opt-in through the separate transition entry.
|
|
143
|
+
`useReducedMotion()` observes the accessibility setting and starts conservatively
|
|
144
|
+
enabled until the first native query finishes. Use it for custom app motion.
|
|
145
|
+
|
|
146
|
+
For headless integrations, `uitheme-rn/core` exports `createThemeStore` and its
|
|
147
|
+
types without importing React Native. The React provider subscribes with
|
|
148
|
+
`useSyncExternalStore`.
|
|
149
|
+
|
|
150
|
+
## Optional theme transitions
|
|
151
|
+
|
|
152
|
+
Install the SDK-compatible animation peers in an Expo app:
|
|
153
|
+
|
|
154
|
+
```sh
|
|
155
|
+
npx expo install react-native-reanimated react-native-worklets
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
```tsx
|
|
159
|
+
import Animated from 'react-native-reanimated';
|
|
160
|
+
import { useUITheme } from 'uitheme-rn';
|
|
161
|
+
import { useThemeTransition } from 'uitheme-rn/reanimated';
|
|
162
|
+
|
|
163
|
+
function Card() {
|
|
164
|
+
const { colors } = useUITheme();
|
|
165
|
+
const transition = useThemeTransition();
|
|
166
|
+
|
|
167
|
+
return (
|
|
168
|
+
<Animated.View
|
|
169
|
+
style={{
|
|
170
|
+
...transition.view,
|
|
171
|
+
backgroundColor: colors.surface,
|
|
172
|
+
borderColor: colors.separator,
|
|
173
|
+
borderWidth: 1,
|
|
174
|
+
padding: 16,
|
|
175
|
+
}}
|
|
176
|
+
>
|
|
177
|
+
<Animated.Text style={{ ...transition.text, color: colors.text }}>
|
|
178
|
+
Your theme, on your device.
|
|
179
|
+
</Animated.Text>
|
|
180
|
+
</Animated.View>
|
|
181
|
+
);
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`useThemeTransition()` returns `view` and `text` styles. View styles transition
|
|
186
|
+
background and border colors. Text styles also transition text color. Each uses
|
|
187
|
+
180 ms and an ease-out curve. Apply the styles to Reanimated components; ordinary
|
|
188
|
+
React Native components cannot run these transitions. Existing screens opt in
|
|
189
|
+
without changing their tree, scroll position, or focus.
|
|
190
|
+
|
|
191
|
+
The hook arms after the hydrated colors commit to a frame. Mounting and preference
|
|
192
|
+
restoration stay immediate. Live Reduce Motion changes remove the transition
|
|
193
|
+
configuration and apply the final colors. Rapid changes are handled by
|
|
194
|
+
Reanimated's transition engine; there is no completion callback that can restore
|
|
195
|
+
an old preference. Setters and persistence remain synchronous and independent
|
|
196
|
+
of animation completion. Unmounting cancels the pending frame used to arm motion.
|
|
197
|
+
|
|
198
|
+
Interpolating light and dark text against an interpolating background can briefly
|
|
199
|
+
reduce contrast. The recorded example shows this in intermediate frames. For
|
|
200
|
+
screens that need continuous reading, apply `transition.view` to surfaces and
|
|
201
|
+
set text colors immediately. Text transitions are opt-in through `transition.text`.
|
|
202
|
+
|
|
203
|
+
Use explicit string colors for predictable interpolation. Native semantic colors
|
|
204
|
+
remain useful for platform-owned controls; do not assume their internal appearance
|
|
205
|
+
animates through these styles. Expo UI Hosts, native navigation headers, and status
|
|
206
|
+
bars update to the resolved theme through their own APIs. The reference app keeps
|
|
207
|
+
those native elements outside the Reanimated color transition.
|
|
208
|
+
|
|
209
|
+
The animation entry requires the New Architecture, Reanimated 4.5.1 and compatible
|
|
210
|
+
Worklets. The reference app verifies the SDK 57 pair, Reanimated 4.5.1 and Worklets
|
|
211
|
+
0.10.1. Bare React Native apps must configure the Worklets Babel plugin as described
|
|
212
|
+
in Reanimated's installation guide. The root, core, and Expo entries do not import
|
|
213
|
+
animation peers.
|
|
214
|
+
|
|
215
|
+
See [the transition acceptance cases](../../apps/examples/example-expo/TRANSITION-CHECKS.md)
|
|
216
|
+
and [the recorded checks](../../apps/examples/example-expo/VERIFICATION.md).
|
|
217
|
+
|
|
218
|
+
## Workspace verification
|
|
219
|
+
|
|
220
|
+
```sh
|
|
221
|
+
pnpm --filter uitheme-rn test
|
|
222
|
+
pnpm --filter uitheme-rn typecheck
|
|
223
|
+
pnpm --filter uitheme-rn build
|
|
224
|
+
pnpm --filter uitheme-rn test:package
|
|
225
|
+
pnpm --filter example-expo typecheck
|
|
226
|
+
pnpm --filter example-expo start
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Use a release build on the slowest supported device to judge native feel. See
|
|
230
|
+
the example README for the native acceptance checklist and repeatable flows.
|
|
231
|
+
|
|
232
|
+
## Screen transitions
|
|
233
|
+
|
|
234
|
+
For the screen effects shown in the
|
|
235
|
+
[reference Snack](https://snack.expo.dev/@mariops03/react-native-theme-transition?platform=ios),
|
|
236
|
+
use the optional `uitheme-rn/transitions` entry. Install SDK-compatible Skia,
|
|
237
|
+
Reanimated, and Worklets through Expo. Pin Skia to `2.11.1` or a supported
|
|
238
|
+
2.11 patch release; SDK 57's bundled Skia 2.6.2 has a broken Android overflow
|
|
239
|
+
capture path. This override requires a custom native build and does not claim
|
|
240
|
+
Expo Go compatibility. See the
|
|
241
|
+
[upstream fix](https://github.com/wcandillon/react-native-skia/pull/4004). The tested pair uses Skia 2.11.1,
|
|
242
|
+
Reanimated 4.5.1, and Worklets 0.10.1 on Expo SDK 57.
|
|
243
|
+
|
|
244
|
+
```tsx
|
|
245
|
+
import { Button, View } from 'react-native';
|
|
246
|
+
import { UIThemeProvider, defaultPalettes } from 'uitheme-rn';
|
|
247
|
+
import {
|
|
248
|
+
UIThemeTransitionProvider,
|
|
249
|
+
useAnimatedUITheme,
|
|
250
|
+
} from 'uitheme-rn/transitions';
|
|
251
|
+
|
|
252
|
+
const palettes = {
|
|
253
|
+
...defaultPalettes,
|
|
254
|
+
forest: {
|
|
255
|
+
label: 'Forest',
|
|
256
|
+
light: { ...defaultPalettes.default.light, accent: '#216E46' },
|
|
257
|
+
dark: { ...defaultPalettes.default.dark, accent: '#80D6A5' },
|
|
258
|
+
},
|
|
259
|
+
};
|
|
260
|
+
|
|
261
|
+
export default function App() {
|
|
262
|
+
return (
|
|
263
|
+
<UIThemeProvider palettes={palettes}>
|
|
264
|
+
<UIThemeTransitionProvider defaults={{ transition: 'circularReveal' }}>
|
|
265
|
+
<Controls />
|
|
266
|
+
</UIThemeTransitionProvider>
|
|
267
|
+
</UIThemeProvider>
|
|
268
|
+
);
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
function Controls() {
|
|
272
|
+
const { setTheme, setColorTheme, isTransitioning } = useAnimatedUITheme();
|
|
273
|
+
|
|
274
|
+
return (
|
|
275
|
+
<View>
|
|
276
|
+
<Button
|
|
277
|
+
title="Dark mode"
|
|
278
|
+
disabled={isTransitioning}
|
|
279
|
+
onPress={() => {
|
|
280
|
+
void setTheme('dark');
|
|
281
|
+
}}
|
|
282
|
+
/>
|
|
283
|
+
<Button
|
|
284
|
+
title="Forest palette"
|
|
285
|
+
disabled={isTransitioning}
|
|
286
|
+
onPress={() => {
|
|
287
|
+
void setColorTheme('forest', { transition: 'wipe' });
|
|
288
|
+
}}
|
|
289
|
+
/>
|
|
290
|
+
</View>
|
|
291
|
+
);
|
|
292
|
+
}
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Both commands capture the provider's native view tree before changing the same
|
|
296
|
+
preference store. The overlay paints the old screen before the new screen commits.
|
|
297
|
+
Skia captures the new screen, and a Reanimated shared value drives the shader on
|
|
298
|
+
the UI runtime. Participating text does not interpolate its individual colors.
|
|
299
|
+
Do not combine this provider with per-element color interpolation on the same tree.
|
|
300
|
+
|
|
301
|
+
Available effects are `fade`, `circularReveal`, `wipe`, `slide`, `split`, `heart`,
|
|
302
|
+
`star`, `pixelize`, and `dissolve`. Options include `duration`, `origin` (a view ref
|
|
303
|
+
or a provider-relative point), `inverted` for shape/split reveals, `direction`,
|
|
304
|
+
`split`, `blockSize`, `noiseSize`, and `animated`. The default duration is 350 ms.
|
|
305
|
+
Busy requests are rejected before preferences change. Immediate root commands
|
|
306
|
+
remain available through `useUITheme`; use the animated hook for screen effects.
|
|
307
|
+
Expo selectors accept `onValueChange`, and the switcher accepts `onPress`, so the
|
|
308
|
+
native controls can call animated commands without taking ownership of preferences.
|
|
309
|
+
|
|
310
|
+
Reduce Motion skips capture. Live Reduce Motion, backgrounding, rotation, and
|
|
311
|
+
unmount cancel the overlay. A capture failure falls back to an immediate change;
|
|
312
|
+
`onError` reports it. Restoration and system appearance updates use the existing
|
|
313
|
+
provider and do not trigger screen captures. Snapshot layers are hidden from the
|
|
314
|
+
accessibility tree. Touch input is blocked while capture/playback is active.
|
|
315
|
+
|
|
316
|
+
Set the transition provider's `enabled` prop to `false` while native navigation
|
|
317
|
+
or another movement changes the captured tree. This cancels an active overlay and
|
|
318
|
+
applies new choices immediately. Re-enable when movement ends. The Expo example
|
|
319
|
+
connects this prop to the stack's `transitionStart` and `transitionEnd` events.
|
|
320
|
+
Commands also skip capture while the app is not active.
|
|
321
|
+
|
|
322
|
+
The capture boundary is the provider's view tree, including navigation inside it.
|
|
323
|
+
System status bars, keyboards, alerts, and separate native windows remain under OS
|
|
324
|
+
control. Two screen images require memory proportional to their pixel dimensions.
|
|
325
|
+
Run [SCREEN-TRANSITION-CHECKS.md](./SCREEN-TRANSITION-CHECKS.md) before claiming
|
|
326
|
+
release performance or accessibility verification.
|
|
327
|
+
|
|
328
|
+
The browser fallback changes preferences immediately; it does not mount Skia or
|
|
329
|
+
require CanvasKit initialization. Native screen effects target iOS and Android.
|
|
330
|
+
|
|
331
|
+
## Styling systems and CSS themes
|
|
332
|
+
|
|
333
|
+
Plain `StyleSheet`, inline native styles, and TypeScript palettes remain the
|
|
334
|
+
base API. Neither Tailwind nor a styling engine is required by the root entry.
|
|
335
|
+
Optional `uitheme-rn/nativewind` and `uitheme-rn/uniwind` adapters connect utility
|
|
336
|
+
classes to the same appearance and palette store. Install one engine in an app.
|
|
337
|
+
|
|
338
|
+
The NativeWind example targets `nativewind@5.0.0-rc.0` and
|
|
339
|
+
`react-native-css@3.1.0-rc.0` with Tailwind 4.3.1. NativeWind v5 is a release
|
|
340
|
+
candidate; v4 is not supported by this adapter. The Uniwind example targets
|
|
341
|
+
Uniwind 1.12.2 with Tailwind 4.3.1. Follow each example's Metro configuration;
|
|
342
|
+
NativeWind also needs the Tailwind v4 PostCSS plugin and Lightning CSS 1.30.1.
|
|
343
|
+
|
|
344
|
+
For existing TypeScript palettes, place `<NativeWindTheme>` or `<UniwindTheme>`
|
|
345
|
+
inside `<UIThemeProvider>`. The adapter provides scoped semantic variables.
|
|
346
|
+
`bg-primary`, `text-primary-foreground`, `bg-card`, `bg-background`,
|
|
347
|
+
`text-foreground`, `text-muted-foreground`, and `border-border` then use the
|
|
348
|
+
same colors as `useThemeColors()`. Native dynamic color objects remain available
|
|
349
|
+
with native styles; CSS conversion requires string colors.
|
|
350
|
+
|
|
351
|
+
For CSS-authored palettes, use label-only metadata and map each palette's modes:
|
|
352
|
+
|
|
353
|
+
```tsx
|
|
354
|
+
import { UIThemeProvider } from 'uitheme-rn';
|
|
355
|
+
import { NativeWindTheme } from 'uitheme-rn/nativewind';
|
|
356
|
+
|
|
357
|
+
const palettes = { supabase: { label: 'Supabase' } };
|
|
358
|
+
const themes = {
|
|
359
|
+
supabase: { light: 'supabase-light', dark: 'supabase-dark' },
|
|
360
|
+
};
|
|
361
|
+
|
|
362
|
+
<UIThemeProvider palettes={palettes} defaultColorTheme="supabase">
|
|
363
|
+
<NativeWindTheme themes={themes}>{/* Your app */}</NativeWindTheme>
|
|
364
|
+
</UIThemeProvider>;
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
For Uniwind, use `<UniwindTheme themes={themes}>` and register the selected names
|
|
368
|
+
in Metro's `extraThemes`. NativeWind uses CSS class names. Uniwind uses scoped
|
|
369
|
+
registered themes. Both adapters resolve seven colors from CSS for native
|
|
370
|
+
controls and hooks. Missing variables or mappings produce a useful error.
|
|
371
|
+
|
|
372
|
+
The examples preserve the Next app's raw names (`--background`, `--primary`,
|
|
373
|
+
etc.) and Tailwind v4 aliases (`--color-background`, `--color-primary`, etc.).
|
|
374
|
+
All 32 color tokens, including chart and sidebar colors, are available to
|
|
375
|
+
utility classes. The native `ThemeColors` contract maps its `accent` to the
|
|
376
|
+
primary action color (`--color-primary`); the separate CSS `--color-accent`
|
|
377
|
+
remains available for accent surfaces.
|
|
378
|
+
|
|
379
|
+
The six example palettes come from `example-next/app/globals.css`: Default,
|
|
380
|
+
Supabase, Mono, Caffeine, Mocha, and Perpetuity. Run `pnpm sync:colors` inside
|
|
381
|
+
either styling example after changing the web colors. The sync script copies
|
|
382
|
+
OKLCH values without translating or inventing palette values. Web layout,
|
|
383
|
+
fonts, shadows, and animation rules remain in the web stylesheet.
|
|
384
|
+
|
|
385
|
+
Place `UIThemeTransitionProvider` inside the styling adapter so captures see the
|
|
386
|
+
resolved CSS scope. Use `useAnimatedUITheme()` for animated appearance and
|
|
387
|
+
palette commands. Semantic colors follow the provider's resolved mode without
|
|
388
|
+
changing OS Appearance. NativeWind's global `dark:` variant still follows the
|
|
389
|
+
engine's system appearance; use semantic colors for provider-owned palettes.
|
|
390
|
+
|
|
391
|
+
## Snapshot performance and native surfaces
|
|
392
|
+
|
|
393
|
+
Screen effects take two snapshots of the provider's content. On the tested
|
|
394
|
+
Android flagship, each awaited view capture takes 113–133 ms. Capture can pause
|
|
395
|
+
the UI before the shader animation begins. Reanimated color transitions avoid
|
|
396
|
+
this snapshot path. Do not assume full-screen effects meet the same frame budget.
|
|
397
|
+
|
|
398
|
+
Disable snapshot transitions with `enabled={false}` around trees containing
|
|
399
|
+
Android `SurfaceView` content, such as some video and camera views. The tested
|
|
400
|
+
Skia capture path waits on the main thread for a callback scheduled on that
|
|
401
|
+
same thread, which can time out and produce incomplete capture. Such trees are
|
|
402
|
+
not verified for these effects. Keep system windows and native chrome outside
|
|
403
|
+
the capture boundary. See the stable release review for current device limits.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Screen transition acceptance
|
|
2
|
+
|
|
3
|
+
Define these checks before implementation. Run in a standalone release app.
|
|
4
|
+
|
|
5
|
+
- Light to Dark and back: the old screen remains covered until the new screen is
|
|
6
|
+
ready; the selected appearance and saved preference agree after completion.
|
|
7
|
+
- Default to Forest to Clay: the same effect changes only the palette.
|
|
8
|
+
- Each effect: fade, circular reveal, wipe, slide, split, heart, star, pixelize,
|
|
9
|
+
and dissolve reach the exact target screen without a leftover overlay.
|
|
10
|
+
- Origin: a control ref and explicit point locate the reveal in provider points.
|
|
11
|
+
- System: changing a palette preserves System; background OS changes still resolve.
|
|
12
|
+
- Restore: startup uses saved preferences without a screen capture or reveal.
|
|
13
|
+
- Reduce Motion: no capture when enabled; enabling it during a transition removes
|
|
14
|
+
the overlay and keeps the current target.
|
|
15
|
+
- Busy: requests during capture or playback do not mutate preferences.
|
|
16
|
+
- Navigation, rotation, background, unmount, and capture failure: release images,
|
|
17
|
+
restore touches, and retain the last committed preference.
|
|
18
|
+
- Disable the provider during native navigation: an active overlay is removed;
|
|
19
|
+
a new choice applies immediately. Re-enable after navigation ends, then verify
|
|
20
|
+
that the next effect captures the settled screen.
|
|
21
|
+
- Accessibility: snapshots are hidden; live controls remain the only semantic tree.
|
|
22
|
+
- Release: measure capture latency, frame hitches, and memory on iOS and Android.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Styling integration acceptance
|
|
2
|
+
|
|
3
|
+
Define before implementing the adapters. Verify with built public package entries.
|
|
4
|
+
|
|
5
|
+
- Native styles: existing palettes, useThemeColors, native controls, and screen
|
|
6
|
+
effects work with no NativeWind, Uniwind, or Tailwind installation.
|
|
7
|
+
- TypeScript palettes: both optional engines render the same semantic colors as
|
|
8
|
+
native style objects when appearance or colorTheme changes.
|
|
9
|
+
- CSS themes: CSS owns values; a palette manifest contains only labels and the
|
|
10
|
+
engine's light/dark class or theme names. Native colors read the selected CSS
|
|
11
|
+
variables, without duplicate TypeScript color definitions.
|
|
12
|
+
- System: palette changes preserve System and follow later OS changes.
|
|
13
|
+
- Scope: independent providers do not modify engine globals or OS Appearance.
|
|
14
|
+
- Animation: both snapshots include the styling engine's selected variables;
|
|
15
|
+
reduced motion applies changes immediately.
|
|
16
|
+
- Missing CSS variables or palette mappings: fail with a useful error rather than
|
|
17
|
+
silently rendering default palette colors. Native dynamic colors remain usable
|
|
18
|
+
with native styles; CSS conversion rejects values that cannot be represented.
|
|
19
|
+
- Distribution: ESM/CJS entries and declarations exist, optional peers remain
|
|
20
|
+
optional, and the core/root do not import either engine.
|
|
21
|
+
- Examples: separate NativeWind and Uniwind apps typecheck, export, and render;
|
|
22
|
+
compare selected CSS colors with native style samples on a running screen.
|
|
23
|
+
|
|
24
|
+
## Verification on 2026-10-09
|
|
25
|
+
|
|
26
|
+
- Package: seven ESM/CJS entry points and declarations build. Packed consumer
|
|
27
|
+
checks pass with neither styling engine required by root/core. Existing nine
|
|
28
|
+
store tests pass. Library, original Expo app, and both styling apps typecheck.
|
|
29
|
+
- Both styling apps export iOS, Android, and web bundles. NativeWind uses
|
|
30
|
+
5.0.0-rc.0/react-native-css 3.1.0-rc.0/Tailwind 4.3.1; Uniwind uses
|
|
31
|
+
1.12.2/Tailwind 4.3.1. Lint passes for the package and both examples.
|
|
32
|
+
- iPhone 16 Pro simulator, iOS 18.6, Expo Go: all six imported palettes render in
|
|
33
|
+
light and dark modes in both engines. Utility samples and native style samples
|
|
34
|
+
show matching compiled colors. The independent nested TypeScript palette
|
|
35
|
+
stays blue while outer CSS palettes change. Appearance and palette commands
|
|
36
|
+
enter Playing and finish Ready. Palette changes preserve selected System mode.
|
|
37
|
+
- Both engines on web: light/dark and Supabase selection update CSS/native samples;
|
|
38
|
+
NativeWind reads inherited computed variables; Uniwind resolves scoped variables. Web commands apply
|
|
39
|
+
immediately, as designed.
|
|
40
|
+
- Original web OKLCH color declarations are copied exactly by sync:colors. The
|
|
41
|
+
mobile stylesheet does not copy web layout, shadow, font, or animation rules.
|
|
42
|
+
- These checks establish development runtime behavior. Android device rendering,
|
|
43
|
+
release device performance, and physical screen-reader interaction remain
|
|
44
|
+
separate checks. No NativeWind v4 or future v5 release compatibility is claimed.
|
package/dist/core.cjs
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/core/index.ts
|
|
21
|
+
var core_exports = {};
|
|
22
|
+
__export(core_exports, {
|
|
23
|
+
createThemeStore: () => createThemeStore,
|
|
24
|
+
isTheme: () => isTheme
|
|
25
|
+
});
|
|
26
|
+
module.exports = __toCommonJS(core_exports);
|
|
27
|
+
|
|
28
|
+
// src/core/store.ts
|
|
29
|
+
var import_zod = require("zod");
|
|
30
|
+
function isTheme(value) {
|
|
31
|
+
return value === "light" || value === "dark" || value === "system";
|
|
32
|
+
}
|
|
33
|
+
function createThemeStore(options) {
|
|
34
|
+
const colorThemes = [...options.colorThemes];
|
|
35
|
+
const defaultColorTheme = options.defaultColorTheme ?? colorThemes[0];
|
|
36
|
+
if (!defaultColorTheme || !colorThemes.includes(defaultColorTheme)) {
|
|
37
|
+
throw new Error("UI-Theme requires an available default color theme.");
|
|
38
|
+
}
|
|
39
|
+
if (options.defaultTheme !== void 0 && !isTheme(options.defaultTheme)) {
|
|
40
|
+
throw new Error("Invalid default appearance mode.");
|
|
41
|
+
}
|
|
42
|
+
const storageKey = options.storageKey ?? "uitheme-rn:preferences";
|
|
43
|
+
const storedPreferences = import_zod.z.object({
|
|
44
|
+
version: import_zod.z.literal(1),
|
|
45
|
+
theme: import_zod.z.enum(["light", "dark", "system"]).optional().catch(void 0),
|
|
46
|
+
colorTheme: import_zod.z.string().refine((name) => colorThemes.includes(name)).optional().catch(void 0)
|
|
47
|
+
});
|
|
48
|
+
const listeners = /* @__PURE__ */ new Set();
|
|
49
|
+
let state = Object.freeze({
|
|
50
|
+
theme: options.defaultTheme ?? "system",
|
|
51
|
+
colorTheme: defaultColorTheme,
|
|
52
|
+
systemTheme: options.systemTheme ?? "light",
|
|
53
|
+
resolvedTheme: options.defaultTheme === "dark" ? "dark" : options.defaultTheme === "light" ? "light" : options.systemTheme ?? "light",
|
|
54
|
+
isHydrated: !options.storage
|
|
55
|
+
});
|
|
56
|
+
let dirtyTheme = false;
|
|
57
|
+
let dirtyColorTheme = false;
|
|
58
|
+
let hydration;
|
|
59
|
+
let writes = Promise.resolve();
|
|
60
|
+
function update(next) {
|
|
61
|
+
const merged = { ...state, ...next };
|
|
62
|
+
merged.resolvedTheme = merged.theme === "system" ? merged.systemTheme : merged.theme;
|
|
63
|
+
if (merged.theme === state.theme && merged.colorTheme === state.colorTheme && merged.systemTheme === state.systemTheme && merged.resolvedTheme === state.resolvedTheme && merged.isHydrated === state.isHydrated)
|
|
64
|
+
return;
|
|
65
|
+
state = Object.freeze(merged);
|
|
66
|
+
listeners.forEach((listener) => listener());
|
|
67
|
+
}
|
|
68
|
+
function persist() {
|
|
69
|
+
if (!options.storage || !state.isHydrated) return;
|
|
70
|
+
const value = JSON.stringify({
|
|
71
|
+
version: 1,
|
|
72
|
+
theme: state.theme,
|
|
73
|
+
colorTheme: state.colorTheme
|
|
74
|
+
});
|
|
75
|
+
writes = writes.then(() => options.storage?.setItem(storageKey, value)).catch((cause) => {
|
|
76
|
+
options.onStorageError?.(
|
|
77
|
+
new Error("Could not write UI-Theme preferences.", { cause })
|
|
78
|
+
);
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
async function restore() {
|
|
82
|
+
try {
|
|
83
|
+
const value = await options.storage?.getItem(storageKey);
|
|
84
|
+
if (value) {
|
|
85
|
+
const result = storedPreferences.safeParse(JSON.parse(value));
|
|
86
|
+
if (!result.success) return;
|
|
87
|
+
const saved = result.data;
|
|
88
|
+
update({
|
|
89
|
+
theme: !dirtyTheme && saved.theme !== void 0 ? saved.theme : state.theme,
|
|
90
|
+
colorTheme: !dirtyColorTheme && saved.colorTheme !== void 0 ? saved.colorTheme : state.colorTheme
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
} catch (cause) {
|
|
94
|
+
options.onStorageError?.(
|
|
95
|
+
new Error("Could not restore UI-Theme preferences.", { cause })
|
|
96
|
+
);
|
|
97
|
+
} finally {
|
|
98
|
+
update({ isHydrated: true });
|
|
99
|
+
if (dirtyTheme || dirtyColorTheme) persist();
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
function setTheme(theme) {
|
|
103
|
+
if (!["system", "light", "dark"].includes(theme))
|
|
104
|
+
throw new Error("Invalid appearance mode.");
|
|
105
|
+
dirtyTheme = true;
|
|
106
|
+
if (theme === state.theme) return;
|
|
107
|
+
update({ theme });
|
|
108
|
+
persist();
|
|
109
|
+
}
|
|
110
|
+
function setColorTheme(colorTheme) {
|
|
111
|
+
if (!colorThemes.includes(colorTheme))
|
|
112
|
+
throw new Error(`Unknown color theme: ${colorTheme}`);
|
|
113
|
+
dirtyColorTheme = true;
|
|
114
|
+
if (colorTheme === state.colorTheme) return;
|
|
115
|
+
update({ colorTheme });
|
|
116
|
+
persist();
|
|
117
|
+
}
|
|
118
|
+
return {
|
|
119
|
+
getSnapshot: () => state,
|
|
120
|
+
subscribe(listener) {
|
|
121
|
+
listeners.add(listener);
|
|
122
|
+
return () => {
|
|
123
|
+
listeners.delete(listener);
|
|
124
|
+
};
|
|
125
|
+
},
|
|
126
|
+
hydrate() {
|
|
127
|
+
hydration ??= restore();
|
|
128
|
+
return hydration;
|
|
129
|
+
},
|
|
130
|
+
async flush() {
|
|
131
|
+
hydration ??= restore();
|
|
132
|
+
await hydration;
|
|
133
|
+
await writes;
|
|
134
|
+
},
|
|
135
|
+
setTheme,
|
|
136
|
+
setColorTheme,
|
|
137
|
+
setSystemTheme(systemTheme) {
|
|
138
|
+
update({ systemTheme });
|
|
139
|
+
},
|
|
140
|
+
toggleTheme() {
|
|
141
|
+
setTheme(state.resolvedTheme === "dark" ? "light" : "dark");
|
|
142
|
+
},
|
|
143
|
+
toggleColorTheme() {
|
|
144
|
+
setColorTheme(
|
|
145
|
+
colorThemes[(colorThemes.indexOf(state.colorTheme) + 1) % colorThemes.length]
|
|
146
|
+
);
|
|
147
|
+
}
|
|
148
|
+
};
|
|
149
|
+
}
|
|
150
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
151
|
+
0 && (module.exports = {
|
|
152
|
+
createThemeStore,
|
|
153
|
+
isTheme
|
|
154
|
+
});
|
package/dist/core.d.cts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import { T as ThemeStoreOptions, a as ThemeSnapshot, b as Theme, R as ResolvedTheme } from './types-BkuOLauF.cjs';
|
|
2
|
+
export { c as ThemeStorage } from './types-BkuOLauF.cjs';
|
|
3
|
+
|
|
4
|
+
declare function isTheme(value: unknown): value is Theme;
|
|
5
|
+
/** One store per provider. No global state, native imports, or browser APIs. */
|
|
6
|
+
declare function createThemeStore(options: ThemeStoreOptions): {
|
|
7
|
+
getSnapshot: () => ThemeSnapshot;
|
|
8
|
+
subscribe(listener: () => void): () => void;
|
|
9
|
+
hydrate(): Promise<void>;
|
|
10
|
+
flush(): Promise<void>;
|
|
11
|
+
setTheme: (theme: Theme) => void;
|
|
12
|
+
setColorTheme: (colorTheme: string) => void;
|
|
13
|
+
setSystemTheme(systemTheme: ResolvedTheme): void;
|
|
14
|
+
toggleTheme(): void;
|
|
15
|
+
toggleColorTheme(): void;
|
|
16
|
+
};
|
|
17
|
+
type ThemeStore = ReturnType<typeof createThemeStore>;
|
|
18
|
+
|
|
19
|
+
export { ResolvedTheme, Theme, ThemeSnapshot, type ThemeStore, ThemeStoreOptions, createThemeStore, isTheme };
|