\n \n \n );\n}\n\nfunction Shell() {\n const { can, hasRole } = usePermission();\n\n return (\n \n
\n\n
\n {/* Route protection */}\n }>\n \n \n \n
\n {/* Button protection */}\n \n \n \n\n \n \n \n
\n );\n}\n\nfunction InvoiceActions({ invoice }: { invoice: { id: string } }) {\n const { can } = usePermission();\n\n return (\n Awaiting permission}>\n \n {/* Feature visibility */}\n {can('invoice.approve') ? : null}\n \n );\n}\n```\n\nThis pattern keeps:\n\n| Concern | Approach |\n| --- | --- |\n| Sidebar | `` / `hasRole` |\n| Buttons | Declarative `` |\n| Routes | `` |\n| Business checks | Out of random utilities |\n\n---\n\n## 11. Architecture\n\nHigh-level data flow:\n\n```text\n┌─────────────────────────────────────────────┐\n│ Application UI │\n│ (pages, buttons, menus) │\n└─────────────────────┬───────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────┐\n│ PermissionProvider │\n│ React adapter · context · lifecycle │\n└─────────────────────┬───────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────┐\n│ Permission Store / Engine │\n│ (src/core · no React) │\n│ │\n│ ┌───────────┐ ┌──────────┐ ┌─────────┐ │\n│ │ Matchers │ │ Roles │ │ Decisions│ │\n│ │ exact + * │ │ inherit │ │ explain │ │\n│ └───────────┘ └──────────┘ └─────────┘ │\n│ │\n│ ┌─────────────────────────────────────┐ │\n│ │ Async: loader · resolver · cache │ │\n│ └─────────────────────────────────────┘ │\n└─────────────────────┬───────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────┐\n│ Permission Decision │\n│ can() · · │\n└─────────────────────────────────────────────┘\n```\n\n### Why the engine is separated\n\n- UI libraries should not own authorization rules\n- The same core can power Vue / Next / Angular adapters later\n- Unit tests can target pure functions without rendering React\n- Bundle stays focused: React layer is a thin wrapper\n\n### Multi-framework direction\n\n```text\n@abolfazl-khalaj/permission-core ← planned extraction of src/core\n ▲\n │\n@abolfazl-khalaj/permission-react ← this package (ships today)\n@abolfazl-khalaj/permission-vue ← planned\n@abolfazl-khalaj/permission-next ← planned\n```\n\nToday, core code ships inside the React package but lives in an isolated `src/core` tree with **zero React imports**.\n\n---\n\n## 12. Best Practices\n\n### Do\n\n| Practice | Why |\n| --- | --- |\n| Load permissions from backend / token into a `Subject` | Single source of truth |\n| Use namespaced strings (`invoice.approve`, `users.*`) | Readable, scalable catalogs |\n| Put `PermissionProvider` near the top of the authenticated tree | One context for the app |\n| Prefer `` for UI, `can()` for logic | Clear separation |\n| Use `loading` UI with `permissionLoader` | Prevents unauthorized flashes |\n| Use `explain` / `debug` while developing rules | Faster diagnosis |\n| Version `roleDefinitions` with your backend | Avoid drift |\n\n### Don’t\n\n| Anti-pattern | Why |\n| --- | --- |\n| Mix auth redirects with authz in random components | Hard to reason about |\n| Hardcode the same permission in 20 files | Drift and typos |\n| Re-implement matching outside the engine | Divergent rules |\n| Assume permissions are ready before `status === 'resolved'` | Race conditions |\n| Depend on internal `src/core` paths | Not a public contract |\n\n**Suggested constants module:**\n\n```ts\nexport const Permissions = {\n UserCreate: 'user.create',\n UserDelete: 'user.delete',\n InvoiceApprove: 'invoice.approve',\n} as const;\n```\n\n---\n\n## 13. Security & Limitations\n\n> **This package is for client-side / UI authorization only.** \n> It does **not** replace backend authorization, API authorization, or server-side policy enforcement.\n\nTreat every permission check in the browser as a **UX and presentation control**:\n\n| Layer | Responsibility |\n| --- | --- |\n| This library | Hide, disable, or gate UI based on known grants |\n| Your backend | Enforce the same rules on every sensitive operation |\n\n### Security principles baked into the engine\n\n| Principle | Behavior |\n| --- | --- |\n| **Fail closed** | Unknown / missing permission → deny |\n| **Empty requirements** | `\"\"` never authorizes |\n| **Loading** | While `status` is `idle` / `loading`, `` does not render privileged children |\n| **Subject input** | Caller mutations of role/permission arrays do not affect a normalized snapshot |\n\n### What this library will not do\n\n- Encrypt or validate tokens\n- Prevent forged client permission arrays\n- Guarantee that a user cannot call your API without a grant\n- Replace CSRF, authn, rate limiting, or tenancy checks\n\nAlways re-check authorization on the server.\n\n---\n\n## 14. Migration Guide\n\n### Before\n\n```tsx\nfunction DeleteButton({ user }: { user: { permissions: string[] } }) {\n if (!user.permissions.includes('user.delete')) {\n return null;\n }\n return ;\n}\n```\n\nProblems: prop drilling, duplicated strings, no loading/disabled modes, no wildcards/roles.\n\n### After\n\n```tsx\n// root\n\n \n\n\n// leaf\n\n \n\n```\n\nOr imperative:\n\n```tsx\nconst { can } = usePermission();\nreturn can('user.delete') ? : null;\n```\n\n**Migration steps:**\n\n1. Map your auth user → `Subject`\n2. Wrap the authenticated tree with `PermissionProvider`\n3. Replace `includes` checks with `can` / ``\n4. Optionally introduce `permissionLoader` if permissions arrive asynchronously\n\n---\n\n## 15. Troubleshooting\n\n### `usePermission must be used within a PermissionProvider`\n\n**Cause:** Hook/component rendered outside the provider.\n\n**Fix:** Wrap the authenticated subtree (or the whole app after login) with `PermissionProvider`.\n\n---\n\n### Permission always denied\n\nChecklist:\n\n- Is `status` still `'loading'`? Wait or show `loading` UI.\n- Does the subject actually include the permission (or a matching wildcard)?\n- Are permissions coming from `permissionLoader` but the loader failed? Check `error`.\n- Did you pass `permissions={...}` *and* an empty `subject.permissions` unexpectedly?\n- For roles: did you configure `roleDefinitions` if you rely on inheritance?\n\n```ts\nconsole.log(usePermission().subject);\nconsole.log(usePermission().explain('user.delete'));\n```\n\n---\n\n### Wrong subject shape\n\n`roles` and `permissions` must be **arrays**. If the backend sends `role: \"admin\"`, convert it:\n\n```ts\nroles: Array.isArray(user.roles) ? user.roles : [user.role]\n```\n\n---\n\n### TypeScript: permission strings\n\nPermission type is `string`. For stricter apps, wrap your own union:\n\n```ts\ntype AppPermission = 'user.create' | 'user.delete' | 'invoice.approve';\ncan('user.create' as AppPermission);\n```\n\n---\n\n### Redirect does nothing in tests / SSR\n\n`PermissionRoute` uses `window.location.assign` when `redirect` / `redirectTo` is set. In non-browser environments, provide `fallback` UI instead of relying on navigation.\n\n---\n\n## 16. API Reference\n\n### Runtime exports\n\n| API | Kind | Purpose | Example |\n| --- | --- | --- | --- |\n| `PermissionProvider` | Component | Provide subject + engine/store | `` |\n| `usePermission` | Hook | Imperative authorization API | `const { can } = usePermission()` |\n| `Can` | Component | Declarative UI gate | `` |\n| `PermissionRoute` | Component | Page/section gate | `` |\n\n### Common types\n\n| Type | Purpose |\n| --- | --- |\n| `Subject` | User snapshot for evaluation |\n| `Permission` / `PermissionList` / `PermissionInput` | Permission identifiers |\n| `PermissionMode` | `hidden` \\| `disable` \\| `readonly` |\n| `PermissionStatus` | `idle` \\| `loading` \\| `resolved` \\| `error` |\n| `RoleDefinition` | Role inheritance + role permissions |\n| `PermissionDecision` | Result of `explain()` |\n| `PermissionLoader` / `PermissionResolver` / `PermissionResponse` | Async integration |\n| `PermissionRuntimeApi` | Return type of `usePermission()` |\n| `CanProps` / `PermissionProviderProps` / `PermissionRouteProps` | Component props |\n| `PermissionRule` / `PermissionCondition` / `PermissionPolicy` / `PermissionQuery` | Future ABAC surface (types only) |\n\n> Internal modules under `src/core` are **not** public API.\n\n---\n\n## 17. Roadmap\n\n| Phase | Focus | Status |\n| --- | --- | --- |\n| **1** | React foundation: Provider, hooks, Can, routes, subject, engine | Done |\n| **2** | Advanced rules: wildcards, role hierarchy, explain/debug, operators | Done |\n| **3** | Async system: loader, resolver, cache, loading/error UI | Done |\n| **4** | ABAC evaluation + policy engine | Planned |\n| **5** | Extract `@abolfazl-khalaj/permission-core` | Planned |\n| **6** | Framework adapters (Next / Vue / Angular) | Planned |\n\n---\n\n## License\n\nMIT © [abolfazl-khalaj](https://www.npmjs.com/~abolfazl-khalaj)\n","readmeFilename":"README.md","homepage":"https://www.npmjs.com/package/@abolfazl-khalaj/permission-react","repository":{"type":"git","url":"git+https://github.com/abolfazl-khalaj/package-permission.git","directory":"packages/react"},"bugs":{"url":"https://github.com/abolfazl-khalaj/package-permission/issues"}}![\"npm](\"https://img.shields.io/npm/v/@abolfazl-khalaj/permission-react.svg?style=flat-square\")
\n ![\"npm](\"https://img.shields.io/npm/dm/@abolfazl-khalaj/permission-react.svg?style=flat-square\")
\n ![\"license\"](\"https://img.shields.io/npm/l/@abolfazl-khalaj/permission-react.svg?style=flat-square\")
\n ![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
\n ![\"React](\"https://img.shields.io/badge/React-18%20%7C%2019-61DAFB?style=flat-square&logo=react&logoColor=black\"){kind=icon}
\n ![\"ESM](\"https://img.shields.io/badge/bundle-ESM%20%2B%20CJS-success?style=flat-square\"){kind=icon}
\n