@sigx/lynx-appearance 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/android/com/sigx/appearance/AppearanceModule.kt

@@ -0,0 +1,160 @@
+package com.sigx.appearance
+
+import android.app.Activity
+import android.content.Context
+import android.content.ContextWrapper
+import android.content.res.Configuration
+import android.graphics.Color
+import android.os.Build
+import android.util.Log
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsControllerCompat
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyMap
+import com.lynx.react.bridge.ReadableMap
+
+/**
+ * System-bar appearance setters + a sync getter for the current color scheme.
+ * JS usage:
+ *   NativeModules.Appearance.setStatusBarStyle({ "style": "light" }, callback)
+ *   NativeModules.Appearance.getColorScheme(callback)
+ *
+ * Status-bar / nav-bar style maps to `WindowInsetsControllerCompat`:
+ *   - "light" style ⇒ light icons on a dark background ⇒
+ *     isAppearanceLightStatusBars = false (the FLAG_LIGHT_STATUS_BAR meaning
+ *     is inverse of its name — it controls whether the *background* is light,
+ *     i.e. icons go dark).
+ *   - "dark" style ⇒ dark icons ⇒ isAppearanceLightStatusBars = true.
+ */
+class AppearanceModule(context: Context) : LynxModule(context) {
+
+    private companion object {
+        const val TAG = "AppearanceModule"
+    }
+
+    @LynxMethod
+    fun setStatusBarStyle(params: ReadableMap?, callback: Callback?) {
+        val style = params?.getString("style") ?: "default"
+        val activity = findActivity(mContext)
+        if (activity == null) {
+            callback?.invoke(errorMap("No hosting Activity found"))
+            return
+        }
+        activity.runOnUiThread {
+            try {
+                val controller = controller(activity)
+                controller.isAppearanceLightStatusBars = style == "dark"
+                callback?.invoke(okMap())
+            } catch (e: Throwable) {
+                Log.w(TAG, "setStatusBarStyle failed: ${e.message}")
+                callback?.invoke(errorMap(e.message ?: "setStatusBarStyle failed"))
+            }
+        }
+    }
+
+    @LynxMethod
+    fun setStatusBarBackgroundColor(params: ReadableMap?, callback: Callback?) {
+        val color = params?.getString("color")
+        val activity = findActivity(mContext)
+        if (activity == null) {
+            callback?.invoke(errorMap("No hosting Activity found"))
+            return
+        }
+        activity.runOnUiThread {
+            try {
+                // Setting statusBarColor on API 35+ (Android 15) does nothing —
+                // edge-to-edge is enforced and the system bar background is
+                // always transparent. Callers should overlay their own
+                // background view instead.
+                @Suppress("DEPRECATION")
+                activity.window.statusBarColor = parseColorOrTransparent(color)
+                callback?.invoke(okMap())
+            } catch (e: Throwable) {
+                Log.w(TAG, "setStatusBarBackgroundColor failed: ${e.message}")
+                callback?.invoke(errorMap(e.message ?: "setStatusBarBackgroundColor failed"))
+            }
+        }
+    }
+
+    @LynxMethod
+    fun setNavigationBarStyle(params: ReadableMap?, callback: Callback?) {
+        val style = params?.getString("style") ?: "default"
+        val color = if (params?.hasKey("color") == true) params.getString("color") else null
+        val activity = findActivity(mContext)
+        if (activity == null) {
+            callback?.invoke(errorMap("No hosting Activity found"))
+            return
+        }
+        activity.runOnUiThread {
+            try {
+                val controller = controller(activity)
+                controller.isAppearanceLightNavigationBars = style == "dark"
+                if (color != null) {
+                    @Suppress("DEPRECATION")
+                    activity.window.navigationBarColor = parseColorOrTransparent(color)
+                }
+                callback?.invoke(okMap())
+            } catch (e: Throwable) {
+                Log.w(TAG, "setNavigationBarStyle failed: ${e.message}")
+                callback?.invoke(errorMap(e.message ?: "setNavigationBarStyle failed"))
+            }
+        }
+    }
+
+    @LynxMethod
+    fun getColorScheme(callback: Callback?) {
+        val night = mContext.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+        val scheme = if (night == Configuration.UI_MODE_NIGHT_YES) "dark" else "light"
+        val map = JavaOnlyMap()
+        map.putString("colorScheme", scheme)
+        callback?.invoke(map)
+    }
+
+    private fun controller(activity: Activity): WindowInsetsControllerCompat {
+        // WindowCompat.getInsetsController is the public-API-version-agnostic
+        // path; under the hood it uses WindowInsetsControllerCompat which
+        // delegates to WindowInsetsController on R+ and the deprecated
+        // SystemUiVisibility flags below.
+        return WindowCompat.getInsetsController(activity.window, activity.window.decorView)
+    }
+
+    private fun parseColorOrTransparent(hex: String?): Int {
+        if (hex.isNullOrBlank()) return Color.TRANSPARENT
+        return try {
+            Color.parseColor(hex)
+        } catch (_: IllegalArgumentException) {
+            Color.TRANSPARENT
+        }
+    }
+
+    private fun findActivity(ctx: Context?): Activity? {
+        var cur: Context? = ctx
+        while (cur is ContextWrapper) {
+            if (cur is Activity) return cur
+            cur = cur.baseContext
+        }
+        return null
+    }
+
+    private fun okMap(): JavaOnlyMap {
+        val m = JavaOnlyMap()
+        m.putBoolean("ok", true)
+        return m
+    }
+
+    private fun errorMap(message: String): JavaOnlyMap {
+        val m = JavaOnlyMap()
+        m.putBoolean("ok", false)
+        m.putString("reason", message)
+        return m
+    }
+
+    // Keep API 35+ awareness from triggering a "field never used" warning on
+    // older toolchains.
+    @Suppress("unused")
+    private fun targetsApi35Plus(activity: Activity): Boolean =
+        Build.VERSION.SDK_INT >= 35 &&
+            activity.applicationInfo.targetSdkVersion >= 35
+}

