@jmruthers/pace-core 0.6.5 → 0.6.7

package/src/hooks/useEventTheme.ts

@@ -38,15 +38,12 @@
  * ```
  */
 
-import { useEffect } from 'react';
+import { useEffect, useContext } from 'react';
 import { useLocation } from 'react-router-dom';
-import { useEvents } from './useEvents';
+import { EventServiceContext } from '../providers/services/EventServiceProvider';
 import { applyPalette, clearPalette } from '../theming/runtime';
 import { parseAndNormalizeEventColours } from '../theming/parseEventColours';
 import type { Event } from '../types/event';
-import { createLogger } from '../utils/core/logger';
-
-const log = createLogger('useEventTheme');
 
 /**
  * Hook that automatically applies event-specific theming
@@ -99,30 +96,21 @@ const log = createLogger('useEventTheme');
  * @param event - Optional event object for public page mode. If not provided, uses EventProvider context.
  */
 export function useEventTheme(event?: Event | null): void {
+  // Call all hooks unconditionally at the top level
+  // Hooks must be called in the same order on every render
   const location = useLocation();
   
-  // Try to get event from EventProvider context (authenticated mode)
-  // Only use useEvents() if event prop is not provided
-  let selectedEvent: Event | null | undefined;
-  try {
-    if (event === undefined) {
-      // No event prop provided, try to use EventProvider context
-      const eventsContext = useEvents();
-      selectedEvent = eventsContext.selectedEvent;
-    } else {
-      // Event prop provided, use it directly (public page mode)
-      selectedEvent = event;
-    }
-  } catch (error) {
-    // useEvents() throws if EventProvider is not available
-    // This is expected for public pages - use the event prop if provided
-    if (event !== undefined) {
-      selectedEvent = event;
-    } else {
-      // No event prop and no EventProvider - can't apply theme
-      selectedEvent = null;
-    }
-  }
+  // Use EventServiceContext directly to handle missing provider gracefully
+  // This allows the hook to work in public pages without EventProvider
+  const eventServiceContext = useContext(EventServiceContext);
+  const eventsContextSelectedEvent = eventServiceContext?.eventService?.getSelectedEvent() ?? null;
+  
+  // Determine which event to use: event prop (public mode) or EventProvider context (authenticated mode)
+  // If event prop is provided, use it (public page mode)
+  // Otherwise, use EventProvider context (authenticated mode)
+  const selectedEvent = event !== undefined 
+    ? event  // Public page mode - use event prop
+    : eventsContextSelectedEvent;  // Authenticated mode - use EventProvider context
 
   useEffect(() => {
     // Skip theme application when on login route
@@ -156,7 +144,7 @@ export function useEventTheme(event?: Event | null): void {
     try {
       applyPalette(normalized);
     } catch (error) {
-      log.error('Failed to apply event palette:', error);
+      // Silently fail - theming is not critical
     }
 
     // Cleanup function to clear palette when component unmounts or event changes

package/src/hooks/useFileDisplay.ts

@@ -26,8 +26,8 @@
  *     FileCategory.EVENT_LOGOS
  *   );
  *
- *   if (isLoading) return <div>Loading...</div>;
- *   if (error) return <div>Error: {error.message}</div>;
+ *   if (isLoading) return <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
  *
  *   return fileUrl ? <img src={fileUrl} alt="File" /> : null;
  * }

package/src/hooks/useOrganisationPermissions.ts

@@ -106,13 +106,11 @@ export function useOrganisationPermissions(orgId?: string): UseOrganisationPermi
     ensureOrganisationContext
   } = useOrganisations();
   
-  // Get super admin context if available (may not be available in all contexts)
-  let superAdminContext: { isSuperAdmin: boolean } = { isSuperAdmin: false };
-  try {
-    superAdminContext = useOrganisationSecurity().superAdminContext;
-  } catch {
-    // Not available in this context, default to false
-  }
+  // Call hook unconditionally - if provider is missing, it will throw
+  // Errors should be handled by error boundaries at a higher level
+  // We cannot conditionally call hooks
+  const organisationSecurity = useOrganisationSecurity();
+  const superAdminContext = organisationSecurity.superAdminContext;
 
   const organisationId = useMemo(() => {
     if (orgId) {

package/src/hooks/useQueryCache.ts

@@ -50,7 +50,6 @@ function runCacheCleanup() {
 // Initialize cleanup timer once
 if (typeof window !== 'undefined' && !cleanupTimer) {
   cleanupTimer = setInterval(runCacheCleanup, CLEANUP_INTERVAL_MS);
-  log.debug('Query cache cleanup initialized.');
   
   // Cleanup on page unload to prevent memory leaks
   window.addEventListener('beforeunload', () => {

package/src/hooks/useSessionDraft.ts

@@ -0,0 +1,380 @@
+/**
+ * @file Session Draft Persistence Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Persistence
+ * @since 1.0.0
+ *
+ * A React hook for persisting component state to sessionStorage.
+ * Provides automatic persistence that survives tab switching but clears on tab close.
+ *
+ * Features:
+ * - Debounced writes to prevent excessive storage operations
+ * - Automatic restoration on mount
+ * - Versioning support for schema migrations
+ * - Safe JSON serialization with error handling
+ * - Type-safe with generics
+ * - Handles storage quota errors gracefully
+ * - Optional cleanup on unmount
+ *
+ * @example
+ * ```tsx
+ * const { state, setState, clearDraft } = useSessionDraft('my-component', {
+ *   filters: [],
+ *   sortBy: 'name'
+ * });
+ *
+ * // State is automatically persisted on changes
+ * setState({ filters: ['active'], sortBy: 'email' });
+ *
+ * // Clear draft when done
+ * clearDraft();
+ * ```
+ *
+ * @dependencies
+ * - React 19+ - Hooks and effects
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+/**
+ * Schema version for stored drafts
+ * Increment when the data structure changes
+ */
+const DRAFT_SCHEMA_VERSION = 1;
+
+/**
+ * Default debounce delay in milliseconds
+ */
+const DEFAULT_DEBOUNCE_MS = 300;
+
+/**
+ * Stored draft payload structure
+ */
+interface StoredDraft<T> {
+  version: number;
+  data: T;
+  timestamp: number;
+}
+
+/**
+ * Options for useSessionDraft hook
+ */
+export interface UseSessionDraftOptions {
+  /**
+   * Debounce delay in milliseconds
+   * @default 300
+   */
+  debounceMs?: number;
+
+  /**
+   * Whether to clear draft on component unmount
+   * @default false
+   */
+  clearOnUnmount?: boolean;
+
+  /**
+   * Whether to enable persistence (useful for conditional persistence)
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Custom storage key prefix
+   * @default 'pace-core:draft'
+   */
+  keyPrefix?: string;
+}
+
+/**
+ * Return value of useSessionDraft hook
+ */
+export interface UseSessionDraftReturn<T> {
+  /**
+   * Current draft state
+   */
+  state: T;
+
+  /**
+   * Update draft state (triggers debounced save)
+   */
+  setState: (newState: T | ((prev: T) => T)) => void;
+
+  /**
+   * Clear the draft from storage
+   */
+  clearDraft: () => void;
+
+  /**
+   * Force immediate save (bypasses debounce)
+   */
+  saveImmediately: () => void;
+
+  /**
+   * Whether the draft was restored from storage
+   */
+  wasRestored: boolean;
+}
+
+/**
+ * Debounce function that matches lodash debounce API
+ */
+function debounce<T extends (...args: any[]) => void>(
+  func: T,
+  wait: number
+): T & { cancel: () => void } {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  const debounced = ((...args: Parameters<T>) => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => {
+      func(...args);
+    }, wait);
+  }) as T & { cancel: () => void };
+
+  debounced.cancel = () => {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  return debounced;
+}
+
+/**
+ * Get the full storage key with namespace
+ */
+function getStorageKey(key: string, prefix: string): string {
+  return `${prefix}:${key}`;
+}
+
+/**
+ * Save draft to sessionStorage
+ */
+function saveDraft<T>(storageKey: string, data: T): boolean {
+  if (typeof window === 'undefined' || !window.sessionStorage) {
+    return false;
+  }
+
+  try {
+    const payload: StoredDraft<T> = {
+      version: DRAFT_SCHEMA_VERSION,
+      data,
+      timestamp: Date.now(),
+    };
+
+    const serialized = JSON.stringify(payload);
+    window.sessionStorage.setItem(storageKey, serialized);
+    return true;
+  } catch (error) {
+    // Handle quota exceeded or other storage errors
+    if (error instanceof DOMException && error.name === 'QuotaExceededError') {
+      console.warn(`[useSessionDraft] Storage quota exceeded for key: ${storageKey}`);
+    } else {
+      console.warn(`[useSessionDraft] Failed to save draft for key: ${storageKey}`, error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Load draft from sessionStorage
+ */
+function loadDraft<T>(storageKey: string): T | null {
+  if (typeof window === 'undefined' || !window.sessionStorage) {
+    return null;
+  }
+
+  try {
+    const stored = window.sessionStorage.getItem(storageKey);
+    if (!stored) {
+      return null;
+    }
+
+    const parsed = JSON.parse(stored) as StoredDraft<T>;
+
+    // Validate version
+    if (parsed.version !== DRAFT_SCHEMA_VERSION) {
+      console.warn(
+        `[useSessionDraft] Schema version mismatch for key: ${storageKey}. Expected ${DRAFT_SCHEMA_VERSION}, got ${parsed.version}`
+      );
+      // Clear outdated draft
+      window.sessionStorage.removeItem(storageKey);
+      return null;
+    }
+
+    // Validate structure
+    if (!parsed.data) {
+      console.warn(`[useSessionDraft] Invalid draft structure for key: ${storageKey}`);
+      window.sessionStorage.removeItem(storageKey);
+      return null;
+    }
+
+    return parsed.data;
+  } catch (error) {
+    console.warn(`[useSessionDraft] Failed to load draft for key: ${storageKey}`, error);
+    // Clear corrupted draft
+    try {
+      if (typeof window !== 'undefined' && window.sessionStorage) {
+        window.sessionStorage.removeItem(storageKey);
+      }
+    } catch {
+      // Ignore cleanup errors
+    }
+    return null;
+  }
+}
+
+/**
+ * Remove draft from sessionStorage
+ */
+function removeDraft(storageKey: string): void {
+  if (typeof window === 'undefined' || !window.sessionStorage) {
+    return;
+  }
+
+  try {
+    window.sessionStorage.removeItem(storageKey);
+  } catch (error) {
+    console.warn(`[useSessionDraft] Failed to remove draft for key: ${storageKey}`, error);
+  }
+}
+
+/**
+ * Hook for persisting component state to sessionStorage
+ *
+ * Automatically saves state changes with debouncing and restores state on mount.
+ * Data persists across tab switches but clears when the tab closes.
+ *
+ * @template T - The type of state to persist
+ * @param key - Unique key for this draft (will be namespaced automatically)
+ * @param initialState - Initial state if no draft exists
+ * @param options - Configuration options
+ * @returns Object containing state, setState, clearDraft, and utility functions
+ *
+ * @example
+ * ```tsx
+ * const { state, setState } = useSessionDraft('user-filters', {
+ *   search: '',
+ *   status: 'all'
+ * });
+ * ```
+ */
+export function useSessionDraft<T>(
+  key: string,
+  initialState: T,
+  options: UseSessionDraftOptions = {}
+): UseSessionDraftReturn<T> {
+  const {
+    debounceMs = DEFAULT_DEBOUNCE_MS,
+    clearOnUnmount = false,
+    enabled = true,
+    keyPrefix = 'pace-core:draft',
+  } = options;
+
+  const storageKey = getStorageKey(key, keyPrefix);
+  const wasRestoredRef = useRef(false);
+
+  // Load draft on mount
+  const [state, setStateInternal] = useState<T>(() => {
+    if (!enabled) {
+      return initialState;
+    }
+
+    const restored = loadDraft<T>(storageKey);
+    if (restored !== null) {
+      wasRestoredRef.current = true;
+      return restored;
+    }
+
+    return initialState;
+  });
+
+  // Create debounced save function
+  const debouncedSaveRef = useRef<ReturnType<typeof debounce> | null>(null);
+
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    // Create debounced save function
+    const debouncedSave = debounce((data: T) => {
+      saveDraft(storageKey, data);
+    }, debounceMs);
+
+    debouncedSaveRef.current = debouncedSave;
+
+    return () => {
+      // Cancel pending saves on unmount
+      debouncedSave.cancel();
+    };
+  }, [storageKey, debounceMs, enabled]);
+
+  // Save state changes
+  const setState = useCallback(
+    (newState: T | ((prev: T) => T)) => {
+      setStateInternal((prev) => {
+        const updated = typeof newState === 'function' ? (newState as (prev: T) => T)(prev) : newState;
+
+        // Save to storage (debounced)
+        if (enabled && debouncedSaveRef.current) {
+          debouncedSaveRef.current(updated);
+        }
+
+        return updated;
+      });
+    },
+    [enabled]
+  );
+
+  // Force immediate save
+  const saveImmediately = useCallback(() => {
+    if (!enabled) {
+      return;
+    }
+
+    // Cancel any pending debounced save
+    if (debouncedSaveRef.current) {
+      debouncedSaveRef.current.cancel();
+    }
+
+    // Save immediately
+    saveDraft(storageKey, state);
+  }, [storageKey, state, enabled]);
+
+  // Clear draft
+  const clearDraft = useCallback(() => {
+    removeDraft(storageKey);
+    setStateInternal(initialState);
+    wasRestoredRef.current = false;
+  }, [storageKey, initialState]);
+
+  // Cleanup on unmount if configured
+  useEffect(() => {
+    if (!enabled || !clearOnUnmount) {
+      return;
+    }
+
+    return () => {
+      // Cancel pending saves
+      if (debouncedSaveRef.current) {
+        debouncedSaveRef.current.cancel();
+      }
+
+      // Clear draft
+      removeDraft(storageKey);
+    };
+  }, [storageKey, clearOnUnmount, enabled]);
+
+  return {
+    state,
+    setState,
+    clearDraft,
+    saveImmediately,
+    wasRestored: wasRestoredRef.current,
+  };
+}
+

package/src/hooks/useSessionRestoration.ts

@@ -16,7 +16,9 @@ import { createLogger } from '../utils/core/logger';
 
 const log = createLogger('useSessionRestoration');
 
-const SESSION_RESTORATION_TIMEOUT_MS = 5000;
+// Increased timeout to handle hard refresh scenarios where localStorage access
+// and session restoration may take longer, especially with organisation/event context
+const SESSION_RESTORATION_TIMEOUT_MS = 10000; // 10 seconds (increased from 5)
 
 /**
  * Return value of the useSessionRestoration hook.

package/src/icons/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @file Icon Exports
+ * @package @jmruthers/pace-core
+ * @module Icons
+ * @since 0.6.6
+ * 
+ * Icon exports from lucide-react.
+ * Import icons from '@jmruthers/pace-core/icons' instead of 'lucide-react'.
+ * 
+ * All lucide-react icons are exported to ensure consuming apps have access
+ * to all icons while enforcing consistent usage through pace-core.
+ * 
+ * @example
+ * ```tsx
+ * // ✅ CORRECT: Import icons from pace-core
+ * import { ChevronDown, Edit, Trash } from '@jmruthers/pace-core/icons';
+ * 
+ * // ❌ WRONG: Direct import from lucide-react (will fail - lucide-react is not a peer dependency)
+ * import { ChevronDown } from 'lucide-react';
+ * ```
+ */
+
+// Export all icons from lucide-react
+// This ensures consuming apps have access to all icons while enforcing
+// consistent usage through pace-core's icon export system
+export * from 'lucide-react';
+

package/src/index.ts

@@ -212,6 +212,8 @@ export { z } from 'zod';
 // Common validation schemas
 export { emailSchema, nameSchema, phoneSchema, urlSchema } from './utils/validation/common';
 export { passwordSchema } from './utils/validation/passwordSchema';
+// Sanitization utilities
+export { sanitizeUserInput, sanitizeFormData, sanitizeHtml } from './utils/validation/sanitization';
 
 // LAYOUT COMPONENTS
 export { Header } from './components/Header/Header';
@@ -260,6 +262,9 @@ export { useEventTheme } from './hooks/useEventTheme';
 export { cn } from './utils/core/cn';
 export { setAppConfig, getAppConfig, getCurrentAppName, getCurrentAppId } from './utils/app/appConfig';
 
+// Supabase client creation (restricted wrapper - ONLY for base client creation)
+export { createBaseClient } from './utils/supabase/createBaseClient';
+
 // LOGGING UTILITIES
 export { Logger, logger, createLogger, LogLevel } from './utils/core/logger';
 export type { LoggerConfig } from './utils/core/logger';

package/src/providers/OrganisationProvider.tsx

@@ -13,9 +13,9 @@
  * for backward compatibility or standalone usage.
  */
 
-import React from 'react';
-import { useUnifiedAuth } from '../providers/services/UnifiedAuthProvider';
-import { OrganisationServiceProvider } from './services/OrganisationServiceProvider';
+import React, { useContext } from 'react';
+import { UnifiedAuthContext } from '../providers/services/UnifiedAuthProvider';
+import { OrganisationServiceProvider, OrganisationServiceContext } from './services/OrganisationServiceProvider';
 import type { OrganisationProviderProps as BaseOrganisationProviderProps } from '../types/organisation';
 
 export interface OrganisationProviderProps extends BaseOrganisationProviderProps {
@@ -45,19 +45,29 @@ export function OrganisationProvider({
   autoSelectPrimaryOrganisation,
   onOrganisationChange
 }: OrganisationProviderProps) {
+  // Call all hooks unconditionally at the top level
+  // Hooks must be called in the same order on every render
+  // Check if we're already inside OrganisationServiceProvider (e.g., from UnifiedAuthProvider)
+  // If so, just pass through children to avoid double-wrapping
+  const existingOrganisationService = useContext(OrganisationServiceContext);
+  
   // Get auth context from UnifiedAuthProvider
-  const authContext = useUnifiedAuth();
+  // Use useContext directly instead of useUnifiedAuth() to avoid throwing
+  // if context isn't available yet (e.g., during initial render)
+  const authContext = useContext(UnifiedAuthContext);
   
-  // If we're inside UnifiedAuthProvider, it already includes OrganisationServiceProvider
-  // So we can just pass through the children
-  // However, if the auth context is not available, we need to handle that
-  if (!authContext) {
-    // If no auth context, we can't provide organisation service
-    // This might happen if used outside UnifiedAuthProvider
-    // In that case, we should probably throw an error or show a message
-    console.warn('OrganisationProvider: No auth context available. Make sure OrganisationProvider is used inside UnifiedAuthProvider.');
+  // Early return after all hooks have been called
+  if (existingOrganisationService) {
+    // We're already inside UnifiedAuthProvider which includes OrganisationServiceProvider
+    // Just pass through children - no need to wrap again
     return <>{children}</>;
   }
+  
+  // If no auth context, we can't provide organisation service
+  // This might happen if used outside UnifiedAuthProvider
+  if (!authContext) {
+    throw new Error('OrganisationProvider must be used inside UnifiedAuthProvider, or OrganisationServiceProvider must be provided separately');
+  }
 
   const { supabase, user, session } = authContext;
 
@@ -66,8 +76,7 @@ export function OrganisationProvider({
   // are handled by the OrganisationService internally, not by the provider
   // Note: supabase is mapped to supabaseClient for OrganisationServiceProvider
   if (!supabase) {
-    console.warn('OrganisationProvider: No supabase client available.');
-    return <>{children}</>;
+    throw new Error('OrganisationProvider: No supabase client available from UnifiedAuthProvider');
   }
 
   return (