rn-system-bar 3.1.7 → 3.2.0

package/specs/NativeSystemBar.ts

@@ -7,33 +7,48 @@ import type { TurboModule } from "react-native";
 import { TurboModuleRegistry } from "react-native";
 
 export interface Spec extends TurboModule {
-  // Navigation Bar (Android-only)
+  // ── Navigation Bar (Android-only) ──────────
+  // color: hex string | "transparent" | "translucent"
   setNavigationBarColor(color: string): void;
   setNavigationBarVisibility(mode: string): void;
   setNavigationBarButtonStyle(style: string): void;
   setNavigationBarStyle(style: string): void;
   setNavigationBarBehavior(behavior: string): void;
 
-  // Status Bar
+  // ── Status Bar ─────────────────────────────
+  // color: hex string | "transparent" | "translucent"
   setStatusBarColor(color: string): void;
   setStatusBarStyle(style: string): void;
   setStatusBarVisibility(visible: boolean): void;
 
-  // Brightness
+  // ── Brightness ─────────────────────────────
   setBrightness(level: number): void;
   getBrightness(): Promise<number>;
 
-  // Volume
+  // ── Volume ─────────────────────────────────
   setVolume(level: number, stream: string): void;
   getVolume(stream: string): Promise<number>;
   setVolumeHUDVisible(visible: boolean): void;
 
-  // Screen
+  // ── Screen ─────────────────────────────────
   keepScreenOn(enable: boolean): void;
   immersiveMode(enable: boolean): void;
+  setSecureScreen(enable: boolean): void;
 
-  // Orientation
+  // ── Orientation ────────────────────────────
   setOrientation(mode: string): void;
+
+  // ── System Screencast ──────────────────────
+  getSystemScreencastInfo(): Promise<Object>;
+  startSystemScreencastListener(): void;
+  stopSystemScreencastListener(): void;
+
+  // ── App-only Cast (Android only) ───────────
+  startAppCastScan(): void;
+  stopAppCastScan(): void;
+  connectAppCast(deviceId: string, pairingPin: string | null): void;
+  disconnectAppCast(): void;
+  getAppCastInfo(): Promise<Object>;
 }
 
 export default TurboModuleRegistry.getEnforcing<Spec>("SystemBar");

package/src/SystemBar.ts

@@ -7,13 +7,17 @@
 import { NativeModules, Platform } from "react-native";
 
 import type {
+  AppCastInfo,
+  AppCastState,
   NavigationBarBehavior,
   NavigationBarButtonStyle,
+  NavigationBarColorValue,
   NavigationBarStyle,
   NavigationBarVisibility,
   Orientation,
-  ScreencastInfo,
+  StatusBarColorValue,
   StatusBarStyle,
+  SystemScreencastInfo,
   VolumeStream,
 } from "./types";
 
@@ -23,33 +27,63 @@ const isAndroid = Platform.OS === "android";
 
 const androidOnly = (name: string): boolean => {
   if (!isAndroid) {
-    if (__DEV__) console.warn(`[rn-system-bar] ${name}() is Android-only, no-op on iOS.`);
+    if (__DEV__)
+      console.warn(`[rn-system-bar] ${name}() is Android-only, no-op on iOS.`);
     return false;
   }
   return true;
 };
 
