rn-system-bar 3.1.7 → 3.1.8

package/src/types.ts

@@ -12,6 +12,45 @@ export type NavigationBarStyle = "auto" | "inverted" | "light" | "dark";
 export type NavigationBarVisibility = "visible" | "hidden";
 export type StatusBarStyle = "light" | "dark";
 
+/**
+ * Navigation bar color value.
+ *
+ * - Any CSS hex string  →  solid colour      e.g. "#1a1a2e", "#000"
+ * - `"transparent"`     →  fully transparent  (FLAG_DRAWS_SYSTEM_BAR_BACKGROUNDS +
+ *                           transparent color; content draws behind bar)
+ * - `"translucent"`     →  semi-transparent   (FLAG_TRANSLUCENT_NAVIGATION)
+ */
+export type NavigationBarColorValue = string | "transparent" | "translucent";
+
+/**
+ * Status bar background color value.
+ *
+ * - Any CSS hex string  →  solid colour
+ * - `"transparent"`     →  fully transparent  (draws behind content)
+ * - `"translucent"`     →  semi-transparent
+ */
+export type StatusBarColorValue = string | "transparent" | "translucent";
+
+// ─────────────────────────────────────────────
+//  Theme
+// ─────────────────────────────────────────────
+
+/**
+ * "system"  → follow the OS Appearance (dark/light).
+ * "dark"    → force dark.
+ * "light"   → force light.
+ */
+export type ThemeMode = "system" | "dark" | "light";
+
+export interface ThemeState {
+  /** Resolved dark-mode flag. Always a concrete boolean. */
+  isDark: boolean;
+  /** Currently active override ("system" = following OS). */
+  mode: ThemeMode;
+  /** Set the override mode. Pass "system" to revert to OS. */
+  setMode: (mode: ThemeMode) => void;
+}
+
 export type Orientation =
   | "portrait"
   | "landscape"
@@ -26,14 +65,59 @@ export type VolumeStream =
   | "alarm"
   | "system";
 
+// ─────────────────────────────────────────────
+//  System screencast  (external display / HDMI)
+// ─────────────────────────────────────────────
+
 export interface ScreencastDisplay {
   id: number;
   name: string;
   isValid: boolean;
 }
 
