@jmruthers/pace-core 0.5.184 → 0.5.186

package/docs/api-reference/components.md

@@ -1829,37 +1829,51 @@ A comprehensive file upload component with drag-and-drop support, validation, an
 ```typescript
 interface FileUploadProps {
   supabase: SupabaseClient;
-  appName: string;
-  orgId: string;
-  onUploadComplete?: (fileRef: FileReference) => void;
-  onUploadStart?: (file: File) => void;
+  table_name: string;
+  record_id: string;
+  organisation_id: string;
+  app_id?: string; // Optional - will be resolved from app name if not provided
+  category: FileCategory; // File category for metadata (stored in file_metadata JSONB field)
+  folder: string; // Folder name in storage bucket (e.g., 'profile_photos', 'documents')
+  pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
   disabled?: boolean;
+  isPublic?: boolean; // Whether files should be uploaded to public-files bucket
   className?: string;
+  showPreview?: boolean; // Show image preview for accepted files
+  showProgress?: boolean; // Show upload progress bar
+  onUploadSuccess?: (result: FileUploadResult) => void;
+  onUploadError?: (error: string, file?: File) => void;
+  onProgress?: (progress: UploadProgress) => void;
   children?: React.ReactNode;
 }
 ```
 
+**Note:** The `category` prop is used for metadata purposes (stored in the `file_metadata` JSONB field), while the `folder` prop determines the actual storage path: `{orgId}/{folder}/{timestamp-uuid-filename}`. You can use the same value for both (e.g., `category={FileCategory.PROFILE_PHOTOS}` and `folder="profile_photos"`), or use different values if needed.
+
 #### Usage
 
 ```tsx
-import { FileUpload, FileCategory, logger } from '@jmruthers/pace-core';
+import { FileUpload, FileCategory } from '@jmruthers/pace-core';
 
 function MyFileUpload() {
-  const handleUpload = (fileRef: FileReference) => {
-    logger.debug('FileUpload', 'File uploaded:', { fileId: fileRef.id, fileName: fileRef.name });
-  };
-
   return (
     <FileUpload
       supabase={supabase}
-      appName="my-app"
-      orgId={organisationId}
-      onUploadComplete={handleUpload}
+      table_name="pace_person"
+      record_id={personId}
+      organisation_id={organisationId}
+      category={FileCategory.PROFILE_PHOTOS}
+      folder="profile_photos"
+      pageContext="configuration"
       accept="image/*"
       maxSize={2 * 1024 * 1024} // 2MB
+      onUploadSuccess={(result) => {
+        console.log('Uploaded:', result.file_reference);
+        console.log('URL:', result.file_url);
+      }}
     >
       <div className="border-2 border-dashed border-main-300 rounded-lg p-8 text-center">
         <p>Drag and drop files here or click to browse</p>

package/docs/api-reference/hooks.md

@@ -486,6 +486,117 @@ function UserForm() {
 }
 ```
 