package/android/com/sigx/appearance/AppearancePublisher.kt

@@ -0,0 +1,113 @@
+package com.sigx.appearance
+
+import android.content.ComponentCallbacks
+import android.content.ComponentCallbacks2
+import android.content.Context
+import android.content.res.Configuration
+import android.util.Log
+import android.view.View
+import com.lynx.react.bridge.JavaOnlyArray
+import com.lynx.react.bridge.JavaOnlyMap
+import com.lynx.tasm.LynxView
+import com.lynx.tasm.TemplateData
+
+/**
+ * Publishes the host's current system color scheme (`light` / `dark`) to JS via:
+ *
+ * 1. **`lynx.__globalProps.appearance`** — populated synchronously via
+ *    [LynxView.updateGlobalProps] before MT first paint, so apps render the
+ *    correct theme on cold start with no flash.
+ *
+ * 2. **`appearanceChanged` global event** — fired via [LynxView.sendGlobalEvent]
+ *    after each republish. The JS `<AppearanceProvider>` subscribes via
+ *    `lynx.getJSModule("GlobalEventEmitter").addListener` and updates its
+ *    reactive signal so consumers (`<ThemeProvider followSystem>`) swap themes
+ *    live when the user toggles dark mode in system settings.
+ *
+ * Lifecycle: one publisher per LynxView. [attach] is called by the autolinker
+ * via `GeneratedLifecyclePublishers.attachAll(lynxView)`. We register a
+ * `ComponentCallbacks2` on the application context to catch
+ * `onConfigurationChanged` (the only reliable signal for runtime dark-mode
+ * flips) and unregister on view detach.
+ */
+class AppearancePublisher(private val lynxView: LynxView) {
+
+    private companion object {
+        const val TAG = "AppearancePublisher"
+        const val EVENT_NAME = "appearanceChanged"
+    }
+
+    private var lastScheme: String = ""
+    private var callbacks: ComponentCallbacks? = null
+
+    fun attach() {
+        // Seed synchronously so __globalProps is populated before MT first
+        // paint reads it. Reading the LynxView's own resources gives the host
+        // window's effective configuration (accounts for app-level
+        // android:configChanges and overrideConfiguration on the activity).
+        publish(lynxView.resources.configuration)
+
+        // Register ComponentCallbacks2 on the application so we get
+        // onConfigurationChanged when the user flips system dark mode in
+        // Settings → Display while the app is foregrounded. View-level
+        // dispatch is unreliable: onConfigurationChanged on a View only fires
+        // if the Activity declares android:configChanges, which most apps
+        // don't (and shouldn't).
+        val appCtx = lynxView.context.applicationContext
+        val cb = object : ComponentCallbacks2 {
+            override fun onConfigurationChanged(newConfig: Configuration) {
+                publish(newConfig)
+            }
+            override fun onLowMemory() {}
+            override fun onTrimMemory(level: Int) {}
+        }
+        appCtx.registerComponentCallbacks(cb)
+        callbacks = cb
+
+        // Detach safely when the LynxView leaves the window — covers
+        // activity recreation, single-LynxView teardown during HMR, etc.
+        lynxView.addOnAttachStateChangeListener(object : View.OnAttachStateChangeListener {
+            override fun onViewAttachedToWindow(v: View) {}
+            override fun onViewDetachedFromWindow(v: View) {
+                detach(appCtx)
+                v.removeOnAttachStateChangeListener(this)
+            }
+        })
+    }
+
+    private fun detach(appCtx: Context) {
+        callbacks?.let {
+            try {
+                appCtx.unregisterComponentCallbacks(it)
+            } catch (_: Throwable) {
+                // unregister can throw if the callback was never registered;
+                // ignore — there's nothing the host can do about it.
+            }
+            callbacks = null
+        }
+    }
+
+    private fun publish(config: Configuration) {
+        val night = config.uiMode and Configuration.UI_MODE_NIGHT_MASK
+        val scheme = if (night == Configuration.UI_MODE_NIGHT_YES) "dark" else "light"
+        if (scheme == lastScheme) return
+        lastScheme = scheme
+
+        val map: Map<String, Any> = mapOf("colorScheme" to scheme)
+
+        try {
+            // Channel 1: __globalProps — sync MT read at first paint.
+            lynxView.updateGlobalProps(TemplateData.fromMap(mapOf("appearance" to map)))
+
+            // Channel 2: appearanceChanged event — live BG update.
+            val payload = JavaOnlyMap().apply { putString("colorScheme", scheme) }
+            val params = JavaOnlyArray().apply { pushMap(payload) }
+            lynxView.sendGlobalEvent(EVENT_NAME, params)
+        } catch (e: Throwable) {
+            // Defensive — bridge calls during teardown can throw. The next
+            // configuration change will republish, so a dropped publish here
+            // is non-fatal.
+            Log.w(TAG, "publish failed: ${e.message}")
+        }
+    }
+}