-export interface ScreencastInfo {
+/** Result of getSystemScreencastInfo() — physical/HDMI/Miracast external display. */
+export interface SystemScreencastInfo {
   isCasting: boolean;
   displayName: string | null;
   displays: ScreencastDisplay[];
 }
+
+// ─────────────────────────────────────────────
+//  App-only cast  (MediaRouter — Chromecast / TV)
+// ─────────────────────────────────────────────
+
+/** Connection state of the in-app cast session. */
+export type AppCastState =
+  | "idle"
+  | "scanning"
+  | "connecting"
+  | "connected"
+  | "disconnecting";
+
+/** A discovered castable device (TV, Chromecast, etc.). */
+export interface AppCastDevice {
+  /** Unique route ID from MediaRouter. */
+  id: string;
+  /** Human-readable device name e.g. "Living Room TV". */
+  name: string;
+  /** Device description / model string (may be null). */
+  description: string | null;
+  /** Signal strength 0–100, or null if unavailable. */
+  signalStrength: number | null;
+  /** Whether a pairing/PIN step is required. */
+  requiresPairing: boolean;
+}
+
+/** Full snapshot of in-app cast state. */
+export interface AppCastInfo {
+  state: AppCastState;
+  /** Devices found during the last scan. */
+  devices: AppCastDevice[];
+  /** The device currently connected (or connecting). */
+  connectedDevice: AppCastDevice | null;
+  /** Error message from the last failed operation. */
+  error: string | null;
+}
+
+/** @deprecated Use SystemScreencastInfo */
+export interface ScreencastInfo extends SystemScreencastInfo {}

package/src/useSystemBar.ts

@@ -2,32 +2,43 @@
 //  rn-system-bar · useSystemBar.ts
 // ─────────────────────────────────────────────
 
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import * as SystemBar from "./SystemBar";
 import type {
+  AppCastInfo,
   NavigationBarBehavior,
   NavigationBarButtonStyle,
+  NavigationBarColorValue,
   NavigationBarStyle,
   NavigationBarVisibility,
   Orientation,
-  ScreencastInfo,
+  StatusBarColorValue,
   StatusBarStyle,
+  SystemScreencastInfo,
+  ThemeMode,
+  ThemeState,
 } from "./types";
-import * as SystemBar from "./SystemBar";
+import { useTheme } from "./useTheme";
 
 // ─────────────────────────────────────────────
-//  useSystemBar — apply system bar config safely
-//  All async calls run inside useEffect — no Suspense crash
+//  SystemBarConfig
 // ─────────────────────────────────────────────
+
 export interface SystemBarConfig {
-  navigationBarColor?: string;
+  // Navigation bar (Android-only)
+  navigationBarColor?: NavigationBarColorValue;
   navigationBarVisibility?: NavigationBarVisibility;
   navigationBarButtonStyle?: NavigationBarButtonStyle;
   navigationBarStyle?: NavigationBarStyle;
   navigationBarBehavior?: NavigationBarBehavior;
-  statusBarColor?: string;
+
+  // Status bar
+  statusBarColor?: StatusBarColorValue;
   statusBarStyle?: StatusBarStyle;
   statusBarVisible?: boolean;
   statusBarAnimated?: boolean;
+
+  // Screen
   keepScreenOn?: boolean;
   immersiveMode?: boolean;
   brightness?: number;
@@ -35,7 +46,20 @@ export interface SystemBarConfig {
   secureScreen?: boolean;
 }
 
-export const useSystemBar = (config: SystemBarConfig) => {
+// ─────────────────────────────────────────────
+//  useSystemBar
+//  Apply system bar settings declaratively.
+//
+//  @example
+//  useSystemBar({
+//    navigationBarColor:       "transparent",
+//    navigationBarButtonStyle: "light",
+//    statusBarStyle:           "light",
+//    keepScreenOn:             true,
+//  });
+// ─────────────────────────────────────────────
+
+export const useSystemBar = (config: SystemBarConfig): void => {
   const configRef = useRef("");
   const configStr = JSON.stringify(config);
 
@@ -44,43 +68,197 @@ export const useSystemBar = (config: SystemBarConfig) => {
     configRef.current = configStr;
 
     const apply = async () => {
-      // All nav bar calls are now sync (no expo-navigation-bar)
-      if (config.navigationBarColor       !== undefined) SystemBar.setNavigationBarColor(config.navigationBarColor);
-      if (config.navigationBarVisibility  !== undefined) SystemBar.setNavigationBarVisibility(config.navigationBarVisibility);
-      if (config.navigationBarButtonStyle !== undefined) SystemBar.setNavigationBarButtonStyle(config.navigationBarButtonStyle);
-      if (config.navigationBarStyle       !== undefined) SystemBar.setNavigationBarStyle(config.navigationBarStyle);
-      if (config.navigationBarBehavior    !== undefined) SystemBar.setNavigationBarBehavior(config.navigationBarBehavior);
-      if (config.statusBarStyle           !== undefined) SystemBar.setStatusBarStyle(config.statusBarStyle);
-      if (config.statusBarVisible         !== undefined) SystemBar.setStatusBarVisibility(config.statusBarVisible);
-      if (config.keepScreenOn             !== undefined) SystemBar.keepScreenOn(config.keepScreenOn);
-      if (config.immersiveMode            !== undefined) SystemBar.immersiveMode(config.immersiveMode);
-      if (config.brightness               !== undefined) SystemBar.setBrightness(config.brightness);
-      if (config.orientation              !== undefined) SystemBar.setOrientation(config.orientation);
-      if (config.secureScreen             !== undefined) SystemBar.setSecureScreen(config.secureScreen);
+      if (config.navigationBarColor !== undefined)
+        SystemBar.setNavigationBarColor(config.navigationBarColor);
+      if (config.navigationBarVisibility !== undefined)
+        SystemBar.setNavigationBarVisibility(config.navigationBarVisibility);
+      if (config.navigationBarButtonStyle !== undefined)
+        SystemBar.setNavigationBarButtonStyle(config.navigationBarButtonStyle);
+      if (config.navigationBarStyle !== undefined)
+        SystemBar.setNavigationBarStyle(config.navigationBarStyle);
+      if (config.navigationBarBehavior !== undefined)
+        SystemBar.setNavigationBarBehavior(config.navigationBarBehavior);
+      if (config.statusBarColor !== undefined)
+        SystemBar.setStatusBarColor(config.statusBarColor);
+      if (config.statusBarStyle !== undefined)
+        SystemBar.setStatusBarStyle(config.statusBarStyle);
+      if (config.statusBarVisible !== undefined)
+        SystemBar.setStatusBarVisibility(config.statusBarVisible);
+      if (config.keepScreenOn !== undefined)
+        SystemBar.keepScreenOn(config.keepScreenOn);
+      if (config.immersiveMode !== undefined)
+        SystemBar.immersiveMode(config.immersiveMode);
+      if (config.brightness !== undefined)
+        SystemBar.setBrightness(config.brightness);
+      if (config.orientation !== undefined)
+        SystemBar.setOrientation(config.orientation);
+      if (config.secureScreen !== undefined)
+        SystemBar.setSecureScreen(config.secureScreen);
     };
 
     apply().catch(() => {
-      if (__DEV__) console.warn("[rn-system-bar] useSystemBar: one or more settings failed.");
+      if (__DEV__)
+        console.warn(
+          "[rn-system-bar] useSystemBar: one or more settings failed.",
+        );
     });
-  // eslint-disable-next-line react-hooks/exhaustive-deps
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [configStr]);
 };
 
 // ─────────────────────────────────────────────
-//  useScreencast
+//  ThemedSystemBarConfig + useThemeSystemBar
+//
+//  Combines useTheme() + useSystemBar() — nav/status bars
+//  automatically update whenever the theme changes (OS or manual).
+//
+//  @example
+//  const { isDark, mode, setMode } = useThemeSystemBar({
+//    dark:  { navigationBarColor: "#000000", statusBarStyle: "light" },
+//    light: { navigationBarColor: "#ffffff", statusBarStyle: "dark"  },
+//    base:  { keepScreenOn: true },
+//  });
+// ─────────────────────────────────────────────
+
+export interface ThemedSystemBarConfig {
+  /** Config applied when the resolved theme is DARK. */
+  dark?: SystemBarConfig;
+  /** Config applied when the resolved theme is LIGHT. */
+  light?: SystemBarConfig;
+  /**
+   * Static config merged under both themes.
+   * Theme-specific (dark/light) values always win.
+   */
+  base?: SystemBarConfig;
+}
+
+export const useThemeSystemBar = (
+  config: ThemedSystemBarConfig,
+): ThemeState => {
+  const theme = useTheme();
+
+  const resolved: SystemBarConfig = {
+    ...(config.base ?? {}),
+    ...(theme.isDark ? (config.dark ?? {}) : (config.light ?? {})),
+  };
+
+  useSystemBar(resolved);
+
+  return theme;
+};
+
+// ─────────────────────────────────────────────
+//  Re-export useTheme + theme types
+// ─────────────────────────────────────────────
+
+export { useTheme } from "./useTheme";
+export type { ThemeMode, ThemeState };
+
+// ─────────────────────────────────────────────
+//  useSystemScreencast
+//  Tracks OS-level external display state.
+//  Android: DisplayManager (HDMI / Miracast / Presentation display).
+//  iOS:     UIScreen.screens (AirPlay mirror).
+//
+//  @example
+//  const { isCasting, displayName, displays } = useSystemScreencast();
 // ─────────────────────────────────────────────
-export const useScreencast = () => {
-  const [info, setInfo] = useState<ScreencastInfo>({
+
+export const useSystemScreencast = (): SystemScreencastInfo => {
+  const [info, setInfo] = useState<SystemScreencastInfo>({
     isCasting: false,
     displayName: null,
     displays: [],
   });
 
   useEffect(() => {
-    SystemBar.getScreencastInfo().then(setInfo).catch(() => {});
-    const unsub = SystemBar.onScreencastChange(setInfo);
+    SystemBar.getSystemScreencastInfo()
+      .then(setInfo)
+      .catch(() => {});
+    const unsub = SystemBar.onSystemScreencastChange(setInfo);
     return () => unsub();
   }, []);
 
   return info;
 };
+
+/** @deprecated Renamed to useSystemScreencast() */
+export const useScreencast = useSystemScreencast;
+
+// ─────────────────────────────────────────────
+//  UseAppCastReturn + useAppCast
+//
+//  In-app device discovery + casting via Android MediaRouter.
+//  Mirrors ONLY this app's screen — NOT the whole system.
+//  iOS always returns idle (AirPlay is system-managed, no public API).
+//
+//  Flow:
+//    1. Mount the component — calls getAppCastInfo() for initial state
+//    2. call scan()                → state = "scanning", devices populate
+//    3. call connect(device.id)    → state = "connecting" → "connected"
+//    4. call disconnect()          → state = "disconnecting" → "idle"
+//    5. Unmount                    → scan auto-stopped (battery safe)
+//
+//  @example
+//  const { state, devices, connectedDevice, error,
+//          scan, stopScan, connect, disconnect } = useAppCast();
+//
+//  <Button title="Find TVs" onPress={scan} />
+//  {devices.map(d => (
+//    <Button key={d.id} title={`Cast to ${d.name}`}
+//            onPress={() => connect(d.id)} />
+//  ))}
+//  {connectedDevice && (
+//    <Button title="Stop casting" onPress={disconnect} />
+//  )}
+// ─────────────────────────────────────────────
+
+export interface UseAppCastReturn extends AppCastInfo {
+  /** Start scanning for nearby castable devices (TV, Chromecast, etc.). */
+  scan: () => void;
+  /** Stop the device discovery scan. */
+  stopScan: () => void;
+  /**
+   * Connect to a discovered device and begin casting this app's screen.
+   * @param deviceId   The `id` field from `AppCastDevice`.
+   * @param pairingPin Optional PIN string if `requiresPairing` is true.
+   */
+  connect: (deviceId: string, pairingPin?: string) => void;
+  /** End the active cast session and return to idle. */
+  disconnect: () => void;
+}
+
+export const useAppCast = (): UseAppCastReturn => {
+  const [info, setInfo] = useState<AppCastInfo>({
+    state: "idle",
+    devices: [],
+    connectedDevice: null,
+    error: null,
+  });
+
+  useEffect(() => {
+    // Sync initial state
+    SystemBar.getAppCastInfo()
+      .then(setInfo)
+      .catch(() => {});
+
+    // Subscribe to all cast events (device found/lost, state changes, errors)
+    const unsub = SystemBar.onAppCastChange(setInfo);
+
+    return () => {
+      unsub();
+      // Auto-stop scan on unmount — avoids background battery drain
+      SystemBar.stopAppCastScan();
+    };
+  }, []);
+
+  const scan = useCallback(() => SystemBar.startAppCastScan(), []);
+  const stopScan = useCallback(() => SystemBar.stopAppCastScan(), []);
+  const connect = useCallback(
+    (id: string, pin?: string) => SystemBar.connectAppCast(id, pin),
+    [],
+  );
+  const disconnect = useCallback(() => SystemBar.disconnectAppCast(), []);
+
+  return { ...info, scan, stopScan, connect, disconnect };
+};

package/src/useTheme.ts

@@ -0,0 +1,95 @@
+// ─────────────────────────────────────────────
+//  rn-system-bar · useTheme.ts
+//
+//  Reads the OS colour scheme via React Native's
+//  `Appearance` API and lets the user override it
+//  with "dark" | "light" | "system".
+//
+//  Usage:
+//    const { isDark, mode, setMode } = useTheme();
+//    const { isDark } = useTheme();               // read-only
+// ─────────────────────────────────────────────
+
+import { useCallback, useEffect, useState } from "react";
+import { Appearance, ColorSchemeName } from "react-native";
+import type { ThemeMode, ThemeState } from "./types";
+
+// ── Module-level singleton so all consumers share state ──────────────────────
+
+let _mode: ThemeMode = "system";
+let _systemIsDark: boolean = Appearance.getColorScheme() === "dark";
+
+type Listener = (state: { isDark: boolean; mode: ThemeMode }) => void;
+const _listeners = new Set<Listener>();
+
+function _notify() {
+  const isDark = resolveIsDark(_mode, _systemIsDark);
+  _listeners.forEach((fn) => fn({ isDark, mode: _mode }));
+}
+
+function resolveIsDark(mode: ThemeMode, systemIsDark: boolean): boolean {
+  if (mode === "dark") return true;
+  if (mode === "light") return false;
+  return systemIsDark; // "system"
+}
+
+// Keep in sync with OS changes
+Appearance.addChangeListener(
+  ({ colorScheme }: { colorScheme: ColorSchemeName }) => {
+    _systemIsDark = colorScheme === "dark";
+    _notify();
+  },
+);
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Set the global theme mode from anywhere (outside a component).
+ * Triggers all `useTheme()` consumers.
+ */
+export function setGlobalThemeMode(mode: ThemeMode): void {
+  _mode = mode;
+  _notify();
+}
+
+/**
+ * React hook — subscribe to theme state.
+ *
+ * @example
+ * const { isDark, mode, setMode } = useTheme();
+ *
+ * // Auto nav bar colour based on theme
+ * useEffect(() => {
+ *   setNavigationBarColor(isDark ? "#000000" : "#ffffff");
+ *   setNavigationBarButtonStyle(isDark ? "light" : "dark");
+ * }, [isDark]);
+ *
+ * // Manual override
+ * <Button onPress={() => setMode("dark")}  title="Force Dark"  />
+ * <Button onPress={() => setMode("light")} title="Force Light" />
+ * <Button onPress={() => setMode("system")}title="Follow OS"   />
+ */
+export function useTheme(): ThemeState {
+  const [state, setState] = useState<{ isDark: boolean; mode: ThemeMode }>(
+    () => ({
+      isDark: resolveIsDark(_mode, _systemIsDark),
+      mode: _mode,
+    }),
+  );
+
+  useEffect(() => {
+    // Sync on mount in case singleton changed between renders
+    setState({ isDark: resolveIsDark(_mode, _systemIsDark), mode: _mode });
+
+    _listeners.add(setState);
+    return () => {
+      _listeners.delete(setState);
+    };
+  }, []);
+
+  const setMode = useCallback((newMode: ThemeMode) => {
+    setGlobalThemeMode(newMode);
+  }, []);
+
+  return { ...state, setMode };
+}