react-native-permission-handler 0.1.0

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "react-native-permission-handler",
+  "version": "0.1.0",
+  "description": "Smart permission UX flows for React Native — pre-prompts, blocked handling, settings redirect & foreground re-check. Built on react-native-permissions.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "lint:fix": "biome check --fix .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "react-native",
+    "permissions",
+    "permission",
+    "permission-flow",
+    "soft-prompt",
+    "pre-prompt",
+    "permission-ux",
+    "ios",
+    "android",
+    "settings",
+    "runtime-permissions",
+    "permission-handler"
+  ],
+  "author": "Radu Ghitescu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/radughitescu/react-native-permission-handler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/radughitescu/react-native-permission-handler/issues"
+  },
+  "homepage": "https://github.com/radughitescu/react-native-permission-handler#readme",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.76.0",
+    "react-native-permissions": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@testing-library/react-native": "^12.0.0",
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "react-native": "^0.76.0",
+    "react-native-permissions": "^5.5.1",
+    "react-test-renderer": "^18.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/components/default-blocked-prompt.tsx

@@ -0,0 +1,76 @@
+import React from "react";
+import { Modal, StyleSheet, Text, TouchableOpacity, View } from "react-native";
+import type { BlockedPromptConfig } from "../types";
+
+export interface DefaultBlockedPromptProps extends BlockedPromptConfig {
+  visible: boolean;
+  onOpenSettings: () => void;
+}
+
+export function DefaultBlockedPrompt({
+  visible,
+  title,
+  message,
+  settingsLabel = "Open Settings",
+  onOpenSettings,
+}: DefaultBlockedPromptProps) {
+  return (
+    <Modal visible={visible} transparent animationType="fade">
+      <View style={styles.overlay}>
+        <View style={styles.modal}>
+          <Text style={styles.title}>{title}</Text>
+          <Text style={styles.message}>{message}</Text>
+          <TouchableOpacity
+            style={styles.settingsButton}
+            onPress={onOpenSettings}
+            accessibilityRole="button"
+          >
+            <Text style={styles.settingsText}>{settingsLabel}</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: "rgba(0,0,0,0.5)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  modal: {
+    backgroundColor: "white",
+    borderRadius: 16,
+    padding: 24,
+    width: "85%",
+    alignItems: "center",
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: "600",
+    marginBottom: 12,
+    textAlign: "center",
+  },
+  message: {
+    fontSize: 15,
+    color: "#666",
+    textAlign: "center",
+    marginBottom: 24,
+    lineHeight: 22,
+  },
+  settingsButton: {
+    backgroundColor: "#007AFF",
+    borderRadius: 12,
+    paddingVertical: 14,
+    paddingHorizontal: 32,
+    width: "100%",
+    alignItems: "center",
+  },
+  settingsText: {
+    color: "white",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+});

package/src/components/default-pre-prompt.tsx

@@ -0,0 +1,87 @@
+import React from "react";
+import { Modal, StyleSheet, Text, TouchableOpacity, View } from "react-native";
+import type { PrePromptConfig } from "../types";
+
+export interface DefaultPrePromptProps extends PrePromptConfig {
+  visible: boolean;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+export function DefaultPrePrompt({
+  visible,
+  title,
+  message,
+  confirmLabel = "Continue",
+  cancelLabel = "Not Now",
+  onConfirm,
+  onCancel,
+}: DefaultPrePromptProps) {
+  return (
+    <Modal visible={visible} transparent animationType="fade">
+      <View style={styles.overlay}>
+        <View style={styles.modal}>
+          <Text style={styles.title}>{title}</Text>
+          <Text style={styles.message}>{message}</Text>
+          <TouchableOpacity
+            style={styles.confirmButton}
+            onPress={onConfirm}
+            accessibilityRole="button"
+          >
+            <Text style={styles.confirmText}>{confirmLabel}</Text>
+          </TouchableOpacity>
+          <TouchableOpacity onPress={onCancel} accessibilityRole="button">
+            <Text style={styles.cancelText}>{cancelLabel}</Text>
+          </TouchableOpacity>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: "rgba(0,0,0,0.5)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  modal: {
+    backgroundColor: "white",
+    borderRadius: 16,
+    padding: 24,
+    width: "85%",
+    alignItems: "center",
+  },
+  title: {
+    fontSize: 20,
+    fontWeight: "600",
+    marginBottom: 12,
+    textAlign: "center",
+  },
+  message: {
+    fontSize: 15,
+    color: "#666",
+    textAlign: "center",
+    marginBottom: 24,
+    lineHeight: 22,
+  },
+  confirmButton: {
+    backgroundColor: "#007AFF",
+    borderRadius: 12,
+    paddingVertical: 14,
+    paddingHorizontal: 32,
+    width: "100%",
+    alignItems: "center",
+    marginBottom: 12,
+  },
+  confirmText: {
+    color: "white",
+    fontSize: 16,
+    fontWeight: "600",
+  },
+  cancelText: {
+    color: "#007AFF",
+    fontSize: 15,
+  },
+});

package/src/components/permission-gate.tsx

@@ -0,0 +1,105 @@
+import React from "react";
+import type { ReactNode } from "react";
+import type { Permission } from "react-native-permissions";
+import { usePermissionHandler } from "../hooks/use-permission-handler";
+import type { BlockedPromptConfig, PermissionCallbacks, PrePromptConfig } from "../types";
+import { DefaultBlockedPrompt } from "./default-blocked-prompt";
+import { DefaultPrePrompt } from "./default-pre-prompt";
+
+export interface PermissionGateProps extends PermissionCallbacks {
+  permission: Permission | "notifications";
+  prePrompt: PrePromptConfig;
+  blockedPrompt: BlockedPromptConfig;
+  children: ReactNode;
+  fallback?: ReactNode;
+  renderPrePrompt?: (props: {
+    config: PrePromptConfig;
+    onConfirm: () => void;
+    onCancel: () => void;
+  }) => ReactNode;
+  renderBlockedPrompt?: (props: {
+    config: BlockedPromptConfig;
+    onOpenSettings: () => void;
+  }) => ReactNode;
+}
+
+export function PermissionGate({
+  permission,
+  prePrompt,
+  blockedPrompt,
+  children,
+  fallback = null,
+  renderPrePrompt,
+  renderBlockedPrompt,
+  onGrant,
+  onDeny,
+  onBlock,
+  onSettingsReturn,
+}: PermissionGateProps) {
+  const handler = usePermissionHandler({
+    permission,
+    prePrompt,
+    blockedPrompt,
+    onGrant,
+    onDeny,
+    onBlock,
+    onSettingsReturn,
+  });
+
+  if (handler.isGranted) {
+    return <>{children}</>;
+  }
+
+  if (handler.isChecking || handler.isUnavailable) {
+    return <>{fallback}</>;
+  }
+
+  if (handler.state === "prePrompt") {
+    if (renderPrePrompt) {
+      return (
+        <>
+          {renderPrePrompt({
+            config: prePrompt,
+            onConfirm: handler.request,
+            onCancel: handler.dismiss,
+          })}
+        </>
+      );
+    }
+    return (
+      <DefaultPrePrompt
+        visible
+        title={prePrompt.title}
+        message={prePrompt.message}
+        confirmLabel={prePrompt.confirmLabel}
+        cancelLabel={prePrompt.cancelLabel}
+        onConfirm={handler.request}
+        onCancel={handler.dismiss}
+      />
+    );
+  }
+
+  if (handler.state === "blockedPrompt") {
+    if (renderBlockedPrompt) {
+      return (
+        <>
+          {renderBlockedPrompt({
+            config: blockedPrompt,
+            onOpenSettings: handler.openSettings,
+          })}
+        </>
+      );
+    }
+    return (
+      <DefaultBlockedPrompt
+        visible
+        title={blockedPrompt.title}
+        message={blockedPrompt.message}
+        settingsLabel={blockedPrompt.settingsLabel}
+        onOpenSettings={handler.openSettings}
+      />
+    );
+  }
+
+  return <>{fallback}</>;
+}

package/src/core/state-machine.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from "vitest";
+import type { PermissionFlowEvent, PermissionFlowState } from "../types";
+import { transition } from "./state-machine";
+
+describe("transition — idle", () => {
+  it("transitions to checking on CHECK", () => {
+    expect(transition("idle", { type: "CHECK" })).toBe("checking");
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("idle", { type: "PRE_PROMPT_CONFIRM" })).toBe("idle");
+    expect(transition("idle", { type: "PRE_PROMPT_DISMISS" })).toBe("idle");
+    expect(transition("idle", { type: "OPEN_SETTINGS" })).toBe("idle");
+    expect(transition("idle", { type: "SETTINGS_RETURN" })).toBe("idle");
+  });
+});
+
+describe("transition — checking", () => {
+  it("transitions to granted on granted status", () => {
+    expect(transition("checking", { type: "CHECK_RESULT", status: "granted" })).toBe("granted");
+  });
+
+  it("transitions to granted on limited status", () => {
+    expect(transition("checking", { type: "CHECK_RESULT", status: "limited" })).toBe("granted");
+  });
+
+  it("transitions to prePrompt on denied status", () => {
+    expect(transition("checking", { type: "CHECK_RESULT", status: "denied" })).toBe("prePrompt");
+  });
+
+  it("transitions to blockedPrompt on blocked status", () => {
+    expect(transition("checking", { type: "CHECK_RESULT", status: "blocked" })).toBe(
+      "blockedPrompt",
+    );
+  });
+
+  it("transitions to unavailable on unavailable status", () => {
+    expect(transition("checking", { type: "CHECK_RESULT", status: "unavailable" })).toBe(
+      "unavailable",
+    );
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("checking", { type: "CHECK" })).toBe("checking");
+    expect(transition("checking", { type: "PRE_PROMPT_CONFIRM" })).toBe("checking");
+  });
+});
+
+describe("transition — prePrompt", () => {
+  it("transitions to requesting on PRE_PROMPT_CONFIRM", () => {
+    expect(transition("prePrompt", { type: "PRE_PROMPT_CONFIRM" })).toBe("requesting");
+  });
+
+  it("transitions to denied on PRE_PROMPT_DISMISS", () => {
+    expect(transition("prePrompt", { type: "PRE_PROMPT_DISMISS" })).toBe("denied");
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("prePrompt", { type: "CHECK" })).toBe("prePrompt");
+    expect(transition("prePrompt", { type: "OPEN_SETTINGS" })).toBe("prePrompt");
+  });
+});
+
+describe("transition — requesting", () => {
+  it("transitions to granted on granted status", () => {
+    expect(transition("requesting", { type: "REQUEST_RESULT", status: "granted" })).toBe("granted");
+  });
+
+  it("transitions to granted on limited status", () => {
+    expect(transition("requesting", { type: "REQUEST_RESULT", status: "limited" })).toBe("granted");
+  });
+
+  it("transitions to denied on denied status", () => {
+    expect(transition("requesting", { type: "REQUEST_RESULT", status: "denied" })).toBe("denied");
+  });
+
+  it("transitions to blockedPrompt on blocked status", () => {
+    expect(transition("requesting", { type: "REQUEST_RESULT", status: "blocked" })).toBe(
+      "blockedPrompt",
+    );
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("requesting", { type: "CHECK" })).toBe("requesting");
+    expect(transition("requesting", { type: "PRE_PROMPT_CONFIRM" })).toBe("requesting");
+  });
+});
+
+describe("transition — blockedPrompt", () => {
+  it("transitions to openingSettings on OPEN_SETTINGS", () => {
+    expect(transition("blockedPrompt", { type: "OPEN_SETTINGS" })).toBe("openingSettings");
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("blockedPrompt", { type: "CHECK" })).toBe("blockedPrompt");
+    expect(transition("blockedPrompt", { type: "PRE_PROMPT_CONFIRM" })).toBe("blockedPrompt");
+  });
+});
+
+describe("transition — openingSettings", () => {
+  it("transitions to recheckingAfterSettings on SETTINGS_RETURN", () => {
+    expect(transition("openingSettings", { type: "SETTINGS_RETURN" })).toBe(
+      "recheckingAfterSettings",
+    );
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("openingSettings", { type: "CHECK" })).toBe("openingSettings");
+    expect(transition("openingSettings", { type: "OPEN_SETTINGS" })).toBe("openingSettings");
+  });
+});
+
+describe("transition — recheckingAfterSettings", () => {
+  it("transitions to granted on granted status", () => {
+    expect(
+      transition("recheckingAfterSettings", {
+        type: "RECHECK_RESULT",
+        status: "granted",
+      }),
+    ).toBe("granted");
+  });
+
+  it("transitions to granted on limited status", () => {
+    expect(
+      transition("recheckingAfterSettings", {
+        type: "RECHECK_RESULT",
+        status: "limited",
+      }),
+    ).toBe("granted");
+  });
+
+  it("transitions to blockedPrompt on blocked status", () => {
+    expect(
+      transition("recheckingAfterSettings", {
+        type: "RECHECK_RESULT",
+        status: "blocked",
+      }),
+    ).toBe("blockedPrompt");
+  });
+
+  it("transitions to blockedPrompt on denied status", () => {
+    expect(
+      transition("recheckingAfterSettings", {
+        type: "RECHECK_RESULT",
+        status: "denied",
+      }),
+    ).toBe("blockedPrompt");
+  });
+
+  it("ignores unrelated events", () => {
+    expect(transition("recheckingAfterSettings", { type: "CHECK" })).toBe(
+      "recheckingAfterSettings",
+    );
+  });
+});
+
+describe("transition — terminal states allow re-checking", () => {
+  it("granted → checking on CHECK", () => {
+    expect(transition("granted", { type: "CHECK" })).toBe("checking");
+  });
+
+  it("denied → checking on CHECK", () => {
+    expect(transition("denied", { type: "CHECK" })).toBe("checking");
+  });
+
+  it("unavailable → checking on CHECK", () => {
+    expect(transition("unavailable", { type: "CHECK" })).toBe("checking");
+  });
+
+  it("granted ignores unrelated events", () => {
+    expect(transition("granted", { type: "OPEN_SETTINGS" })).toBe("granted");
+  });
+
+  it("denied ignores unrelated events", () => {
+    expect(transition("denied", { type: "OPEN_SETTINGS" })).toBe("denied");
+  });
+
+  it("unavailable ignores unrelated events", () => {
+    expect(transition("unavailable", { type: "OPEN_SETTINGS" })).toBe("unavailable");
+  });
+});
+
+describe("transition — blocked state", () => {
+  it("stays blocked on any event", () => {
+    expect(transition("blocked", { type: "CHECK" })).toBe("blocked");
+    expect(transition("blocked", { type: "OPEN_SETTINGS" })).toBe("blocked");
+    expect(transition("blocked", { type: "PRE_PROMPT_CONFIRM" })).toBe("blocked");
+  });
+});
+
+describe("transition — robustness: no state throws on any event", () => {
+  const allStates: PermissionFlowState[] = [
+    "idle",
+    "checking",
+    "prePrompt",
+    "requesting",
+    "granted",
+    "denied",
+    "blocked",
+    "blockedPrompt",
+    "openingSettings",
+    "recheckingAfterSettings",
+    "unavailable",
+  ];
+
+  const allEvents: PermissionFlowEvent[] = [
+    { type: "CHECK" },
+    { type: "CHECK_RESULT", status: "granted" },
+    { type: "CHECK_RESULT", status: "denied" },
+    { type: "CHECK_RESULT", status: "blocked" },
+    { type: "CHECK_RESULT", status: "unavailable" },
+    { type: "CHECK_RESULT", status: "limited" },
+    { type: "PRE_PROMPT_CONFIRM" },
+    { type: "PRE_PROMPT_DISMISS" },
+    { type: "REQUEST_RESULT", status: "granted" },
+    { type: "REQUEST_RESULT", status: "denied" },
+    { type: "REQUEST_RESULT", status: "blocked" },
+    { type: "REQUEST_RESULT", status: "limited" },
+    { type: "OPEN_SETTINGS" },
+    { type: "SETTINGS_RETURN" },
+    { type: "RECHECK_RESULT", status: "granted" },
+    { type: "RECHECK_RESULT", status: "denied" },
+    { type: "RECHECK_RESULT", status: "blocked" },
+    { type: "RECHECK_RESULT", status: "limited" },
+  ];
+
+  for (const state of allStates) {
+    for (const event of allEvents) {
+      it(`does not throw: state=${state}, event=${event.type}`, () => {
+        expect(() => transition(state, event)).not.toThrow();
+      });
+    }
+  }
+});

