@jmruthers/pace-core 0.5.54 → 0.5.56

package/docs/api-reference/components.md

@@ -1240,169 +1240,6 @@ import { PasswordChangeForm } from '@jmruthers/pace-core';
 />
 ```
 
-## Print Components
-
-PACE Core includes a comprehensive set of print-optimized components for creating reports and documents.
-
-### PrintLayout
-
-The main container for print documents with A4 optimization.
-
-```typescript
-interface PrintLayoutProps {
-  children: React.ReactNode;
-  orientation?: 'portrait' | 'landscape';
-  pageSize?: 'A4' | 'A3' | 'Letter';
-  className?: string;
-}
-```
-
-### PrintHeader
-
-Document header with title and branding.
-
-```typescript
-interface PrintHeaderProps {
-  title: string;
-  subtitle?: string;
-  branding?: {
-    companyName: string;
-    projectName?: string;
-    logo?: string;
-  };
-  className?: string;
-}
-```
-
-### PrintDataTable
-
-Print-optimized data table with pagination and styling.
-
-```typescript
-interface PrintDataTableProps<TData> {
-  data: TData[];
-  columns: PrintColumn<TData>[];
-  title?: string;
-  showPagination?: boolean;
-  pageSize?: number;
-  className?: string;
-}
-```
-
-### PrintCard
-
-Print-optimized card component.
-
-```typescript
-interface PrintCardProps {
-  children: React.ReactNode;
-  title?: string;
-  className?: string;
-}
-```
-
-### PrintSection
-
-Section divider for print documents.
-
-```typescript
-interface PrintSectionProps {
-  children: React.ReactNode;
-  title?: string;
-  level?: 1 | 2 | 3;
-  className?: string;
-}
-```
-
-### PrintGrid
-
-Grid layout for print documents.
-
-```typescript
-interface PrintGridProps {
-  children: React.ReactNode;
-  columns?: 1 | 2 | 3 | 4;
-  gap?: 'sm' | 'md' | 'lg';
-  className?: string;
-}
-```
-
-### PrintButton
-
-Print-optimized button (appears as text in print).
-
-```typescript
-interface PrintButtonProps {
-  children: React.ReactNode;
-  onClick?: () => void;
-  className?: string;
-}
-```
-
-### PrintPageBreak
-
-Forces a page break in print documents.
-
-```tsx
-<PrintPageBreak />
-```
-
-### PrintDivider
-
-Visual divider for print documents.
-
-```tsx
-<PrintDivider />
-```
-
-### Print Usage Example
-
-```tsx
-import {
-  PrintLayout,
-  PrintHeader,
-  PrintDataTable,
-  PrintCard,
-  PrintSection,
-  PrintPageBreak
-} from '@jmruthers/pace-core';
-
-function ReportPage() {
-  return (
-    <PrintLayout orientation="portrait" pageSize="A4">
-      <PrintHeader
-        title="Monthly Report"
-        subtitle="Q4 2024"
-        branding={{
-          companyName: "Your Company",
-          projectName: "Analytics Dashboard"
-        }}
-      />
-      
-      <PrintSection title="Executive Summary" level={1}>
-        <PrintCard title="Key Metrics">
-          <p>Total revenue: $1,234,567</p>
-          <p>Growth rate: 15.3%</p>
-        </PrintCard>
-      </PrintSection>
-      
-      <PrintPageBreak />
-      
-      <PrintSection title="Detailed Data" level={1}>
-        <PrintDataTable
-          data={reportData}
-          columns={columns}
-          title="Revenue by Region"
-          showPagination={true}
-          pageSize={20}
-        />
-      </PrintSection>
-    </PrintLayout>
-  );
-}
-```
-
-For detailed print component usage, see [Print Components Guide](../print-components/README.md).
 
 ## Public Page Components
 
@@ -1572,6 +1409,147 @@ import { ErrorBoundary } from '@jmruthers/pace-core';
 ```
 
 
