@jmruthers/pace-core 0.6.9 → 0.6.11

package/dist/usePublicRouteParams-BgV6VhMi.d.ts

@@ -0,0 +1,946 @@
+import { h as Event, u as OrganisationRole, v as OrganisationPermission, S as SuperAdminContext } from './event-BfCox3N2.js';
+import * as react_hook_form from 'react-hook-form';
+import { DefaultValues } from 'react-hook-form';
+import { z } from 'zod';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { D as Database } from './database.generated-qkdoiVrJ.js';
+import { F as FileCategory, a as FileReference } from './file-reference-DU1hcawx.js';
+
+/**
+ * @file Event Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.1.0
+ *
+ * Convenience hook for accessing event context.
+ * This hook provides a simple interface for working with events.
+ *
+ * Note: This is a convenience wrapper around the EventService.
+ * For better performance, consider using useEventService directly.
+ */
+
+/**
+ * Optional event context hook that never throws.
+ * Use when a component must work with or without EventServiceProvider (e.g. PaceAppLayout).
+ *
+ * @returns `{ selectedEvent: Event | null }` — when provider is absent, `selectedEvent` is always null.
+ * @example
+ * const { selectedEvent } = useOptionalEvents();
+ * // selectedEvent is null when outside EventServiceProvider; otherwise the current selected event.
+ */
+declare function useOptionalEvents(): {
+    selectedEvent: Event | null;
+};
+interface EventContextType {
+    events: Event[];
+    selectedEvent: Event | null;
+    isLoading: boolean;
+    error: Error | null;
+    setSelectedEvent: (event: Event | null) => void;
+    refreshEvents: () => Promise<void>;
+    clearEventSelection: () => Promise<void>;
+}
+/**
+ * Hook to access event context
+ *
+ * @returns Event context with events, selected event, and helper methods
+ * @throws {Error} If used outside EventServiceProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { events, selectedEvent, setSelectedEvent } = useEvents();
+ *
+ *   return (
+ *     <nav>
+ *       <ul>
+ *         {events.map(event => (
+ *           <li key={event.id}>
+ *             <button onClick={() => setSelectedEvent(event)}>
+ *               {event.event_name}
+ *             </button>
+ *           </li>
+ *         ))}
+ *       </ul>
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */
+declare function useEvents(): EventContextType;
+
+interface UseZodFormProps<T extends z.ZodTypeAny> {
+    schema: T;
+    defaultValues?: DefaultValues<z.infer<T>>;
+    mode?: 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all';
+}
+declare function useZodForm<T extends z.ZodTypeAny>({ schema, defaultValues, mode }: UseZodFormProps<T>): react_hook_form.UseFormReturn<z.TypeOf<T>, any, z.TypeOf<T>>;
+
+/**
+ * @file useFormDialog Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.1.0
+ *
+ * Generic React hook for managing form dialog state (open/close, form data, reset behavior).
+ *
+ * @example
+ * ```ts
+ * interface ContactFormData {
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * function ContactDialog() {
+ *   const { isOpen, formData, openDialog, closeDialog, handleOpenChange } =
+ *     useFormDialog<ContactFormData>();
+ *
+ *   // Use in Dialog component
+ *   // <Dialog open={isOpen} onOpenChange={handleOpenChange}>...</Dialog>
+ * }
+ * ```
+ */
+/**
+ * Options for configuring the useFormDialog hook behavior
+ */
+interface UseFormDialogOptions {
+    /**
+     * Callback invoked when the dialog open state changes
+     * @param open - The new open state
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Whether to reset form data when the dialog closes
+     * @default true
+     */
+    resetOnClose?: boolean;
+}
+/**
+ * Return type for the useFormDialog hook
+ */
+interface UseFormDialogReturn<T = unknown> {
+    /**
+     * Current open state of the dialog
+     */
+    isOpen: boolean;
+    /**
+     * Current form data (null when dialog is closed or no data provided)
+     */
+    formData: T | null;
+    /**
+     * Open the dialog with optional form data
+     * @param data - Optional form data to populate the dialog
+     */
+    openDialog: (data?: T | null) => void;
+    /**
+     * Close the dialog
+     */
+    closeDialog: () => void;
+    /**
+     * Handler for controlled dialog components (e.g., Radix UI Dialog)
+     * @param open - The new open state
+     */
+    handleOpenChange: (open: boolean) => void;
+}
+/**
+ * Generic React hook for managing form dialog state.
+ *
+ * Provides state management for form dialogs including:
+ * - Open/close state
+ * - Form data management
+ * - Automatic reset on close (configurable)
+ * - Controlled and uncontrolled usage patterns
+ *
+ * @param options - Configuration options for the hook
+ * @returns Object containing dialog state and control functions
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const { isOpen, openDialog, closeDialog } = useFormDialog();
+ *
+ * // With form data
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ * }
+ * const { isOpen, formData, openDialog } = useFormDialog<UserData>();
+ *
+ * // Open with data
+ * openDialog({ id: '1', name: 'John' });
+ *
+ * // Controlled usage with callback
+ * const { handleOpenChange, isOpen } = useFormDialog({
+ *   onOpenChange: (open) => console.log('Dialog state:', open),
+ *   resetOnClose: false
+ * });
+ * ```
+ */
+declare function useFormDialog<T = unknown>({ onOpenChange, resetOnClose, }?: UseFormDialogOptions): UseFormDialogReturn<T>;
+
+/**
+ * @file useOrganisationPermissions Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/useOrganisationPermissions
+ * @since 0.4.0
+ *
+ * Hook for managing organisation-specific permissions and role validation.
+ * Provides secure access to user's role and permissions within organisations.
+ *
+ * @example
+ * ```tsx
+ * function OrganisationComponent() {
+ *   const {
+ *     isOrgAdmin,
+ *     canManageMembers,
+ *     userRole,
+ *     hasOrganisationAccess
+ *   } = useOrganisationPermissions();
+ *
+ *   return (
+ *     <section>
+ *       {isOrgAdmin && <AdminPanel />}
+ *       {canManageMembers && <MemberManagement />}
+ *       <p>Your role: {userRole}</p>
+ *     </section>
+ *   );
+ * }
+ *
+ * // For specific organisation
+ * function MultiOrgComponent() {
+ *   const permissions = useOrganisationPermissions('org-123');
+ *
+ *   if (!permissions.hasOrganisationAccess) {
+ *     return <main>No access to this organisation</main>;
+ *   }
+ *
+ *   return <main>Role in org-123: {permissions.userRole}</main>;
+ * }
+ * ```
+ *
+ * @security
+ * - Validates user membership in organisation
+ * - Provides role-based permission checks
+ * - Ensures secure access to organisation data
+ * - Real-time permission validation
+ */
+
+/**
+ * Return value of the useOrganisationPermissions hook.
+ * Provides organisation-specific permissions and role information.
+ */
+interface UseOrganisationPermissionsReturn {
+    /** User's role in the organisation */
+    userRole: OrganisationRole | 'no_access';
+    /** Whether user has organisation admin role */
+    isOrgAdmin: boolean;
+    /** Whether user is a super admin */
+    isSuperAdmin: boolean;
+    /** Whether user can moderate content */
+    canModerate: boolean;
+    /** Whether user can manage members */
+    canManageMembers: boolean;
+    /** Whether user can manage organisation settings */
+    canManageSettings: boolean;
+    /** Whether user can manage events */
+    canManageEvents: boolean;
+    /** Whether user has any admin privileges */
+    hasAdminPrivileges: boolean;
+    /** Whether user has access to the organisation */
+    hasOrganisationAccess: boolean;
+    /** Check if user has specific permission */
+    hasPermission: (permission: OrganisationPermission) => boolean;
+    /** Get all permissions for the user */
+    getAllPermissions: () => OrganisationPermission[];
+    /** Organisation ID being checked */
+    organisationId: string;
+}
+/**
+ * Hook to access organisation-specific permissions and roles
+ *
+ * @param orgId - Optional organisation ID. Defaults to currently selected organisation
+ * @returns Organisation permissions and role information
+ */
+declare function useOrganisationPermissions(orgId?: string): UseOrganisationPermissionsReturn;
+
+/**
+ * @file Organisation Security Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/OrganisationSecurity
+ * @since 0.4.0
+ *
+ * Security-focused hook for organisation access validation and super admin functionality.
+ * Provides utilities for validating user access to organisations and checking permissions.
+ */
+
+/**
+ * Organisation security hook interface.
+ * Provides security utilities for organisation access validation and super admin functionality.
+ */
+interface OrganisationSecurityHook {
+    superAdminContext: SuperAdminContext;
+    validateOrganisationAccess: (orgId: string) => Promise<boolean>;
+    hasMinimumRole: (minRole: string, orgId?: string) => boolean;
+    canAccessChildOrganisations: (orgId?: string) => boolean;
+    hasPermission: (permission: string, orgId?: string) => Promise<boolean>;
+    getUserPermissions: (orgId?: string) => Promise<string[]>;
+    logOrganisationAccess: (action: string, details?: Record<string, unknown>) => Promise<void>;
+    ensureOrganisationAccess: (orgId: string) => Promise<void>;
+    validateUserAccess: (userId: string, orgId: string) => Promise<boolean>;
+}
+declare const useOrganisationSecurity: () => OrganisationSecurityHook;
+
+/**
+ * @file useAppConfig Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/useAppConfig
+ * @since 0.4.0
+ *
+ * Hook for accessing app name and loading state.
+ *
+ * NOTE: Scope configuration (requires_event) is now page-level only (rbac_app_pages.scope_type).
+ * Use getPageScopeType() to determine if a specific page requires event or organisation context.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { appName, isLoading } = useAppConfig();
+ *
+ *   if (isLoading) return <p>Loading...</p>;
+ *
+ *   return <p>App: {appName}</p>;
+ * }
+ * ```
+ */
+interface UseAppConfigReturn {
+    appName: string;
+    isLoading: boolean;
+}
+/**
+ * Hook to access app configuration
+ * Works in both authenticated and public contexts
+ * @returns App configuration and loading state
+ */
+declare function useAppConfig(): UseAppConfigReturn;
+
+/**
+ * @file Event Theme Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/EventTheme
+ * @since 2.0.0
+ *
+ * Hook that automatically applies event-specific theming when an event is selected.
+ * This ensures consistent UX across all apps in the pace suite.
+ *
+ * Works in two modes:
+ * 1. Authenticated mode: Uses EventProvider context via useEvents() hook
+ * 2. Public page mode: Accepts event prop directly (no EventProvider required)
+ *
+ * @example
+ * ```tsx
+ * // Authenticated pages (with EventProvider)
+ * import { useEventTheme } from '@jmruthers/pace-core/hooks';
+ *
+ * function MyApp() {
+ *   // Automatically applies event colors when event is selected via EventProvider
+ *   useEventTheme();
+ *
+ *   return <main>Your app content</main>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Public pages (without EventProvider)
+ * import { useEventTheme } from '@jmruthers/pace-core/hooks';
+ *
+ * function PublicPageLayout({ event }) {
+ *   // Applies event colors directly from event prop
+ *   useEventTheme(event);
+ *
+ *   return <main>Public page content</main>;
+ * }
+ * ```
+ */
+
+/**
+ * Hook that automatically applies event-specific theming
+ *
+ * This hook applies event colors using the theming system. It works in two modes:
+ *
+ * **Authenticated Mode (default):**
+ * - Uses EventProvider context via useEvents() hook
+ * - Automatically watches selectedEvent changes
+ * - Used in authenticated pages with EventProvider
+ *
+ * **Public Page Mode:**
+ * - Accepts event prop directly
+ * - No EventProvider required
+ * - Used in public pages without authentication context
+ *
+ * Behavior:
+ * - Applies event colors when an event with `event_colours` is provided
+ * - Clears theming when no event is provided
+ * - Skips theme application when on the login route to prevent login screen styling
+ * - Handles cleanup and error cases gracefully
+ *
+ * @param event - Optional event object. If provided, uses this event directly (public page mode).
+ *                If not provided, uses EventProvider context via useEvents() (authenticated mode).
+ *
+ * @returns void - This is an effect hook with no return value
+ *
+ * @example
+ * ```tsx
+ * // Authenticated mode - uses EventProvider
+ * function MyApp() {
+ *   useEventTheme(); // Watches selectedEvent from EventProvider
+ *   return <main>App content</main>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Public page mode - uses event prop
+ * function PublicPageLayout({ event }) {
+ *   useEventTheme(event); // Uses event prop directly
+ *   return <main>Public content</main>;
+ * }
+ * ```
+ */
+/**
+ * Hook that automatically applies event-specific theming.
+ * Works in authenticated mode (via EventProvider) or public page mode (via event prop).
+ *
+ * @param event - Optional event object for public page mode. If not provided, uses EventProvider context.
+ */
+declare function useEventTheme(event?: Event | null): void;
+
+/**
+ * Storage utility types for pace-core
+ */
+interface StorageUploadOptions {
+    /** The app name from rbac_apps */
+    appName: string;
+    /** Organisation ID for scoping (required if userId not provided) */
+    orgId?: string;
+    /** User ID for user-scoped files (required if orgId not provided) */
+    userId?: string;
+    /** Whether the file should be publicly accessible */
+    isPublic?: boolean;
+    /** Optional tags for categorisation */
+    tags?: string[];
+    /** Optional custom path within the app/org/user structure */
+    customPath?: string;
+    /** Optional metadata to store with the file */
+    metadata?: Record<string, unknown>;
+}
+interface StorageFileMetadata {
+    mimeType: string;
+    size: number;
+    width?: number;
+    height?: number;
+    hash?: string;
+    orgId?: string;
+    userId?: string;
+    appName: string;
+    uploadedBy: string;
+    uploadedAt: string;
+    tags?: string[];
+    isPublic: boolean;
+    customMetadata?: Record<string, unknown>;
+}
+interface StorageUploadResult {
+    success: boolean;
+    path?: string;
+    publicUrl?: string;
+    metadata?: StorageFileMetadata;
+    error?: string;
+}
+/** Success payload for uploadFile when using ApiResult. */
+interface StorageUploadSuccess {
+    path: string;
+    publicUrl?: string;
+    metadata?: StorageFileMetadata;
+}
+interface StorageUrlOptions {
+    /** The app name from rbac_apps */
+    appName: string;
+    /** Organisation ID for scoping (required if userId not provided) */
+    orgId?: string;
+    /** User ID for user-scoped files (required if orgId not provided) */
+    userId?: string;
+    /** Expiry time in seconds for signed URLs (default: 3600) */
+    expiresIn?: number;
+}
+interface StorageListOptions {
+    /** The app name from rbac_apps */
+    appName: string;
+    /** Organisation ID for scoping (required if userId not provided) */
+    orgId?: string;
+    /** User ID for user-scoped files (required if orgId not provided) */
+    userId?: string;
+    /** Optional path prefix to filter by */
+    pathPrefix?: string;
+    /** Optional tags to filter by */
+    tags?: string[];
+    /** Maximum number of files to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+interface StorageFileInfo {
+    name: string;
+    path: string;
+    size: number;
+    mimeType: string;
+    lastModified: string;
+    metadata: StorageFileMetadata;
+}
+interface StorageListResult {
+    files: StorageFileInfo[];
+    totalCount: number;
+    hasMore: boolean;
+}
+interface FileSizeLimits {
+    [mimeType: string]: number;
+}
+interface StorageConfig {
+    bucketName: string;
+    fileSizeLimits: FileSizeLimits;
+    defaultFileSizeLimit: number;
+}
+
+/**
+ * @file Public Event Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for accessing public event data without authentication.
+ * Provides event information by event_code for public pages.
+ *
+ * Features:
+ * - No authentication required
+ * - Caching for performance
+ * - Error handling and loading states
+ * - TypeScript support
+ * - Automatic refetch capabilities
+ *
+ * @example
+ * ```tsx
+ * import { usePublicEvent } from '@jmruthers/pace-core';
+ *
+ * function PublicEventPage() {
+ *   const { eventCode } = usePublicRouteParams();
+ *   const { event, isLoading, error, refetch } = usePublicEvent(eventCode);
+ *
+ *   if (isLoading) return <p>Loading event...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *   if (!event) return <p>Event not found</p>;
+ *
+ *   return (
+ *     <section>
+ *       <h1>{event.event_name}</h1>
+ *       <p>Date: {event.event_date}</p>
+ *       <p>Venue: {event.event_venue}</p>
+ *     </section>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - No direct accessibility concerns (hook)
+ * - Enables accessible public event display
+ * - Supports screen reader friendly loading states
+ *
+ * @security
+ * - Only returns public-safe event data
+ * - Validates event_code before querying
+ * - No sensitive information exposed
+ * - Rate limiting applied at database level
+ *
+ * @performance
+ * - Built-in caching with TTL
+ * - Minimal re-renders with stable references
+ * - Lazy loading support
+ * - Error boundary integration
+ *
+ * @dependencies
+ * - React 19+ - Hooks and effects
+ * - @supabase/supabase-js - Database integration
+ * - Event types - Type definitions
+ */
+
+/**
+ * Return value of the usePublicEvent hook.
+ * Provides event data, loading state, error, and refetch function.
+ */
+interface UsePublicEventReturn {
+    /** The event data, null if not loaded or not found */
+    event: Event | null;
+    /** Whether the data is currently loading */
+    isLoading: boolean;
+    /** Any error that occurred during loading */
+    error: Error | null;
+    /** Function to manually refetch the data */
+    refetch: () => Promise<void>;
+}
+interface UsePublicEventOptions {
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtl?: number;
+    /** Whether to enable caching (default: true) */
+    enableCache?: boolean;
+}
+/**
+ * Hook for accessing public event data by event_code
+ *
+ * This hook provides access to public event information without requiring
+ * authentication. It includes caching, error handling, and loading states.
+ *
+ * @param eventCode - The event code to look up
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing event data, loading state, error, and refetch function
+ */
+declare function usePublicEvent(eventCode: string, options?: UsePublicEventOptions): UsePublicEventReturn;
+/**
+ * Clear all cached public event data
+ * Useful for testing or when you need to force refresh all data
+ */
+declare function clearPublicEventCache(): void;
+/**
+ * Get cache statistics for debugging
+ */
+declare function getPublicEventCacheStats(): {
+    size: number;
+    keys: string[];
+};
+
+/**
+ * @file Public File Display Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for accessing file references in public contexts without authentication.
+ * Provides file URLs and metadata for public pages.
+ *
+ * Features:
+ * - No authentication required
+ * - Only returns public files (is_public = true)
+ * - Caching for performance
+ * - Error handling and loading states
+ * - TypeScript support
+ * - Supports both single file (category) and multiple files
+ *
+ * @example
+ * ```tsx
+ * import { usePublicFileDisplay } from '@jmruthers/pace-core';
+ *
+ * function PublicFileView() {
+ *   const { fileUrl, fileReference, isLoading, error } = usePublicFileDisplay(
+ *     'event',
+ *     eventId,
+ *     organisationId,
+ *     FileCategory.EVENT_LOGOS,
+ *     { supabase }
+ *   );
+ *
+ *   if (isLoading) return <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return fileUrl ? <img src={fileUrl} alt="File" /> : null;
+ * }
+ * ```
+ */
+
+/**
+ * Return value of the usePublicFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
+interface UsePublicFileDisplayReturn {
+    /** Single file URL if category is provided and file found, null otherwise */
+    fileUrl: string | null;
+    /** Single file reference if category is provided and file found, null otherwise */
+    fileReference: FileReference | null;
+    /** Array of all file references for the record (when category not provided or for multiple files) */
+    fileReferences: FileReference[];
+    /** Map of file IDs to URLs for multiple files */
+    fileUrls: Map<string, string>;
+    /** Total count of files for the record */
+    fileCount: number;
+    /** Whether the data is currently loading */
+    isLoading: boolean;
+    /** Any error that occurred during loading */
+    error: Error | null;
+    /** Function to manually refetch the data */
+    refetch: () => Promise<void>;
+}
+interface UsePublicFileDisplayOptions {
+    /** Cache TTL in milliseconds (default: 30 minutes) */
+    cacheTtl?: number;
+    /** Whether to enable caching (default: true) */
+    enableCache?: boolean;
+    /** Supabase client instance (required) */
+    supabase: SupabaseClient<Database>;
+}
+/**
+ * Hook for accessing public file references
+ *
+ * This hook provides access to file references without requiring
+ * authentication. It only returns public files and generates public URLs.
+ *
+ * @param table_name - The table name containing the file reference
+ * @param record_id - The record ID that owns the file(s)
+ * @param organisation_id - The organisation ID for storage path
+ * @param category - Optional file category to filter by (for single file mode)
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing file data, loading state, error, and refetch function
+ */
+declare function usePublicFileDisplay(table_name: string | undefined, record_id: string | undefined, organisation_id: string | undefined, category: FileCategory | undefined, options: UsePublicFileDisplayOptions): UsePublicFileDisplayReturn;
+/**
+ * Clear all cached public file data
+ * Useful for testing or when you need to force refresh all data
+ */
+declare function clearPublicFileDisplayCache(): void;
+/**
+ * Get cache statistics for debugging
+ */
+declare function getPublicFileDisplayCacheStats(): {
+    size: number;
+    keys: string[];
+};
+
+/**
+ * @file Public Event Logo Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for accessing public event logo URLs without authentication.
+ * Provides logo URLs with fallback handling for public pages.
+ *
+ * Features:
+ * - No authentication required
+ * - Automatic fallback to event initials
+ * - Caching for performance
+ * - Error handling and loading states
+ * - TypeScript support
+ * - Image validation
+ *
+ * @example
+ * ```tsx
+ * import { usePublicEventLogo } from '@jmruthers/pace-core';
+ *
+ * function EventHeader() {
+ *   const { logoUrl, fallbackText, isLoading, error } = usePublicEventLogo(
+ *     eventId,
+ *     eventName,
+ *     organisationId
+ *   );
+ *
+ *   if (isLoading) return <p>Loading logo...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return (
+ *     <section>
+ *       {logoUrl ? (
+ *         <img src={logoUrl} alt={`${eventName} logo`} />
+ *       ) : (
+ *         <p className="logo-fallback">{fallbackText}</p>
+ *       )}
+ *     </section>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - No direct accessibility concerns (hook)
+ * - Enables accessible logo display with proper alt text
+ * - Supports screen reader friendly fallbacks
+ *
+ * @security
+ * - Only returns public-safe logo URLs
+ * - Validates image existence before returning URL
+ * - No sensitive information exposed
+ * - Rate limiting applied at storage level
+ *
+ * @performance
+ * - Built-in caching with TTL
+ * - Image validation and optimization
+ * - Minimal re-renders with stable references
+ * - Lazy loading support
+ *
+ * @dependencies
+ * - React 19+ - Hooks and effects
+ * - @supabase/supabase-js - Storage integration
+ * - Event types - Type definitions
+ */
+
+/**
+ * Return value of the usePublicEventLogo hook.
+ * Provides logo URL, fallback text, loading state, error, and refetch function.
+ */
+interface UsePublicEventLogoReturn {
+    /** The logo URL if available, null if not found or error */
+    logoUrl: string | null;
+    /** Fallback text (event initials) if no logo is available */
+    fallbackText: string;
+    /** Whether the logo is currently loading */
+    isLoading: boolean;
+    /** Any error that occurred during loading */
+    error: Error | null;
+    /** Function to manually refetch the logo */
+    refetch: () => Promise<void>;
+}
+interface UsePublicEventLogoOptions {
+    /** Cache TTL in milliseconds (default: 30 minutes) */
+    cacheTtl?: number;
+    /** Whether to enable caching (default: true) */
+    enableCache?: boolean;
+    /** Whether to validate image existence (default: true) */
+    validateImage?: boolean;
+    /** Custom fallback text generator */
+    generateFallbackText?: (eventName: string) => string;
+    /** Supabase client instance (required) */
+    supabase: SupabaseClient<Database>;
+}
+/**
+ * Hook for accessing public event logo URLs
+ *
+ * This hook provides access to event logo URLs without requiring
+ * authentication. It includes fallback handling and image validation.
+ *
+ * @param eventId - The event ID to fetch logo for
+ * @param eventName - The event name for fallback text generation
+ * @param organisationId - The organisation ID for storage path
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing logo URL, fallback text, loading state, error, and refetch function
+ */
+declare function usePublicEventLogo(eventId: string | undefined, eventName: string | undefined, organisationId: string | undefined, options: UsePublicEventLogoOptions): UsePublicEventLogoReturn;
+/**
+ * Clear all cached public logo data
+ * Useful for testing or when you need to force refresh all data
+ */
+declare function clearPublicLogoCache(): void;
+/**
+ * Get cache statistics for debugging
+ */
+declare function getPublicLogoCacheStats(): {
+    size: number;
+    keys: string[];
+};
+
+/**
+ * @file Public Route Params Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for extracting and validating public route parameters.
+ * Provides event code extraction and validation for public pages.
+ *
+ * Features:
+ * - URL parameter extraction
+ * - Event code validation
+ * - TypeScript support
+ * - Error handling
+ * - Route pattern support
+ *
+ * @example
+ * ```tsx
+ * import { usePublicRouteParams } from '@jmruthers/pace-core';
+ *
+ * function PublicEventPage() {
+ *   const { eventCode, eventId, event, error, isLoading } = usePublicRouteParams();
+ *
+ *   if (isLoading) return <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *   if (!event) return <p>Event not found</p>;
+ *
+ *   return (
+ *     <section>
+ *       <h1>{event.event_name}</h1>
+ *       <p>Event Code: {eventCode}</p>
+ *     </section>
+ *   );
+ * }
+ * ```
+ *
+ * @accessibility
+ * - No direct accessibility concerns (hook)
+ * - Enables accessible route parameter handling
+ * - Supports screen reader friendly error states
+ *
+ * @security
+ * - Validates event codes before processing
+ * - Sanitizes URL parameters
+ * - No sensitive information exposed
+ * - Rate limiting applied at route level
+ *
+ * @performance
+ * - Minimal re-renders with stable references
+ * - Efficient parameter extraction
+ * - Caching integration
+ *
+ * @dependencies
+ * - React 19+ - Hooks and effects
+ * - React Router - URL parameter extraction
+ * - Event types - Type definitions
+ */
+
+/**
+ * Return value of the usePublicRouteParams hook.
+ * Provides event code, event ID, event data, loading state, error, and refetch function.
+ */
+interface UsePublicRouteParamsReturn {
+    /** The event code from the URL */
+    eventCode: string | null;
+    /** The event ID (resolved from event code) */
+    eventId: string | null;
+    /** The full event object */
+    event: Event | null;
+    /** Whether the route parameters are being processed */
+    isLoading: boolean;
+    /** Any error that occurred during processing */
+    error: Error | null;
+    /** Function to manually refetch the event data */
+    refetch: () => Promise<void>;
+}
+interface UsePublicRouteParamsOptions {
+    /** Whether to automatically fetch event data (default: true) */
+    fetchEventData?: boolean;
+    /** Custom event code parameter name (default: 'eventCode') */
+    eventCodeParam?: string;
+    /** Whether to validate event code format (default: true) */
+    validateEventCode?: boolean;
+}
+/**
+ * Hook for extracting and validating public route parameters
+ *
+ * This hook extracts event codes from URL parameters and optionally
+ * fetches the corresponding event data. It provides validation and
+ * error handling for public routes.
+ *
+ * @param options - Configuration options for behavior
+ * @returns Object containing route parameters, event data, loading state, error, and refetch function
+ */
+declare function usePublicRouteParams(options?: UsePublicRouteParamsOptions): UsePublicRouteParamsReturn;
+/**
+ * Hook for extracting just the event code without fetching event data
+ * Useful when you only need the event code and will fetch data separately
+ */
+declare function usePublicEventCode(eventCodeParam?: string): {
+    eventCode: string | null;
+    error: Error | null;
+};
+/**
+ * Utility function to generate public route paths
+ */
+declare function generatePublicRoutePath(eventCode: string, pageName?: string): string;
+/**
+ * Utility function to extract event code from a public route path
+ * Supports 2-50 character event codes
+ */
+declare function extractEventCodeFromPath(path: string): string | null;
+
+export { generatePublicRoutePath as A, extractEventCodeFromPath as B, type UsePublicEventReturn as C, type UsePublicEventOptions as D, type EventContextType as E, type UsePublicFileDisplayReturn as F, type UsePublicFileDisplayOptions as G, type UsePublicEventLogoReturn as H, type UsePublicEventLogoOptions as I, type UsePublicRouteParamsReturn as J, type FileSizeLimits as K, type StorageConfig as L, type StorageFileMetadata as M, type StorageUploadSuccess as N, type OrganisationSecurityHook as O, type StorageUrlOptions as P, type StorageUploadOptions as S, type UseOrganisationPermissionsReturn as U, type StorageUploadResult as a, type StorageListOptions as b, type StorageListResult as c, type StorageFileInfo as d, useOptionalEvents as e, useEventTheme as f, useOrganisationPermissions as g, useOrganisationSecurity as h, useZodForm as i, useFormDialog as j, type UseFormDialogOptions as k, type UseFormDialogReturn as l, useAppConfig as m, type UseAppConfigReturn as n, usePublicEvent as o, clearPublicEventCache as p, getPublicEventCacheStats as q, usePublicFileDisplay as r, clearPublicFileDisplayCache as s, getPublicFileDisplayCacheStats as t, useEvents as u, usePublicEventLogo as v, clearPublicLogoCache as w, getPublicLogoCacheStats as x, usePublicRouteParams as y, usePublicEventCode as z };