@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/api-reference/hooks.md

@@ -1,7 +1,5 @@
 # Hooks API Reference
 
-> **🔗 React Hooks Reference** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
-
 This section provides detailed API documentation for all React hooks in `@jmruthers/pace-core`.
 
 ## Authentication Hooks
@@ -490,130 +488,6 @@ function useUserDashboard() {
 }
 ```
 
-## Public Page Hooks
-
-### usePublicRouteParams
-
-Extract parameters from public page URLs.
-
-```typescript
-interface UsePublicRouteParamsOptions {
-  fetchEventData?: boolean;
-}
-
-interface UsePublicRouteParamsReturn {
-  eventCode: string | null;
-  reportId: string | null;
-  pageId: string | null;
-  [key: string]: string | null;
-}
-
-function usePublicRouteParams(
-  options?: UsePublicRouteParamsOptions
-): UsePublicRouteParamsReturn;
-```
-
-**Usage:**
-```tsx
-import { usePublicRouteParams } from '@jmruthers/pace-core';
-
-function PublicEventPage() {
-  const { eventCode, reportId } = usePublicRouteParams({ 
-    fetchEventData: false 
-  });
-  
-  console.log('Event Code:', eventCode);
-  console.log('Report ID:', reportId);
-  
-  return <div>Event: {eventCode}</div>;
-}
-```
-
-### usePublicEvent
-
-Fetch event data for public pages.
-
-```typescript
-interface UsePublicEventReturn {
-  event: Event | null;
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => void;
-}
-
-function usePublicEvent(eventCode: string): UsePublicEventReturn;
-```
-
-**Usage:**
-```tsx
-import { usePublicEvent } from '@jmruthers/pace-core';
-
-function PublicEventPage() {
-  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
-  const { event, isLoading, error, refetch } = usePublicEvent(eventCode || '');
-  
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!event) return <div>Event not found</div>;
-  
-  return <div>Event: {event.event_name}</div>;
-}
-```
-
-### useIsPublicPage
-
-Check if current page is a public page.
-
-```typescript
-function useIsPublicPage(): boolean;
-```
-
-**Usage:**
-```tsx
-import { useIsPublicPage } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const isPublicPage = useIsPublicPage();
-  
-  if (isPublicPage) {
-    return <div>This is a public page</div>;
-  }
-  
-  return <div>This is an authenticated page</div>;
-}
-```
-
-### usePublicPageContext
-
-Access public page context and environment variables.
-
-```typescript
-interface UsePublicPageContextReturn {
-  isPublicPage: true;
-  environment: {
-    supabaseUrl: string | null;
-    supabaseKey: string | null;
-  };
-}
-
-function usePublicPageContext(): UsePublicPageContextReturn;
-```
-
-**Usage:**
-```tsx
-import { usePublicPageContext } from '@jmruthers/pace-core';
-
-function PublicComponent() {
-  const { environment } = usePublicPageContext();
-  
-  console.log('Supabase URL:', environment.supabaseUrl);
-  
-  return <div>Public component</div>;
-}
-```
-
-For detailed public page implementation, see [Public Pages Guide](../implementation-guides/public-pages.md).
-
 ## Hook Testing
 
 All hooks include comprehensive testing:

package/docs/api-reference/providers.md

@@ -17,17 +17,6 @@ interface UnifiedAuthProviderProps {
   requireOrganisationContext?: boolean;
   enableRBAC?: boolean;
   onAuthStateChange?: (event: AuthChangeEvent, session: Session | null) => void;
-  
-  // Inactivity auto-logout configuration
-  idleTimeoutMs?: number; // Default: 30 minutes
-  warnBeforeMs?: number; // Default: 60 seconds
-  onIdleLogout?: (reason: 'inactivity') => void; // App handles redirect/navigation
-  renderInactivityWarning?: (args: {
-    timeRemaining: number;
-    onStaySignedIn: () => void;
-    onSignOutNow: () => void;
-  }) => React.ReactNode; // Optional custom warning UI
-  dangerouslyDisableInactivity?: boolean; // Dev-only; must not disable in production
 }
 ```
 
@@ -66,129 +55,6 @@ function App() {
 | `requireOrganisationContext` | `boolean` | `true` | Require organisation context for security |
 | `enableRBAC` | `boolean` | `false` | Enable the RBAC system |
 | `onAuthStateChange` | `function` | `undefined` | Callback for auth state changes |
-| `idleTimeoutMs` | `number` | `1800000` | Inactivity timeout in milliseconds (30 minutes) |
-| `warnBeforeMs` | `number` | `60000` | Warning time before logout in milliseconds (60 seconds) |
-| `onIdleLogout` | `function` | `undefined` | Callback when user is logged out due to inactivity |
-| `renderInactivityWarning` | `function` | `undefined` | Custom warning UI renderer |
-| `dangerouslyDisableInactivity` | `boolean` | `false` | Dev-only: disable inactivity feature (not allowed in production) |
-
-### Inactivity Auto-Logout
-
-The `UnifiedAuthProvider` includes built-in inactivity tracking that automatically logs out users after a period of inactivity for security purposes.
-
-#### Features
-
-- **Automatic logout** after 30 minutes of inactivity (configurable)
-- **Warning modal** appears 60 seconds before logout (configurable)
-- **Cross-tab synchronization** - activity in any tab resets the timer
-- **Persistence** - survives page reloads and browser restarts
-- **Production-safe** - cannot be disabled in production builds
-- **SSR-safe** - works correctly with server-side rendering
-- **Accessible** - includes proper ARIA attributes and keyboard navigation
-
-#### Basic Usage
-
-```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import { createClient } from '@supabase/supabase-js';
-import { useNavigate } from 'react-router-dom';
-
-const supabase = createClient(url, key);
-
-function App() {
-  const navigate = useNavigate();
-
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="my-app"
-      onIdleLogout={() => navigate('/login')}
-    >
-      <AppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-#### Custom Configuration
-
-```tsx
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="my-app"
-  idleTimeoutMs={20 * 60 * 1000} // 20 minutes
-  warnBeforeMs={2 * 60 * 1000}   // 2 minutes warning
-  onIdleLogout={(reason) => {
-    console.log(`User logged out due to: ${reason}`);
-    navigate('/login');
-  }}
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-#### Custom Warning UI
-
-```tsx
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="my-app"
-  renderInactivityWarning={({ timeRemaining, onStaySignedIn, onSignOutNow }) => (
-    <div className="fixed inset-0 bg-main-950/50 flex items-center justify-center z-50">
-      <div className="bg-main-50 p-6 rounded-lg shadow-lg">
-        <h2 className="text-xl font-bold mb-4">Session Timeout</h2>
-        <p className="mb-4">
-          You'll be logged out in {Math.ceil(timeRemaining / 60)} minutes.
-        </p>
-        <div className="flex gap-2">
-          <button onClick={onStaySignedIn} className="px-4 py-2 bg-main-500 text-main-50 rounded">
-            Stay Signed In
-          </button>
-          <button onClick={onSignOutNow} className="px-4 py-2 bg-sec-500 text-main-50 rounded">
-            Sign Out Now
-          </button>
-        </div>
-      </div>
-    </div>
-  )}
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-#### Development Mode
-
-In development, you can disable the inactivity feature for testing:
-
-```tsx
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="my-app"
-  dangerouslyDisableInactivity={true} // Only works in development
->
-  <AppContent />
-</UnifiedAuthProvider>
-```
-
-**⚠️ Warning**: The `dangerouslyDisableInactivity` prop is only available in development mode and will be ignored in production builds.
-
-#### Monitored Events
-
-The inactivity tracker monitors the following user interactions:
-
-- Mouse events (click, move, scroll, wheel)
-- Touch events (start, move, end)
-- Keyboard events (keydown, keyup, keypress)
-- Focus events (focus, blur)
-- Page visibility changes
-
-#### Security Considerations
-
-- **Production enforcement**: The inactivity feature cannot be disabled in production
-- **Cross-tab sync**: Activity in any tab resets the timer across all tabs
-- **Persistent state**: Last activity time is stored in localStorage
-- **Automatic cleanup**: All timers and listeners are properly cleaned up
-- **Error handling**: Graceful fallback if localStorage or BroadcastChannel fail
 
 ## OrganisationProvider
 
@@ -308,6 +174,41 @@ function App() {
 | `autoSelectNextEvent` | `boolean` | `true` | Auto-select next upcoming event |
 | `onEventChange` | `function` | `undefined` | Callback for event changes |
 
+## ThemeProvider
+
+Manages application theme and provides theme context to all components.
+
+### Props
+
+```typescript
+interface ThemeProviderProps {
+  children: React.ReactNode;
+  defaultTheme?: 'light' | 'dark' | 'system';
+  storageKey?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { ThemeProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <ThemeProvider defaultTheme="system" storageKey="app-theme">
+      <AppContent />
+    </ThemeProvider>
+  );
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultTheme` | `'light' \| 'dark' \| 'system'` | `'system'` | Default theme to use |
+| `storageKey` | `string` | `'ui-theme'` | Local storage key for theme persistence |
+
 ## ErrorBoundary
 
 Catches and handles JavaScript errors in component trees.
@@ -362,13 +263,15 @@ function App() {
 function App() {
   return (
     <ErrorBoundary>
-      <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-        <OrganisationProvider>
-          <EventProvider>
-            <AppContent />
-          </EventProvider>
-        </OrganisationProvider>
-      </UnifiedAuthProvider>
+      <ThemeProvider>
+        <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+          <OrganisationProvider>
+            <EventProvider>
+              <AppContent />
+            </EventProvider>
+          </OrganisationProvider>
+        </UnifiedAuthProvider>
+      </ThemeProvider>
     </ErrorBoundary>
   );
 }
@@ -377,6 +280,7 @@ function App() {
 ### Provider Dependencies
 
 - **ErrorBoundary** - No dependencies, can wrap everything
+- **ThemeProvider** - No dependencies, provides theme context
 - **UnifiedAuthProvider** - Requires Supabase client
 - **OrganisationProvider** - Requires UnifiedAuthProvider
 - **EventProvider** - Requires OrganisationProvider
@@ -458,6 +362,23 @@ function EventSelector() {
 }
 ```
 
+### useTheme
+
+Access theme context:
+
+```tsx
+import { useTheme } from '@jmruthers/pace-core';
+
+function ThemeToggle() {
+  const { theme, setTheme } = useTheme();
+  
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      Switch to {theme === 'light' ? 'dark' : 'light'} mode
+    </button>
+  );
+}
+```
 
 ## Best Practices
 
@@ -469,6 +390,9 @@ Always maintain the correct provider hierarchy for proper context availability.
 
 Wrap your app with ErrorBoundary to catch and handle errors gracefully.
 
+### 3. Theme Provider
+
+Place ThemeProvider early in the tree to ensure all components have theme access.
 
 ### 4. Context Optimization
 

package/docs/api-reference/types.md

@@ -228,6 +228,7 @@ Settings for an organisation.
 
 ```typescript
 interface OrganisationSettings {
+  theme: 'light' | 'dark' | 'auto';
   timezone: string;
   date_format: string;
   time_format: '12h' | '24h';
@@ -491,74 +492,14 @@ Props for the Dialog component (replaces Modal).
 
 ```typescript
 interface DialogProps {
+  isOpen: boolean;
+  onClose: () => void;
+  title?: string;
   children: React.ReactNode;
-  open?: boolean;
-  onOpenChange?: (open: boolean) => void;
-}
-```
-
-### DialogContentProps
-
-Props for the DialogContent component.
-
-```typescript
-interface DialogContentProps {
-  children: React.ReactNode;
-  className?: string;
-  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'auto';
-  showCloseButton?: boolean;
-  overlayClassName?: string;
-  preventCloseOnEscape?: boolean;
-  preventCloseOnOutsideClick?: boolean;
-  maxHeightPercent?: number;
-  maxWidthPercent?: number;
-  enableScrolling?: boolean;
-  maxHeight?: string;
-  maxWidth?: string;
-  minHeight?: string;
-  minWidth?: string;
-}
-```
-
-### DialogBodyProps
-
-Props for the DialogBody component with HTML content support.
-
-```typescript
-interface DialogBodyProps {
-  children: React.ReactNode;
-  className?: string;
-  maxHeight?: string;
-  htmlContent?: string;
-  allowHtml?: boolean;
-  strictSanitization?: boolean;
-  logWarnings?: boolean;
-}
-```
-
-### DialogTitleProps
-
-Props for the DialogTitle component with HTML content support.
-
-```typescript
-interface DialogTitleProps {
-  children: React.ReactNode;
-  className?: string;
-  htmlContent?: string;
-  allowHtml?: boolean;
-}
-```
-
-### DialogDescriptionProps
-
-Props for the DialogDescription component with HTML content support.
-
-```typescript
-interface DialogDescriptionProps {
-  children: React.ReactNode;
+  size?: 'sm' | 'md' | 'lg' | 'xl';
   className?: string;
-  htmlContent?: string;
-  allowHtml?: boolean;
+  closeOnBackdrop?: boolean;
+  closeOnEscape?: boolean;
 }
 ```
 
@@ -610,6 +551,27 @@ interface Toast extends ToastConfig {
 }
 ```
 
+## Theme Types
+
+### Theme
+
+Represents the application theme.
+
+```typescript
+type Theme = 'light' | 'dark' | 'auto';
+```
+
+### ThemeConfig
+
+Configuration for theme management.
+
+```typescript
+interface ThemeConfig {
+  defaultTheme: Theme;
+  storageKey: string;
+  enableSystemPreference?: boolean;
+}
+```
 
 ## Hook Return Types
 
@@ -667,6 +629,12 @@ interface UseEventsReturn {
 }
 ```
 
+### UseThemeReturn
+
+Return type for the useTheme hook.
+
+```typescript
+interface UseThemeReturn {
   theme: Theme;
   setTheme: (theme: Theme) => void;
   toggleTheme: () => void;
@@ -852,6 +820,7 @@ interface FeatureFlags {
   organisations: boolean;
   analytics: boolean;
   notifications: boolean;
+  darkMode: boolean;
   experimental: {
     newUI: boolean;
     betaFeatures: boolean;
@@ -970,6 +939,7 @@ export type {
   UseUnifiedAuthReturn,
   UseRBACReturn,
   UseEventsReturn,
+  UseThemeReturn,
   UseToastReturn,
   
   // Utilities

package/docs/api-reference/utilities.md

@@ -944,7 +944,7 @@ const storage = {
 import { storage } from '@jmruthers/pace-core';
 
 // Store data
-storage.set('user-preferences', { notifications: true });
+storage.set('user-preferences', { theme: 'dark' });
 
 // Retrieve data
 const preferences = storage.get('user-preferences');

package/docs/architecture/README.md

@@ -78,6 +78,7 @@ graph TD
     B --> B1[UnifiedAuthProvider]
     B --> B2[EventProvider]
     B --> B3[OrganisationProvider]
+    B --> B4[ThemeProvider]
     
     C --> C1[UI Components]
     C --> C2[Form Components]
@@ -119,7 +120,7 @@ ComponentName/
 
 ### Component Design Patterns
 
-1. **Compound Components**: Components that work together (e.g., DataTable + DataTableToolbar + DataTableBody)
+1. **Compound Components**: Components that work together (e.g., DataTable + DataTableHeader + DataTableBody)
 2. **Render Props**: Flexible rendering patterns for complex components
 3. **Controlled/Uncontrolled**: Support for both controlled and uncontrolled usage
 4. **Composition**: Components that can be composed together