react-native-permission-gate 0.1.0

package/src/hooks/usePermission.ts

@@ -0,0 +1,205 @@
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+import { reduce, type MachineEvent, type MachineState } from '../core/machine';
+import { PermissionContext } from '../context';
+import type {
+  PermissionController,
+  PermissionName,
+  PermissionStatus,
+  UsePermissionOptions,
+} from '../types';
+
+interface Pending {
+  promise: Promise<PermissionStatus>;
+  resolve: (status: PermissionStatus) => void;
+}
+
+/**
+ * Headless permission-flow controller. Owns the state machine and wires its
+ * effects to the native adapter; renders nothing. Bring your own rationale and
+ * "blocked" UI and drive it off `phase` / `status`.
+ */
+export function usePermission(
+  name: PermissionName,
+  options: UsePermissionOptions = {}
+): PermissionController {
+  const ctx = useContext(PermissionContext);
+
+  const rationale = options.rationale ?? ctx.defaults.rationale ?? false;
+  const revalidateOnFocus =
+    options.revalidateOnFocus ?? ctx.defaults.revalidateOnFocus ?? true;
+  const requestOnMount =
+    options.requestOnMount ?? ctx.defaults.requestOnMount ?? false;
+  const onStatusChange = options.onStatusChange;
+  const adapter = options.adapter ?? ctx.adapter;
+
+  const supported = adapter.isSupported(name);
+
+  const neutral = (): MachineState => ({
+    status: supported ? 'requestable' : 'unavailable',
+    phase: 'idle',
+  });
+
+  const [state, setState] = useState<MachineState>(neutral);
+
+  // Mirror volatile values in refs so async effect callbacks read fresh data
+  // and the public callbacks stay referentially stable.
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const rationaleRef = useRef(rationale);
+  rationaleRef.current = rationale;
+  const onStatusChangeRef = useRef(onStatusChange);
+  onStatusChangeRef.current = onStatusChange;
+  const requestOnMountRef = useRef(requestOnMount);
+  requestOnMountRef.current = requestOnMount;
+
+  // Single in-flight request. Dedupes concurrent/double `request()` calls so a
+  // double-tap can never orphan a promise or fire two native prompts.
+  const pendingRef = useRef<Pending | null>(null);
+  const mountedRef = useRef(true);
+
+  const dispatch = useCallback(
+    (event: MachineEvent) => {
+      const { state: next, effects } = reduce(stateRef.current, event, {
+        rationale: rationaleRef.current,
+      });
+      stateRef.current = next;
+      if (mountedRef.current) setState(next);
+
+      for (const effect of effects) {
+        if (effect.type === 'resolve') {
+          const pending = pendingRef.current;
+          pendingRef.current = null;
+          pending?.resolve(effect.status);
+        } else if (effect.type === 'runRequest') {
+          adapter
+            .request(name)
+            .then((status) =>
+              dispatchRef.current({ type: 'REQUEST_RESULT', status })
+            )
+            .catch(() =>
+              dispatchRef.current({
+                type: 'REQUEST_RESULT',
+                status: stateRef.current.status,
+              })
+            );
+        }
+      }
+    },
+    [adapter, name]
+  );
+  const dispatchRef = useRef(dispatch);
+  dispatchRef.current = dispatch;
+
+  const request = useCallback(() => {
+    // Reuse the in-flight promise instead of starting a second flow.
+    if (pendingRef.current) return pendingRef.current.promise;
+    let resolve!: (status: PermissionStatus) => void;
+    const promise = new Promise<PermissionStatus>((r) => {
+      resolve = r;
+    });
+    pendingRef.current = { promise, resolve };
+    dispatchRef.current({ type: 'REQUEST' });
+    return promise;
+  }, []);
+  const requestRef = useRef(request);
+  requestRef.current = request;
+
+  const confirmRationale = useCallback(
+    () => dispatchRef.current({ type: 'CONFIRM_RATIONALE' }),
+    []
+  );
+
+  const cancelRationale = useCallback(
+    () => dispatchRef.current({ type: 'CANCEL_RATIONALE' }),
+    []
+  );
+
+  const refresh = useCallback(async () => {
+    if (!supported) return 'unavailable' as PermissionStatus;
+    const status = await adapter.check(name);
+    dispatchRef.current({ type: 'REFRESH_RESULT', status });
+    return status;
+  }, [adapter, name, supported]);
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+
+  const openSettings = useCallback(() => adapter.openSettings(), [adapter]);
+
+  // Initial check on mount and whenever the permission identity changes. On a
+  // change we reset to a neutral state first so a stale status never lingers.
+  const firstRunRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!firstRunRef.current) {
+      const reset = neutral();
+      stateRef.current = reset;
+      setState(reset);
+      pendingRef.current = null;
+    }
+    firstRunRef.current = false;
+
+    if (supported) {
+      adapter
+        .check(name)
+        .then((status) => {
+          dispatchRef.current({ type: 'CHECK_RESULT', status });
+          if (requestOnMountRef.current) requestRef.current();
+        })
+        .catch(() => {});
+    }
+    return () => {
+      mountedRef.current = false;
+    };
+    // `neutral` is derived from supported; requestOnMount is read via ref.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapter, name, supported]);
+
+  // Re-check when the app returns to the foreground.
+  useEffect(() => {
+    if (!revalidateOnFocus || !supported) return;
+    const sub = AppState.addEventListener('change', (next: AppStateStatus) => {
+      if (next === 'active') refreshRef.current();
+    });
+    return () => sub.remove();
+  }, [revalidateOnFocus, supported]);
+
+  // Notify on resolved-status changes.
+  const prevStatusRef = useRef(state.status);
+  useEffect(() => {
+    if (prevStatusRef.current !== state.status) {
+      prevStatusRef.current = state.status;
+      onStatusChangeRef.current?.(state.status);
+    }
+  }, [state.status]);
+
+  return useMemo<PermissionController>(
+    () => ({
+      status: state.status,
+      phase: state.phase,
+      isGranted: state.status === 'granted',
+      isBlocked: state.status === 'blocked',
+      request,
+      confirmRationale,
+      cancelRationale,
+      openSettings,
+      refresh,
+    }),
+    [
+      state.status,
+      state.phase,
+      request,
+      confirmRationale,
+      cancelRationale,
+      openSettings,
+      refresh,
+    ]
+  );
+}

package/src/hooks/usePermissions.ts

@@ -0,0 +1,241 @@
+import {
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+import { PermissionContext } from '../context';
+import type {
+  FlowPhase,
+  PermissionName,
+  PermissionStatus,
+  UsePermissionOptions,
+} from '../types';
+
+export type PermissionStatusMap = Partial<
+  Record<PermissionName, PermissionStatus>
+>;
+
+export interface PermissionsController {
+  /** Current status per requested permission. */
+  statuses: PermissionStatusMap;
+  /** Shared flow position for the batch. */
+  phase: FlowPhase;
+  /** Every requested permission is `granted`. */
+  allGranted: boolean;
+  /** At least one requested permission is `blocked`. */
+  anyBlocked: boolean;
+  /**
+   * Run the flow for every not-yet-granted permission behind a single shared
+   * rationale gate. Prompts are shown one after another. Resolves with the
+   * final status map.
+   */
+  request: () => Promise<PermissionStatusMap>;
+  /** Proceed from the shared `rationale` phase to the prompts. */
+  confirmRationale: () => void;
+  /** Abort the shared `rationale` phase. */
+  cancelRationale: () => void;
+  openSettings: () => Promise<void>;
+  refresh: () => Promise<PermissionStatusMap>;
+}
+
+interface Pending {
+  promise: Promise<PermissionStatusMap>;
+  resolve: (map: PermissionStatusMap) => void;
+}
+
+/**
+ * Aggregate variant of {@link usePermission} for permissions acquired together
+ * (e.g. camera + microphone for video). One shared rationale gate, one
+ * `request()`, one status map. The `names` array is treated as a stable set -
+ * pass a constant or memoized array.
+ */
+export function usePermissions(
+  names: PermissionName[],
+  options: UsePermissionOptions = {}
+): PermissionsController {
+  const ctx = useContext(PermissionContext);
+  const rationale = options.rationale ?? ctx.defaults.rationale ?? false;
+  const revalidateOnFocus =
+    options.revalidateOnFocus ?? ctx.defaults.revalidateOnFocus ?? true;
+  const requestOnMount =
+    options.requestOnMount ?? ctx.defaults.requestOnMount ?? false;
+  const adapter = options.adapter ?? ctx.adapter;
+
+  // Stable identity for the set so effects don't re-run on every new array.
+  const key = names.join(',');
+
+  const buildInitial = useCallback((): PermissionStatusMap => {
+    const map: PermissionStatusMap = {};
+    for (const name of names) {
+      map[name] = adapter.isSupported(name) ? 'requestable' : 'unavailable';
+    }
+    return map;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapter, key]);
+
+  const [statuses, setStatuses] = useState<PermissionStatusMap>(buildInitial);
+  const [phase, setPhase] = useState<FlowPhase>('idle');
+
+  const statusesRef = useRef(statuses);
+  statusesRef.current = statuses;
+  const phaseRef = useRef(phase);
+  phaseRef.current = phase;
+  const rationaleRef = useRef(rationale);
+  rationaleRef.current = rationale;
+  const requestOnMountRef = useRef(requestOnMount);
+  requestOnMountRef.current = requestOnMount;
+
+  const pendingRef = useRef<Pending | null>(null);
+  const requestableRef = useRef<PermissionName[]>([]);
+  const mountedRef = useRef(true);
+
+  const commit = useCallback((next: PermissionStatusMap) => {
+    statusesRef.current = next;
+    if (mountedRef.current) setStatuses(next);
+  }, []);
+
+  const settle = useCallback(() => {
+    if (mountedRef.current) setPhase('settled');
+    const pending = pendingRef.current;
+    pendingRef.current = null;
+    pending?.resolve(statusesRef.current);
+  }, []);
+
+  const runBatch = useCallback(
+    async (list: PermissionName[]) => {
+      if (mountedRef.current) setPhase('requesting');
+      for (const name of list) {
+        try {
+          const status = await adapter.request(name);
+          commit({ ...statusesRef.current, [name]: status });
+        } catch {
+          // Keep the previous status for this permission on failure.
+        }
+      }
+      settle();
+    },
+    [adapter, commit, settle]
+  );
+  const runBatchRef = useRef(runBatch);
+  runBatchRef.current = runBatch;
+
+  const request = useCallback(() => {
+    if (pendingRef.current) return pendingRef.current.promise;
+
+    let resolve!: (map: PermissionStatusMap) => void;
+    const promise = new Promise<PermissionStatusMap>((r) => {
+      resolve = r;
+    });
+    pendingRef.current = { promise, resolve };
+
+    const requestable = names.filter(
+      (name) => statusesRef.current[name] === 'requestable'
+    );
+    requestableRef.current = requestable;
+
+    if (requestable.length === 0) {
+      settle();
+    } else if (rationaleRef.current) {
+      if (mountedRef.current) setPhase('rationale');
+    } else {
+      runBatchRef.current(requestable);
+    }
+    return promise;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, settle]);
+  const requestRef = useRef(request);
+  requestRef.current = request;
+
+  const confirmRationale = useCallback(() => {
+    if (phaseRef.current !== 'rationale') return;
+    runBatchRef.current(requestableRef.current);
+  }, []);
+
+  const cancelRationale = useCallback(() => {
+    if (phaseRef.current !== 'rationale') return;
+    if (mountedRef.current) setPhase('idle');
+    const pending = pendingRef.current;
+    pendingRef.current = null;
+    pending?.resolve(statusesRef.current);
+  }, []);
+
+  const refresh = useCallback(async () => {
+    const entries = await Promise.all(
+      names.map(async (name) => {
+        if (!adapter.isSupported(name)) {
+          return [name, 'unavailable'] as const;
+        }
+        return [name, await adapter.check(name)] as const;
+      })
+    );
+    const next: PermissionStatusMap = {};
+    for (const [name, status] of entries) next[name] = status;
+    commit(next);
+    return next;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [adapter, key, commit]);
+  const refreshRef = useRef(refresh);
+  refreshRef.current = refresh;
+
+  const openSettings = useCallback(() => adapter.openSettings(), [adapter]);
+
+  // Initial check on mount / when the set changes.
+  const firstRunRef = useRef(true);
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!firstRunRef.current) {
+      commit(buildInitial());
+      setPhase('idle');
+      pendingRef.current = null;
+    }
+    firstRunRef.current = false;
+
+    refreshRef.current().then(() => {
+      if (requestOnMountRef.current) requestRef.current();
+    });
+
+    return () => {
+      mountedRef.current = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
+
+  // Re-check on foreground.
+  useEffect(() => {
+    if (!revalidateOnFocus) return;
+    const sub = AppState.addEventListener('change', (next: AppStateStatus) => {
+      if (next === 'active') refreshRef.current();
+    });
+    return () => sub.remove();
+  }, [revalidateOnFocus]);
+
+  return useMemo<PermissionsController>(() => {
+    const allGranted = names.every((name) => statuses[name] === 'granted');
+    const anyBlocked = names.some((name) => statuses[name] === 'blocked');
+    return {
+      statuses,
+      phase,
+      allGranted,
+      anyBlocked,
+      request,
+      confirmRationale,
+      cancelRationale,
+      openSettings,
+      refresh,
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    key,
+    statuses,
+    phase,
+    request,
+    confirmRationale,
+    cancelRationale,
+    openSettings,
+    refresh,
+  ]);
+}

package/src/imperative.ts

@@ -0,0 +1,35 @@
+import { reactNativePermissionsAdapter } from './adapters/reactNativePermissions';
+import type {
+  PermissionAdapter,
+  PermissionName,
+  PermissionStatus,
+} from './types';
+
+/**
+ * Imperative helpers for use outside React (services, sagas, utilities). These
+ * are the raw check/request/openSettings calls with no rationale UX - for the
+ * full flow with pre-prompts, use {@link usePermission} or {@link PermissionGate}.
+ */
+
+/** Read current status without prompting. */
+export function checkPermission(
+  name: PermissionName,
+  adapter: PermissionAdapter = reactNativePermissionsAdapter
+): Promise<PermissionStatus> {
+  return adapter.check(name);
+}
+
+/** Trigger the native OS prompt and resolve with the resulting status. */
+export function requestPermission(
+  name: PermissionName,
+  adapter: PermissionAdapter = reactNativePermissionsAdapter
+): Promise<PermissionStatus> {
+  return adapter.request(name);
+}
+
+/** Open the OS settings screen for this app. */
+export function openAppSettings(
+  adapter: PermissionAdapter = reactNativePermissionsAdapter
+): Promise<void> {
+  return adapter.openSettings();
+}

package/src/index.tsx

@@ -0,0 +1,42 @@
+// Hooks - the primary, headless API.
+export { usePermission } from './hooks/usePermission';
+export { usePermissions } from './hooks/usePermissions';
+export type {
+  PermissionsController,
+  PermissionStatusMap,
+} from './hooks/usePermissions';
+
+// Declarative convenience.
+export { PermissionGate } from './components/PermissionGate';
+export type {
+  PermissionGateProps,
+  RationaleControls,
+  BlockedControls,
+} from './components/PermissionGate';
+
+// Provider - optional shared adapter + default options.
+export { PermissionProvider, PermissionContext } from './context';
+export type {
+  PermissionProviderProps,
+  PermissionContextValue,
+  PermissionDefaults,
+} from './context';
+
+// Imperative helpers for use outside React.
+export {
+  checkPermission,
+  requestPermission,
+  openAppSettings,
+} from './imperative';
+
+// Default adapter (override via options.adapter or PermissionProvider).
+export { reactNativePermissionsAdapter } from './adapters/reactNativePermissions';
+
+export type {
+  PermissionName,
+  PermissionStatus,
+  FlowPhase,
+  PermissionController,
+  PermissionAdapter,
+  UsePermissionOptions,
+} from './types';

package/src/types.ts

@@ -0,0 +1,114 @@
+/**
+ * The OS-level truth about a permission, normalized across platforms.
+ *
+ * - `granted`      - access is allowed.
+ * - `limited`      - partial access (iOS: e.g. selected photos / contacts).
+ * - `requestable`  - not granted yet, but the OS prompt can still be shown.
+ * - `blocked`      - denied and the OS will no longer prompt; only Settings helps.
+ * - `unavailable`  - the capability does not exist on this device/build.
+ */
+export type PermissionStatus =
+  'granted' | 'limited' | 'requestable' | 'blocked' | 'unavailable';
+
+/**
+ * Where the request flow currently sits. Independent from {@link PermissionStatus}:
+ * `status` is the OS truth, `phase` is the position in the UX state machine.
+ *
+ * - `idle`        - nothing in flight.
+ * - `rationale`   - pre-prompt is shown, awaiting the user's decision.
+ * - `requesting`  - the native OS dialog is up.
+ * - `settled`     - the flow finished; read `status` for the outcome.
+ */
+export type FlowPhase = 'idle' | 'rationale' | 'requesting' | 'settled';
+
+/**
+ * Cross-platform permission aliases. Each maps to the correct native permission
+ * per platform inside the adapter. Aliases with no meaning on the current
+ * platform resolve to `unavailable`.
+ */
+export type PermissionName =
+  | 'camera'
+  | 'microphone'
+  | 'photoLibrary'
+  | 'photoLibraryAddOnly'
+  | 'mediaLibrary'
+  | 'contacts'
+  | 'calendar'
+  | 'calendarWriteOnly'
+  | 'reminders'
+  | 'locationWhenInUse'
+  | 'locationAlways'
+  | 'notifications'
+  | 'bluetooth'
+  | 'motion'
+  | 'speechRecognition'
+  | 'appTrackingTransparency'
+  | 'bodySensors'
+  | 'storageReadAudio'
+  | 'storageReadVideo'
+  | 'faceId';
+
+/**
+ * Backend that performs the actual native permission calls. The core state
+ * machine is adapter-agnostic, which keeps it fully unit-testable without any
+ * native module. The default adapter is built on `react-native-permissions`.
+ */
+export interface PermissionAdapter {
+  /** Whether the alias is meaningful on the current platform. */
+  isSupported(name: PermissionName): boolean;
+  /** Read current status without prompting. */
+  check(name: PermissionName): Promise<PermissionStatus>;
+  /** Trigger the native OS prompt and resolve with the resulting status. */
+  request(name: PermissionName): Promise<PermissionStatus>;
+  /** Open the OS settings screen for this app. */
+  openSettings(): Promise<void>;
+}
+
+export interface UsePermissionOptions {
+  /**
+   * Gate the native prompt behind a `rationale` phase so you can show a
+   * pre-prompt explanation first. When `true`, `request()` moves to
+   * `phase: 'rationale'` and waits for `confirmRationale()` / `cancelRationale()`.
+   * @default false
+   */
+  rationale?: boolean;
+  /**
+   * Re-check status when the app returns to the foreground - catches changes the
+   * user made in the OS Settings screen.
+   * @default true
+   */
+  revalidateOnFocus?: boolean;
+  /**
+   * Run the full request flow automatically on mount.
+   * @default false
+   */
+  requestOnMount?: boolean;
+  /** Called whenever the resolved {@link PermissionStatus} changes. */
+  onStatusChange?: (status: PermissionStatus) => void;
+  /** Override the backend. Defaults to the `react-native-permissions` adapter. */
+  adapter?: PermissionAdapter;
+}
+
+/** The headless controller returned by {@link usePermission}. */
+export interface PermissionController {
+  status: PermissionStatus;
+  phase: FlowPhase;
+  /** Convenience: `status === 'granted'`. */
+  isGranted: boolean;
+  /** Convenience: `status === 'blocked'`. */
+  isBlocked: boolean;
+  /**
+   * Run the flow: check → (rationale gate) → native prompt → settle. The promise
+   * resolves with the final status once the whole flow finishes, so it works
+   * both imperatively (`await request()`) and declaratively (render on `phase`).
+   */
+  request: () => Promise<PermissionStatus>;
+  /** Proceed from the `rationale` phase to the native prompt. */
+  confirmRationale: () => void;
+  /** Abort the `rationale` phase and return to `idle`. */
+  cancelRationale: () => void;
+  /** Open the OS settings screen for this app. */
+  openSettings: () => Promise<void>;
+  /** Re-check status on demand (also happens automatically on focus). */
+  refresh: () => Promise<PermissionStatus>;
+}