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 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
- # Temporary Holding Version
1
+ # uitheme-rn
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ });
@@ -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 };