+## File Management Components
+
+### FileUpload
+
+A comprehensive file upload component with drag-and-drop support, validation, and progress tracking.
+
+#### Props
+
+```typescript
+interface FileUploadProps {
+  supabase: SupabaseClient;
+  appName: string;
+  orgId: string;
+  onUploadComplete?: (fileRef: FileReference) => void;
+  onUploadStart?: (file: File) => void;
+  accept?: string;
+  maxSize?: number;
+  multiple?: boolean;
+  disabled?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+}
+```
+
+#### Usage
+
+```tsx
+import { FileUpload, FileCategory } from '@jmruthers/pace-core';
+
+function MyFileUpload() {
+  const handleUpload = (fileRef: FileReference) => {
+    console.log('File uploaded:', fileRef);
+  };
+
+  return (
+    <FileUpload
+      supabase={supabase}
+      appName="my-app"
+      orgId={organisationId}
+      onUploadComplete={handleUpload}
+      accept="image/*"
+      maxSize={2 * 1024 * 1024} // 2MB
+    >
+      <div className="border-2 border-dashed border-main-300 rounded-lg p-8 text-center">
+        <p>Drag and drop files here or click to browse</p>
+      </div>
+    </FileUpload>
+  );
+}
+```
+
+For detailed implementation, see [File Upload & Storage Guide](../implementation-guides/file-upload-storage.md).
+
+### InactivityWarningModal
+
+A modal component that displays inactivity warnings with countdown timer and action buttons.
+
+#### Props
+
+```typescript
+interface InactivityWarningModalProps {
+  isOpen: boolean;
+  timeRemaining: number;
+  onStayActive: () => void;
+  onSignOut: () => void;
+  title?: string;
+  message?: string;
+  stayActiveText?: string;
+  signOutText?: string;
+  className?: string;
+}
+```
+
+#### Usage
+
+```tsx
+import { InactivityWarningModal, useInactivityTracker } from '@jmruthers/pace-core';
+
+function MyApp() {
+  const { showWarning, timeRemaining, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 30 * 60 * 1000,
+    warnBeforeMs: 5 * 60 * 1000
+  });
+
+  return (
+    <div>
+      <h1>My App</h1>
+      
+      <InactivityWarningModal
+        isOpen={showWarning}
+        timeRemaining={timeRemaining}
+        onStayActive={resetActivity}
+        onSignOut={() => signOut()}
+        title="Session Timeout Warning"
+        message="You will be signed out due to inactivity."
+      />
+    </div>
+  );
+}
+```
+
+For detailed implementation, see [Inactivity Tracking Guide](../implementation-guides/inactivity-tracking.md).
+
+### EventLogo
+
+A component for displaying event logos with automatic loading and caching.
+
+#### Props
+
+```typescript
+interface EventLogoProps {
+  eventId: string;
+  size?: 'small' | 'medium' | 'large' | 'xlarge';
+  variant?: 'default' | 'square' | 'wide';
+  className?: string;
+  fallback?: React.ReactNode;
+  showLoading?: boolean;
+}
+```
+
+#### Usage
+
+```tsx
+import { EventLogo } from '@jmruthers/pace-core';
+
+function EventHeader({ eventId }: { eventId: string }) {
+  return (
+    <div className="text-center">
+      <EventLogo 
+        eventId={eventId} 
+        size="large"
+        className="mx-auto mb-4"
+      />
+      <h1>Event Name</h1>
+    </div>
+  );
+}
+```
+
+For detailed implementation, see [Public Pages Advanced Guide](../implementation-guides/public-pages-advanced.md).
+
 ## Component Styling
 
 All components use Tailwind CSS for styling and support:

package/docs/api-reference/hooks.md

