react-native-permission-handler 0.1.0

package/src/hooks/use-permission-handler.ts

@@ -0,0 +1,158 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { AppState } from "react-native";
+import {
+  type PermissionStatus,
+  check,
+  checkNotifications,
+  openSettings,
+  request,
+  requestNotifications,
+} from "react-native-permissions";
+import { transition } from "../core/state-machine";
+import type {
+  PermissionFlowState,
+  PermissionHandlerConfig,
+  PermissionHandlerResult,
+} from "../types";
+
+function isNotifications(
+  permission: PermissionHandlerConfig["permission"],
+): permission is "notifications" {
+  return permission === "notifications";
+}
+
+export function usePermissionHandler(config: PermissionHandlerConfig): PermissionHandlerResult {
+  const [flowState, setFlowState] = useState<PermissionFlowState>("idle");
+  const [nativeStatus, setNativeStatus] = useState<PermissionStatus | null>(null);
+  const isRequesting = useRef(false);
+  const waitingForSettings = useRef(false);
+  const appStateRef = useRef(AppState.currentState);
+
+  const { permission, autoCheck = true, onGrant, onDeny, onBlock, onSettingsReturn } = config;
+
+  const checkPermission = useCallback(async () => {
+    setFlowState((s) => transition(s, { type: "CHECK" }));
+    try {
+      let status: PermissionStatus;
+      if (isNotifications(permission)) {
+        const result = await checkNotifications();
+        status = result.status;
+      } else {
+        status = await check(permission);
+      }
+      setNativeStatus(status);
+      setFlowState((s) => {
+        const next = transition(s, { type: "CHECK_RESULT", status });
+        if (next === "granted" && s !== "granted") onGrant?.();
+        return next;
+      });
+    } catch {
+      setFlowState("idle");
+    }
+  }, [permission, onGrant]);
+
+  const requestPermission = useCallback(async () => {
+    if (isRequesting.current) return;
+    isRequesting.current = true;
+
+    setFlowState((s) => transition(s, { type: "PRE_PROMPT_CONFIRM" }));
+    try {
+      let status: PermissionStatus;
+      if (isNotifications(permission)) {
+        const result = await requestNotifications(["alert", "badge", "sound"]);
+        status = result.status;
+      } else {
+        status = await request(permission);
+      }
+      setNativeStatus(status);
+      setFlowState((s) => {
+        const next = transition(s, { type: "REQUEST_RESULT", status });
+        if (next === "granted") onGrant?.();
+        if (next === "denied") onDeny?.();
+        if (next === "blockedPrompt") onBlock?.();
+        return next;
+      });
+    } catch {
+      setFlowState("denied");
+    } finally {
+      isRequesting.current = false;
+    }
+  }, [permission, onGrant, onDeny, onBlock]);
+
+  const dismiss = useCallback(() => {
+    setFlowState((s) => transition(s, { type: "PRE_PROMPT_DISMISS" }));
+    onDeny?.();
+  }, [onDeny]);
+
+  const goToSettings = useCallback(async () => {
+    setFlowState((s) => transition(s, { type: "OPEN_SETTINGS" }));
+    waitingForSettings.current = true;
+    try {
+      await openSettings();
+    } catch {
+      waitingForSettings.current = false;
+      setFlowState("blockedPrompt");
+    }
+  }, []);
+
+  const recheckAfterSettings = useCallback(async () => {
+    setFlowState((s) => transition(s, { type: "SETTINGS_RETURN" }));
+    try {
+      let status: PermissionStatus;
+      if (isNotifications(permission)) {
+        const result = await checkNotifications();
+        status = result.status;
+      } else {
+        status = await check(permission);
+      }
+      setNativeStatus(status);
+      setFlowState((s) => {
+        const next = transition(s, { type: "RECHECK_RESULT", status });
+        if (next === "granted") onGrant?.();
+        onSettingsReturn?.(next === "granted");
+        return next;
+      });
+    } catch {
+      setFlowState("blockedPrompt");
+    }
+  }, [permission, onGrant, onSettingsReturn]);
+
+  // Auto-check on mount
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only effect
+  useEffect(() => {
+    if (autoCheck) {
+      checkPermission();
+    }
+  }, []);
+
+  // AppState listener for settings return
+  useEffect(() => {
+    const subscription = AppState.addEventListener("change", (nextAppState) => {
+      if (
+        appStateRef.current.match(/inactive|background/) &&
+        nextAppState === "active" &&
+        waitingForSettings.current
+      ) {
+        waitingForSettings.current = false;
+        recheckAfterSettings();
+      }
+      appStateRef.current = nextAppState;
+    });
+    return () => subscription.remove();
+  }, [recheckAfterSettings]);
+
+  return {
+    state: flowState,
+    nativeStatus,
+    isGranted: flowState === "granted",
+    isDenied: flowState === "denied",
+    isBlocked:
+      flowState === "blocked" || flowState === "blockedPrompt" || flowState === "openingSettings",
+    isChecking: flowState === "checking" || flowState === "recheckingAfterSettings",
+    isUnavailable: flowState === "unavailable",
+    request: requestPermission,
+    check: checkPermission,
+    dismiss,
+    openSettings: goToSettings,
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  BlockedPromptConfig,
+  MultiPermissionEntry,
+  MultiplePermissionsConfig,
+  MultiplePermissionsResult,
+  PermissionCallbacks,
+  PermissionFlowEvent,
+  PermissionFlowState,
+  PermissionHandlerConfig,
+  PermissionHandlerResult,
+  PrePromptConfig,
+} from "./types";
+
+export { transition } from "./core/state-machine";
+export { usePermissionHandler } from "./hooks/use-permission-handler";
+export { useMultiplePermissions } from "./hooks/use-multiple-permissions";
+export { PermissionGate } from "./components/permission-gate";
+export type { PermissionGateProps } from "./components/permission-gate";
+export { DefaultPrePrompt } from "./components/default-pre-prompt";
+export type { DefaultPrePromptProps } from "./components/default-pre-prompt";
+export { DefaultBlockedPrompt } from "./components/default-blocked-prompt";
+export type { DefaultBlockedPromptProps } from "./components/default-blocked-prompt";

package/src/types.ts

@@ -0,0 +1,114 @@
+import type { Permission, PermissionStatus } from "react-native-permissions";
+
+/**
+ * States of the permission flow state machine.
+ */
+export type PermissionFlowState =
+  | "idle"
+  | "checking"
+  | "prePrompt"
+  | "requesting"
+  | "granted"
+  | "denied"
+  | "blocked"
+  | "blockedPrompt"
+  | "openingSettings"
+  | "recheckingAfterSettings"
+  | "unavailable";
+
+/**
+ * Events that drive state transitions.
+ */
+export type PermissionFlowEvent =
+  | { type: "CHECK" }
+  | { type: "CHECK_RESULT"; status: PermissionStatus }
+  | { type: "PRE_PROMPT_CONFIRM" }
+  | { type: "PRE_PROMPT_DISMISS" }
+  | { type: "REQUEST_RESULT"; status: PermissionStatus }
+  | { type: "OPEN_SETTINGS" }
+  | { type: "SETTINGS_RETURN" }
+  | { type: "RECHECK_RESULT"; status: PermissionStatus };
+
+/**
+ * Configuration for the pre-prompt modal.
+ */
+export interface PrePromptConfig {
+  title: string;
+  message: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+}
+
+/**
+ * Configuration for the blocked-prompt modal.
+ */
+export interface BlockedPromptConfig {
+  title: string;
+  message: string;
+  settingsLabel?: string;
+}
+
+/**
+ * Callbacks for analytics and side effects.
+ */
+export interface PermissionCallbacks {
+  onGrant?: () => void;
+  onDeny?: () => void;
+  onBlock?: () => void;
+  onSettingsReturn?: (granted: boolean) => void;
+}
+
+/**
+ * Configuration for usePermissionHandler.
+ */
+export interface PermissionHandlerConfig extends PermissionCallbacks {
+  permission: Permission | "notifications";
+  prePrompt: PrePromptConfig;
+  blockedPrompt: BlockedPromptConfig;
+  autoCheck?: boolean;
+  recheckOnForeground?: boolean;
+}
+
+/**
+ * Return type of usePermissionHandler.
+ */
+export interface PermissionHandlerResult {
+  state: PermissionFlowState;
+  nativeStatus: PermissionStatus | null;
+  isGranted: boolean;
+  isDenied: boolean;
+  isBlocked: boolean;
+  isChecking: boolean;
+  isUnavailable: boolean;
+  request: () => void;
+  check: () => void;
+  dismiss: () => void;
+  openSettings: () => void;
+}
+
+/**
+ * Configuration for a single permission within useMultiplePermissions.
+ */
+export interface MultiPermissionEntry extends PermissionCallbacks {
+  permission: Permission | "notifications";
+  prePrompt: PrePromptConfig;
+  blockedPrompt: BlockedPromptConfig;
+}
+
+/**
+ * Configuration for useMultiplePermissions.
+ */
+export interface MultiplePermissionsConfig {
+  permissions: MultiPermissionEntry[];
+  strategy: "sequential" | "parallel";
+  onAllGranted?: () => void;
+}
+
+/**
+ * Return type of useMultiplePermissions.
+ */
+export interface MultiplePermissionsResult {
+  statuses: Record<string, PermissionFlowState>;
+  allGranted: boolean;
+  request: () => void;
+}