@jmruthers/pace-core 0.5.127 → 0.5.129

package/docs/api/modules.md

@@ -1,6 +1,6 @@
-[@jmruthers/pace-core - v0.5.127](README.md) / Exports
+[@jmruthers/pace-core - v0.5.129](README.md) / Exports
 
-# @jmruthers/pace-core - v0.5.127
+# @jmruthers/pace-core - v0.5.129
 
 **`File`**
 
@@ -2309,6 +2309,12 @@ This component is designed to work with React Router's nested routing pattern us
 Outlet to render child routes. It provides integrated authentication, navigation,
 and user management functionality.
 
+**Super Admin Access:** When `enforcePermissions={true}`, PaceAppLayout automatically
+checks if the user is a super admin before enforcing permissions. Super admins bypass
+all permission checks and can access any route without violations. The component extracts
+base page names from route paths (e.g., `/organisation/scouts-victoria` → `"organisation"`)
+for permission checking, which can be overridden using `pageIdMapping`.
+
 **Important:** The appName prop should use an APP_NAME constant declared in your App.tsx
 file. This ensures consistency with public pages (via PublicPageProvider) which should
 also receive the same APP_NAME constant. The logo URL is automatically constructed as
@@ -2325,6 +2331,7 @@ Features:
 - Layout-level permission enforcement
 - Permission-based navigation filtering
 - Automatic page permission validation
+- Super admin bypass (super admins automatically bypass all permission checks)
 
 #### Parameters
 
@@ -2455,7 +2462,7 @@ function AdminApp() {
 
 #### Defined in
 
-[packages/core/src/components/PaceAppLayout/PaceAppLayout.tsx:336](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PaceAppLayout/PaceAppLayout.tsx#L336)
+[packages/core/src/components/PaceAppLayout/PaceAppLayout.tsx:344](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/PaceAppLayout/PaceAppLayout.tsx#L344)
 
 ___
 

package/docs/api-reference/components.md

@@ -123,6 +123,12 @@ interface DataTableProps<TData extends DataRecord> {
   onDeleteRow?: (row: TData) => void;
   onCreateRow?: (data: Partial<TData>) => void;
   onImport?: (data: TData[]) => void | Promise<void>;
+  /** 
+   * Custom export handler - allows full control over export columns and filename
+   * Receives ExportOptions with tableRows, allColumns, visibleColumns, and more
+   * If not provided, defaults to exporting all visible columns
+   */
+  onExport?: (options: ExportOptions<TData>) => void | Promise<void>;
   onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
   
   // Performance
@@ -276,6 +282,24 @@ const columns: DataTableColumn<User>[] = [
   onEditRow={handleEdit}
   onDeleteRow={handleDelete}
   onCreateRow={handleCreate}
+  onExport={async (options) => {
+    // Custom export with specific columns
+    const exportColumns = options.allColumns
+      .filter(col => ['name', 'email'].includes(col.accessorKey || ''))
+      .map(col => ({
+        header: col.header || col.accessorKey,
+        id: col.id || col.accessorKey,
+        accessorKey: col.accessorKey,
+        accessorFn: 'accessorFn' in col ? col.accessorFn : undefined,
+      }));
+    
+    await exportToCSVWithTableRows(
+      options.tableRows,
+      exportColumns,
+      options.columnIdToTableColumn,
+      'users-export.csv'
+    );
+  }}
 />
 ```
 

package/docs/api-reference/types.md

@@ -334,6 +334,33 @@ interface ButtonProps {
 }
 ```
 
+### ExportOptions
+
+Options provided to the `onExport` handler for custom export functionality.
+
+```typescript
+interface ExportOptions<TData extends DataRecord> {
+  /** Filtered table rows with getValue() method for proper accessorFn evaluation */
+  tableRows: Array<{
+    original: TData;
+    getValue: (columnId: string) => any;
+    id: string;
+  }>;
+  /** All column definitions passed to the DataTable */
+  allColumns: DataTableColumn<TData>[];
+  /** Currently visible columns in the table */
+  visibleColumns: DataTableColumn<TData>[];
+  /** Mapping of column IDs to TanStack table column instances (for getValue() calls) */
+  columnIdToTableColumn: Map<string, any>;
+  /** Raw data array (unfiltered) */
+  data: TData[];
+  /** Default filename generated from table title */
+  filename: string;
+  /** TanStack table instance for advanced operations */
+  table: any;
+}
+```
+
 ### DataTableProps
 
 Props for the DataTable component.
@@ -948,6 +975,7 @@ export type {
   // UI Components
   ButtonProps,
   DataTableProps,
+  ExportOptions,
   ColumnDef,
   PaginationConfig,
   SortingConfig,

package/docs/implementation-guides/data-tables.md

@@ -1746,35 +1746,118 @@ The import automatically recognizes and maps:
 />
 ```
 
-### Custom Export Filename
+### Custom Export
 
 The export filename is automatically generated from the table `title` prop:
 
 - If `title` is provided: `{title}_{date}.csv` (e.g., `meals_2024-04-11.csv`)
 - If no `title`: `data_export_{date}.csv`
 
-To customize the filename, you can provide a custom `onExport` handler:
+By default, the DataTable exports all **visible columns**. To customize the export (different columns, custom filename, etc.), you can provide a custom `onExport` handler:
 
 ```tsx
+import { DataTable, type ExportOptions, exportToCSVWithTableRows, type ExportColumn } from '@jmruthers/pace-core';
+
 <DataTable
   title="Meals"
   columns={columns}
   features={{ export: true }}
-  onExport={async () => {
-    // Custom export logic
-    const data = getFilteredData();
-    await exportToCSV(data, columns, 'custom-export-name.csv');
+  onExport={async (options: ExportOptions<Meal>) => {
+    // Export only specific columns (different from visible columns)
+    const exportColumnIds = ['name', 'email', 'role'];
+    
+    const exportColumns: ExportColumn[] = exportColumnIds
+      .map(columnId => {
+        // Find the column definition
+        const column = options.allColumns.find(col => 
+          col.id === columnId || col.accessorKey === columnId
+        );
+        if (!column) return null;
+
+        // CRITICAL: The id must match the key in columnIdToTableColumn
+        // TanStack Table uses String(column.id || column.accessorKey) as the column ID
+        const tableColumnId = String(column.id || column.accessorKey);
+        
+        // Verify this column ID exists in the mapping (for getValue() to work)
+        if (!options.columnIdToTableColumn.has(tableColumnId)) {
+          console.warn(`Column ID ${tableColumnId} not found in columnIdToTableColumn map`);
+          return null;
+        }
+
+        return {
+          header: column.header || column.accessorKey,
+          id: tableColumnId, // Must be string and match columnIdToTableColumn key
+          accessorKey: column.accessorKey,
+          accessorFn: 'accessorFn' in column ? column.accessorFn : undefined,
+        };
+      })
+      .filter((col): col is ExportColumn => col !== null);
+    
+    // Use the provided table rows and column mapping for proper accessorFn evaluation
+    await exportToCSVWithTableRows(
+      options.tableRows,
+      exportColumns,
+      options.columnIdToTableColumn,
+      'custom-export-name.csv'
+    );
   }}
 />
 ```
 
+### Export Options
+
+The `onExport` handler receives an `ExportOptions` object with:
+
+- `tableRows` - Filtered table rows with `getValue()` method for proper `accessorFn` evaluation
+- `allColumns` - All column definitions passed to the DataTable
+- `visibleColumns` - Currently visible columns in the table
+- `columnIdToTableColumn` - Mapping of column IDs to TanStack table column instances (for `getValue()` calls)
+- `data` - Raw data array (unfiltered)
+- `filename` - Default filename generated from table title
+- `table` - TanStack table instance for advanced operations
+
 ### Export Column Selection
 
-**Important**: Only **visible columns** are exported. If a column is hidden (via column visibility controls), it will not be included in the export.
+**Default Behavior**: Only **visible columns** are exported. If a column is hidden (via column visibility controls), it will not be included in the export.
+
+**Custom Export**: Use the `onExport` handler to export different columns than what's visible in the table:
+
+```tsx
+onExport={async (options) => {
+  // Export all columns (including hidden ones)
+  const allExportColumns: ExportColumn[] = options.allColumns
+    .map(col => {
+      // Get the table column ID (must match columnIdToTableColumn key)
+      const tableColumnId = String(col.id || col.accessorKey);
+      
+      // Only include columns that exist in the table mapping
+      if (!options.columnIdToTableColumn.has(tableColumnId)) {
+        return null;
+      }
+      
+      return {
+        header: col.header || col.accessorKey,
+        id: tableColumnId, // Must be string and match columnIdToTableColumn key
+        accessorKey: col.accessorKey,
+        accessorFn: 'accessorFn' in col ? col.accessorFn : undefined,
+      };
+    })
+    .filter((col): col is ExportColumn => col !== null);
+  
+  await exportToCSVWithTableRows(
+    options.tableRows,
+    allExportColumns,
+    options.columnIdToTableColumn,
+    'all-columns-export.csv'
+  );
+}}
+```
 
-To ensure all columns are exported:
-- Make sure all desired columns are visible before exporting
-- Or use a custom `onExport` handler to export specific columns
+**Important Notes:**
+- The `id` field in `ExportColumn` **must** be a string and must exactly match a key in `columnIdToTableColumn`
+- Use `String(column.id || column.accessorKey)` to get the correct table column ID
+- Always verify the column ID exists in `columnIdToTableColumn` before using it
+- This ensures `getValue()` works correctly for columns with `accessorFn`
 
 ### Import Column Mapping
 

package/docs/implementation-guides/permission-enforcement.md

@@ -53,6 +53,8 @@ setupRBAC(supabase);
 
 Layout-level enforcement provides a safety net that prevents consuming apps from forgetting to implement permission checks. It ensures that every route is automatically validated for permissions.
 
+**Note:** Super admins automatically bypass all permission checks in PaceAppLayout. The component checks super admin status before enforcing permissions, ensuring super admins can access any route without violations.
+
 ### Basic Implementation
 
 ```tsx
@@ -107,6 +109,8 @@ Configure different permissions for different routes:
 />
 ```
 
+**Page Name Mapping:** PaceAppLayout automatically extracts the base page name from route paths. For nested routes like `/organisation/scouts-victoria`, it uses `"organisation"` (the first path segment) as the page name. You can override this using `pageIdMapping` to provide custom page IDs for specific routes.
+
 ### Navigation Filtering
 
 Filter navigation items based on user permissions:

package/docs/rbac/super-admin-guide.md

@@ -260,7 +260,45 @@ function FilteredDataTable() {
 }
 ```
 
-## 8. Navigation Guards
+## 8. PaceAppLayout Super Admin Bypass
+
+When using `PaceAppLayout` with `enforcePermissions={true}`, super admins automatically bypass all permission checks:
+
+```tsx
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+      <Router>
+        <Routes>
+          <Route path="/" element={
+            <PaceAppLayout 
+              appName="My Application"
+              enforcePermissions={true}
+              defaultPermission="read"
+            />
+          }>
+            <Route index element={<HomePage />} />
+            <Route path="dashboard" element={<DashboardPage />} />
+            <Route path="organisation/:orgSlug" element={<OrganisationPage />} />
+          </Route>
+        </Routes>
+      </Router>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+**Key Features:**
+- Super admins bypass all permission checks automatically
+- No strict mode violations logged for super admins
+- Page name extraction: nested routes like `/organisation/scouts-victoria` use `"organisation"` as the page name
+- Custom page IDs can be provided via `pageIdMapping` prop
+
+**Note:** PaceAppLayout checks super admin status before enforcing permissions, ensuring super admins can access any route without violations or access denied errors.
+
+## 9. Navigation Guards
 
 Protect entire routes for super admins:
 
@@ -303,7 +341,7 @@ function AdminRoutes() {
 }
 ```
 
-## 9. Environment-Specific Configuration
+## 10. Environment-Specific Configuration
 
 You can also check for super admin access in your environment configuration:
 
@@ -321,7 +359,7 @@ const appConfig = {
 };
 ```
 
-## 10. Best Practices
+## 11. Best Practices
 
 ### ✅ Do:
 - Always check `isSuperAdmin` first for performance
@@ -336,7 +374,7 @@ const appConfig = {
 - Skip permission checks assuming super admin status
 - Use anon key for super admin operations
 
-## 11. Testing Super Admin Access
+## 12. Testing Super Admin Access
 
 ```tsx
 import { render, screen } from '@testing-library/react';
@@ -373,7 +411,7 @@ test('shows regular content for non-super admin users', () => {
 });
 ```
 
-## 12. Practical Examples
+## 13. Practical Examples
 
 ### Basic Super Admin Check
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.127",
+  "version": "0.5.129",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {