@ahmed109/gatekeeper-react 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Tamer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @ahmed109/gatekeeper-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Declarative React authorization and feature-flag toolkit with fail-safe loading state.
+
+Part of the **Gatekeeper** toolkit. Built on top of [`@ahmed109/gatekeeper-core`](https://www.npmjs.com/package/@ahmed109/gatekeeper-core).
+
+## Installation
+
+```bash
+npm install @ahmed109/gatekeeper-react @ahmed109/gatekeeper-core
+# or
+pnpm add @ahmed109/gatekeeper-react @ahmed109/gatekeeper-core
+```
+
+### Peer Dependencies
+
+- `react`: `>=18.0.0`
+- `react-dom`: `>=18.0.0`
+
+## Features
+
+- **Fail-Safe Loading**: Authorization decisions default to closed (`false`) during `isLoading: true`, eliminating UI flashes of restricted content.
+- **Declarative Guards**: `<Can>` and `<Feature>` components with customizable `fallback` slots.
+- **Reactive Hooks**: `usePermission()`, `useFeatureFlag()`, `useCanAll()`, `useCanAny()`, and `useGatekeeper()`.
+- **Permission Memoization**: Automatically caches effective permission sets to minimize evaluation overhead.
+
+## Quickstart
+
+```tsx
+import React from 'react';
+import { GatekeeperProvider, Can, Feature, usePermission } from '@ahmed109/gatekeeper-react';
+import type { GatekeeperUser } from '@ahmed109/gatekeeper-core';
+
+const currentUser: GatekeeperUser = {
+  id: 'usr_123',
+  name: 'Alice',
+  role: 'manager',
+  permissions: [],
+};
+
+const activeFlags = {
+  'beta-analytics': true,
+};
+
+export function App() {
+  return (
+    <GatekeeperProvider user={currentUser} flags={activeFlags} isLoading={false}>
+      <Dashboard />
+    </GatekeeperProvider>
+  );
+}
+
+function Dashboard() {
+  const canManage = usePermission('settings.manage');
+
+  return (
+    <div>
+      <h1>Operations Dashboard</h1>
+
+      {/* Declarative permission guard */}
+      <Can permission="users.read" fallback={<p>Access denied to users list.</p>}>
+        <UsersList />
+      </Can>
+
+      {/* Declarative feature flag guard */}
+      <Feature flag="beta-analytics" fallback={<p>Analytics coming soon.</p>}>
+        <AnalyticsPanel />
+      </Feature>
+    </div>
+  );
+}
+```
+
+## License
+
+MIT © [Ahmed Tamer](https://github.com/Ahmed1092002)

package/dist/index.cjs

@@ -0,0 +1,180 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Can: () => Can,
+  Feature: () => Feature,
+  GatekeeperContext: () => GatekeeperContext,
+  GatekeeperProvider: () => GatekeeperProvider,
+  useCanAll: () => useCanAll,
+  useCanAny: () => useCanAny,
+  useFeatureFlag: () => useFeatureFlag,
+  useGatekeeper: () => useGatekeeper,
+  usePermission: () => usePermission
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/context.tsx
+var import_react = require("react");
+var import_gatekeeper_core = require("@ahmed109/gatekeeper-core");
+var import_jsx_runtime = require("react/jsx-runtime");
+var GatekeeperContext = (0, import_react.createContext)(null);
+var GatekeeperProvider = ({
+  user,
+  currentUser,
+  subject,
+  flags,
+  featureFlags,
+  roleMap = import_gatekeeper_core.DEFAULT_ROLE_PERMISSIONS,
+  policy,
+  context,
+  isLoading = false,
+  children,
+  fallback = null
+}) => {
+  const activeUser = subject ?? user ?? currentUser ?? null;
+  const rawFlags = flags ?? featureFlags;
+  const normalizedFlags = (0, import_react.useMemo)(() => (0, import_gatekeeper_core.normalizeFeatureFlags)(rawFlags), [rawFlags]);
+  const effectivePermissions = (0, import_react.useMemo)(() => {
+    if (isLoading) return [];
+    return Array.from((0, import_gatekeeper_core.getUserEffectivePermissions)(activeUser, roleMap));
+  }, [activeUser, roleMap, isLoading]);
+  const contextValue = (0, import_react.useMemo)(() => {
+    return {
+      user: activeUser,
+      subject: activeUser,
+      flags: normalizedFlags,
+      roleMap,
+      policy,
+      context,
+      isLoading,
+      can: (permission, canOptions) => {
+        if (isLoading) return false;
+        const combinedOptions = {
+          roleMap: canOptions?.roleMap ?? roleMap,
+          policy: canOptions?.policy ?? policy,
+          context: canOptions?.context ?? context
+        };
+        return (0, import_gatekeeper_core.can)(activeUser, permission, combinedOptions);
+      },
+      canAll: (permissions, canOptions) => {
+        if (isLoading) return false;
+        const combinedOptions = {
+          roleMap: canOptions?.roleMap ?? roleMap,
+          policy: canOptions?.policy ?? policy,
+          context: canOptions?.context ?? context
+        };
+        return (0, import_gatekeeper_core.canAll)(activeUser, permissions, combinedOptions);
+      },
+      canAny: (permissions, canOptions) => {
+        if (isLoading) return false;
+        const combinedOptions = {
+          roleMap: canOptions?.roleMap ?? roleMap,
+          policy: canOptions?.policy ?? policy,
+          context: canOptions?.context ?? context
+        };
+        return (0, import_gatekeeper_core.canAny)(activeUser, permissions, combinedOptions);
+      },
+      isFeatureEnabled: (flagKey) => {
+        if (isLoading) return false;
+        return (0, import_gatekeeper_core.isFeatureEnabled)(normalizedFlags, flagKey);
+      },
+      effectivePermissions
+    };
+  }, [activeUser, normalizedFlags, roleMap, policy, context, isLoading, effectivePermissions]);
+  if (isLoading && fallback) {
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GatekeeperContext.Provider, { value: contextValue, children: fallback });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(GatekeeperContext.Provider, { value: contextValue, children });
+};
+
+// src/hooks.ts
+var import_react2 = require("react");
+function useGatekeeper() {
+  const context = (0, import_react2.useContext)(GatekeeperContext);
+  if (!context) {
+    throw new Error(
+      "useGatekeeper must be used within a <GatekeeperProvider>. Make sure to wrap your application with <GatekeeperProvider>."
+    );
+  }
+  return context;
+}
+function usePermission(permission, options) {
+  const { can } = useGatekeeper();
+  return can(permission, options);
+}
+function useFeatureFlag(flagKey) {
+  const { isFeatureEnabled } = useGatekeeper();
+  return isFeatureEnabled(flagKey);
+}
+function useCanAll(permissions, options) {
+  const { canAll } = useGatekeeper();
+  return canAll(permissions, options);
+}
+function useCanAny(permissions, options) {
+  const { canAny } = useGatekeeper();
+  return canAny(permissions, options);
+}
+
+// src/components.tsx
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var Can = ({
+  permission,
+  permissions,
+  requireAll = true,
+  context,
+  policy,
+  fallback = null,
+  children
+}) => {
+  const { can, canAll, canAny } = useGatekeeper();
+  let isAllowed = false;
+  const options = context || policy ? { context, policy } : void 0;
+  if (permission) {
+    isAllowed = can(permission, options);
+  } else if (permissions && permissions.length > 0) {
+    isAllowed = requireAll ? canAll(permissions, options) : canAny(permissions, options);
+  }
+  if (!isAllowed) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children });
+};
+var Feature = ({ flag, fallback = null, children }) => {
+  const { isFeatureEnabled } = useGatekeeper();
+  const enabled = isFeatureEnabled(flag);
+  if (!enabled) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_jsx_runtime2.Fragment, { children });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Can,
+  Feature,
+  GatekeeperContext,
+  GatekeeperProvider,
+  useCanAll,
+  useCanAny,
+  useFeatureFlag,
+  useGatekeeper,
+  usePermission
+});

package/dist/index.d.cts

@@ -0,0 +1,110 @@
+import { Permission, AuthorizationPolicy, AuthorizationSubject, RolePermissionsMap, EvaluateOptions, FeatureFlag } from '@ahmed109/gatekeeper-core';
+export { AuthorizationResult, FeatureFlag, GatekeeperUser, Permission, Role, RolePermissionsMap } from '@ahmed109/gatekeeper-core';
+import React, { ReactNode } from 'react';
+
+interface GatekeeperContextValue {
+    user: AuthorizationSubject | null;
+    subject: AuthorizationSubject | null;
+    flags: Record<string, boolean>;
+    roleMap: RolePermissionsMap;
+    policy?: AuthorizationPolicy;
+    context?: Record<string, unknown>;
+    isLoading: boolean;
+    can: (permission: Permission, options?: EvaluateOptions) => boolean;
+    canAll: (permissions: Permission[], options?: EvaluateOptions) => boolean;
+    canAny: (permissions: Permission[], options?: EvaluateOptions) => boolean;
+    isFeatureEnabled: (flagKey: string) => boolean;
+    effectivePermissions: string[];
+}
+interface GatekeeperProviderProps {
+    user?: AuthorizationSubject | null;
+    currentUser?: AuthorizationSubject | null;
+    subject?: AuthorizationSubject | null;
+    flags?: Record<string, boolean> | FeatureFlag[];
+    featureFlags?: Record<string, boolean> | FeatureFlag[];
+    roleMap?: RolePermissionsMap;
+    policy?: AuthorizationPolicy;
+    context?: Record<string, unknown>;
+    isLoading?: boolean;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface CanProps {
+    /** Single permission to check */
+    permission?: Permission;
+    /** Multiple permissions to check */
+    permissions?: Permission[];
+    /** If true when multiple permissions given, user must have all. Default is true */
+    requireAll?: boolean;
+    /** Optional scoped context for policy evaluation */
+    context?: Record<string, unknown>;
+    /** Optional policy callback overriding or supplementing provider policy */
+    policy?: AuthorizationPolicy;
+    /** Custom fallback component if unauthorized */
+    fallback?: ReactNode;
+    /** Content to render when authorized */
+    children: ReactNode;
+}
+interface FeatureProps {
+    /** Feature flag key to check */
+    flag: string;
+    /** Custom fallback component if flag is disabled */
+    fallback?: ReactNode;
+    /** Content to render when flag is active */
+    children: ReactNode;
+}
+
+declare const GatekeeperContext: React.Context<GatekeeperContextValue | null>;
+/**
+ * Top-level provider for Gatekeeper authorization and feature flags in React.
+ */
+declare const GatekeeperProvider: React.FC<GatekeeperProviderProps>;
+
+/**
+ * Access the full Gatekeeper context.
+ */
+declare function useGatekeeper(): GatekeeperContextValue;
+/**
+ * React hook to check if the current user has a specific permission.
+ *
+ * @example
+ * const canDelete = usePermission('users.delete');
+ * const canEdit = usePermission('projects.update', { context: { projectOwnerId: 'u1' } });
+ */
+declare function usePermission(permission: Permission, options?: EvaluateOptions): boolean;
+/**
+ * React hook to check if a feature flag is enabled.
+ *
+ * @example
+ * const hasBeta = useFeatureFlag('beta-analytics');
+ */
+declare function useFeatureFlag(flagKey: string): boolean;
+/**
+ * React hook to check if the current user has all specified permissions.
+ */
+declare function useCanAll(permissions: Permission[], options?: EvaluateOptions): boolean;
+/**
+ * React hook to check if the current user has at least one of the specified permissions.
+ */
+declare function useCanAny(permissions: Permission[], options?: EvaluateOptions): boolean;
+
+/**
+ * Conditionally renders children if the authenticated user has the required permission(s).
+ *
+ * @example
+ * <Can permission="users.delete" fallback={<p>Not allowed</p>}>
+ *   <DeleteUserButton />
+ * </Can>
+ */
+declare const Can: React.FC<CanProps>;
+/**
+ * Conditionally renders children if a specific feature flag is enabled.
+ *
+ * @example
+ * <Feature flag="new-dashboard" fallback={<LegacyDashboard />}>
+ *   <NewDashboard />
+ * </Feature>
+ */
+declare const Feature: React.FC<FeatureProps>;
+
+export { Can, type CanProps, Feature, type FeatureProps, GatekeeperContext, type GatekeeperContextValue, GatekeeperProvider, type GatekeeperProviderProps, useCanAll, useCanAny, useFeatureFlag, useGatekeeper, usePermission };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { Permission, AuthorizationPolicy, AuthorizationSubject, RolePermissionsMap, EvaluateOptions, FeatureFlag } from '@ahmed109/gatekeeper-core';
+export { AuthorizationResult, FeatureFlag, GatekeeperUser, Permission, Role, RolePermissionsMap } from '@ahmed109/gatekeeper-core';
+import React, { ReactNode } from 'react';
+
+interface GatekeeperContextValue {
+    user: AuthorizationSubject | null;
+    subject: AuthorizationSubject | null;
+    flags: Record<string, boolean>;
+    roleMap: RolePermissionsMap;
+    policy?: AuthorizationPolicy;
+    context?: Record<string, unknown>;
+    isLoading: boolean;
+    can: (permission: Permission, options?: EvaluateOptions) => boolean;
+    canAll: (permissions: Permission[], options?: EvaluateOptions) => boolean;
+    canAny: (permissions: Permission[], options?: EvaluateOptions) => boolean;
+    isFeatureEnabled: (flagKey: string) => boolean;
+    effectivePermissions: string[];
+}
+interface GatekeeperProviderProps {
+    user?: AuthorizationSubject | null;
+    currentUser?: AuthorizationSubject | null;
+    subject?: AuthorizationSubject | null;
+    flags?: Record<string, boolean> | FeatureFlag[];
+    featureFlags?: Record<string, boolean> | FeatureFlag[];
+    roleMap?: RolePermissionsMap;
+    policy?: AuthorizationPolicy;
+    context?: Record<string, unknown>;
+    isLoading?: boolean;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface CanProps {
+    /** Single permission to check */
+    permission?: Permission;
+    /** Multiple permissions to check */
+    permissions?: Permission[];
+    /** If true when multiple permissions given, user must have all. Default is true */
+    requireAll?: boolean;
+    /** Optional scoped context for policy evaluation */
+    context?: Record<string, unknown>;
+    /** Optional policy callback overriding or supplementing provider policy */
+    policy?: AuthorizationPolicy;
+    /** Custom fallback component if unauthorized */
+    fallback?: ReactNode;
+    /** Content to render when authorized */
+    children: ReactNode;
+}
+interface FeatureProps {
+    /** Feature flag key to check */
+    flag: string;
+    /** Custom fallback component if flag is disabled */
+    fallback?: ReactNode;
+    /** Content to render when flag is active */
+    children: ReactNode;
+}
+
+declare const GatekeeperContext: React.Context<GatekeeperContextValue | null>;
+/**
+ * Top-level provider for Gatekeeper authorization and feature flags in React.
+ */
+declare const GatekeeperProvider: React.FC<GatekeeperProviderProps>;
+
+/**
+ * Access the full Gatekeeper context.
+ */
+declare function useGatekeeper(): GatekeeperContextValue;
+/**
+ * React hook to check if the current user has a specific permission.
+ *
+ * @example
+ * const canDelete = usePermission('users.delete');
+ * const canEdit = usePermission('projects.update', { context: { projectOwnerId: 'u1' } });
+ */
+declare function usePermission(permission: Permission, options?: EvaluateOptions): boolean;
+/**
+ * React hook to check if a feature flag is enabled.
+ *
+ * @example
+ * const hasBeta = useFeatureFlag('beta-analytics');
+ */
+declare function useFeatureFlag(flagKey: string): boolean;
+/**
+ * React hook to check if the current user has all specified permissions.
+ */
+declare function useCanAll(permissions: Permission[], options?: EvaluateOptions): boolean;
+/**
+ * React hook to check if the current user has at least one of the specified permissions.
+ */
+declare function useCanAny(permissions: Permission[], options?: EvaluateOptions): boolean;
+
+/**
+ * Conditionally renders children if the authenticated user has the required permission(s).
+ *
+ * @example
+ * <Can permission="users.delete" fallback={<p>Not allowed</p>}>
+ *   <DeleteUserButton />
+ * </Can>
+ */
+declare const Can: React.FC<CanProps>;
+/**
+ * Conditionally renders children if a specific feature flag is enabled.
+ *
+ * @example
+ * <Feature flag="new-dashboard" fallback={<LegacyDashboard />}>
+ *   <NewDashboard />
+ * </Feature>
+ */
+declare const Feature: React.FC<FeatureProps>;
+
+export { Can, type CanProps, Feature, type FeatureProps, GatekeeperContext, type GatekeeperContextValue, GatekeeperProvider, type GatekeeperProviderProps, useCanAll, useCanAny, useFeatureFlag, useGatekeeper, usePermission };

package/dist/index.js

@@ -0,0 +1,153 @@
+// src/context.tsx
+import { createContext, useMemo } from "react";
+import {
+  DEFAULT_ROLE_PERMISSIONS,
+  can as coreCan,
+  canAll as coreCanAll,
+  canAny as coreCanAny,
+  getUserEffectivePermissions,
+  isFeatureEnabled as coreIsFeatureEnabled,
+  normalizeFeatureFlags
+} from "@ahmed109/gatekeeper-core";
+import { jsx } from "react/jsx-runtime";
+var GatekeeperContext = createContext(null);
+var GatekeeperProvider = ({
+  user,
+  currentUser,
+  subject,
+  flags,
+  featureFlags,
+  roleMap = DEFAULT_ROLE_PERMISSIONS,
+  policy,
+  context,
+  isLoading = false,
+  children,
+  fallback = null
+}) => {
+  const activeUser = subject ?? user ?? currentUser ?? null;
+  const rawFlags = flags ?? featureFlags;
+  const normalizedFlags = useMemo(() => normalizeFeatureFlags(rawFlags), [rawFlags]);
+  const effectivePermissions = useMemo(() => {
+    if (isLoading) return [];
+    return Array.from(getUserEffectivePermissions(activeUser, roleMap));
+  }, [activeUser, roleMap, isLoading]);
+  const contextValue = useMemo(() => {
+    return {
+      user: activeUser,
+      subject: activeUser,
+      flags: normalizedFlags,
+      roleMap,
+      policy,
+      context,
+      isLoading,
+      can: (permission, canOptions) => {
+        if (isLoading) return false;
+        const combinedOptions = {
+          roleMap: canOptions?.roleMap ?? roleMap,
+          policy: canOptions?.policy ?? policy,
+          context: canOptions?.context ?? context
+        };
+        return coreCan(activeUser, permission, combinedOptions);
+      },
+      canAll: (permissions, canOptions) => {
+        if (isLoading) return false;
+        const combinedOptions = {
+          roleMap: canOptions?.roleMap ?? roleMap,
+          policy: canOptions?.policy ?? policy,
+          context: canOptions?.context ?? context
+        };
+        return coreCanAll(activeUser, permissions, combinedOptions);
+      },
+      canAny: (permissions, canOptions) => {
+        if (isLoading) return false;
+        const combinedOptions = {
+          roleMap: canOptions?.roleMap ?? roleMap,
+          policy: canOptions?.policy ?? policy,
+          context: canOptions?.context ?? context
+        };
+        return coreCanAny(activeUser, permissions, combinedOptions);
+      },
+      isFeatureEnabled: (flagKey) => {
+        if (isLoading) return false;
+        return coreIsFeatureEnabled(normalizedFlags, flagKey);
+      },
+      effectivePermissions
+    };
+  }, [activeUser, normalizedFlags, roleMap, policy, context, isLoading, effectivePermissions]);
+  if (isLoading && fallback) {
+    return /* @__PURE__ */ jsx(GatekeeperContext.Provider, { value: contextValue, children: fallback });
+  }
+  return /* @__PURE__ */ jsx(GatekeeperContext.Provider, { value: contextValue, children });
+};
+
+// src/hooks.ts
+import { useContext } from "react";
+function useGatekeeper() {
+  const context = useContext(GatekeeperContext);
+  if (!context) {
+    throw new Error(
+      "useGatekeeper must be used within a <GatekeeperProvider>. Make sure to wrap your application with <GatekeeperProvider>."
+    );
+  }
+  return context;
+}
+function usePermission(permission, options) {
+  const { can } = useGatekeeper();
+  return can(permission, options);
+}
+function useFeatureFlag(flagKey) {
+  const { isFeatureEnabled } = useGatekeeper();
+  return isFeatureEnabled(flagKey);
+}
+function useCanAll(permissions, options) {
+  const { canAll } = useGatekeeper();
+  return canAll(permissions, options);
+}
+function useCanAny(permissions, options) {
+  const { canAny } = useGatekeeper();
+  return canAny(permissions, options);
+}
+
+// src/components.tsx
+import { Fragment, jsx as jsx2 } from "react/jsx-runtime";
+var Can = ({
+  permission,
+  permissions,
+  requireAll = true,
+  context,
+  policy,
+  fallback = null,
+  children
+}) => {
+  const { can, canAll, canAny } = useGatekeeper();
+  let isAllowed = false;
+  const options = context || policy ? { context, policy } : void 0;
+  if (permission) {
+    isAllowed = can(permission, options);
+  } else if (permissions && permissions.length > 0) {
+    isAllowed = requireAll ? canAll(permissions, options) : canAny(permissions, options);
+  }
+  if (!isAllowed) {
+    return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ jsx2(Fragment, { children });
+};
+var Feature = ({ flag, fallback = null, children }) => {
+  const { isFeatureEnabled } = useGatekeeper();
+  const enabled = isFeatureEnabled(flag);
+  if (!enabled) {
+    return /* @__PURE__ */ jsx2(Fragment, { children: fallback });
+  }
+  return /* @__PURE__ */ jsx2(Fragment, { children });
+};
+export {
+  Can,
+  Feature,
+  GatekeeperContext,
+  GatekeeperProvider,
+  useCanAll,
+  useCanAny,
+  useFeatureFlag,
+  useGatekeeper,
+  usePermission
+};

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@ahmed109/gatekeeper-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "React authorization and feature-flag toolkit with fail-safe loading state powered by Gatekeeper Core",
+  "keywords": [
+    "react",
+    "authorization",
+    "permissions",
+    "feature-flags",
+    "rbac",
+    "hooks",
+    "components"
+  ],
+  "author": "Ahmed Tamer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ahmed1092002/npm-packages.git",
+    "directory": "gatekeeper/packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/Ahmed1092002/npm-packages/issues"
+  },
+  "homepage": "https://github.com/Ahmed1092002/npm-packages/tree/main/gatekeeper#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "@ahmed109/gatekeeper-core": "^0.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "jsdom": "^26.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external react,react-dom,@ahmed109/gatekeeper-core",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch --external react,react-dom,@ahmed109/gatekeeper-core",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
 }