uitheme-rn 0.1.0-alpha → 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.
Files changed (2) hide show
  1. package/README.md +62 -13
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -7,7 +7,7 @@ controls in `uitheme-rn/expo` use SwiftUI on iOS and Jetpack Compose on Android.
7
7
  ## Install
8
8
 
9
9
  ```sh
10
- pnpm add uitheme-rn
10
+ pnpm add uitheme-rn@alpha
11
11
  # Optional native controls in an Expo SDK 56 or 57 app:
12
12
  npx expo install @expo/ui
13
13
  ```
@@ -18,6 +18,13 @@ The reference app uses SDK 57, React 19.2.3, and React Native 0.86.3. The declar
18
18
  React Native range begins at 0.83; older versions in that range still need device
19
19
  verification. Expo is required only for the `/expo` entry point.
20
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
+
21
28
  ## Provider
22
29
 
23
30
  ```tsx
@@ -131,7 +138,8 @@ Each control owns an Expo UI Host with the resolved color scheme:
131
138
 
132
139
  For custom settings composition, use `useUITheme()` with your own `@expo/ui`
133
140
  controls. Native control feedback and navigation transitions stay platform-owned.
134
- The package does not mount snapshots, duplicate screen trees, or global wipes.
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.
135
143
  `useReducedMotion()` observes the accessibility setting and starts conservatively
136
144
  enabled until the first native query finishes. Use it for custom app motion.
137
145
 
@@ -226,21 +234,35 @@ the example README for the native acceptance checklist and repeatable flows.
226
234
  For the screen effects shown in the
227
235
  [reference Snack](https://snack.expo.dev/@mariops03/react-native-theme-transition?platform=ios),
228
236
  use the optional `uitheme-rn/transitions` entry. Install SDK-compatible Skia,
229
- Reanimated, and Worklets through Expo. The tested pair uses Skia 2.6.2,
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,
230
242
  Reanimated 4.5.1, and Worklets 0.10.1 on Expo SDK 57.
231
243
 
232
244
  ```tsx
233
- import { UIThemeProvider } from 'uitheme-rn';
245
+ import { Button, View } from 'react-native';
246
+ import { UIThemeProvider, defaultPalettes } from 'uitheme-rn';
234
247
  import {
235
248
  UIThemeTransitionProvider,
236
249
  useAnimatedUITheme,
237
250
  } from 'uitheme-rn/transitions';
238
251
 
239
- function App() {
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() {
240
262
  return (
241
- <UIThemeProvider>
263
+ <UIThemeProvider palettes={palettes}>
242
264
  <UIThemeTransitionProvider defaults={{ transition: 'circularReveal' }}>
243
- <Navigation />
265
+ <Controls />
244
266
  </UIThemeTransitionProvider>
245
267
  </UIThemeProvider>
246
268
  );
@@ -248,12 +270,25 @@ function App() {
248
270
 
249
271
  function Controls() {
250
272
  const { setTheme, setColorTheme, isTransitioning } = useAnimatedUITheme();
251
- // Call in an event handler. Commands return Promise<boolean>.
252
- // false means unchanged, interrupted before commit, or another effect is busy.
253
- const changeAppearance = () =>
254
- setTheme('dark', { transition: 'circularReveal' });
255
- const changePalette = () => setColorTheme('forest', { transition: 'wipe' });
256
- // Connect these handlers to your controls; disable them while isTransitioning.
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
+ );
257
292
  }
258
293
  ```
259
294
 
@@ -352,3 +387,17 @@ resolved CSS scope. Use `useAnimatedUITheme()` for animated appearance and
352
387
  palette commands. Semantic colors follow the provider's resolved mode without
353
388
  changing OS Appearance. NativeWind's global `dark:` variant still follows the
354
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uitheme-rn",
3
- "version": "0.1.0-alpha",
3
+ "version": "1.0.0",
4
4
  "description": "Native appearance and color palettes for React Native and Expo",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -110,12 +110,12 @@
110
110
  },
111
111
  "peerDependencies": {
112
112
  "@expo/ui": ">=56.0.0 <58",
113
- "@shopify/react-native-skia": ">=2.6.2 <3",
113
+ "@shopify/react-native-skia": ">=2.11.1 <2.12",
114
114
  "react": ">=19.2.0 <20",
115
115
  "react-native": ">=0.83.0 <0.87",
116
- "react-native-reanimated": ">=4.5.1 <5",
116
+ "react-native-reanimated": ">=4.5.1 <4.6",
117
117
  "react-native-worklets": ">=0.10.1 <0.11",
118
- "nativewind": ">=5.0.0-rc.0 <6",
118
+ "nativewind": "5.0.0-rc.0",
119
119
  "uniwind": ">=1.12.2 <2"
120
120
  },
121
121
  "peerDependenciesMeta": {
@@ -140,7 +140,7 @@
140
140
  },
141
141
  "devDependencies": {
142
142
  "@expo/ui": "~57.0.22",
143
- "@shopify/react-native-skia": "2.6.2",
143
+ "@shopify/react-native-skia": "2.11.1",
144
144
  "@types/react": "~19.2.2",
145
145
  "@types/react-dom": "~19.2.2",
146
146
  "nativewind": "5.0.0-rc.0",