package/src/core/state-machine.ts

@@ -0,0 +1,87 @@
+import type { PermissionFlowEvent, PermissionFlowState } from "../types";
+
+export function transition(
+  state: PermissionFlowState,
+  event: PermissionFlowEvent,
+): PermissionFlowState {
+  switch (state) {
+    case "idle":
+      if (event.type === "CHECK") return "checking";
+      return state;
+
+    case "checking":
+      if (event.type === "CHECK_RESULT") {
+        switch (event.status) {
+          case "granted":
+          case "limited":
+            return "granted";
+          case "denied":
+            return "prePrompt";
+          case "blocked":
+            return "blockedPrompt";
+          case "unavailable":
+            return "unavailable";
+          default:
+            return state;
+        }
+      }
+      return state;
+
+    case "prePrompt":
+      if (event.type === "PRE_PROMPT_CONFIRM") return "requesting";
+      if (event.type === "PRE_PROMPT_DISMISS") return "denied";
+      return state;
+
+    case "requesting":
+      if (event.type === "REQUEST_RESULT") {
+        switch (event.status) {
+          case "granted":
+          case "limited":
+            return "granted";
+          case "denied":
+            return "denied";
+          case "blocked":
+            return "blockedPrompt";
+          default:
+            return state;
+        }
+      }
+      return state;
+
+    case "blockedPrompt":
+      if (event.type === "OPEN_SETTINGS") return "openingSettings";
+      return state;
+
+    case "openingSettings":
+      if (event.type === "SETTINGS_RETURN") return "recheckingAfterSettings";
+      return state;
+
+    case "recheckingAfterSettings":
+      if (event.type === "RECHECK_RESULT") {
+        switch (event.status) {
+          case "granted":
+          case "limited":
+            return "granted";
+          case "blocked":
+            return "blockedPrompt";
+          case "denied":
+            return "blockedPrompt";
+          default:
+            return state;
+        }
+      }
+      return state;
+
+    case "granted":
+    case "denied":
+    case "unavailable":
+      if (event.type === "CHECK") return "checking";
+      return state;
+
+    case "blocked":
+      return state;
+
+    default:
+      return state;
+  }
+}