@jmruthers/pace-core 0.5.120 → 0.5.123

package/docs/implementation-guides/datatable-rbac-usage.md

@@ -0,0 +1,317 @@
+# DataTable RBAC Usage Guide
+
+## Overview
+
+The DataTable component now properly enforces page-based RBAC permissions instead of resource-based permissions. This ensures that DataTable permissions align with your application's page-level permission system.
+
+## Correct Usage
+
+### Basic Usage
+
+```tsx
+import { DataTable } from '@jmruthers/pace-core';
+
+function DishesPage() {
+  const dishes = [
+    { id: '1', name: 'Pasta', category: 'Main' },
+    { id: '2', name: 'Salad', category: 'Side' }
+  ];
+
+  const columns = [
+    { accessorKey: 'id', header: 'ID' },
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'category', header: 'Category' }
+  ];
+
+  return (
+    <DataTable
+      data={dishes}
+      columns={columns}
+      rbac={{
+        pageName: 'dishes'        // Page name for permissions (recommended)
+      }}
+      features={{
+        search: true,
+        pagination: true,
+        sorting: true,
+        filtering: true,
+        creation: true,           // Will be controlled by create:page.dishes permission
+        editing: true,            // Will be controlled by update:page.dishes permission
+        deletion: true,           // Will be controlled by delete:page.dishes permission
+        export: true,             // Will be controlled by read:page.dishes permission
+        import: true              // Will be controlled by create:page.dishes permission
+      }}
+      getRowId={(row) => row.id}
+    />
+  );
+}
+```
+
+### Page Identification Options
+
+The DataTable supports two ways to identify the page for RBAC permissions:
+
+#### Option 1: Page Name (Recommended)
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  rbac={{
+    pageName: 'dishes'  // Will be resolved to page ID by RBAC engine
+  }}
+  features={features}
+/>
+```
+
+#### Option 2: Page ID (Direct)
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  rbac={{
+    pageId: 'uuid-here'  // Use page ID directly
+  }}
+  features={features}
+/>
+```
+
+**Note:** You must provide either `pageName` or `pageId`, but not both. If both are provided, `pageId` takes precedence.
+
+### Permission Mapping
+
+The DataTable now checks the following page-based permissions:
+
+| DataTable Feature | Permission Checked | Description |
+|------------------|-------------------|-------------|
+| **Data Display** | `read:page.{pageId}` | Controls whether data is visible |
+| **Create Button** | `create:page.{pageId}` | Controls create functionality |
+| **Edit Actions** | `update:page.{pageId}` | Controls edit/update functionality |
+| **Delete Actions** | `delete:page.{pageId}` | Controls delete functionality |
+| **Export** | `read:page.{pageId}` | Controls export functionality |
+| **Import** | `create:page.{pageId}` | Controls import functionality |
+
+### Role-Based Examples
+
+#### Planner Role (AJ2025)
+```tsx
+// For a planner on the dishes page
+<DataTable
+  data={dishes}
+  columns={columns}
+  rbac={{
+    pageId: 'dishes'  // Will check read:page.dishes, create:page.dishes, etc.
+  }}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true,
+    creation: true,    // ✅ Allowed if planner has create:page.dishes
+    editing: true,     // ✅ Allowed if planner has update:page.dishes  
+    deletion: false,   // ❌ Disabled if planner lacks delete:page.dishes
+    export: true,      // ✅ Allowed if planner has read:page.dishes
+    import: false      // ❌ Disabled if planner lacks create:page.dishes
+  }}
+  getRowId={(row) => row.id}
+/>
+```
+
+#### Viewer Role
+```tsx
+// For a viewer on the dishes page
+<DataTable
+  data={dishes}
+  columns={columns}
+  rbac={{
+    pageId: 'dishes'
+  }}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true,
+    creation: false,   // ❌ Disabled - viewer typically lacks create:page.dishes
+    editing: false,    // ❌ Disabled - viewer typically lacks update:page.dishes
+    deletion: false,   // ❌ Disabled - viewer typically lacks delete:page.dishes
+    export: false,     // ❌ Disabled - viewer typically lacks read:page.dishes
+    import: false      // ❌ Disabled - viewer typically lacks create:page.dishes
+  }}
+  getRowId={(row) => row.id}
+/>
+```
+
+## Database Setup
+
+### Required Page Permissions
+
+Ensure your `rbac_page_permissions` table has entries for each page and role:
+
+```sql
+-- Example: Planner role permissions for dishes page
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed) VALUES
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'read', 'planner', true),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'create', 'planner', true),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'update', 'planner', true),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'delete', 'planner', false),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'manage', 'planner', true);
+
+-- Example: Viewer role permissions for dishes page  
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed) VALUES
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'read', 'viewer', true),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'create', 'viewer', false),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'update', 'viewer', false),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'delete', 'viewer', false),
+  ((SELECT id FROM rbac_app_pages WHERE page_name = 'dishes'), 'manage', 'viewer', false);
+```
+
+## Migration Guide
+
+### From Resource-Based to Page-Based Permissions
+
+If you're migrating from the old resource-based system:
+
+1. **Update DataTable Usage:**
+   ```tsx
+   // OLD (resource-based)
+   rbac={{
+     resource: 'dishes'
+   }}
+   
+   // NEW (page-based)
+   rbac={{
+     pageId: 'dishes'  // Only pageId is required for page-based permissions
+   }}
+   ```
+
+2. **Update Database Permissions:**
+   - Ensure `rbac_app_pages` table has entries for your pages
+   - Update `rbac_page_permissions` to use page-based permissions
+   - Remove old resource-based permission entries if they exist
+
+3. **Test Permission Scenarios:**
+   - Test with different roles (planner, viewer, admin)
+   - Verify that DataTable features are properly enabled/disabled
+   - Ensure data is still visible even when write permissions are denied
+
+## Troubleshooting
+
+### Common Issues
+
+1. **DataTable shows "Access Denied" even for read-only users:**
+   - Ensure `read:page.{pageId}` permission exists for the user's role
+   - Check that the page exists in `rbac_app_pages` table
+
+2. **Create/Edit/Delete buttons not showing:**
+   - Verify that the corresponding page permissions exist in the database
+   - Check that the user's role has the required permissions
+
+3. **Permission checks not working:**
+   - Ensure the `pageId` is correctly set in the DataTable rbac config
+   - Verify that the user has the correct event-app role for the context
+
+### Debugging
+
+Enable debug logging to see permission checks:
+
+```tsx
+// In your app setup
+<UnifiedAuthProvider 
+  supabaseClient={supabase}
+  appName="your-app"
+  enableRBAC={true}
+  debug={true}  // Enable debug logging
+>
+  <YourApp />
+</UnifiedAuthProvider>
+```
+
+## Best Practices
+
+1. **Always specify pageId:** Use the actual page identifier for proper permission checking
+2. **Consistent naming:** Use the same page ID across your app for consistency
+3. **Test thoroughly:** Verify permissions work correctly for all roles
+4. **Document permissions:** Keep track of which roles have which permissions for each page
+5. **Use feature flags:** Control DataTable features based on user permissions, not hardcoded values
+
+## Example Complete Implementation
+
+```tsx
+// pages/DishesPage.tsx
+import { DataTable } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function DishesPage() {
+  const { user } = useUnifiedAuth();
+  const [dishes, setDishes] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  // Fetch dishes data
+  useEffect(() => {
+    fetchDishes().then(setDishes).finally(() => setLoading(false));
+  }, []);
+
+  const columns = [
+    { accessorKey: 'id', header: 'ID' },
+    { accessorKey: 'name', header: 'Dish Name' },
+    { accessorKey: 'category', header: 'Category' },
+    { accessorKey: 'allergens', header: 'Allergens' }
+  ];
+
+  const handleCreateDish = (data) => {
+    // Create dish logic
+    console.log('Creating dish:', data);
+  };
+
+  const handleEditDish = (row, data) => {
+    // Edit dish logic
+    console.log('Editing dish:', row, data);
+  };
+
+  const handleDeleteDish = (row) => {
+    // Delete dish logic
+    console.log('Deleting dish:', row);
+  };
+
+  if (loading) return <div>Loading dishes...</div>;
+
+  return (
+    <div>
+      <h1>Dishes Management</h1>
+      <DataTable
+        data={dishes}
+        columns={columns}
+        rbac={{
+          pageId: 'dishes'  // This will check read:page.dishes, create:page.dishes, etc.
+        }}
+        features={{
+          search: true,
+          pagination: true,
+          sorting: true,
+          filtering: true,
+          creation: true,    // Controlled by create:page.dishes permission
+          editing: true,     // Controlled by update:page.dishes permission
+          deletion: true,    // Controlled by delete:page.dishes permission
+          export: true,      // Controlled by read:page.dishes permission
+          import: true       // Controlled by create:page.dishes permission
+        }}
+        onCreateRow={handleCreateDish}
+        onEditRow={handleEditDish}
+        onDeleteRow={handleDeleteDish}
+        getRowId={(row) => row.id}
+        title="Dishes"
+        description="Manage event dishes and meal options"
+      />
+    </div>
+  );
+}
+```
+
+This implementation ensures that:
+- Users with `read:page.dishes` can see the data
+- Users with `create:page.dishes` can create new dishes
+- Users with `update:page.dishes` can edit existing dishes
+- Users with `delete:page.dishes` can delete dishes
+- Users with `read:page.dishes` can export data
+- Users with `create:page.dishes` can import data
+
+The DataTable will automatically show/hide features based on the user's actual permissions for the dishes page.