package/dist/globals.d.ts

@@ -0,0 +1,21 @@
+import type { ColorScheme } from './types.js';
+/**
+ * Key under `lynx.__globalProps` where the native publisher writes the
+ * appearance map. Single string shared by iOS / Android publishers, the JS
+ * reader, and tests.
+ */
+export declare const GLOBAL_PROPS_KEY = "appearance";
+export interface RawAppearanceProps {
+    colorScheme?: ColorScheme;
+}
+/**
+ * Synchronously read the current system color scheme from
+ * `lynx.__globalProps`. Returns `null` when the publisher hasn't populated
+ * yet (early cold start) or when running outside a Lynx host (web preview,
+ * SSR, tests). Callers should treat `null` as "unknown — fall back to your
+ * default theme".
+ *
+ * Safe on both BG and MT threads — `__globalProps` is mirrored across both.
+ */
+export declare function readGlobalColorScheme(): ColorScheme | null;
+//# sourceMappingURL=globals.d.ts.map

package/dist/globals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAYD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,GAAG,IAAI,CAO1D"}

package/dist/globals.js

@@ -0,0 +1,25 @@
+/**
+ * Key under `lynx.__globalProps` where the native publisher writes the
+ * appearance map. Single string shared by iOS / Android publishers, the JS
+ * reader, and tests.
+ */
+export const GLOBAL_PROPS_KEY = 'appearance';
+/**
+ * Synchronously read the current system color scheme from
+ * `lynx.__globalProps`. Returns `null` when the publisher hasn't populated
+ * yet (early cold start) or when running outside a Lynx host (web preview,
+ * SSR, tests). Callers should treat `null` as "unknown — fall back to your
+ * default theme".
+ *
+ * Safe on both BG and MT threads — `__globalProps` is mirrored across both.
+ */
+export function readGlobalColorScheme() {
+    const lynxObj = typeof lynx !== 'undefined'
+        ? lynx
+        : undefined;
+    const raw = lynxObj?.__globalProps?.[GLOBAL_PROPS_KEY];
+    if (!raw || typeof raw !== 'object')
+        return null;
+    return raw.colorScheme === 'dark' ? 'dark' : raw.colorScheme === 'light' ? 'light' : null;
+}
+//# sourceMappingURL=globals.js.map

package/dist/globals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globals.js","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAgB7C;;;;;;;;GAQG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAA+B,OAAO,IAAI,KAAK,WAAW;QACrE,CAAC,CAAE,IAAkC;QACrC,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,GAAG,GAAG,OAAO,EAAE,aAAa,EAAE,CAAC,gBAAgB,CAAmC,CAAC;IACzF,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,OAAO,GAAG,CAAC,WAAW,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC5F,CAAC"}

package/dist/hooks.d.ts

@@ -0,0 +1,25 @@
+import { type Computed, type PrimitiveSignal } from '@sigx/reactivity';
+import type { ColorScheme } from './types.js';
+type ColorSchemeRead = PrimitiveSignal<ColorScheme> | Computed<ColorScheme>;
+/**
+ * BG-side reactive read of the current system color scheme. Returns the
+ * live signal — components calling this re-render when the user flips dark
+ * mode in system settings.
+ *
+ * If no `<AppearanceProvider>` is in scope, returns a fallback signal seeded
+ * from `lynx.__globalProps` once at first call (still gives the correct
+ * value on cold start; just doesn't update live). This lets ThemeProvider
+ * use the hook even when its consumer hasn't mounted `<AppearanceProvider>`.
+ */
+export declare function useSystemColorScheme(): ColorSchemeRead;
+/**
+ * MT-thread synchronous read of the current system color scheme. For use
+ * inside `'main thread'`-marked worklet bodies. Reads `lynx.__globalProps`
+ * directly — no subscription, callers re-evaluate per worklet invocation.
+ *
+ * Returns `'light'` when the publisher hasn't populated yet (cold start before
+ * first publish, or non-Lynx hosts).
+ */
+export declare function useSystemColorSchemeMT(): ColorScheme;
+export type { PrimitiveSignal, Computed } from '@sigx/reactivity';
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAG/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,eAAe,GAAG,eAAe,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;AAE5E;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,IAAI,eAAe,CAItD;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,IAAI,WAAW,CAEpD;AAYD,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/hooks.js

@@ -0,0 +1,38 @@
+import { signal } from '@sigx/reactivity';
+import { useAppearanceContext } from './injectable.js';
+import { readGlobalColorScheme } from './globals.js';
+/**
+ * BG-side reactive read of the current system color scheme. Returns the
+ * live signal — components calling this re-render when the user flips dark
+ * mode in system settings.
+ *
+ * If no `<AppearanceProvider>` is in scope, returns a fallback signal seeded
+ * from `lynx.__globalProps` once at first call (still gives the correct
+ * value on cold start; just doesn't update live). This lets ThemeProvider
+ * use the hook even when its consumer hasn't mounted `<AppearanceProvider>`.
+ */
+export function useSystemColorScheme() {
+    const ctx = useAppearanceContext();
+    if (ctx)
+        return ctx.colorScheme;
+    return fallbackSignal();
+}
+/**
+ * MT-thread synchronous read of the current system color scheme. For use
+ * inside `'main thread'`-marked worklet bodies. Reads `lynx.__globalProps`
+ * directly — no subscription, callers re-evaluate per worklet invocation.
+ *
+ * Returns `'light'` when the publisher hasn't populated yet (cold start before
+ * first publish, or non-Lynx hosts).
+ */
+export function useSystemColorSchemeMT() {
+    return readGlobalColorScheme() ?? 'light';
+}
+let _fallback;
+function fallbackSignal() {
+    if (!_fallback) {
+        _fallback = signal(readGlobalColorScheme() ?? 'light');
+    }
+    return _fallback;
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAuC,MAAM,kBAAkB,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAKrD;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,GAAG,oBAAoB,EAAE,CAAC;IACnC,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC,WAAW,CAAC;IAChC,OAAO,cAAc,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,qBAAqB,EAAE,IAAI,OAAO,CAAC;AAC5C,CAAC;AAED,IAAI,SAAmD,CAAC;AACxD,SAAS,cAAc;IACrB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,MAAM,CAAc,qBAAqB,EAAE,IAAI,OAAO,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { AppearanceProvider, APPEARANCE_EVENT } from './provider.js';
+export type { AppearanceProviderProps } from './provider.js';
+export { useAppearanceContext } from './injectable.js';
+export type { AppearanceContextValue } from './injectable.js';
+export { useSystemColorScheme, useSystemColorSchemeMT, } from './hooks.js';
+export { setStatusBarStyle, setStatusBarBackgroundColor, setNavigationBarStyle, setSystemBarsStyle, isAvailable, } from './setters.js';
+export { readGlobalColorScheme, GLOBAL_PROPS_KEY, } from './globals.js';
+export type { RawAppearanceProps } from './globals.js';
+export type { ColorScheme, SystemBarStyle, SystemBarsStyleInput, SetterResult, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACrE,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,YAAY,EACV,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Public API for @sigx/lynx-appearance.
+export { AppearanceProvider, APPEARANCE_EVENT } from './provider.js';
+export { useAppearanceContext } from './injectable.js';
+export { useSystemColorScheme, useSystemColorSchemeMT, } from './hooks.js';
+export { setStatusBarStyle, setStatusBarBackgroundColor, setNavigationBarStyle, setSystemBarsStyle, isAvailable, } from './setters.js';
+export { readGlobalColorScheme, GLOBAL_PROPS_KEY, } from './globals.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAExC,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAGvD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,GACjB,MAAM,cAAc,CAAC"}

package/dist/injectable.d.ts

@@ -0,0 +1,16 @@
+import type { PrimitiveSignal } from '@sigx/reactivity';
+import type { ColorScheme } from './types.js';
+/** DI shape exposed by `<AppearanceProvider>`. */
+export interface AppearanceContextValue {
+    /** BG-side reactive color scheme. Re-renders consumers on system flip. */
+    readonly colorScheme: PrimitiveSignal<ColorScheme>;
+}
+/**
+ * The DI handle for the appearance context.
+ *
+ * Factory returns `null` so consumers outside a provider get a clear signal
+ * (vs. a phantom `'light'` signal that silently never updates). Hooks in
+ * `./hooks.ts` wrap this with the null-check + fallback signal.
+ */
+export declare const useAppearanceContext: import("@sigx/runtime-core").InjectableFunction<AppearanceContextValue | null>;
+//# sourceMappingURL=injectable.d.ts.map

package/dist/injectable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.d.ts","sourceRoot":"","sources":["../src/injectable.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC,WAAW,CAAC,CAAC;CACpD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,gFAEhC,CAAC"}

package/dist/injectable.js

@@ -0,0 +1,10 @@
+import { defineInjectable } from '@sigx/lynx';
+/**
+ * The DI handle for the appearance context.
+ *
+ * Factory returns `null` so consumers outside a provider get a clear signal
+ * (vs. a phantom `'light'` signal that silently never updates). Hooks in
+ * `./hooks.ts` wrap this with the null-check + fallback signal.
+ */
+export const useAppearanceContext = defineInjectable(() => null);
+//# sourceMappingURL=injectable.js.map

package/dist/injectable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injectable.js","sourceRoot":"","sources":["../src/injectable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAU9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,gBAAgB,CAClD,GAAG,EAAE,CAAC,IAAI,CACX,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,27 @@
+import { type Define } from '@sigx/lynx';
+/**
+ * Event name fired by the native publisher (iOS `AppearancePublisher.swift`,
+ * Android `AppearancePublisher.kt`) via `GlobalEventEmitter` every time the
+ * host's system color scheme flips. Payload mirrors the same map stored under
+ * `lynx.__globalProps.appearance`.
+ *
+ * Kept as a constant so iOS/Android publishers and the JS listener agree on
+ * a single string.
+ */
+export declare const APPEARANCE_EVENT = "appearanceChanged";
+export type AppearanceProviderProps = Define.Prop<'class', string, false> & Define.Prop<'style', Record<string, string | number>, false> & Define.Slot<'default'>;
+/**
+ * Mount near the root of an app (above any consumer of `useSystemColorScheme`).
+ * Cheap — just one BG signal + one GlobalEventEmitter subscription. The
+ * native publisher writes `lynx.__globalProps.appearance` before MT first
+ * paint, so the initial value is correct on cold start with no flash.
+ *
+ * On platforms where the publisher isn't wired (web preview, tests),
+ * `readGlobalColorScheme()` returns `null` and we seed `'light'` as a safe
+ * default. Consumers can detect the unwired case via the live-update
+ * subscription never firing.
+ */
+export declare const AppearanceProvider: import("@sigx/runtime-core").ComponentFactory<AppearanceProviderProps, void, {
+    default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
+}>;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAKpB;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAapD,MAAM,MAAM,uBAAuB,GAC/B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,GACnC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EAAE,KAAK,CAAC,GAC5D,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AAE3B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;EAgC7B,CAAC"}

package/dist/provider.js

@@ -0,0 +1,59 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { component, defineProvide, signal, onMounted, onUnmounted, } from '@sigx/lynx';
+import { useAppearanceContext } from './injectable.js';
+import { readGlobalColorScheme } from './globals.js';
+/**
+ * Event name fired by the native publisher (iOS `AppearancePublisher.swift`,
+ * Android `AppearancePublisher.kt`) via `GlobalEventEmitter` every time the
+ * host's system color scheme flips. Payload mirrors the same map stored under
+ * `lynx.__globalProps.appearance`.
+ *
+ * Kept as a constant so iOS/Android publishers and the JS listener agree on
+ * a single string.
+ */
+export const APPEARANCE_EVENT = 'appearanceChanged';
+/**
+ * Mount near the root of an app (above any consumer of `useSystemColorScheme`).
+ * Cheap — just one BG signal + one GlobalEventEmitter subscription. The
+ * native publisher writes `lynx.__globalProps.appearance` before MT first
+ * paint, so the initial value is correct on cold start with no flash.
+ *
+ * On platforms where the publisher isn't wired (web preview, tests),
+ * `readGlobalColorScheme()` returns `null` and we seed `'light'` as a safe
+ * default. Consumers can detect the unwired case via the live-update
+ * subscription never firing.
+ */
+export const AppearanceProvider = component(({ props, slots }) => {
+    const initial = readGlobalColorScheme() ?? 'light';
+    const colorScheme = signal(initial);
+    const ctx = { colorScheme };
+    defineProvide(useAppearanceContext, () => ctx);
+    let listener;
+    let emitter;
+    onMounted(() => {
+        const lynxObj = typeof lynx !== 'undefined'
+            ? lynx
+            : undefined;
+        emitter = lynxObj?.getJSModule?.('GlobalEventEmitter');
+        if (!emitter)
+            return;
+        listener = (raw) => {
+            const next = normaliseScheme(raw);
+            if (next && next !== colorScheme.value)
+                colorScheme.value = next;
+        };
+        emitter.addListener(APPEARANCE_EVENT, listener);
+    });
+    onUnmounted(() => {
+        if (emitter && listener)
+            emitter.removeListener(APPEARANCE_EVENT, listener);
+    });
+    return () => (_jsx("view", { class: props.class, style: props.style, children: slots.default?.() }));
+});
+function normaliseScheme(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const v = raw['colorScheme'];
+    return v === 'dark' ? 'dark' : v === 'light' ? 'light' : null;
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,SAAS,EACT,aAAa,EACb,MAAM,EACN,SAAS,EACT,WAAW,GAEZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAA+B,MAAM,iBAAiB,CAAC;AACpF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAkBpD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAA0B,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE;IACxF,MAAM,OAAO,GAAgB,qBAAqB,EAAE,IAAI,OAAO,CAAC;IAChE,MAAM,WAAW,GAAG,MAAM,CAAc,OAAO,CAAC,CAAC;IAEjD,MAAM,GAAG,GAA2B,EAAE,WAAW,EAAE,CAAC;IACpD,aAAa,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAE/C,IAAI,QAAiD,CAAC;IACtD,IAAI,OAA2C,CAAC;IAEhD,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAyB,OAAO,IAAI,KAAK,WAAW;YAC/D,CAAC,CAAE,IAA4B;YAC/B,CAAC,CAAC,SAAS,CAAC;QACd,OAAO,GAAG,OAAO,EAAE,WAAW,EAAE,CAAC,oBAAoB,CAAC,CAAC;QACvD,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,QAAQ,GAAG,CAAC,GAAY,EAAE,EAAE;YAC1B,MAAM,IAAI,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,IAAI,IAAI,IAAI,KAAK,WAAW,CAAC,KAAK;gBAAE,WAAW,CAAC,KAAK,GAAG,IAAI,CAAC;QACnE,CAAC,CAAC;QACF,OAAO,CAAC,WAAW,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,WAAW,CAAC,GAAG,EAAE;QACf,IAAI,OAAO,IAAI,QAAQ;YAAE,OAAO,CAAC,cAAc,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC;IAC9E,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,EAAE,CAAC,CACX,eAAM,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,YACzC,KAAK,CAAC,OAAO,EAAE,EAAE,GACb,CACR,CAAC;AACJ,CAAC,CAAC,CAAC;AAEH,SAAS,eAAe,CAAC,GAAY;IACnC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACjD,MAAM,CAAC,GAAI,GAA+B,CAAC,aAAa,CAAC,CAAC;IAC1D,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC"}

package/dist/setters.d.ts

@@ -0,0 +1,58 @@
+import type { SetterResult, SystemBarStyle, SystemBarsStyleInput } from './types.js';
+/**
+ * Set the status-bar *content* tint (clock + icons).
+ *
+ * - `'light'` = light content (white-ish icons) — use when behind a dark theme.
+ * - `'dark'`  = dark content — use when behind a light theme.
+ *
+ * On iOS the host VC must forward `preferredStatusBarStyle` to
+ * `AppearanceModule.preferredStatusBarStyle` for this to take effect — the
+ * lynx-cli iOS template wires that automatically.
+ *
+ * Resolves `{ ok: false, reason: 'unsupported' }` (never rejects) when the
+ * native module isn't registered — typical in web preview, SSR, tests, or
+ * apps that don't link the module. Fire-and-forget callers can therefore
+ * `void setStatusBarStyle(...)` without risking unhandled rejections.
+ */
+export declare function setStatusBarStyle(style: SystemBarStyle): Promise<SetterResult>;
+/**
+ * Android only — set the status-bar background color. Pass `null` (or
+ * omit / pass `'transparent'`) to clear. iOS resolves `{ ok: false,
+ * reason: 'unsupported' }` since iOS has no separate status-bar background.
+ *
+ * On Android 15+ (API 35) edge-to-edge is enforced and this call is a no-op
+ * at the system level — callers should overlay their own background view
+ * inside the safe-area top padding.
+ *
+ * Resolves `{ ok: false, reason: 'unsupported' }` (never rejects) when the
+ * native module isn't registered. See `setStatusBarStyle` for the rationale.
+ */
+export declare function setStatusBarBackgroundColor(color: string | null): Promise<SetterResult>;
+/**
+ * Android only — set the navigation-bar content tint + optional background.
+ * iOS resolves `{ ok: false, reason: 'unsupported' }` since there's no
+ * separate navigation bar.
+ *
+ * Resolves `{ ok: false, reason: 'unsupported' }` (never rejects) when the
+ * native module isn't registered. See `setStatusBarStyle` for the rationale.
+ */
+export declare function setNavigationBarStyle(opts: {
+    style: SystemBarStyle;
+    color?: string;
+}): Promise<SetterResult>;
+/**
+ * Convenience: apply status-bar tint + (optionally) status-bar background +
+ * nav-bar tint in one call. Resolves to the aggregate result — `ok: false`
+ * if any leg returned a non-`unsupported` failure, with the first such
+ * failure's reason. `unsupported` legs (e.g. status-bar background on iOS)
+ * are intentionally ignored so a partially-supported platform can still
+ * report success for the legs that do apply.
+ *
+ * Fields are optional; omitting any leaves that surface untouched. Order is
+ * deterministic (statusBar → statusBarBackground → navigationBar) so the
+ * resolved reason on partial failure is unambiguous.
+ */
+export declare function setSystemBarsStyle(opts: SystemBarsStyleInput): Promise<SetterResult>;
+/** Quick check whether the native Appearance module is registered. */
+export declare function isAvailable(): boolean;
+//# sourceMappingURL=setters.d.ts.map

package/dist/setters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setters.d.ts","sourceRoot":"","sources":["../src/setters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMrF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAG9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAGvF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAG5G;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAY1F;AAED,sEAAsE;AACtE,wBAAgB,WAAW,IAAI,OAAO,CAErC"}