@@ -614,6 +614,353 @@ function PublicComponent() {
 
 For detailed public page implementation, see [Public Pages Guide](../implementation-guides/public-pages.md).
 
+## Inactivity Tracking Hooks
+
+### useInactivityTracker
+
+Hook for tracking user inactivity with configurable timeouts and callbacks.
+
+```typescript
+interface UseInactivityTrackerOptions {
+  idleTimeoutMs?: number;
+  warnBeforeMs?: number;
+  onIdle?: () => void;
+  onWarning?: () => void;
+  onActivity?: () => void;
+  events?: string[];
+  throttleMs?: number;
+  enableCrossTabSync?: boolean;
+  storageKey?: string;
+  debug?: boolean;
+}
+
+interface UseInactivityTrackerReturn {
+  isIdle: boolean;
+  timeRemaining: number;
+  showWarning: boolean;
+  resetActivity: () => void;
+  startTracking: () => void;
+  stopTracking: () => void;
+  getActivityStatus: () => {
+    isIdle: boolean;
+    timeRemaining: number;
+    lastActivity: number;
+  };
+}
+
+function useInactivityTracker(options?: UseInactivityTrackerOptions): UseInactivityTrackerReturn;
+```
+
+**Usage:**
+```tsx
+import { useInactivityTracker } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { isIdle, timeRemaining, showWarning, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 30 * 60 * 1000, // 30 minutes
+    warnBeforeMs: 5 * 60 * 1000,   // 5 minutes warning
+    onIdle: () => {
+      console.log('User is idle');
+      signOut();
+    },
+    onWarning: () => {
+      console.log('Warning: User will be idle soon');
+    }
+  });
+
+  return (
+    <div>
+      <p>Idle: {isIdle ? 'Yes' : 'No'}</p>
+      <p>Time remaining: {Math.floor(timeRemaining / 1000)}s</p>
+      {showWarning && (
+        <div>
+          <p>You will be signed out soon due to inactivity.</p>
+          <button onClick={resetActivity}>Stay Active</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+For detailed implementation, see [Inactivity Tracking Guide](../implementation-guides/inactivity-tracking.md).
+
+## Organisation Security Hooks
+
+### useOrganisationSecurity
+
+Hook for organisation-level security operations and super admin functionality.
+
+```typescript
+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?: any) => Promise<void>;
+  ensureOrganisationAccess: (orgId: string) => Promise<void>;
+  validateUserAccess: (userId: string, orgId: string) => Promise<boolean>;
+}
+
+interface SuperAdminContext {
+  isSuperAdmin: boolean;
+  context: 'organisation' | 'event' | 'global';
+  bypassEnabled: boolean;
+  elevatedPermissions: string[];
+}
+
+function useOrganisationSecurity(): OrganisationSecurityHook;
+```
+
+**Usage:**
+```tsx
+import { useOrganisationSecurity } from '@jmruthers/pace-core';
+
+function SecureComponent() {
+  const {
+    superAdminContext,
+    validateOrganisationAccess,
+    hasPermission,
+    logOrganisationAccess
+  } = useOrganisationSecurity();
+
+  const handleSecureAction = async () => {
+    try {
+      const hasAccess = await validateOrganisationAccess(organisationId);
+      if (!hasAccess) {
+        throw new Error('Access denied');
+      }
+
+      const canEdit = await hasPermission('update:users', organisationId);
+      if (!canEdit) {
+        throw new Error('Insufficient permissions');
+      }
+
+      await logOrganisationAccess('user_update', { userId, organisationId });
+      // Perform secure action
+    } catch (error) {
+      console.error('Security check failed:', error);
+    }
+  };
+
+  return (
+    <div>
+      <p>Super Admin: {superAdminContext.isSuperAdmin ? 'Yes' : 'No'}</p>
+      <button onClick={handleSecureAction}>Perform Secure Action</button>
+    </div>
+  );
+}
+```
+
+For detailed implementation, see [Organisation Security Guide](../implementation-guides/organisation-security.md).
+
+## Storage Hooks
+
+### useStorage
+
+Hook for file storage operations with Supabase.
+
+```typescript
+interface UseStorageOptions {
+  bucket?: string;
+  folder?: string;
+  maxFileSize?: number;
+  allowedTypes?: string[];
+}
+
+interface UseStorageReturn {
+  uploadFile: (file: File, path?: string) => Promise<string>;
+  downloadFile: (path: string) => Promise<Blob>;
+  deleteFile: (path: string) => Promise<void>;
+  getPublicUrl: (path: string) => string;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+function useStorage(options?: UseStorageOptions): UseStorageReturn;
+```
+
+**Usage:**
+```tsx
+import { useStorage } from '@jmruthers/pace-core';
+
+function FileUpload() {
+  const { uploadFile, isLoading, error } = useStorage({
+    bucket: 'my-bucket',
+    folder: 'uploads',
+    maxFileSize: 5 * 1024 * 1024, // 5MB
+    allowedTypes: ['image/jpeg', 'image/png', 'application/pdf']
+  });
+
+  const handleFileUpload = async (file: File) => {
+    try {
+      const url = await uploadFile(file);
+      console.log('File uploaded:', url);
+    } catch (err) {
+      console.error('Upload failed:', err);
+    }
+  };
+
+  return (
+    <div>
+      <input 
+        type="file" 
+        onChange={(e) => e.target.files?.[0] && handleFileUpload(e.target.files[0])}
+        disabled={isLoading}
+      />
+      {isLoading && <div>Uploading...</div>}
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+### useFileUpload
+
+Hook for file upload operations with progress tracking.
+
+```typescript
+interface UseFileUploadOptions {
+  onProgress?: (progress: number) => void;
+  onSuccess?: (url: string) => void;
+  onError?: (error: Error) => void;
+}
+
+interface UseFileUploadReturn {
+  uploadFile: (file: File, path?: string) => Promise<string>;
+  uploadProgress: number;
+  isUploading: boolean;
+  error: Error | null;
+  reset: () => void;
+}
+
+function useFileUpload(options?: UseFileUploadOptions): UseFileUploadReturn;
+```
+
+**Usage:**
+```tsx
+import { useFileUpload } from '@jmruthers/pace-core';
+
+function FileUploadWithProgress() {
+  const { uploadFile, uploadProgress, isUploading, error, reset } = useFileUpload({
+    onProgress: (progress) => console.log(`Upload progress: ${progress}%`),
+    onSuccess: (url) => console.log('Upload successful:', url),
+    onError: (error) => console.error('Upload failed:', error)
+  });
+
+  const handleFileUpload = async (file: File) => {
+    try {
+      await uploadFile(file, `uploads/${file.name}`);
+    } catch (err) {
+      console.error('Upload failed:', err);
+    }
+  };
+
+  return (
+    <div>
+      <input 
+        type="file" 
+        onChange={(e) => e.target.files?.[0] && handleFileUpload(e.target.files[0])}
+        disabled={isUploading}
+      />
+      {isUploading && (
+        <div>
+          <div>Uploading... {uploadProgress}%</div>
+          <div className="w-full bg-sec-200 rounded-full h-2">
+            <div 
+              className="bg-main-600 h-2 rounded-full transition-all duration-300"
+              style={{ width: `${uploadProgress}%` }}
+            />
+          </div>
+        </div>
+      )}
+      {error && (
+        <div>
+          <div>Error: {error.message}</div>
+          <button onClick={reset}>Try Again</button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+For detailed implementation, see [File Upload & Storage Guide](../implementation-guides/file-upload-storage.md).
+
+## App Configuration Hooks
+
+### useAppConfig
+
+Hook for accessing and managing app configuration.
+
+```typescript
+interface UseAppConfigReturn {
+  config: AppConfig | null;
+  isLoading: boolean;
+  error: Error | null;
+  updateConfig: (updates: Partial<AppConfig>) => Promise<void>;
+  resetConfig: () => Promise<void>;
+}
+
+interface AppConfig {
+  appName: string;
+  appId: string;
+  version: string;
+  environment: 'development' | 'staging' | 'production';
+  features: Record<string, boolean>;
+  settings: Record<string, any>;
+}
+
+function useAppConfig(): UseAppConfigReturn;
+```
+
+**Usage:**
+```tsx
+import { useAppConfig } from '@jmruthers/pace-core';
+
+function AppSettings() {
+  const { config, isLoading, error, updateConfig } = useAppConfig();
+
+  const handleToggleFeature = async (featureName: string) => {
+    if (!config) return;
+    
+    await updateConfig({
+      features: {
+        ...config.features,
+        [featureName]: !config.features[featureName]
+      }
+    });
+  };
+
+  if (isLoading) return <div>Loading configuration...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!config) return <div>No configuration available</div>;
+
+  return (
+    <div>
+      <h2>App Configuration</h2>
+      <p>App Name: {config.appName}</p>
+      <p>Version: {config.version}</p>
+      <p>Environment: {config.environment}</p>
+      
+      <h3>Features</h3>
+      {Object.entries(config.features).map(([name, enabled]) => (
+        <label key={name}>
+          <input
+            type="checkbox"
+            checked={enabled}
+            onChange={() => handleToggleFeature(name)}
+          />
+          {name}
+        </label>
+      ))}
+    </div>
+  );
+}
+```
+
 ## Hook Testing
 
 All hooks include comprehensive testing: