rn-system-bar 3.0.2 → 3.1.0

package/src/SystemBar.ts

@@ -1,236 +1,310 @@
 // ─────────────────────────────────────────────
-//  rn-system-bar · SystemBar.ts
+//  rn-system-bar · SystemBar.ts  v5
+//  All features — Android + iOS
 // ─────────────────────────────────────────────
 
-import { NativeModules, Platform } from "react-native";
+import { NativeModules, Platform, StatusBar, Vibration } from "react-native";
 
 import type {
+  BatteryInfo,
+  FontScaleInfo,
+  HapticPattern,
   NavigationBarBehavior,
   NavigationBarButtonStyle,
   NavigationBarStyle,
   NavigationBarVisibility,
+  NetworkInfo,
   Orientation,
+  ScreencastInfo,
   StatusBarStyle,
   VolumeStream,
 } from "./types";
 
-const { SystemBar } = NativeModules;
+// expo-navigation-bar — peer dep, loaded at runtime
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const NavBar = (() => {
+  try { return require("expo-navigation-bar"); }
+  catch { return null; }
+})();
 
-// ─── Guard helper ──────────────────────────────
-// Navigation-bar APIs are Android-only.
-// iOS has no navigation bar concept.
-// All other APIs work on both platforms.
+const { SystemBar: Native } = NativeModules;
 
 const isAndroid = Platform.OS === "android";
+const isIOS     = Platform.OS === "ios";
 
-const androidOnly = (name: string) => {
+const androidOnly = (name: string): boolean => {
   if (!isAndroid) {
-    if (__DEV__) {
-      console.warn(
-        `[rn-system-bar] ${name}() is Android-only and has no effect on iOS.`
-      );
-    }
+    if (__DEV__) console.warn(`[rn-system-bar] ${name}() is Android-only, no-op on iOS.`);
     return false;
   }
   return true;
 };
 
-const checkModule = () => {
-  if (!SystemBar) {
-    throw new Error(
-      "[rn-system-bar] Native module not found. " +
-        "Did you forget to run `pod install` (iOS) or rebuild the Android project?"
-    );
-  }
+const checkNative = () => {
+  if (!Native) throw new Error("[rn-system-bar] Native module not found. Rebuild your project.");
 };
 
 // ═══════════════════════════════════════════════
-//  NAVIGATION BAR  (Android-only)
+//  NAVIGATION BAR  (Android — expo-navigation-bar)
 // ═══════════════════════════════════════════════
 
-/**
- * Set navigation bar background color.
- * @param color  Hex color string e.g. "#000000"
- * @platform android
- */
-export const setNavigationBarColor = (color: string): void => {
-  if (!androidOnly("setNavigationBarColor")) return;
-  checkModule();
-  SystemBar.setNavigationBarColor(color);
+export const setNavigationBarColor = (color: string): Promise<void> => {
+  if (!androidOnly("setNavigationBarColor")) return Promise.resolve();
+  return NavBar?.setBackgroundColorAsync(color) ?? Promise.resolve();
 };
 
-/**
- * Show or hide the navigation bar.
- * @platform android
- */
-export const setNavigationBarVisibility = (
-  mode: NavigationBarVisibility
-): void => {
-  if (!androidOnly("setNavigationBarVisibility")) return;
-  checkModule();
-  SystemBar.setNavigationBarVisibility(mode);
+export const setNavigationBarVisibility = (mode: NavigationBarVisibility): Promise<void> => {
+  if (!androidOnly("setNavigationBarVisibility")) return Promise.resolve();
+  return NavBar?.setVisibilityAsync(mode) ?? Promise.resolve();
 };
 
-/**
- * Set icon/button style of the navigation bar.
- * @param style  "light" = white icons | "dark" = black icons
- * @platform android
- */
-export const setNavigationBarButtonStyle = (
-  style: NavigationBarButtonStyle
-): void => {
-  if (!androidOnly("setNavigationBarButtonStyle")) return;
-  checkModule();
-  SystemBar.setNavigationBarButtonStyle(style);
+export const setNavigationBarButtonStyle = (style: NavigationBarButtonStyle): Promise<void> => {
+  if (!androidOnly("setNavigationBarButtonStyle")) return Promise.resolve();
+  return NavBar?.setButtonStyleAsync(style) ?? Promise.resolve();
 };
 
-/**
- * Set the overall visual style of the navigation bar.
- * @platform android
- */
-export const setNavigationBarStyle = (style: NavigationBarStyle): void => {
-  if (!androidOnly("setNavigationBarStyle")) return;
-  checkModule();
-  SystemBar.setNavigationBarStyle(style);
+export const setNavigationBarStyle = (style: NavigationBarStyle): Promise<void> => {
+  if (!androidOnly("setNavigationBarStyle")) return Promise.resolve();
+  const btn: NavigationBarButtonStyle = style === "dark" || style === "auto" ? "dark" : "light";
+  return NavBar?.setButtonStyleAsync(btn) ?? Promise.resolve();
 };
 
-/**
- * Set the gesture behavior of the navigation bar.
- * @platform android
- */
-export const setNavigationBarBehavior = (
-  behavior: NavigationBarBehavior
-): void => {
-  if (!androidOnly("setNavigationBarBehavior")) return;
-  checkModule();
-  SystemBar.setNavigationBarBehavior(behavior);
+export const setNavigationBarBehavior = (behavior: NavigationBarBehavior): Promise<void> => {
+  if (!androidOnly("setNavigationBarBehavior")) return Promise.resolve();
+  return NavBar?.setBehaviorAsync(behavior) ?? Promise.resolve();
 };
 
 // ═══════════════════════════════════════════════
 //  STATUS BAR
 // ═══════════════════════════════════════════════
 
-/**
- * Set status bar background color.
- * @param color  Hex color string e.g. "#FF0000"
- * @platform android  (iOS ignores background color by OS design)
- */
-export const setStatusBarColor = (color: string): void => {
+export const setStatusBarColor = (color: string, animated = false): void => {
   if (!androidOnly("setStatusBarColor")) return;
-  checkModule();
-  SystemBar.setStatusBarColor(color);
+  StatusBar.setBackgroundColor(color, animated);
 };
 
-/**
- * Set status bar icon style (light/dark icons).
- * Works on both Android and iOS.
- */
-export const setStatusBarStyle = (style: StatusBarStyle): void => {
-  checkModule();
-  SystemBar.setStatusBarStyle(style);
+export const setStatusBarStyle = (style: StatusBarStyle, animated = false): void => {
+  StatusBar.setBarStyle(style === "light" ? "light-content" : "dark-content", animated);
 };
 
-/**
- * Show or hide the status bar.
- */
-export const setStatusBarVisibility = (visible: boolean): void => {
-  checkModule();
-  SystemBar.setStatusBarVisibility(visible);
+export const setStatusBarVisibility = (visible: boolean, animated = false): void => {
+  StatusBar.setHidden(!visible, animated ? "slide" : "none");
 };
 
 // ═══════════════════════════════════════════════
 //  BRIGHTNESS
 // ═══════════════════════════════════════════════
 
+export const setBrightness = (level: number): void => {
+  checkNative();
+  Native.setBrightness(Math.max(0, Math.min(1, level)));
+};
+
+export const getBrightness = (): Promise<number> => {
+  checkNative();
+  return Native.getBrightness();
+};
+
+// ═══════════════════════════════════════════════
+//  VOLUME
+// ═══════════════════════════════════════════════
+
+export const setVolume = (level: number, stream: VolumeStream = "music"): void => {
+  checkNative();
+  Native.setVolume(Math.max(0, Math.min(1, level)), stream);
+};
+
+export const getVolume = (stream: VolumeStream = "music"): Promise<number> => {
+  checkNative();
+  return Native.getVolume(stream);
+};
+
+export const setVolumeHUDVisible = (visible: boolean): void => {
+  if (!androidOnly("setVolumeHUDVisible")) return;
+  checkNative();
+  Native.setVolumeHUDVisible(visible);
+};
+
+// ═══════════════════════════════════════════════
+//  SCREEN
+// ═══════════════════════════════════════════════
+
+export const keepScreenOn = (enable: boolean): void => {
+  checkNative();
+  Native.keepScreenOn(enable);
+};
+
+export const immersiveMode = (enable: boolean): void => {
+  if (!androidOnly("immersiveMode")) return;
+  checkNative();
+  Native.immersiveMode(enable);
+};
+
+// ═══════════════════════════════════════════════
+//  ORIENTATION
+// ═══════════════════════════════════════════════
+
+export const setOrientation = (mode: Orientation): void => {
+  checkNative();
+  Native.setOrientation(mode);
+};
+
+// ═══════════════════════════════════════════════
+//  🆕 NETWORK INFO
+// ═══════════════════════════════════════════════
+
 /**
- * Set screen brightness.
- * @param level  0.0 (min) – 1.0 (max)
+ * Get current network connection info.
+ * Includes: type, isConnected, isAirplaneMode, ssid, cellularGeneration
  */
-export const setBrightness = (level: number): void => {
-  checkModule();
-  SystemBar.setBrightness(Math.max(0, Math.min(1, level)));
+export const getNetworkInfo = (): Promise<NetworkInfo> => {
+  checkNative();
+  return Native.getNetworkInfo();
 };
 
 /**
- * Get current screen brightness.
- * @returns Promise<number>  0.0 – 1.0
+ * Subscribe to network changes.
+ * @returns unsubscribe function — call it in useEffect cleanup
+ * @example
+ * const unsub = onNetworkChange((info) => console.log(info));
+ * return () => unsub();
  */
-export const getBrightness = (): Promise<number> => {
-  checkModule();
-  return SystemBar.getBrightness();
+export const onNetworkChange = (
+  callback: (info: NetworkInfo) => void
+): (() => void) => {
+  checkNative();
+  // Native side emits "SystemBar_NetworkChange" events
+  const { DeviceEventEmitter } = require("react-native");
+  Native.startNetworkListener();
+  const sub = DeviceEventEmitter.addListener("SystemBar_NetworkChange", callback);
+  return () => {
+    sub.remove();
+    Native.stopNetworkListener();
+  };
 };
 
 // ═══════════════════════════════════════════════
-//  VOLUME
+//  🆕 BATTERY
 // ═══════════════════════════════════════════════
 
 /**
- * Set volume level.
- * @param level   0.0 (mute) – 1.0 (max)
- * @param stream  Audio stream to target (default: "music")
+ * Get current battery info: level (0–100), state, isCharging, isLow.
  */
-export const setVolume = (
-  level: number,
-  stream: VolumeStream = "music"
-): void => {
-  checkModule();
-  SystemBar.setVolume(Math.max(0, Math.min(1, level)), stream);
+export const getBatteryInfo = (): Promise<BatteryInfo> => {
+  checkNative();
+  return Native.getBatteryInfo();
 };
 
 /**
- * Get current volume level.
- * @param stream  Audio stream to query (default: "music")
- * @returns Promise<number>  0.0 – 1.0
+ * Subscribe to battery level / state changes.
+ * @returns unsubscribe function
  */
-export const getVolume = (stream: VolumeStream = "music"): Promise<number> => {
-  checkModule();
-  return SystemBar.getVolume(stream);
+export const onBatteryChange = (
+  callback: (info: BatteryInfo) => void
+): (() => void) => {
+  checkNative();
+  const { DeviceEventEmitter } = require("react-native");
+  Native.startBatteryListener();
+  const sub = DeviceEventEmitter.addListener("SystemBar_BatteryChange", callback);
+  return () => {
+    sub.remove();
+    Native.stopBatteryListener();
+  };
 };
 
+// ═══════════════════════════════════════════════
+//  🆕 HAPTIC FEEDBACK
+// ═══════════════════════════════════════════════
+
 /**
- * Show or hide the system Volume HUD when changing volume.
- * @param visible  false = suppress the volume popup
- * @platform android
+ * Trigger haptic feedback.
+ *
+ * iOS: Uses UIImpactFeedbackGenerator / UINotificationFeedbackGenerator.
+ * Android: Uses Vibrator / VibrationEffect (API 26+).
+ *
+ * @param pattern  "light" | "medium" | "heavy" | "success" | "warning" | "error" | "selection"
  */
-export const setVolumeHUDVisible = (visible: boolean): void => {
-  if (!androidOnly("setVolumeHUDVisible")) return;
-  checkModule();
-  SystemBar.setVolumeHUDVisible(visible);
+export const haptic = (pattern: HapticPattern): void => {
+  if (isIOS) {
+    checkNative();
+    Native.haptic(pattern);
+    return;
+  }
+
+  // Android fallback using RN's built-in Vibration API
+  // when native module is unavailable
+  if (isAndroid) {
+    checkNative();
+    Native.haptic(pattern);
+  }
 };
 
 // ═══════════════════════════════════════════════
-//  SCREEN
+//  🆕 SCREENCAST DETECTION
 // ═══════════════════════════════════════════════
 
 /**
- * Prevent the screen from sleeping.
- * @param enable  true = keep screen on | false = allow sleep
+ * Check if screen is currently being cast or mirrored.
  */
-export const keepScreenOn = (enable: boolean): void => {
-  checkModule();
-  SystemBar.keepScreenOn(enable);
+export const getScreencastInfo = (): Promise<ScreencastInfo> => {
+  checkNative();
+  return Native.getScreencastInfo();
+};
+
+/**
+ * Subscribe to screencast state changes (started / stopped).
+ * @returns unsubscribe function
+ */
+export const onScreencastChange = (
+  callback: (info: ScreencastInfo) => void
+): (() => void) => {
+  checkNative();
+  const { DeviceEventEmitter } = require("react-native");
+  Native.startScreencastListener();
+  const sub = DeviceEventEmitter.addListener("SystemBar_ScreencastChange", callback);
+  return () => {
+    sub.remove();
+    Native.stopScreencastListener();
+  };
 };
 
 /**
- * Enable or disable immersive fullscreen mode.
- * Hides both status bar and navigation bar.
+ * Prevent screen content from appearing in screenshots / recordings.
+ * Useful for sensitive screens (payments, passwords).
  * @platform android
  */
-export const immersiveMode = (enable: boolean): void => {
-  if (!androidOnly("immersiveMode")) return;
-  checkModule();
-  SystemBar.immersiveMode(enable);
+export const setSecureScreen = (enable: boolean): void => {
+  if (!androidOnly("setSecureScreen")) return;
+  checkNative();
+  Native.setSecureScreen(enable);
 };
 
 // ═══════════════════════════════════════════════
-//  ORIENTATION
+//  🆕 FONT SCALE / DISPLAY INFO
 // ═══════════════════════════════════════════════
 
 /**
- * Lock or unlock screen orientation.
- * @param mode  "portrait" | "landscape" | "landscape-left" | "landscape-right" | "auto"
+ * Get current system font scale and display density.
+ * Useful for adapting layout to accessibility settings.
  */
-export const setOrientation = (mode: Orientation): void => {
-  checkModule();
-  SystemBar.setOrientation(mode);
+export const getFontScaleInfo = (): Promise<FontScaleInfo> => {
+  checkNative();
+  return Native.getFontScaleInfo();
+};
+
+/**
+ * Subscribe to font scale changes (user changes system text size).
+ * @returns unsubscribe function
+ */
+export const onFontScaleChange = (
+  callback: (info: FontScaleInfo) => void
+): (() => void) => {
+  checkNative();
+  const { DeviceEventEmitter } = require("react-native");
+  Native.startFontScaleListener();
+  const sub = DeviceEventEmitter.addListener("SystemBar_FontScaleChange", callback);
+  return () => {
+    sub.remove();
+    Native.stopFontScaleListener();
+  };
 };

package/src/types.ts

@@ -1,30 +1,21 @@
 // ─────────────────────────────────────────────
-//  rn-system-bar · types.ts
+//  rn-system-bar · types.ts  v5
 // ─────────────────────────────────────────────
 
+// ── Navigation Bar ────────────────────────────
 export type NavigationBarBehavior =
-  | "overlay-swipe"   // Swipe from edge reveals bar briefly (overlay)
-  | "inset-swipe"     // Swipe insets content when bar appears
-  | "inset-touch";    // Touch insets content when bar appears
+  | "overlay-swipe"
+  | "inset-swipe"
+  | "inset-touch";
 
-export type NavigationBarButtonStyle =
-  | "light"           // White / light-coloured icons
-  | "dark";           // Black / dark-coloured icons
+export type NavigationBarButtonStyle = "light" | "dark";
+export type NavigationBarStyle = "auto" | "inverted" | "light" | "dark";
+export type NavigationBarVisibility = "visible" | "hidden";
 
-export type NavigationBarStyle =
-  | "auto"            // System decides
-  | "inverted"        // Inverted from system
-  | "light"           // Light background nav bar
-  | "dark";           // Dark background nav bar
-
-export type NavigationBarVisibility =
-  | "visible"
-  | "hidden";
-
-export type StatusBarStyle =
-  | "light"           // Light icons (for dark backgrounds)
-  | "dark";           // Dark icons (for light backgrounds)
+// ── Status Bar ────────────────────────────────
+export type StatusBarStyle = "light" | "dark";
 
+// ── Orientation ───────────────────────────────
 export type Orientation =
   | "portrait"
   | "landscape"
@@ -32,6 +23,7 @@ export type Orientation =
   | "landscape-right"
   | "auto";
 
+// ── Volume ────────────────────────────────────
 export type VolumeStream =
   | "music"
   | "ring"
@@ -39,32 +31,67 @@ export type VolumeStream =
   | "alarm"
   | "system";
 
-export interface SystemBarAPI {
-  // Navigation Bar
-  setNavigationBarColor(color: string): void;
-  setNavigationBarVisibility(mode: NavigationBarVisibility): void;
-  setNavigationBarButtonStyle(style: NavigationBarButtonStyle): void;
-  setNavigationBarStyle(style: NavigationBarStyle): void;
-  setNavigationBarBehavior(behavior: NavigationBarBehavior): void;
+// ── Network ───────────────────────────────────
+export type NetworkType =
+  | "wifi"
+  | "cellular"
+  | "ethernet"
+  | "none"
+  | "unknown";
+
+export interface NetworkInfo {
+  /** Current connection type */
+  type: NetworkType;
+  /** true if any network is reachable */
+  isConnected: boolean;
+  /** true if in airplane mode */
+  isAirplaneMode: boolean;
+  /** WiFi SSID — Android only; null on iOS / when not connected */
+  ssid: string | null;
+  /** Cellular network generation: "2G" | "3G" | "4G" | "5G" | null */
+  cellularGeneration: "2G" | "3G" | "4G" | "5G" | null;
+}
 
-  // Status Bar
-  setStatusBarColor(color: string): void;
-  setStatusBarStyle(style: StatusBarStyle): void;
-  setStatusBarVisibility(visible: boolean): void;
+// ── Battery ───────────────────────────────────
+export type BatteryState =
+  | "charging"
+  | "discharging"
+  | "full"
+  | "unknown";
 
-  // Brightness
-  setBrightness(level: number): void;
-  getBrightness(): Promise<number>;
+export interface BatteryInfo {
+  /** 0–100 */
+  level: number;
+  /** Current charging state */
+  state: BatteryState;
+  /** Shorthand: is it plugged in? */
+  isCharging: boolean;
+  /** Low battery threshold (<= 20%) */
+  isLow: boolean;
+}
 
-  // Volume
-  setVolume(level: number, stream?: VolumeStream): void;
-  getVolume(stream?: VolumeStream): Promise<number>;
-  setVolumeHUDVisible(visible: boolean): void;
+// ── Haptics ───────────────────────────────────
+export type HapticPattern =
+  | "light"       // subtle tap
+  | "medium"      // standard tap
+  | "heavy"       // strong tap
+  | "success"     // double bump — success feedback
+  | "warning"     // single bump — warning feedback
+  | "error"       // triple bump — error feedback
+  | "selection";  // light tick — selection change
 
-  // Screen
-  keepScreenOn(enable: boolean): void;
-  immersiveMode(enable: boolean): void;
+// ── Screencast ────────────────────────────────
+export interface ScreencastInfo {
+  /** true if screen is currently being cast / mirrored */
+  isCasting: boolean;
+  /** Name of the display being cast to, or null */
+  displayName: string | null;
+}
 
-  // Orientation
-  setOrientation(mode: Orientation): void;
+// ── Font Scale ────────────────────────────────
+export interface FontScaleInfo {
+  /** System font scale multiplier, e.g. 1.0 = default, 1.3 = large */
+  fontScale: number;
+  /** Display density (Android: dp ratio, iOS: scale) */
+  density: number;
 }