react-ability-kit 0.1.4 → 0.1.6

package/README.md

@@ -1,22 +1,35 @@
 # React Ability
 
-A small, typed permission layer for React that keeps authorization logic **out of your components** and **in one place**.
+**A small, strongly-typed permission layer for React**  
+Keep authorization logic **out of your components** and **in one place**.
 
 ---
 
-## Core idea (in one sentence)
+## Why this exists
 
-> The package centralizes and standardizes permission logic so your UI doesn’t turn into a mess of `if (user.role === …)` checks scattered everywhere.
+Most React apps don’t plan to become permission nightmares — they just grow into one.
 
-That’s it. Everything else is implementation details.
+Permissions slowly spread across components as ad-hoc checks:
+
+- `if (user.role === "admin")`
+- `if (invoice.ownerId === user.id)`
+- `if (permissions.includes("invoice:update"))`
+
+This package introduces a **policy-first** approach to permissions, so your UI stays clean and your rules stay auditable.
 
 ---
 
-## The real problem (what goes wrong in real apps)
+## Core idea (one sentence)
+
+> Define permission rules once, then query them everywhere — instead of scattering fragile `if` checks across your UI.
+
+Everything else is just implementation details.
+
+---
 
-Let’s start with how apps usually look **without** a permission layer.
+## The real problem (what goes wrong in real apps)
 
-### ❌ Without a package (today’s reality)
+### ❌ Without a permission layer
 
 ```tsx
 // Button.tsx
@@ -41,69 +54,144 @@ if (user && user.role !== "guest") {
 }
 ```
 
+### Problems this creates
 
-Problems this creates
-❌ Logic duplication
-The same rules are written differently in many files.
-
-❌ Rules drift
-Someone updates one condition but forgets others.
+- ❌ **Logic duplication** – same rules rewritten in different places  
+- ❌ **Rules drift** – one condition changes, others don’t  
+- ❌ **Impossible to audit** – “Who can edit invoices?” → grep the whole repo  
+- ❌ **UI inconsistencies**
+  - Button visible but API rejects
+  - Button hidden but API allows
+- ❌ **No type safety**
 
-❌ Impossible to audit
-“Who can edit invoices?” → you must search the entire codebase.
+  ```ts
+  "inovice:update" // typo = silent bug
+  ```
 
-❌ UI bugs
-Button visible but API rejects
+- ❌ **Hard to evolve roles** – adding a new role breaks logic everywhere
 
-Button hidden but API allows
+---
 
-❌ No type safety
-ts
-Copier le code
-"inovice:update" // typo = silent bug
-❌ Hard to change roles
-Adding a new role breaks logic everywhere.
+## The missing abstraction: policy-first permissions
 
-What this package introduces (the missing abstraction)
-Key idea: policy-first permissions
 Instead of asking:
 
-“Can the user do this?”
-
-everywhere in the UI…
+> “Can the user do this?”  
+> everywhere in the UI…
 
 You define rules once, then query them everywhere.
 
-Mental model (important)
-Think of your app like this:
+### Mental model
 
-```bash
+```text
 User + Context → Ability → UI decisions
 ```
 
-react-ability-kit only handles the Ability part.
+```text
+User ──► Policy ──► Ability ──► UI / Components
+```
+
+---
+
+## Installation
 
 ```bash
-User ──► Policy ──► Ability ──► UI / Components
+npm install react-ability
 ```
 
-What the package actually solves (concretely)
-1️⃣ Single source of truth for permissions
-Instead of scattered checks, you get one policy file:
+or
+
+```bash
+pnpm add react-ability
+```
+
+or
+
+```bash
+yarn add react-ability
+```
+
+---
+
+## Quick start (5 minutes)
+
+### 1️⃣ Define your abilities (policy-first)
+
+Create a single policy file.
+
+```ts
+// ability.ts
+import { defineAbility } from "react-ability";
+
+export const ability = defineAbility((allow, deny, user) => {
+  allow("read", "Invoice");
+
+  allow(
+    "update",
+    "Invoice",
+    invoice => invoice.ownerId === user.id && invoice.status === "draft"
+  );
+
+  deny("delete", "Invoice");
+});
+```
+
+This file is your **single source of truth**.
+
+---
+
+### 2️⃣ Provide the ability to your app
+
+```tsx
+import { AbilityProvider } from "react-ability";
+import { ability } from "./ability";
+
+export function App() {
+  return (
+    <AbilityProvider ability={ability}>
+      <YourApp />
+    </AbilityProvider>
+  );
+}
+```
+
+---
+
+### 3️⃣ Use permissions anywhere
+
+#### Using the `<Can />` component
+
+```tsx
+<Can I="update" a="Invoice" this={invoice}>
+  <EditButton />
+</Can>
+```
+
+#### Using the `can()` function
+
+```ts
+const canEdit = can("update", "Invoice", invoice);
+```
+
+---
+
+## What this package actually solves
+
+### 1️⃣ Single source of truth for permissions
 
 ```ts
-// policy.ts
 allow("update", "Invoice", invoice => invoice.ownerId === user.id);
 deny("delete", "Invoice");
 ```
 
-Result:
+- All rules live in one place
+- Easy to review, change, and reason about
+- No scattered conditionals
 
-All permission logic lives in one place
+---
 
-Easy to review, change, and reason about
+### 2️⃣ Business rules become readable policies
 
-2️⃣ Turns business rules into readable policies
 ❌ Before
 
 ```ts
@@ -115,7 +203,7 @@ if (
 )
 ```
 
-✅ With the package
+✅ After
 
 ```ts
 allow(
@@ -125,12 +213,15 @@ allow(
 );
 ```
 
-This is domain language, not UI logic.
+This is **domain language**, not UI logic.
+
+---
+
+### 3️⃣ Removes permission logic from components
 
-3️⃣ Removes permission logic from components
 ❌ Before
 
-```ts
+```tsx
 {user?.role === "admin" && <DeleteButton />}
 ```
 
@@ -142,10 +233,11 @@ This is domain language, not UI logic.
 </Can>
 ```
 
-Components now care only about UI, not authorization details.
+Your components focus on **rendering**, not authorization.
+
+---
 
-4️⃣ Prevents permission bugs at compile time (TypeScript win)
-This is huge.
+### 4️⃣ Type-safe permissions (TypeScript win)
 
 ❌ Without typing
 
@@ -160,56 +252,39 @@ can("updtae", "Invioce");
 // ❌ TypeScript error immediately
 ```
 
-This eliminates an entire class of bugs.
-
-5️⃣ Makes ownership rules first-class (not hacks)
-Ownership checks are usually scattered:
+This removes an entire class of bugs.
 
-```ts
-if (invoice.ownerId === user.id)
-```
+---
 
-With this package:
+### 5️⃣ Ownership rules become first-class
 
 ```ts
 allow("update", "Invoice", invoice => invoice.ownerId === user.id);
 ```
 
-Ownership logic becomes:
-
-consistent
+Ownership logic is now:
 
-reusable
+- consistent
+- reusable
+- testable
 
-testable
-
-6️⃣ Makes SSR and hydration predictable
-Without a system:
-
-UI flickers
-
-Buttons appear/disappear after hydration
+---
 
-Different logic runs on server vs client
+### 6️⃣ Predictable SSR & hydration
 
-With this package:
+- No permission flicker
+- No server/client mismatch
+- Same rules, same result everywhere
 
-Ability is created once from the same user data
+---
 
-Server and client render the same decisions
+## What `<Can />` actually does
 
-What the <Can /> component really is
 It’s not magic.
 
 It simply means:
 
-“Render children only if a permission rule passes.”
-
-Instead of:
-```tsx
-if (!canEdit) return null;
-```
-You write:
+> Render children **only if the permission passes**
 
 ```tsx
 <Can I="update" a="Invoice" this={invoice}>
@@ -219,68 +294,60 @@ You write:
 
 That’s it.
 
-What this package is NOT
-This is important.
-
-❌ Not an auth system
-❌ Not a backend security layer
-❌ Not a role manager UI
-❌ Not a permission database
-
-This package:
-
-does not replace backend checks
-
-does not handle authentication
+---
 
-does not store roles
+## What this package is NOT
 
-It only answers one question:
+❌ Not an authentication system  
+❌ Not a backend security layer  
+❌ Not a role management UI  
+❌ Not a permission database  
 
-“Given a user and a resource, is this action allowed?”
+This package **does not**:
 
-When this package makes sense
-✅ SaaS dashboards
-✅ Multi-role apps
-✅ B2B products
-✅ Apps with ownership rules
-✅ Teams larger than 1 developer
+- replace backend checks
+- handle authentication
+- store users or roles
 
-When it’s overkill
-❌ Landing pages
-❌ Simple blogs
-❌ Apps with only admin / non-admin logic
+It answers one question only:
 
-Why this is worth publishing
-Most developers:
+> **“Given a user and a resource, is this action allowed?”**
 
-feel this pain
+---
 
-write ad-hoc permission logic
+## When this package makes sense
 
-never extract it cleanly
+- ✅ SaaS dashboards
+- ✅ Multi-role applications
+- ✅ B2B products
+- ✅ Ownership-based rules
+- ✅ Teams larger than one developer
 
-This package:
+---
 
-gives a clear, repeatable pattern
+## When it’s overkill
 
-provides excellent TypeScript DX
+- ❌ Landing pages
+- ❌ Simple blogs
+- ❌ Admin / non-admin only apps
 
-keeps the API small and focused
+---
 
-That’s exactly what successful small libraries do.
+## Final summary
 
-Final simplified summary
-This package solves one problem:
+**React Ability solves one problem:**
 
-“How do I express and use permissions in React without scattering fragile conditional logic everywhere?”
+> How do I express and use permissions in React without scattering fragile conditional logic everywhere?
 
-It solves it by:
+It does this by:
 
-centralizing permission rules
+- centralizing permission rules
+- typing actions and resources
+- exposing a clean `can()` API
+- providing `<Can />` for UI rendering
 
-typing actions and resources
+---
 
-exposing a clean can() API
+## Credits
 
-providing <Can /> for UI rendering
+Created by **Mohamed Ali Sraieb**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-ability-kit",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "main": "./dist/index.cjs",