@sigx/lynx-appearance 0.4.1 → 0.4.3

package/README.md

@@ -0,0 +1,93 @@
+# @sigx/lynx-appearance
+
+System color-scheme observer + status-bar / navigation-bar tint setters for sigx-lynx. The native publisher writes `lynx.__globalProps.appearance` before MT first paint, so the initial light/dark value is available on cold start with no flash; subsequent system flips publish through `GlobalEventEmitter` and update a BG signal.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-appearance
+```
+
+`sigx prebuild` auto-discovers the package, registers `AppearanceModule` / `AppearancePublisher` on both platforms, and wires the iOS host VC to forward `preferredStatusBarStyle` to the module so `setStatusBarStyle(...)` actually takes effect.
+
+## Usage
+
+Mount the provider once near the root, then read the color scheme reactively from any component:
+
+```tsx
+import { component, effect } from '@sigx/lynx';
+import {
+    AppearanceProvider,
+    useSystemColorScheme,
+    setSystemBarsStyle,
+} from '@sigx/lynx-appearance';
+
+const Root = component(() => () => (
+    <AppearanceProvider>
+        <App />
+    </AppearanceProvider>
+));
+
+const App = component(() => {
+    const scheme = useSystemColorScheme();
+
+    // Keep the system bars in sync with the current scheme.
+    effect(() => {
+        void setSystemBarsStyle({
+            statusBar: scheme.value === 'dark' ? 'light' : 'dark',
+            statusBarBackground: scheme.value === 'dark' ? '#000' : '#fff',
+            navigationBar: { style: scheme.value === 'dark' ? 'light' : 'dark' },
+        });
+    });
+
+    return () => (
+        <text>System is {scheme.value} mode</text>
+    );
+});
+```
+
+From inside a `'main thread'` worklet, use the sync variant — no subscription, reads `lynx.__globalProps` directly:
+
+```ts
+import { useSystemColorSchemeMT } from '@sigx/lynx-appearance';
+// inside a main-thread worklet body:
+const isDark = useSystemColorSchemeMT() === 'dark';
+```
+
+## API
+
+| Surface | Use for |
+|---|---|
+| `AppearanceProvider` | Mount once near the root. Provides the live color-scheme signal to descendants. |
+| `useSystemColorScheme()` | BG-side reactive read. Returns a signal of `'light' \| 'dark'`. Re-runs effects when the user flips dark mode in system settings. |
+| `useSystemColorSchemeMT()` | MT-side sync read. Returns `'light' \| 'dark'` from `lynx.__globalProps`. For use inside `'main thread'` worklet bodies. |
+| `setStatusBarStyle(style)` | Set status-bar *content* tint. `'light'` = light icons (legible on dark bg). |
+| `setStatusBarBackgroundColor(color)` | **Android only** — status-bar background color (`null` clears). iOS resolves `{ ok: false, reason: 'unsupported' }`. |
+| `setNavigationBarStyle({ style, color? })` | **Android only** — navigation-bar tint + optional background. iOS resolves `{ ok: false, reason: 'unsupported' }`. |
+| `setSystemBarsStyle({ statusBar?, statusBarBackground?, navigationBar? })` | Convenience — apply all three in one deterministic call. Returns first non-`unsupported` failure, or `{ ok: true }`. |
+| `isAvailable()` | Whether the native Appearance module is registered in the current build. |
+| `APPEARANCE_EVENT` | The event name (`'appearanceChanged'`) fired by the native publishers. Exported so iOS / Android / JS agree on a single string. |
+
+```ts
+type ColorScheme = 'light' | 'dark';
+type SystemBarStyle = 'light' | 'dark';
+interface SetterResult {
+    ok: boolean;
+    /** Present when `ok === false` — e.g. `'unsupported'` on iOS for
+     *  nav-bar / status-bar-background calls. */
+    reason?: string;
+}
+```
+
+All setters return `Promise<SetterResult>` and **never reject** — unwired platforms, web preview, SSR, and test runs all resolve to `{ ok: false, reason: 'unsupported' }`. You can therefore `void setSystemBarsStyle(...)` without risking unhandled rejections.
+
+## Gotchas
+
+- **iOS status-bar style needs host VC forwarding.** `setStatusBarStyle(...)` resolves successfully but won't visibly change anything unless the host view controller forwards `preferredStatusBarStyle` to `AppearanceModule.preferredStatusBarStyle`. The lynx-cli iOS template does this automatically; if you're integrating into an existing UIViewController, copy the forwarding pattern.
+- **Android 15+ (API 35) edge-to-edge.** `setStatusBarBackgroundColor` is a no-op at the system level on API 35+ because edge-to-edge is enforced. Render your own background view inside the safe-area top padding instead — pairs naturally with [`@sigx/lynx-safe-area`](https://github.com/signalxjs/lynx/tree/main/packages/lynx-safe-area).
+- **`'light'` vs `'dark'` is the *content* tint, not the background.** `style: 'light'` means "light-colored icons" (so a dark background behind them is legible). Easy to flip the wrong way the first time.
+- **Cold-start value.** `readGlobalColorScheme()` reads the value the native publisher wrote before first paint. If it returns `null` (e.g. running on a host that didn't link the publisher), the hook seeds `'light'` as a safe default.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-appearance",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "System appearance (color scheme observation + status/navigation bar tint setters) for sigx-lynx",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,15 +31,15 @@
   "license": "MIT",
   "dependencies": {
     "@sigx/reactivity": "^0.4.8",
-    "@sigx/lynx": "^0.4.1",
-    "@sigx/lynx-core": "^0.4.1"
+    "@sigx/lynx": "^0.4.3",
+    "@sigx/lynx-core": "^0.4.3"
   },
   "devDependencies": {
     "@typescript/native-preview": "7.0.0-dev.20260521.1",
     "typescript": "^6.0.3",
-    "@sigx/lynx-plugin": "^0.4.1",
-    "@sigx/lynx-testing": "^0.4.1",
-    "@sigx/lynx-runtime-main": "^0.4.1"
+    "@sigx/lynx-plugin": "^0.4.3",
+    "@sigx/lynx-testing": "^0.4.3",
+    "@sigx/lynx-runtime-main": "^0.4.3"
   },
   "repository": {
     "type": "git",