@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/getting-started/faq.md

@@ -222,7 +222,7 @@ function MyComponent() {
     }
   }, [hasPermission, organisationId]);
 
-  if (isLoading) return <div>Loading...</div>;
+  if (isLoading) return <p>Loading...</p>;
 
   return <DataTable data={data} />;
 }
@@ -281,7 +281,7 @@ See [Public Pages Guide](./implementation-guides/public-pages.md).
 3. Use React.memo for expensive components
 4. Optimize data table rendering
 
-See [Performance Guide](./best-practices/performance.md).
+See [Performance Optimization](../standards/9-operations-standards.md#performance-optimization).
 
 ## Still Have Questions?
 

package/docs/getting-started/installation-guide.md

@@ -36,10 +36,23 @@ npm install @jmruthers/pace-core
 
 **Required Peer Dependencies:**
 ```bash
-npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
+npm install react react-dom @tanstack/react-query @tanstack/react-table clsx date-fns date-fns-tz react-day-picker react-hook-form react-router-dom tailwind-merge tailwindcss zod
 ```
 
-**Note**: `@supabase/supabase-js` and `@tanstack/react-query` are included as dependencies and do not need to be installed separately.
+> **📦 Complete Dependencies Reference**: See [Dependencies Guide](./dependencies.md) for a detailed breakdown of:
+> - ✅ Which packages are **already included** (don't install)
+> - ⚠️ Which packages are **required peer dependencies** (must install)
+> - ❌ Common mistakes to avoid
+> - 🔍 How to verify your installation
+
+**Note**: The following packages are **included dependencies** - **DO NOT install them**, use pace-core exports instead:
+- `@supabase/supabase-js` - Use `createBaseClient()` from `@jmruthers/pace-core` (security enforcement)
+- `@radix-ui/*` packages - Use pace-core components (consistency enforcement)
+- `lucide-react` - Use `@jmruthers/pace-core/icons` (consistency enforcement)
+
+The following packages are **peer dependencies** and **MUST be installed**:
+- `@tanstack/react-query` - Required for `QueryClient`, `QueryClientProvider`, and React Query hooks
+- `date-fns` and `date-fns-tz` - Required for date formatting (apps may use date-fns functions directly)
 
 ### Step 2: Install Tailwind CSS v4
 
@@ -286,19 +299,19 @@ export default App;
 
 If you're using PACE Core's authentication features:
 
-```bash
-npm install @supabase/supabase-js
-```
+**⚠️ Important**: `@supabase/supabase-js` is **included** in pace-core - you do NOT need to install it separately. Use `createBaseClient()` from pace-core instead.
 
 Create `src/lib/supabase.ts`:
 
 ```typescript
-import { createClient } from '@supabase/supabase-js'
+import { createBaseClient } from '@jmruthers/pace-core'
 
+// Base Supabase client for UnifiedAuthProvider only
+// DO NOT use this client directly - use useSecureSupabase() instead
 const supabaseUrl = process.env.VITE_SUPABASE_URL!
 const supabasePublishableKey = process.env.VITE_SUPABASE_PUBLISHABLE_KEY!
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+export const supabase = createBaseClient(supabaseUrl, supabasePublishableKey)
 ```
 
 Set environment variables in `.env.local`:

package/docs/getting-started/quick-reference.md

@@ -92,7 +92,7 @@ import { useUnifiedAuth } from '@jmruthers/pace-core';
 function MyComponent() {
   const { user, loading, signIn, signOut } = useUnifiedAuth();
 
-  if (loading) return <div>Loading...</div>;
+  if (loading) return <p>Loading...</p>;
   if (!user) return <button onClick={signIn}>Sign In</button>;
 
   return (
@@ -184,7 +184,7 @@ function SuperAdminPanel() {
 
   if (!isSuperAdmin) return null;
 
-  return <div>Super admin panel</div>;
+  return <section>Super admin panel</section>;
 }
 ```
 
@@ -510,7 +510,7 @@ function MyComponent() {
   const { user, loading, error } = useUnifiedAuth();
 
   if (error) {
-    return <div>Error: {error.message}</div>;
+    return <p>Error: {error.message}</p>;
   }
 
   // ... rest of component
@@ -611,4 +611,4 @@ function AdminPanel() {
 - **Common Issues**: [Troubleshooting Guide](./troubleshooting/common-issues.md)
 - **Debugging**: [Debugging Guide](./troubleshooting/debugging.md)
 - **Migration**: [Migration Guide](./migration/)
-- **Security**: [Security Best Practices](./best-practices/security.md)
+- **Security**: [Security & RBAC Standards](../standards/6-security-rbac-standards.md)

package/docs/getting-started/quick-start.md

@@ -29,20 +29,29 @@ npm install
 
 ## Step 2: Install PACE Core
 
+> **📦 Dependencies Guide**: See [Dependencies Guide](./dependencies.md) for complete details on which packages to install and which are already included.
+
 ```bash
-# Install PACE Core and required peer dependencies
-npm install @jmruthers/pace-core \
-  @supabase/supabase-js \
-  @tanstack/react-query @tanstack/react-table \
-  @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog \
-  @radix-ui/react-label @radix-ui/react-slot \
-  @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip \
-  clsx lucide-react react-day-picker react-hook-form react-router-dom tailwind-merge zod
-
-# Install Tailwind v4
-npm install -D tailwindcss@^4.0.0 @tailwindcss/vite
+# Install PACE Core
+npm install @jmruthers/pace-core
+
+# Install required peer dependencies
+npm install react react-dom @tanstack/react-query @tanstack/react-table \
+  clsx date-fns date-fns-tz react-day-picker react-hook-form react-router-dom tailwind-merge tailwindcss zod
+
+# Install Tailwind v4 (dev dependency)
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
 ```
 
+**⚠️ Important**: 
+- ❌ **DO NOT install** `@supabase/supabase-js`, `@radix-ui/*`, or `lucide-react` - they're included in pace-core. Use pace-core exports instead:
+  - `createBaseClient()` from `@jmruthers/pace-core` (instead of `createClient` from `@supabase/supabase-js`)
+  - pace-core components (instead of `@radix-ui/*` primitives)
+  - `@jmruthers/pace-core/icons` (instead of `lucide-react`)
+- ⚠️ `@tanstack/react-query` is a **peer dependency** - you MUST install it (required for QueryClient configuration)
+- ⚠️ All listed packages above are **required peer dependencies** - you must install them
+- See [Dependencies Guide](./dependencies.md) for the complete breakdown
+
 ## Step 3: Configure Vite
 
 **⚠️ CRITICAL**: This configuration prevents React context and Router context errors.
@@ -120,9 +129,11 @@ import { createClient } from '@supabase/supabase-js';
 const supabaseUrl = import.meta.env.VITE_SUPABASE_URL!;
 const supabasePublishableKey = import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!;
 
-export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+export const supabase = createClient(supabaseUrl, supabasePublishableKey);
 ```
 
+**Note**: `@supabase/supabase-js` is already included in pace-core, so you don't need to install it separately. Just import it directly.
+
 ## Step 6: Set Up Your Database
 
 In your Supabase dashboard, run this SQL to create a simple `tasks` table:

package/docs/implementation-guides/authentication.md

@@ -326,9 +326,9 @@ function UserDashboard() {
     hasEventAccess, // Check event access
   } = useUnifiedAuth();
 
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!user) return <div>Please log in</div>;
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (!user) return <p>Please log in</p>;
 
   return (
     <div>
@@ -441,14 +441,14 @@ function EventContent() {
   const { selectedEvent, hasEventAccess } = useUnifiedAuth();
 
   if (!selectedEvent) {
-    return <div>Please select an event</div>;
+    return <p>Please select an event</p>;
   }
 
   if (!hasEventAccess(selectedEvent.id)) {
-    return <div>You don't have access to this event</div>;
+    return <p>You don't have access to this event</p>;
   }
 
-  return <div>Event content for {selectedEvent.name}</div>;
+  return <section>Event content for {selectedEvent.name}</section>;
 }
 ```
 
@@ -703,14 +703,14 @@ function ConditionalContent() {
   const { user, loading } = useUnifiedAuth();
 
   if (loading) {
-    return <div>Loading...</div>;
+    return <p>Loading...</p>;
   }
 
   if (!user) {
-    return <div>Please log in to continue</div>;
+    return <p>Please log in to continue</p>;
   }
 
-  return <div>Welcome, {user.email}!</div>;
+  return <p>Welcome, {user.email}!</p>;
 }
 ```
 
@@ -850,11 +850,11 @@ function App() {
 function AuthTest() {
   const { user, loading, error } = useUnifiedAuth();
   
-  if (loading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!user) return <div>Not logged in</div>;
-  
-  return <div>Welcome {user.email}</div>;
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+  if (!user) return <p>Not logged in</p>;
+
+  return <p>Welcome {user.email}</p>;
 }
 ```
 
@@ -1105,7 +1105,7 @@ See the [Authentication Implementation Guide](./authentication.md) for a complet
 
 ### Advanced Patterns
 
-See the [Common Patterns Guide](./best-practices/common-patterns.md) for advanced authentication patterns.
+See the [Authentication Implementation Guide](./authentication.md) for advanced authentication patterns and the [Standards Overview](../standards/0-standards-overview.md) for compliance requirements.
 
 ## Related Documentation
 

package/docs/implementation-guides/component-styling.md

@@ -408,7 +408,7 @@ function DashboardCard({ title, children }) {
 ## Related Documentation
 
 - [Styling Overview](../styles/README.md) - Complete styling system
-- [Performance Guide](../best-practices/performance.md) - Performance optimization
+- [Performance Optimization](../standards/9-operations-standards.md#performance-optimization) - Performance optimization
 - [Component API Reference](../api-reference/components.md) - Component props
 
 ---

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

@@ -408,11 +408,11 @@ const columns: DataTableColumn<Dish>[] = [
       const indentLevel = isParent ? 0 : 1;
       
       return (
-        <div className={`flex items-center ${isParent ? 'font-semibold' : ''}`}>
-          <div style={{ marginLeft: `${indentLevel * 20}px` }}>
+        <section className={`flex items-center ${isParent ? 'font-semibold' : ''}`}>
+          <section style={{ marginLeft: `${indentLevel * 20}px` }}>
             {isParent ? '🍽️' : '🥬'} {row.original.name}
-          </div>
-        </div>
+          </section>
+        </section>
       );
     }
   },
@@ -478,26 +478,26 @@ const columns: DataTableColumn<Dish>[] = [
       if (isParent) {
         // Parent row actions
         return (
-          <div className="flex gap-2">
+          <section className="flex gap-2">
             <Button size="sm" variant="outline">
               Edit Dish
             </Button>
             <Button size="sm" variant="outline">
               Add Ingredient
             </Button>
-          </div>
+          </section>
         );
       } else {
         // Child row actions
         return (
-          <div className="flex gap-2">
+          <section className="flex gap-2">
             <Button size="sm" variant="ghost">
               Edit Ingredient
             </Button>
             <Button size="sm" variant="ghost">
               Remove
             </Button>
-          </div>
+          </section>
         );
       }
     }
@@ -1197,7 +1197,7 @@ import { DataTable } from '@jmruthers/pace-core';
 
 **✅ Column Alignment in Virtualized Tables**
 - **Problem**: Header and body columns were misaligned in virtualized mode due to separate table layouts.
-- **Solution**: Enhanced `VirtualizedDataTable` component with synchronized column sizing between header and body tables, `table-fixed` layout for consistent column widths, dynamic column width calculation and synchronization, proper `useLayoutEffect` for measuring actual column widths.
+- **Solution**: `UnifiedTableBody` component handles virtualization automatically with synchronized column sizing between header and body tables, `table-fixed` layout for consistent column widths, dynamic column width calculation and synchronization, proper virtualization handling for large datasets.
 
 **✅ Pagination State Synchronization**
 - **Problem**: Page size dropdown showed 50 but displayed 20 rows due to hardcoded values and virtualization conflicts.
@@ -2167,7 +2167,7 @@ function UserForm({ user, onSubmit, onCancel }) {
 
   return (
     <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
-      <div>
+      <section>
         <label htmlFor="name">Name</label>
         <input
           id="name"
@@ -2177,9 +2177,9 @@ function UserForm({ user, onSubmit, onCancel }) {
         {errors.name && (
           <p className="text-acc-600 text-sm">{errors.name.message}</p>
         )}
-      </div>
+      </section>
 
-      <div>
+      <section>
         <label htmlFor="email">Email</label>
         <input
           id="email"
@@ -2190,9 +2190,9 @@ function UserForm({ user, onSubmit, onCancel }) {
         {errors.email && (
           <p className="text-acc-600 text-sm">{errors.email.message}</p>
         )}
-      </div>
+      </section>
 
-      <div>
+      <section>
         <label htmlFor="role">Role</label>
         <select
           id="role"
@@ -2206,9 +2206,9 @@ function UserForm({ user, onSubmit, onCancel }) {
         {errors.role && (
           <p className="text-acc-600 text-sm">{errors.role.message}</p>
         )}
-      </div>
+      </section>
 
-      <div className="flex gap-2">
+      <section className="flex gap-2">
         <button
           type="submit"
           disabled={isSubmitting}
@@ -2223,7 +2223,7 @@ function UserForm({ user, onSubmit, onCancel }) {
         >
           Cancel
         </button>
-      </div>
+      </section>
     </form>
   );
 }
@@ -2496,25 +2496,118 @@ If you're upgrading from a previous version:
 
 ### Component Structure
 
+The DataTable component is built with a modular architecture that separates concerns and provides clear component boundaries. The structure is organized into main components, sub-components, hooks, utilities, and core architecture classes.
+
 ```
-DataTable
-├── useDataTablePerformance (hook)
-│   ├── DataChunkManager
-│   ├── SearchIndex
-│   ├── PerformanceMonitor
-│   └── VisibilityTracker
-├── VirtualizedDataTable (when enabled)
-│   ├── MemoizedRow
-│   └── MemoizedCell
-├── HierarchicalDataTable (when enabled)
-│   ├── ExpandCollapseControls
-│   └── HierarchicalRow
-└── EnhancedPaginationControls
-    ├── Performance metrics display
-    ├── Jump to page functionality
-    └── Memory usage tracking
+DataTable (Main Entry Point)
+│
+├── DataTableCore (Internal Orchestrator)
+│   ├── DataTableErrorBoundary
+│   ├── LoadingState
+│   ├── AccessDeniedPage
+│   └── DataTableLayout
+│       │
+│       ├── DataTableToolbar
+│       │   ├── GroupingDropdown
+│       │   ├── ColumnVisibilityDropdown
+│       │   └── BulkOperationsDropdown
+│       │
+│       ├── UnifiedTableBody
+│       │   ├── FilterRow
+│       │   │   └── ColumnFilter
+│       │   ├── MemoizedRow (RowComponent)
+│       │   │   ├── EditableRow
+│       │   │   │   └── EditFields
+│       │   │   ├── ActionButtons
+│       │   │   └── RowComponent (handles grouped rows inline and hierarchical expand/collapse)
+│       │   └── EmptyState
+│       │
+│       ├── PaginationControls
+│       │   └── EnhancedPaginationControls (when enabled)
+│       │
+│       └── DataTableModals
+│           └── ImportModal
+│
+├── Hooks (State & Logic Management)
+│   ├── useDataTableState
+│   ├── useDataTableDataPipeline
+│   ├── useDataTableConfiguration
+│   ├── useDataTablePermissions
+│   ├── useTableColumns
+│   ├── useTableHandlers
+│   ├── useColumnOrderPersistence
+│   ├── useColumnVisibilityPersistence
+│   ├── useEffectiveColumnOrder
+│   ├── useHierarchicalState
+│   ├── useServerSideDataEffect
+│   ├── useKeyboardNavigation
+│   └── useDataTablePerformance (from core hooks)
+│       ├── DataChunkManager
+│       ├── SearchIndex
+│       ├── PerformanceMonitor
+│       └── VisibilityTracker
+│
+├── Core Architecture Classes
+│   ├── ColumnFactory
+│   ├── ColumnManager
+│   ├── DataManager
+│   ├── StateManager
+│   ├── ActionManager
+│   ├── LocalDataAdapter
+│   └── PluginRegistry
+│
+└── Utilities
+    ├── aggregationUtils (sum, average, count, min, max)
+    ├── columnUtils
+    ├── exportUtils
+    ├── hierarchicalUtils
+    ├── hierarchicalSorting
+    ├── paginationUtils
+    ├── performanceUtils
+    ├── rowUtils
+    ├── a11yUtils
+    ├── errorHandling
+    └── flexibleImport
 ```
 
+#### Component Descriptions
+
+**Main Components:**
+- **`DataTable`**: Public API component that wraps `DataTableCore` with feature normalization
+- **`DataTableCore`**: Internal orchestrator that manages all hooks, state, and sub-components
+- **`DataTableLayout`**: Main layout component that arranges toolbar, body, pagination, and modals
+
+**Toolbar Components:**
+- **`DataTableToolbar`**: Top toolbar with search, grouping, column visibility, and action buttons
+- **`GroupingDropdown`**: Dropdown for selecting columns to group by
+- **`ColumnVisibilityDropdown`**: Dropdown for showing/hiding columns
+- **`BulkOperationsDropdown`**: Menu for bulk operations (delete selected, etc.)
+
+**Table Body Components:**
+- **`UnifiedTableBody`**: Unified component that handles both standard and virtualized rendering
+- **`FilterRow`**: Row of filter inputs below column headers
+- **`ColumnFilter`**: Individual column filter component
+- **`MemoizedRow`** (RowComponent): Individual table row with memoization
+- **`EditableRow`**: Inline editable row with form fields
+- **`EditFields`**: Field renderers for editable columns (text, select, date, number, boolean)
+- **`ActionButtons`**: Row action buttons (edit, delete, custom actions)
+- **Hierarchical expand/collapse**: Handled inline by `RowComponent` for hierarchical rows
+- **Grouped rows**: Handled inline by `RowComponent` when `row.getIsGrouped()` returns true
+- **`EmptyState`**: Component displayed when table has no data
+
+**Pagination Components:**
+- **`PaginationControls`**: Standard pagination controls
+- **`EnhancedPaginationControls`**: Enhanced version with performance metrics and jump-to-page
+
+**Modal Components:**
+- **`DataTableModals`**: Container for all modal dialogs
+- **`ImportModal`**: CSV import modal with column mapping
+
+**Supporting Components:**
+- **`DataTableErrorBoundary`**: Error boundary for graceful error handling
+- **`LoadingState`**: Loading indicator component
+- **`AccessDeniedPage`**: Component shown when user lacks permissions
+
 ### Performance Utilities
 
 - **`determinePaginationMode`**: Automatically selects optimal pagination strategy

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

@@ -271,7 +271,7 @@ function DishesPage() {
     console.log('Deleting dish:', row);
   };
 
-  if (loading) return <div>Loading dishes...</div>;
+  if (loading) return <p>Loading dishes...</p>;
 
   return (
     <div>

package/docs/implementation-guides/dynamic-colors.md

@@ -93,7 +93,7 @@ function MyApp() {
   // Automatically applies event colors when an event is selected
   useEventTheme();
   
-  return <div>Your app content</div>;
+  return <main>Your app content</main>;
 }
 ```
 
@@ -268,7 +268,7 @@ import { useEventTheme } from '@jmruthers/pace-core';
 function MyApp() {
   useEventTheme(); // Automatically applies event colors
   
-  return <div>Your app content</div>;
+  return <main>Your app content</main>;
 }
 ```
 
@@ -319,7 +319,7 @@ function App() {
 function App() {
   useEventTheme(); // Replaces the above useEffect
   
-  return <div>Your app</div>;
+  return <main>Your app</main>;
 }
 ```
 

package/docs/implementation-guides/file-upload-storage.md

@@ -388,7 +388,7 @@ function FileManager() {
     <div>
       {/* Upload UI */}
       {isLoading && <div>Uploading...</div>}
-      {error && <div>Error: {error.message}</div>}
+      {error && <p>Error: {error.message}</p>}
     </div>
   );
 }
@@ -941,6 +941,6 @@ When network is interrupted during upload:
 ## Next Steps
 
 - **[Storage Utilities](../api-reference/utilities.md#storage)** - Additional storage utilities
-- **[Security Best Practices](../best-practices/security.md)** - Security guidelines
+- **[Security & RBAC Standards](../standards/6-security-rbac-standards.md)** - Security guidelines
 - **[RBAC Integration](./permission-enforcement.md)** - Permission-based file access
 - **[Performance Optimization](./performance.md)** - Large file handling