@jmruthers/pace-core 0.6.4 → 0.6.6

package/src/hooks/useEventTheme.ts

@@ -20,7 +20,7 @@
  *   // Automatically applies event colors when event is selected via EventProvider
  *   useEventTheme();
  *   
- *   return <div>Your app content</div>;
+ *   return <main>Your app content</main>;
  * }
  * ```
  * 
@@ -33,14 +33,14 @@
  *   // Applies event colors directly from event prop
  *   useEventTheme(event);
  *   
- *   return <div>Public page content</div>;
+ *   return <main>Public page content</main>;
  * }
  * ```
  */
 
-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';
@@ -79,7 +79,7 @@ const log = createLogger('useEventTheme');
  * // Authenticated mode - uses EventProvider
  * function MyApp() {
  *   useEventTheme(); // Watches selectedEvent from EventProvider
- *   return <div>App content</div>;
+ *   return <main>App content</main>;
  * }
  * ```
  * 
@@ -88,7 +88,7 @@ const log = createLogger('useEventTheme');
  * // Public page mode - uses event prop
  * function PublicPageLayout({ event }) {
  *   useEventTheme(event); // Uses event prop directly
- *   return <div>Public content</div>;
+ *   return <main>Public content</main>;
  * }
  * ```
  */
@@ -99,30 +99,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

package/src/hooks/useEvents.ts

@@ -37,13 +37,17 @@ export interface EventContextType {
  *   const { events, selectedEvent, setSelectedEvent } = useEvents();
  *   
  *   return (
- *     <div>
- *       {events.map(event => (
- *         <button key={event.id} onClick={() => setSelectedEvent(event)}>
- *           {event.event_name}
- *         </button>
- *       ))}
- *     </div>
+ *     <nav>
+ *       <ul>
+ *         {events.map(event => (
+ *           <li key={event.id}>
+ *             <button onClick={() => setSelectedEvent(event)}>
+ *               {event.event_name}
+ *             </button>
+ *           </li>
+ *         ))}
+ *       </ul>
+ *     </nav>
  *   );
  * }
  * ```

package/src/hooks/useKeyboardShortcuts.ts

@@ -86,7 +86,7 @@ function matchesKeyCombo(event: KeyboardEvent, combo: string): boolean {
  * 
  *   useKeyboardShortcuts(shortcuts);
  *   
- *   return <div>Content</div>;
+ *   return <main>Content</main>;
  * }
  * ```
  */

package/src/hooks/useOrganisationPermissions.ts

@@ -18,11 +18,11 @@
  *   } = useOrganisationPermissions();
  *   
  *   return (
- *     <div>
+ *     <section>
  *       {isOrgAdmin && <AdminPanel />}
  *       {canManageMembers && <MemberManagement />}
  *       <p>Your role: {userRole}</p>
- *     </div>
+ *     </section>
  *   );
  * }
  * 
@@ -31,10 +31,10 @@
  *   const permissions = useOrganisationPermissions('org-123');
  *   
  *   if (!permissions.hasOrganisationAccess) {
- *     return <div>No access to this organisation</div>;
+ *     return <main>No access to this organisation</main>;
  *   }
  *   
- *   return <div>Role in org-123: {permissions.userRole}</div>;
+ *   return <main>Role in org-123: {permissions.userRole}</main>;
  * }
  * ```
  *
@@ -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/useOrganisations.ts

@@ -26,14 +26,20 @@ import { Organisation, OrganisationMembership, OrganisationContextType } from '.
  *   const { selectedOrganisation, organisations, switchOrganisation } = useOrganisations();
  *   
  *   return (
- *     <div>
+ *     <main>
  *       <h1>Current Organisation: {selectedOrganisation.display_name}</h1>
- *       {organisations.map(org => (
- *         <button key={org.id} onClick={() => switchOrganisation(org.id)}>
- *           {org.display_name}
- *         </button>
- *       ))}
- *     </div>
+ *       <nav>
+ *         <ul>
+ *           {organisations.map(org => (
+ *             <li key={org.id}>
+ *               <button onClick={() => switchOrganisation(org.id)}>
+ *                 {org.display_name}
+ *               </button>
+ *             </li>
+ *           ))}
+ *         </ul>
+ *       </nav>
+ *     </main>
  *   );
  * }
  * ```

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

@@ -101,7 +101,6 @@ export type { ProgressProps } from './components/Progress';
 export {
   Dialog,
   DialogPortal,
-  DialogOverlay,
   DialogTrigger,
   DialogClose,
   DialogContent,
@@ -111,6 +110,17 @@ export {
   DialogTitle,
   DialogDescription,
 } from './components/Dialog/Dialog';
+export type {
+  DialogProps,
+  DialogTriggerProps,
+  DialogContentProps,
+  DialogPortalProps,
+  DialogCloseProps,
+  DialogHeaderProps,
+  DialogFooterProps,
+  DialogBodyProps,
+  DialogSize
+} from './components/Dialog/Dialog';
 
 // Dropdown Menu exports
 // DropdownMenu components have been merged into Select components
@@ -202,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';
@@ -250,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';