-const checkNative = () => {
-  if (!Native) throw new Error("[rn-system-bar] Native module not found. Rebuild your project.");
+const checkNative = (method?: string) => {
+  if (!Native)
+    throw new Error(
+      "[rn-system-bar] Native module not found. Rebuild your project.",
+    );
+  if (method && typeof Native[method] !== "function")
+    throw new Error(
+      `[rn-system-bar] Native.${method} not found. Rebuild your project.`,
+    );
 };
 
 // ═══════════════════════════════════════════════
 //  NAVIGATION BAR  (Android — 100% native)
 // ═══════════════════════════════════════════════
 
-export const setNavigationBarColor = (color: string): void => {
+/**
+ * Set the navigation bar background colour.
+ *
+ * @param color
+ *   - Any hex string   →  solid colour        e.g. `"#1a1a2e"`
+ *   - `"transparent"`  →  fully transparent   (content draws behind bar)
+ *   - `"translucent"`  →  semi-transparent    (system scrim over content)
+ *
+ * @example
+ * setNavigationBarColor("#000000");       // solid black
+ * setNavigationBarColor("transparent");   // glass / edge-to-edge
+ * setNavigationBarColor("translucent");   // frosted glass
+ */
+export const setNavigationBarColor = (color: NavigationBarColorValue): void => {
   if (!androidOnly("setNavigationBarColor")) return;
   checkNative();
-  Native.setNavigationBarColor(color);
+  Native.setNavigationBarColor(color); // Kotlin handles the special values
 };
 
-export const setNavigationBarVisibility = (mode: NavigationBarVisibility): void => {
+/**
+ * Hide or show the navigation bar.
+ *
+ * @param mode `"visible"` | `"hidden"`
+ */
+export const setNavigationBarVisibility = (
+  mode: NavigationBarVisibility,
+): void => {
   if (!androidOnly("setNavigationBarVisibility")) return;
   checkNative();
   Native.setNavigationBarVisibility(mode);
 };
 
-export const setNavigationBarButtonStyle = (style: NavigationBarButtonStyle): void => {
+export const setNavigationBarButtonStyle = (
+  style: NavigationBarButtonStyle,
+): void => {
   if (!androidOnly("setNavigationBarButtonStyle")) return;
   checkNative();
   Native.setNavigationBarButtonStyle(style);
@@ -61,7 +95,9 @@ export const setNavigationBarStyle = (style: NavigationBarStyle): void => {
   Native.setNavigationBarStyle(style);
 };
 
-export const setNavigationBarBehavior = (behavior: NavigationBarBehavior): void => {
+export const setNavigationBarBehavior = (
+  behavior: NavigationBarBehavior,
+): void => {
   if (!androidOnly("setNavigationBarBehavior")) return;
   checkNative();
   Native.setNavigationBarBehavior(behavior);
@@ -71,6 +107,20 @@ export const setNavigationBarBehavior = (behavior: NavigationBarBehavior): void
 //  STATUS BAR  (native — no RN StatusBar)
 // ═══════════════════════════════════════════════
 
+/**
+ * Set the status bar background colour (Android only).
+ *
+ * @param color
+ *   - Any hex string   →  solid colour
+ *   - `"transparent"`  →  fully transparent
+ *   - `"translucent"`  →  semi-transparent
+ */
+export const setStatusBarColor = (color: StatusBarColorValue): void => {
+  if (!androidOnly("setStatusBarColor")) return;
+  checkNative();
+  Native.setStatusBarColor(color);
+};
+
 export const setStatusBarStyle = (style: StatusBarStyle): void => {
   checkNative();
   Native.setStatusBarStyle(style);
@@ -96,18 +146,18 @@ export const getBrightness = (): Promise<number> => {
 };
 
 /**
- * Subscribe to system brightness changes (polls every 500ms on Android).
+ * Subscribe to system brightness changes (polls every 500 ms on Android).
  * @returns unsubscribe function
  */
 export const onBrightnessChange = (
-  callback: (brightness: number) => void
+  callback: (brightness: number) => void,
 ): (() => void) => {
   checkNative();
   const { DeviceEventEmitter } = require("react-native");
   Native.startBrightnessListener();
   const sub = DeviceEventEmitter.addListener(
     "SystemBar_BrightnessChange",
-    (e: { brightness: number }) => callback(e.brightness)
+    (e: { brightness: number }) => callback(e.brightness),
   );
   return () => {
     sub.remove();
@@ -119,7 +169,10 @@ export const onBrightnessChange = (
 //  VOLUME
 // ═══════════════════════════════════════════════
 
-export const setVolume = (level: number, stream: VolumeStream = "music"): void => {
+export const setVolume = (
+  level: number,
+  stream: VolumeStream = "music",
+): void => {
   checkNative();
   Native.setVolume(Math.max(0, Math.min(1, level)), stream);
 };
@@ -140,14 +193,15 @@ export const setVolumeHUDVisible = (visible: boolean): void => {
  * @returns unsubscribe function
  */
 export const onVolumeChange = (
-  callback: (volume: number, stream: VolumeStream) => void
+  callback: (volume: number, stream: VolumeStream) => void,
 ): (() => void) => {
   checkNative();
   const { DeviceEventEmitter } = require("react-native");
   Native.startVolumeListener();
   const sub = DeviceEventEmitter.addListener(
     "SystemBar_VolumeChange",
-    (e: { volume: number; stream: VolumeStream }) => callback(e.volume, e.stream)
+    (e: { volume: number; stream: VolumeStream }) =>
+      callback(e.volume, e.stream),
   );
   return () => {
     sub.remove();
@@ -186,23 +240,155 @@ export const setOrientation = (mode: Orientation): void => {
 };
 
 // ═══════════════════════════════════════════════
-//  SCREENCAST
+//  SYSTEM SCREENCAST  (external display / HDMI / Miracast)
+//  Reads DisplayManager — detects any externally mirrored display.
+// ═══════════════════════════════════════════════
+
+/**
+ * One-shot snapshot of system-level external display state.
+ * Works on both Android (DisplayManager) and iOS (UIScreen.screens).
+ */
+export const getSystemScreencastInfo = (): Promise<SystemScreencastInfo> => {
+  if (!Native || typeof Native.getSystemScreencastInfo !== "function") {
+    if (__DEV__)
+      console.warn(
+        "[rn-system-bar] getSystemScreencastInfo not available on this build.",
+      );
+    return Promise.resolve({
+      isCasting: false,
+      displayName: null,
+      displays: [],
+    });
+  }
+  return Native.getSystemScreencastInfo();
+};
+
+/**
+ * Subscribe to system external-display changes.
+ * Fires when an HDMI / Miracast / AirPlay display connects or disconnects.
+ * @returns unsubscribe function
+ */
+export const onSystemScreencastChange = (
+  callback: (info: SystemScreencastInfo) => void,
+): (() => void) => {
+  checkNative();
+  const { DeviceEventEmitter } = require("react-native");
+  Native.startSystemScreencastListener();
+  const sub = DeviceEventEmitter.addListener(
+    "SystemBar_SystemScreencastChange",
+    callback,
+  );
+  return () => {
+    sub.remove();
+    Native.stopSystemScreencastListener();
+  };
+};
+
+// ─────────────────────────────────────────────
+//  Legacy aliases (backward compat)
+// ─────────────────────────────────────────────
+/** @deprecated Use getSystemScreencastInfo() */
+export const getScreencastInfo = getSystemScreencastInfo;
+/** @deprecated Use onSystemScreencastChange() */
+export const onScreencastChange = onSystemScreencastChange;
+
+// ═══════════════════════════════════════════════
+//  APP-ONLY CAST  (MediaRouter — Chromecast / TV)
+//  Mirrors only this app's screen — NOT the whole system.
+//  Flow:  startAppCastScan() → onAppCastChange (devices arrive)
+//         → connectAppCast(deviceId) → onAppCastChange (state = "connected")
+//         → disconnectAppCast()
 // ═══════════════════════════════════════════════
 
-export const getScreencastInfo = (): Promise<ScreencastInfo> => {
+/**
+ * Start scanning for nearby castable devices (Chromecast, TV, etc.).
+ * Listen for results via `onAppCastChange`.
+ * Android: uses MediaRouter. iOS: no-op (AirPlay is system-only).
+ */
+export const startAppCastScan = (): void => {
+  if (!androidOnly("startAppCastScan")) return;
+  checkNative();
+  Native.startAppCastScan();
+};
+
+/**
+ * Stop the device discovery scan.
+ */
+export const stopAppCastScan = (): void => {
+  if (!androidOnly("stopAppCastScan")) return;
+  checkNative();
+  Native.stopAppCastScan();
+};
+
+/**
+ * Connect to a discovered device and begin casting this app's screen.
+ * @param deviceId  The `id` field from `AppCastDevice` (MediaRouter route ID).
+ * @param pairingPin  Optional PIN string if `requiresPairing` is true.
+ */
+export const connectAppCast = (deviceId: string, pairingPin?: string): void => {
+  if (!androidOnly("connectAppCast")) return;
+  checkNative();
+  Native.connectAppCast(deviceId, pairingPin ?? null);
+};
+
+/**
+ * Disconnect the active in-app cast session.
+ */
+export const disconnectAppCast = (): void => {
+  if (!androidOnly("disconnectAppCast")) return;
+  checkNative();
+  Native.disconnectAppCast();
+};
+
+/**
+ * Get the current in-app cast snapshot (state + device list).
+ */
+export const getAppCastInfo = (): Promise<AppCastInfo> => {
+  if (!isAndroid) {
+    return Promise.resolve({
+      state: "idle" as AppCastState,
+      devices: [],
+      connectedDevice: null,
+      error: null,
+    });
+  }
   checkNative();
-  return Native.getScreencastInfo();
+  return Native.getAppCastInfo();
 };
 
-export const onScreencastChange = (
-  callback: (info: ScreencastInfo) => void
+/**
+ * Subscribe to in-app cast state changes.
+ * Fires on: device discovered/lost, state changes (scanning → connecting → connected),
+ * pairing requests, errors.
+ *
+ * @example
+ * const unsub = onAppCastChange((info) => {
+ *   if (info.state === "connected") console.log("Casting to", info.connectedDevice?.name);
+ *   if (info.error) console.warn("Cast error:", info.error);
+ * });
+ *
+ * @returns unsubscribe function
+ */
+export const onAppCastChange = (
+  callback: (info: AppCastInfo) => void,
 ): (() => void) => {
+  if (!isAndroid) {
+    // iOS: immediately call with idle state, return no-op
+    callback({
+      state: "idle",
+      devices: [],
+      connectedDevice: null,
+      error: null,
+    });
+    return () => {};
+  }
   checkNative();
   const { DeviceEventEmitter } = require("react-native");
-  Native.startScreencastListener();
-  const sub = DeviceEventEmitter.addListener("SystemBar_ScreencastChange", callback);
+  const sub = DeviceEventEmitter.addListener(
+    "SystemBar_AppCastChange",
+    callback,
+  );
   return () => {
     sub.remove();
-    Native.stopScreencastListener();
   };
 };

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 {}