@jmruthers/pace-core 0.5.184 → 0.5.185

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`:

package/docs/implementation-guides/authentication.md

@@ -69,17 +69,64 @@ if (!supabaseUrl || !supabaseAnonKey) {
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 4. App Setup with Authentication
+### 4. Configure Vite (CRITICAL)
 
-**CRITICAL**: UnifiedAuthProvider now requires inactivity timeout configuration:
+**⚠️ CRITICAL**: This configuration prevents React context and Router context errors.
+
+Add to your `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: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  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'
+    ],
+    exclude: ['@jmruthers/pace-core', 'react-router-dom']
+  },
+});
+```
+
+### 5. App Setup with Authentication
+
+**⚠️ CRITICAL**: 
+1. Provider nesting order matters - follow the exact structure below
+2. UnifiedAuthProvider requires inactivity timeout configuration
+3. setupRBAC() must be called before rendering
 
 ```tsx
 // src/main.tsx
 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
+  UnifiedAuthProvider,
+  OrganisationProvider,
+  setupRBAC
 } from '@jmruthers/pace-core'
 import { supabase } from './lib/supabase'
 import App from './App.tsx'
@@ -87,17 +134,46 @@ import App from './App.tsx'
 // CRITICAL: Import the CSS system - includes everything you need
 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>
-    <BrowserRouter>
-      <UnifiedAuthProvider 
-        supabaseClient={supabase} 
-        appName="my-app"
-        requireOrganisationContext={true}
-        idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
-        warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
-        onIdleLogout={() => window.location.href = '/login'}  // REQUIRED
-      >
+    {/* CRITICAL: Correct nesting order */}
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <UnifiedAuthProvider 
+          supabaseClient={supabase} 
+          appName="my-app"
+          requireOrganisationContext={true}
+          idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
+          warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
+          onIdleLogout={() => window.location.href = '/login'}  // REQUIRED
+        >
+          <OrganisationProvider>
+            <App />
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
+      </BrowserRouter>
+    </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
+- Wrong nesting causes "useNavigate() may be used only in the context of a <Router>" errors
         <App />
       </UnifiedAuthProvider>
     </BrowserRouter>