+### useFormDialog
+
+Generic React hook for managing form dialog state (open/close, form data, reset behavior).
+
+```typescript
+interface UseFormDialogOptions<T = unknown> {
+  onOpenChange?: (open: boolean) => void;
+  resetOnClose?: boolean; // Default: true
+}
+
+interface UseFormDialogReturn<T = unknown> {
+  isOpen: boolean;
+  formData: T | null;
+  openDialog: (data?: T | null) => void;
+  closeDialog: () => void;
+  handleOpenChange: (open: boolean) => void;
+}
+
+function useFormDialog<T = unknown>(
+  options?: UseFormDialogOptions<T>
+): UseFormDialogReturn<T>;
+```
+
+#### Usage
+
+```tsx
+import { useFormDialog } from '@jmruthers/pace-core';
+import { Dialog, DialogContent, DialogTrigger } from '@jmruthers/pace-core';
+
+interface ContactFormData {
+  id: string;
+  name: string;
+  email: string;
+}
+
+function ContactDialog() {
+  const { isOpen, formData, openDialog, closeDialog, handleOpenChange } = 
+    useFormDialog<ContactFormData>();
+
+  return (
+    <>
+      <button onClick={() => openDialog({ id: '1', name: 'John', email: 'john@example.com' })}>
+        Edit Contact
+      </button>
+      <Dialog open={isOpen} onOpenChange={handleOpenChange}>
+        <DialogContent>
+          {formData && <p>Editing: {formData.name}</p>}
+          {/* Form content */}
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+```
+
+#### Basic Usage
+
+```tsx
+// Simple dialog without form data
+const { isOpen, openDialog, closeDialog } = useFormDialog();
+
+// Open dialog
+openDialog();
+
+// Close dialog
+closeDialog();
+```
+
+#### With Form Data
+
+```tsx
+interface UserData {
+  id: string;
+  name: string;
+}
+
+const { isOpen, formData, openDialog } = useFormDialog<UserData>();
+
+// Open with data
+openDialog({ id: '1', name: 'John' });
+
+// Access form data
+if (formData) {
+  console.log(formData.name);
+}
+```
+
+#### Controlled Usage
+
+```tsx
+const { handleOpenChange, isOpen } = useFormDialog({
+  onOpenChange: (open) => {
+    console.log('Dialog state:', open);
+  },
+  resetOnClose: false // Keep form data after closing
+});
+```
+
+#### Options
+
+- `onOpenChange?: (open: boolean) => void` - Callback invoked when dialog state changes
+- `resetOnClose?: boolean` - Whether to reset form data when dialog closes (default: `true`)
+
+#### Return Values
+
+- `isOpen: boolean` - Current open state of the dialog
+- `formData: T | null` - Current form data (null when closed or no data provided)
+- `openDialog: (data?: T | null) => void` - Open dialog with optional form data
+- `closeDialog: () => void` - Close dialog
+- `handleOpenChange: (open: boolean) => void` - Handler for controlled dialog components
+
 ## Utility Hooks
 
 ### useDebounce

package/docs/api-reference/rpc-functions.md

@@ -120,7 +120,7 @@ Documented in [File Reference System Guide](../implementation-guides/file-refere
 - `data_file_reference_count_get` - Get count of file references for a record
 
 **Write Operations (exception to naming standard):**
-- `data_file_reference_create` - Create a file reference (uses `data_*` prefix for consistency within file reference system)
+- `data_file_reference_create` - Create a file reference with context-aware permission checks. Requires `p_page_context` parameter to check appropriate page-level permissions (e.g., 'create:page.configuration' or 'update:page.configuration'). Uses `data_*` prefix for consistency within file reference system.
 - `data_file_reference_delete` - Delete a file reference (uses `data_*` prefix for consistency within file reference system)
 
 ### RBAC System

package/docs/api-reference/utilities.md

@@ -369,6 +369,190 @@ import { getDateRange } from '@jmruthers/pace-core';
 const dateRange = getDateRange(startDate, endDate, 'day');
 ```
 
+## Timezone Utilities
+
+Comprehensive timezone conversion and formatting utilities using `date-fns-tz` and native `Intl` APIs. All functions handle DST transitions and return safe error values ('Invalid date' strings) rather than throwing exceptions.
+
+### formatInTimeZone
+
+Format a date in a specific timezone using date-fns format strings.
+
+```typescript
+function formatInTimeZone(
+  date: Date | string | number,
+  timeZone: string,
+  formatStr: string
+): string;
+```
+
+#### Usage
+
+```typescript
+import { formatInTimeZone } from '@jmruthers/pace-core';
+
+// Format UTC date in specific timezone
+formatInTimeZone(new Date('2024-01-15T10:00:00Z'), 'America/New_York', 'MMM dd, yyyy HH:mm');
+// "Jan 15, 2024 05:00"
+
+// With ISO string
+formatInTimeZone('2024-01-15T10:00:00Z', 'Europe/London', 'yyyy-MM-dd');
+// "2024-01-15"
+```
+
+### getTimezoneAbbreviation
+
+Get the timezone abbreviation (EST, PST, etc.) for a date in a specific timezone.
+
+```typescript
+function getTimezoneAbbreviation(date: Date, timeZone: string): string;
+```
+
+#### Usage
+
+```typescript
+import { getTimezoneAbbreviation } from '@jmruthers/pace-core';
+
+getTimezoneAbbreviation(new Date('2024-01-15T10:00:00Z'), 'America/New_York');
+// "EST" or "EDT" depending on DST
+```
+
+### formatTimeInTimeZone
+
+Format time only in a specific timezone (HH:mm format).
+
+```typescript
+function formatTimeInTimeZone(date: Date | string, timeZone: string): string;
+```
+
+#### Usage
+
+```typescript
+import { formatTimeInTimeZone } from '@jmruthers/pace-core';
+
+formatTimeInTimeZone(new Date('2024-01-15T10:00:00Z'), 'America/New_York');
+// "05:00"
+```
+
+### getUserTimeZone
+
+Get the user's browser timezone.
+
+```typescript
+function getUserTimeZone(): string;
+```
+
+#### Usage
+
+```typescript
+import { getUserTimeZone } from '@jmruthers/pace-core';
+
+const userTz = getUserTimeZone();
+// "America/New_York" (or user's actual timezone)
+```
+
+### toZonedTime
+
+Convert a UTC date to a specific timezone's local time representation.
+
+```typescript
+function toZonedTime(date: Date, timezone: string): Date;
+```
+
+#### Usage
+
+```typescript
+import { toZonedTime } from '@jmruthers/pace-core';
+
+const utcDate = new Date('2024-01-15T10:00:00Z');
+const localDate = toZonedTime(utcDate, 'America/New_York');
+// Returns Date object representing Jan 15, 2024 05:00 in local time
+```
+
+### fromZonedTime
+
+Convert a local time in a specific timezone to UTC.
+
+```typescript
+function fromZonedTime(localDate: Date, timezone: string): Date;
+```
+
+#### Usage
+
+```typescript
+import { fromZonedTime } from '@jmruthers/pace-core';
+
+const localInput = new Date(2024, 0, 15, 10, 0); // Jan 15, 2024 10:00 AM (local)
+const utcDate = fromZonedTime(localInput, 'America/New_York');
+// Returns Date object representing Jan 15, 2024 15:00 UTC
+```
+
+### roundToNearestMinutes
+
+Round a date to the nearest X minutes.
+
+```typescript
+function roundToNearestMinutes(date: Date, minutesStep?: number): Date;
+```
+
+#### Usage
+
+```typescript
+import { roundToNearestMinutes } from '@jmruthers/pace-core';
+
+const date = new Date('2024-01-15T10:23:00Z');
+roundToNearestMinutes(date, 5);
+// Returns Date object for 10:25:00
+
+roundToNearestMinutes(date, 15);
+// Returns Date object for 10:30:00
+```
+
+**Note:** `minutesStep` must be one of: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, or 30. Other values will be rounded to the nearest valid step.
+
+### getTimeZoneDifference
+
+Calculate the time difference between two timezones in hours.
+
+```typescript
+function getTimeZoneDifference(fromTimeZone: string, toTimeZone: string): number;
+```
+
+#### Usage
+
+```typescript
+import { getTimeZoneDifference } from '@jmruthers/pace-core';
+
+getTimeZoneDifference('America/New_York', 'America/Los_Angeles');
+// Returns -3 (EST is 3 hours ahead of PST)
+
+getTimeZoneDifference('UTC', 'America/New_York');
+// Returns -5 (or -4 during DST)
+```
+
+#### Complete Example
+
+```typescript
+import { 
+  toZonedTime, 
+  fromZonedTime, 
+  formatInTimeZone,
+  getUserTimeZone 
+} from '@jmruthers/pace-core';
+
+// Convert UTC to local timezone
+const utcDate = new Date('2024-01-15T10:00:00Z');
+const userTz = getUserTimeZone();
+const localDate = toZonedTime(utcDate, userTz);
+
+// Format with timezone
+const formatted = formatInTimeZone(utcDate, userTz, 'MMM dd, yyyy HH:mm (zzz)');
+// "Jan 15, 2024 05:00 (EST)"
+
+// Convert local time to UTC
+const localInput = new Date(2024, 0, 15, 10, 0);
+const utcResult = fromZonedTime(localInput, userTz);
+```
+
 ## String Utilities
 
 ### truncateText

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

@@ -56,7 +56,10 @@ npm uninstall tailwindcss@^3.0.0 postcss autoprefixer
 
 ### Step 3: Configure Vite
 
-**⚠️ CRITICAL**: Without this configuration, PACE Core components will not be styled.
+**⚠️ CRITICAL**: This configuration is required for:
+1. **Tailwind CSS scanning** - Ensures PACE Core components are styled
+2. **React context consistency** - Prevents "useUnifiedAuth must be used within a UnifiedAuthProvider" errors
+3. **Router context availability** - Prevents "useNavigate() may be used only in the context of a <Router>" errors
 
 Create or update `vite.config.ts`:
 
@@ -64,6 +67,7 @@ Create or update `vite.config.ts`:
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
+import path from 'path'
 
 export default defineConfig({
   plugins: [
@@ -76,6 +80,27 @@ export default defineConfig({
       ]
     })
   ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+    // CRITICAL: Dedupe React and React Router to ensure single instances
+    // This prevents Router context issues when pace-core uses react-router-dom
+    dedupe: ['react', 'react-dom', 'react-router-dom']
+  },
+  // CRITICAL: Exclude pace-core from pre-bundling to prevent React context mismatches
+  // Pre-bundling creates separate React instances, causing context errors
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime',
+      '@radix-ui/react-slot'
+    ],
+    // CRITICAL: Exclude pace-core and react-router-dom from pre-bundling
+    // This ensures pace-core uses the same React instance as your app
+    exclude: ['@jmruthers/pace-core', 'react-router-dom']
+  },
   server: {
     port: 3000,
     open: true,
@@ -279,27 +304,61 @@ VITE_SUPABASE_URL=https://your-project.supabase.co
 VITE_SUPABASE_ANON_KEY=your-publishable-key-or-anon-key-here
 ```
 
-Wrap your app with providers:
+Wrap your app with providers in the correct nesting order:
 
 ```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+// src/main.tsx - CRITICAL: Correct provider nesting order
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UnifiedAuthProvider, OrganisationProvider, setupRBAC } from '@jmruthers/pace-core';
 import { supabase } from './lib/supabase';
+import App from './App';
 
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="my-app"
-      idleTimeoutMs={30 * 60 * 1000}
-      warnBeforeMs={5 * 60 * 1000}
-      onIdleLogout={() => window.location.href = '/login'}
-    >
-      <YourApp />
-    </UnifiedAuthProvider>
-  );
-}
+// Import CSS
+import '@jmruthers/pace-core/src/styles/core.css';
+
+// ⚠️ REQUIRED: Setup RBAC before rendering
+setupRBAC(supabase);
+
+const queryClient = new QueryClient();
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    {/* CRITICAL: Correct nesting order */}
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <UnifiedAuthProvider
+          supabaseClient={supabase}
+          appName="my-app"
+          idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+          warnBeforeMs={5 * 60 * 1000} // 5 minutes warning
+          onIdleLogout={() => window.location.href = '/login'}
+        >
+          <OrganisationProvider>
+            <App />
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  </React.StrictMode>
+);
 ```
 
+**⚠️ CRITICAL Provider Nesting Order:**
+1. `QueryClientProvider` (outermost)
+2. `BrowserRouter`
+3. `UnifiedAuthProvider`
+4. `OrganisationProvider`
+5. `App` (innermost)
+
+**Common mistakes to avoid:**
+- ❌ `BrowserRouter` inside `UnifiedAuthProvider` (causes Router context errors)
+- ❌ `UnifiedAuthProvider` wrapping `BrowserRouter` (causes context errors)
+- ❌ Missing `BrowserRouter` (causes `useNavigate` errors)
+- ❌ Missing `QueryClientProvider` (required for React Query features)
+
 ## 🚨 Breaking Changes (v0.5.65+)
 
 **CRITICAL**: As of v0.5.65+, inactivity timeouts are **mandatory** in `UnifiedAuthProvider`.

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

@@ -45,12 +45,15 @@ npm install -D tailwindcss@^4.0.0 @tailwindcss/vite
 
 ## Step 3: Configure Vite
 
+**⚠️ CRITICAL**: This configuration prevents React context and Router context errors.
+
 Create or update `vite.config.ts`:
 
 ```typescript
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
+import path from 'path';
 
 export default defineConfig({
   plugins: [
@@ -62,6 +65,23 @@ export default defineConfig({
       ]
     })
   ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+    // CRITICAL: Dedupe React and React Router to ensure single instances
+    dedupe: ['react', 'react-dom', 'react-router-dom']
+  },
+  // CRITICAL: Exclude pace-core from pre-bundling to prevent React context mismatches
+  optimizeDeps: {
+    include: [
+      'react',
+      'react-dom',
+      'react/jsx-runtime'
+    ],
+    // CRITICAL: Exclude pace-core and react-router-dom from pre-bundling
+    exclude: ['@jmruthers/pace-core', 'react-router-dom']
+  },
   server: {
     port: 3000,
     open: true,
@@ -135,39 +155,66 @@ CREATE POLICY "Users can delete their own tasks" ON tasks
 
 ## Step 7: Create Your App
 
+**⚠️ CRITICAL**: Provider nesting order matters! Follow this exact structure.
+
 Update `src/main.tsx`:
 
 ```tsx
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import { BrowserRouter } from 'react-router-dom';
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UnifiedAuthProvider, OrganisationProvider, setupRBAC } from '@jmruthers/pace-core';
 import { supabase } from './lib/supabase';
 import App from './App';
 import './app.css';
 
+// ⚠️ REQUIRED: Setup RBAC before rendering
+setupRBAC(supabase);
+
+const queryClient = new QueryClient();
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="My Task App"
-      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
-      warnBeforeMs={60 * 1000} // 1 minute warning
-      onIdleLogout={() => window.location.assign('/login')}
-    >
+    {/* CRITICAL: Correct nesting order */}
+    <QueryClientProvider client={queryClient}>
       <BrowserRouter>
-        <App />
+        <UnifiedAuthProvider
+          supabaseClient={supabase}
+          appName="My Task App"
+          idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+          warnBeforeMs={60 * 1000} // 1 minute warning
+          onIdleLogout={() => window.location.assign('/login')}
+        >
+          <OrganisationProvider>
+            <App />
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
       </BrowserRouter>
-    </UnifiedAuthProvider>
+    </QueryClientProvider>
   </React.StrictMode>
 );
 ```
 
+**Provider Nesting Order (CRITICAL):**
+1. `React.StrictMode` (outermost)
+2. `QueryClientProvider`
+3. `BrowserRouter`
+4. `UnifiedAuthProvider`
+5. `OrganisationProvider`
+6. `App` (innermost)
+
+**Why this order matters:**
+- `BrowserRouter` must wrap `UnifiedAuthProvider` to provide Router context
+- `UnifiedAuthProvider` must be inside `BrowserRouter` to use Router hooks
+- `QueryClientProvider` wraps everything for React Query support
+- Wrong nesting causes "useNavigate() may be used only in the context of a <Router>" errors
+
 Create `src/App.tsx`:
 
 ```tsx
 import { Routes, Route, Navigate } from 'react-router-dom';
-import { useUnifiedAuth, PaceLoginPage, PaceAppLayout, ProtectedRoute } from '@jmruthers/pace-core';
+import { PaceLoginPage, PaceAppLayout, ProtectedRoute, useUnifiedAuth } from '@jmruthers/pace-core';
 import { TasksPage } from './pages/TasksPage';
 import { DashboardPage } from './pages/DashboardPage';
 
@@ -180,6 +227,7 @@ function App() {
         path="/login" 
         element={isAuthenticated ? <Navigate to="/" replace /> : <PaceLoginPage appName="My Task App" />} 
       />
+      {/* ProtectedRoute from pace-core package - handles auth and event selection */}
       <Route element={<ProtectedRoute />}>
         <Route element={<PaceAppLayout appName="My Task App" />}>
           <Route path="/" element={<DashboardPage />} />
@@ -193,6 +241,8 @@ function App() {
 export default App;
 ```
 
+**Note:** `ProtectedRoute` is imported from `@jmruthers/pace-core` - do not create a local version. The package version handles authentication, session restoration, and optional event selection.
+
 ## Step 8: Create the Dashboard Page
 
 Create `src/pages/DashboardPage.tsx`: