@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/components/FileDisplay/FileDisplay.tsx

@@ -1,63 +1,21 @@
-import React, { useState, useEffect, useCallback, useRef, useContext, useMemo } from 'react';
-import { FileText, ExternalLink } from 'lucide-react';
+import React, { useState, useEffect, useContext } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
 import { FileReference, FileCategory } from '../../types/file-reference';
-import { usePublicFileDisplay } from '../../hooks/public/usePublicFileDisplay';
-import { useFileDisplay } from '../../hooks/useFileDisplay';
+import { usePublicFileDisplay } from './usePublicFileDisplay';
+import { useFileDisplay } from './useFileDisplay';
 import { useFileUrl } from '../../hooks/useFileUrl';
-import { PublicPageContext, useIsPublicPage } from '../PublicLayout/PublicPageProvider';
+import { PublicPageContext } from '../PublicLayout/PublicPageContext';
+import { useIsPublicPage } from '../PublicLayout/usePublicPageContext';
 import { useUnifiedAuth } from '../../providers/services/UnifiedAuthProvider';
-import { Dialog, DialogContent, DialogHeader, DialogBody, DialogFooter } from '../Dialog/Dialog';
-import { Button } from '../Button/Button';
-import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import { FileDisplayContent } from './FileDisplayContent';
+import { getFallbackClasses } from './fallbackUtils';
 import { logger } from '../../utils/core/logger';
 
-/**
- * Size classes for fallback display
- */
-const fallbackSizeClasses = {
-  xs: 'size-4 text-xs',
-  sm: 'size-6 text-sm',
-  md: 'size-8 text-base',
-  lg: 'size-12 text-lg',
-  xl: 'size-16 text-xl',
-  '2xl': 'size-20 text-2xl'
-};
-
-/**
- * Base classes for fallback display
- */
-const fallbackBaseClasses = 'size-full grid place-items-center text-center text-sec-600 font-semibold';
-
-/**
- * Helper function to compute fallback classes for a given size
- */
-function getFallbackClasses(size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' = 'md'): string {
-  const sizeClass = fallbackSizeClasses[size];
-  return `${fallbackBaseClasses} ${sizeClass}`.trim();
-}
-
-/**
- * Default fallback text generator - extracts initials from file name
- */
-function defaultGenerateFallbackText(fileName?: string): string {
-  if (!fileName) return 'FL';
-  
-  // Extract initials from file name (without extension)
-  const baseName = fileName.replace(/\.[^/.]+$/, '');
-  const words = baseName.split(/[\s\-_]+/);
-  
-  if (words.length === 0) return 'FL';
-  
-  return words
-    .map(word => word.charAt(0).toUpperCase())
-    .join('')
-    .substring(0, 3); // Max 3 characters
-}
-
 export interface FileDisplayProps {
   table_name: string;
   record_id: string;
-  /** 
+  /**
    * Optional organisation ID. When not provided (undefined), the component will automatically
    * search for files in both user-scoped (organisation_id = null) and organisation-scoped contexts.
    * If both types of files exist, organisation-scoped files are preferred.
@@ -86,9 +44,9 @@ export interface FileDisplayProps {
   fallbackSourceText?: string;
   /** Size variant for fallback display (only applies when showFallback is true) */
   fallbackSize?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
-  /** 
-   * Enable children rendering in displayOnly mode. When true, uses standard display path 
-   * (with children support) even if showDelete is false. The delete button will only appear 
+  /**
+   * Enable children rendering in displayOnly mode. When true, uses standard display path
+   * (with children support) even if showDelete is false. The delete button will only appear
    * if showDelete is also true.
    */
   enableChildren?: boolean;
@@ -96,540 +54,6 @@ export interface FileDisplayProps {
   showMetadata?: boolean;
 }
 
-// Shared rendering logic for file display
-interface FileDisplayContentProps {
-  isLoading: boolean;
-  error: string | Error | null;
-  fileUrl: string | null;
-  fileReference: FileReference | null;
-  fileReferences: FileReference[];
-  fileUrls: Map<string, string>;
-  fileCount: number;
-  category: FileCategory | undefined;
-  displayOnly: boolean;
-  showDelete: boolean;
-  className: string;
-  imgClassName?: string;
-  children?: React.ReactNode;
-  onDelete?: () => Promise<void>;
-  clearError?: () => void;
-  organisation_id: string | undefined;
-  loadingComponent?: React.ComponentType;
-  errorComponent?: React.ComponentType<{ error: Error | string | null; retry?: () => void }>;
-  showFallback?: boolean;
-  generateFallbackText?: (fileName?: string) => string;
-  fallbackText?: string;
-  fallbackSourceText?: string;
-  fallbackSize?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
-  enableChildren?: boolean;
-  showMetadata?: boolean;
-}
-
-const FileDisplayContent = React.memo(function FileDisplayContent({
-  isLoading,
-  error,
-  fileUrl,
-  fileReference,
-  fileReferences,
-  fileUrls,
-  fileCount,
-  category,
-  displayOnly,
-  showDelete,
-  className,
-  imgClassName,
-  children,
-  onDelete,
-  clearError,
-  organisation_id,
-  loadingComponent: LoadingComponent,
-  errorComponent: ErrorComponent,
-  showFallback = false,
-  generateFallbackText = defaultGenerateFallbackText,
-  fallbackText,
-  fallbackSourceText,
-  fallbackSize = 'md',
-  enableChildren = false,
-  showMetadata = true
-}: FileDisplayContentProps) {
-  const [imageError, setImageError] = useState(false);
-  const [internalFileUrls, setInternalFileUrls] = useState<Map<string, string>>(new Map(fileUrls));
-  const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
-  const fileReferencesRef = useRef<FileReference[]>([]);
-  const imgRef = useRef<HTMLImageElement | null>(null);
-  const currentSrcRef = useRef<string | null>(null);
-  const isImageLoadingRef = useRef(false);
-
-  // Stabilize fileUrl to prevent unnecessary image reloads
-  // This prevents NS_BINDING_ABORTED errors when the component re-renders
-  const stableFileUrl = useMemo(() => fileUrl, [fileUrl]);
-
-  // Track when image starts loading to prevent cancellation
-  const handleImageLoadStart = useCallback(() => {
-    isImageLoadingRef.current = true;
-    if (stableFileUrl) {
-      currentSrcRef.current = stableFileUrl;
-    }
-  }, [stableFileUrl]);
-
-  // Track when image finishes loading
-  const handleImageLoad = useCallback(() => {
-    isImageLoadingRef.current = false;
-    if (stableFileUrl) {
-      currentSrcRef.current = stableFileUrl;
-    }
-  }, [stableFileUrl]);
-
-  // Compute fallback text
-  const computedFallbackText = useMemo(() => {
-    if (fallbackText) return fallbackText;
-    // Use fallbackSourceText if provided, otherwise fall back to filename
-    const sourceText = fallbackSourceText ?? fileReference?.file_metadata?.fileName;
-    return generateFallbackText(sourceText);
-  }, [fallbackText, fallbackSourceText, fileReference, generateFallbackText]);
-
-  // Compute fallback classes
-  const fallbackClasses = useMemo(() => {
-    return getFallbackClasses(fallbackSize);
-  }, [fallbackSize]);
-
-  // Sync fileUrls prop with internal state
-  // Track file references to detect when they change and sync URLs
-  useEffect(() => {
-    const currentIds = fileReferences.map(f => f.id).join(',');
-    const prevIds = fileReferencesRef.current.map(f => f.id).join(',');
-    
-    if (currentIds !== prevIds) {
-      fileReferencesRef.current = fileReferences;
-      // Reset internal URLs when file references change, then immediately sync from props
-      setInternalFileUrls(new Map(fileUrls));
-    } else {
-      // If file references haven't changed, just sync URLs
-      setInternalFileUrls(new Map(fileUrls));
-    }
-  }, [fileReferences, fileUrls]);
-
-  const handleDeleteClick = () => {
-    setDeleteDialogOpen(true);
-  };
-
-  const handleDeleteConfirm = async () => {
-    setDeleteDialogOpen(false);
-    try {
-      if (onDelete) {
-        await onDelete();
-      }
-      setImageError(false);
-    } catch (error) {
-      // Error handling is delegated to onDelete callback
-      setImageError(false);
-    }
-  };
-
-  const handleImageError = () => {
-    setImageError(true);
-  };
-
-  const getFileIcon = (fileType: string) => {
-    if (fileType.startsWith('image/')) return '🖼️';
-    if (fileType.startsWith('video/')) return '🎥';
-    if (fileType.startsWith('audio/')) return '🎵';
-    if (fileType.includes('pdf')) return '📄';
-    if (fileType.includes('word')) return '📝';
-    if (fileType.includes('excel') || fileType.includes('spreadsheet')) return '📊';
-    if (fileType.includes('powerpoint') || fileType.includes('presentation')) return '📊';
-    return '📁';
-  };
-
-  const formatFileSize = (bytes: number) => {
-    if (bytes === 0) return '0 Bytes';
-    const k = 1024;
-    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
-    const i = Math.floor(Math.log(bytes) / Math.log(k));
-    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
-  };
-
-  // Check for errors first - errors should be shown even if fileCount is 0
-  if (error) {
-    if (ErrorComponent) {
-      return <ErrorComponent error={error} retry={clearError} />;
-    }
-    
-    // Show fallback if enabled
-    if (showFallback) {
-      return (
-        <figure className={className} title="File unavailable">
-          <p className={fallbackClasses}>
-            {computedFallbackText}
-          </p>
-        </figure>
-      );
-    }
-    
-    return (
-      <figure className={className} title="Error">
-        <p className={getFallbackClasses(fallbackSize || 'md')}>
-          Error loading file: {error instanceof Error ? error.message : String(error)}
-        </p>
-        {clearError && (
-          <Button
-            onClick={clearError}
-            className="mt-2"
-            aria-label="Retry loading file"
-          >
-            Try again
-          </Button>
-        )}
-      </figure>
-    );
-  }
-
-  // Show fallback immediately if enabled and we have no files (even during loading)
-  // This provides better UX by showing fallback UI instead of a spinner when we know there are no files
-  if (fileCount === 0 && !isLoading) {
-    // Show fallback if enabled
-    if (showFallback) {
-      return (
-        <figure className={className} title="No file">
-          <p className={fallbackClasses}>
-            {computedFallbackText}
-          </p>
-          {children}
-        </figure>
-      );
-    }
-    
-    return (
-      <figure className={`text-sec-500 text-center p-4 ${className}`}>
-        <p>No files found</p>
-        {children}
-      </figure>
-    );
-  }
-
-  // During loading, show fallback if enabled (better UX than spinner for empty states)
-  if (isLoading && showFallback && fileCount === 0) {
-    return (
-      <figure className={className} title="Loading...">
-        <p className={fallbackClasses}>
-          {computedFallbackText}
-        </p>
-        {children}
-      </figure>
-    );
-  }
-
-  if (isLoading) {
-    if (LoadingComponent) {
-      return <LoadingComponent />;
-    }
-    return (
-      <figure className={className} title="Loading">
-        <p className="flex items-center justify-center p-4">
-          <LoadingSpinner />
-        </p>
-      </figure>
-    );
-  }
-
-  // Single file display (when category or displayOnly is specified)
-  if ((category || displayOnly) && fileReference) {
-    const isImage = fileReference.file_metadata.fileType?.startsWith('image/');
-    
-    // Simplified image-only display when displayOnly is true and it's an image
-    // Only use simplified path if enableChildren is not explicitly enabled
-    if (displayOnly && isImage && !showDelete && !enableChildren) {
-      // Show fallback if image error occurred and fallback is enabled
-      if (imageError && showFallback) {
-        return (
-          <figure className={className} title={fileReference.file_metadata.fileName || 'File'}>
-            <p className={fallbackClasses}>
-              {computedFallbackText}
-            </p>
-          </figure>
-        );
-      }
-      
-      // Show loading skeleton if URL is not available yet
-      if (!stableFileUrl) {
-        return (
-          <figure className={className || "max-w-full h-48"} title="Loading">
-            <p className={fallbackClasses}>
-              <LoadingSpinner />
-            </p>
-          </figure>
-        );
-      }
-      
-      return (
-        <figure className={className || ""}>
-          <img
-            ref={imgRef}
-            key={fileReference.id}
-            src={stableFileUrl || undefined}
-            alt={fileReference.file_metadata.fileName || 'File'}
-            className={imgClassName || "object-cover size-full"}
-            onError={handleImageError}
-            onLoadStart={handleImageLoadStart}
-            onLoad={handleImageLoad}
-            loading="lazy"
-          />
-        </figure>
-      );
-    }
-    
-    // Document link display when displayOnly is true and file is not an image
-    // Render non-image files as clickable links that open in a new tab
-    if (displayOnly && !isImage && stableFileUrl && fileReference && !showDelete) {
-      const fileName = fileReference.file_metadata?.fileName || 'Document';
-      const ariaLabel = `Open ${fileName} in new tab`;
-      
-      return (
-        <figure className={className}>
-          <a
-            href={stableFileUrl || undefined}
-            target="_blank"
-            rel="noopener noreferrer"
-            aria-label={ariaLabel}
-            className="flex items-center gap-2 p-3 bg-sec-50 border border-sec-200 rounded-lg hover:bg-sec-100 transition-colors text-main-600 hover:text-main-700 focus:outline-none focus:ring-2 focus:ring-main-500 focus:ring-offset-2"
-          >
-            <FileText className="size-5 shrink-0" aria-hidden="true" />
-            <span className="flex-1 font-medium truncate">
-              {fileName}
-            </span>
-            <ExternalLink className="size-5 shrink-0" aria-hidden="true" />
-          </a>
-          {showMetadata && (
-            <figcaption>
-              <p>{fileName}</p>
-              {fileReference.file_metadata.fileSize && (
-                <p>{formatFileSize(fileReference.file_metadata.fileSize)} • {fileReference.file_metadata.fileType}</p>
-              )}
-            </figcaption>
-          )}
-        </figure>
-      );
-    }
-    
-    // Standard single file display with wrapper
-    // For displayOnly mode, if fallback is enabled and there's no URL or image error, show fallback instead of folder icon
-    if (displayOnly && showFallback && (!stableFileUrl || imageError || !isImage)) {
-      return (
-        <figure className={className} title={fileReference.file_metadata.fileName || 'File'}>
-          <p className={fallbackClasses}>
-            {computedFallbackText}
-          </p>
-        </figure>
-      );
-    }
-    
-    return (
-      <figure className={`relative ${className}`}>
-        {isImage && stableFileUrl && !imageError ? (
-          <>
-            <img
-              key={fileReference.id}
-              src={stableFileUrl}
-              alt={fileReference.file_metadata.fileName || 'File'}
-              className={imgClassName || "object-cover size-full"}
-              onError={handleImageError}
-              loading="lazy"
-            />
-            {showDelete && (
-              <>
-                <Button
-                  variant="destructive"
-                  size="icon"
-                  onClick={handleDeleteClick}
-                  className="absolute top-2 right-2"
-                  title="Delete file"
-                  aria-label="Delete file"
-                >
-                  ×
-                </Button>
-                <Dialog open={deleteDialogOpen} onOpenChange={setDeleteDialogOpen}>
-                  <DialogContent size="sm" title="Confirm Delete">
-                    <DialogHeader>
-                      <h2>Confirm Delete</h2>
-                    </DialogHeader>
-                    <DialogBody>
-                      <p>Are you sure you want to delete this file? This action cannot be undone.</p>
-                    </DialogBody>
-                    <DialogFooter>
-                      <Button variant="outline" onClick={() => setDeleteDialogOpen(false)}>
-                        Cancel
-                      </Button>
-                      <Button variant="destructive" onClick={handleDeleteConfirm}>
-                        Delete
-                      </Button>
-                    </DialogFooter>
-                  </DialogContent>
-                </Dialog>
-              </>
-            )}
-            {children}
-            {showMetadata && (
-              <figcaption>
-                <p>{fileReference.file_metadata.fileName || 'Unknown file'}</p>
-                {(fileReference.file_metadata.fileSize || fileReference.file_metadata.fileType) && (
-                  <p>
-                    {fileReference.file_metadata.fileSize && formatFileSize(fileReference.file_metadata.fileSize)}
-                    {fileReference.file_metadata.fileSize && fileReference.file_metadata.fileType && ' • '}
-                    {fileReference.file_metadata.fileType}
-                  </p>
-                )}
-              </figcaption>
-            )}
-          </>
-        ) : isImage && imageError && showFallback ? (
-          // Show fallback when image fails to load and fallback is enabled
-          <>
-            <p className={fallbackClasses} title={fileReference.file_metadata.fileName || 'File'}>
-              {computedFallbackText}
-            </p>
-            {children}
-            {showMetadata && (
-              <figcaption>
-                <p>{fileReference.file_metadata.fileName || 'Unknown file'}</p>
-                {(fileReference.file_metadata.fileSize || fileReference.file_metadata.fileType) && (
-                  <p>
-                    {fileReference.file_metadata.fileSize && formatFileSize(fileReference.file_metadata.fileSize)}
-                    {fileReference.file_metadata.fileSize && fileReference.file_metadata.fileType && ' • '}
-                    {fileReference.file_metadata.fileType}
-                  </p>
-                )}
-              </figcaption>
-            )}
-          </>
-        ) : (
-          <>
-            <p className="flex items-center space-x-3 p-3 bg-sec-50 rounded-lg border border-sec-200">
-              <span className="text-2xl">
-                {getFileIcon(fileReference.file_metadata.fileType || '')}
-              </span>
-              {showDelete && (
-                <>
-                  <Button
-                    variant="destructive"
-                    size="icon"
-                    onClick={handleDeleteClick}
-                    className="ml-auto"
-                    title="Delete file"
-                    aria-label="Delete file"
-                  >
-                    ×
-                  </Button>
-                  <Dialog open={deleteDialogOpen} onOpenChange={setDeleteDialogOpen}>
-                    <DialogContent size="sm" title="Confirm Delete">
-                      <DialogHeader>
-                        <h2>Confirm Delete</h2>
-                      </DialogHeader>
-                      <DialogBody>
-                        <p>Are you sure you want to delete this file? This action cannot be undone.</p>
-                      </DialogBody>
-                      <DialogFooter>
-                        <Button variant="outline" onClick={() => setDeleteDialogOpen(false)}>
-                          Cancel
-                        </Button>
-                        <Button variant="destructive" onClick={handleDeleteConfirm}>
-                          Delete
-                        </Button>
-                      </DialogFooter>
-                    </DialogContent>
-                  </Dialog>
-                </>
-              )}
-            </p>
-            {children}
-            {showMetadata && (
-              <figcaption>
-                <p>{fileReference.file_metadata.fileName || 'Unknown file'}</p>
-                {(fileReference.file_metadata.fileSize || fileReference.file_metadata.fileType) && (
-                  <p>
-                    {fileReference.file_metadata.fileSize && formatFileSize(fileReference.file_metadata.fileSize)}
-                    {fileReference.file_metadata.fileSize && fileReference.file_metadata.fileType && ' • '}
-                    {fileReference.file_metadata.fileType}
-                  </p>
-                )}
-              </figcaption>
-            )}
-          </>
-        )}
-      </figure>
-    );
-  }
-
-  // Multiple files display
-  return (
-    <figure className={`space-y-2 ${className}`}>
-      {fileReferences.map((fileRef) => {
-        const isImage = fileRef.file_metadata.fileType?.startsWith('image/');
-        const fileUrl = internalFileUrls.get(fileRef.id) || null;
-        const canDownload = !isImage && fileUrl;
-        
-        return (
-          <figure key={fileRef.id} className="flex items-center space-x-3 p-3 bg-sec-50 rounded-lg border border-sec-200">
-            {isImage && fileUrl ? (
-              <img
-                key={fileRef.id}
-                src={fileUrl || undefined}
-                alt={fileRef.file_metadata.fileName || 'File'}
-                className={imgClassName || "object-cover size-full"}
-                onError={handleImageError}
-                loading="lazy"
-              />
-            ) : (
-              <span className="text-2xl">
-                {getFileIcon(fileRef.file_metadata.fileType || '')}
-              </span>
-            )}
-            {showMetadata && (
-              <figcaption className="flex-1 min-w-0">
-                <p className="font-medium text-sec-900 truncate">
-                  {fileRef.file_metadata.fileName || 'Unknown file'}
-                </p>
-                {(fileRef.file_metadata.fileSize || fileRef.file_metadata.fileType || fileRef.file_metadata.category) && (
-                  <p className="text-sm text-sec-500">
-                    {fileRef.file_metadata.fileSize && formatFileSize(fileRef.file_metadata.fileSize)}
-                    {fileRef.file_metadata.fileSize && fileRef.file_metadata.fileType && ' • '}
-                    {fileRef.file_metadata.fileType}
-                    {(fileRef.file_metadata.fileSize || fileRef.file_metadata.fileType) && fileRef.file_metadata.category && ' • '}
-                    {fileRef.file_metadata.category}
-                  </p>
-                )}
-              </figcaption>
-            )}
-            <p className="flex items-center space-x-2">
-              {canDownload && (
-                <a
-                  href={fileRef.file_path}
-                  download={fileRef.file_metadata.fileName || 'download'}
-                  className="text-main-500 hover:text-main-700 p-1"
-                  title="Download file"
-                >
-                  ↓
-                </a>
-              )}
-              {showDelete && onDelete && (
-                <Button
-                  variant="destructive"
-                  size="icon"
-                  onClick={handleDeleteClick}
-                  title="Delete file"
-                  aria-label="Delete file"
-                >
-                  ×
-                </Button>
-              )}
-            </p>
-          </figure>
-        );
-      })}
-      {children}
-    </figure>
-  );
-});
-
 /**
  * Internal component for public page context
  * Uses PublicPageContext to get Supabase client
@@ -654,14 +78,9 @@ function FileDisplayPublic({
   enableChildren,
   showMetadata
 }: FileDisplayProps) {
-  // Call all hooks unconditionally at the top level
-  // Hooks must be called in the same order on every render
   const publicPageContext = useContext(PublicPageContext);
   const supabase = publicPageContext?.supabase ?? null;
 
-  // Call hook unconditionally - if supabase is null, the hook will handle it
-  // Use a dummy supabase client if null to satisfy type requirements
-  // The hook should handle null gracefully, but TypeScript requires a valid type
   const {
     fileUrl,
     fileReference,
@@ -669,19 +88,16 @@ function FileDisplayPublic({
     fileUrls,
     fileCount,
     isLoading,
-    error,
-    refetch
+    error
   } = usePublicFileDisplay(
     table_name,
     record_id,
     organisation_id,
     category,
-    { supabase: supabase as any } // Type assertion needed due to type mismatch between contexts
+    { supabase: supabase as unknown as SupabaseClient<Database> }
   );
 
-  // Early return after all hooks have been called
   if (!supabase) {
-    // If fallback is enabled, show fallback UI instead of error
     if (showFallback) {
       return (
         <FileDisplayContent
@@ -712,8 +128,6 @@ function FileDisplayPublic({
         />
       );
     }
-    
-    // Only show error if fallback is not enabled
     return (
       <figure className={className} title="Error">
         <p className={getFallbackClasses(fallbackSize || 'md')}>
@@ -723,7 +137,6 @@ function FileDisplayPublic({
     );
   }
 
-  // Log errors for debugging public file display issues
   if (error) {
     logger.error('FileDisplayPublic', 'Error fetching file', {
       table_name,
@@ -735,28 +148,23 @@ function FileDisplayPublic({
     });
   }
 
-  // Public context doesn't support delete operations
   const handleDelete = async () => {
     // Delete operations are not available in public context for security reasons
   };
 
-  // Handle displayOnly mode: select first file (prefer images) from all files
   let finalFileReference = fileReference;
   let finalFileUrl = fileUrl;
   let finalFileReferences = fileReferences;
   let finalFileCount = fileCount;
 
   if (displayOnly && !category && fileReferences.length > 0) {
-    // Prefer image files
-    const imageFiles = fileReferences.filter(f => 
+    const imageFiles = fileReferences.filter(f =>
       f.file_metadata.fileType?.startsWith('image/')
     );
     const targetFile = imageFiles.length > 0 ? imageFiles[0] : fileReferences[0];
     finalFileReference = targetFile;
     finalFileReferences = [targetFile];
     finalFileCount = 1;
-    
-    // Get URL for target file from fileUrls map
     finalFileUrl = fileUrls.get(targetFile.id) || null;
   }
 
@@ -771,7 +179,7 @@ function FileDisplayPublic({
       fileCount={finalFileCount}
       category={category}
       displayOnly={displayOnly}
-      showDelete={false} // Never show delete in public context
+      showDelete={false}
       className={className}
       imgClassName={imgClassName}
       children={children}
@@ -815,11 +223,9 @@ function FileDisplayAuthenticated({
   showMetadata
 }: FileDisplayProps) {
   const { supabase } = useUnifiedAuth();
+  const [displayOnlyFileReference, setDisplayOnlyFileReference] =
+    useState<FileReference | null>(null);
 
-  // Consolidated state for displayOnly mode - must be before early return
-  const [displayOnlyFileReference, setDisplayOnlyFileReference] = useState<FileReference | null>(null);
-
-  // Call hooks before any early returns - hooks must handle null supabase gracefully
   const {
     fileUrl,
     fileReference,
@@ -829,16 +235,13 @@ function FileDisplayAuthenticated({
     isLoading,
     error,
     refetch
-  } = useFileDisplay(
-    table_name,
-    record_id,
-    organisation_id,
-    category,
-    { supabase: supabase || null }
-  );
-  
-  // Use fileUrls map if available, otherwise use useFileUrl hook
-  const displayOnlyFileUrlFromMap = displayOnlyFileReference ? fileUrls.get(displayOnlyFileReference.id) : null;
+  } = useFileDisplay(table_name, record_id, organisation_id, category, {
+    supabase: supabase || null
+  });
+
+  const displayOnlyFileUrlFromMap = displayOnlyFileReference
+    ? fileUrls.get(displayOnlyFileReference.id)
+    : null;
   const displayOnlyFileUrlHook = useFileUrl(
     displayOnlyFileReference && !displayOnlyFileUrlFromMap ? displayOnlyFileReference : null,
     {
@@ -849,23 +252,18 @@ function FileDisplayAuthenticated({
   );
   const displayOnlyFileUrl = displayOnlyFileUrlFromMap || displayOnlyFileUrlHook.url;
 
-  // Handle displayOnly mode: select first file (prefer images) from all files
   useEffect(() => {
     if (displayOnly && !category && fileReferences.length > 0) {
-      // Prefer image files
-      const imageFiles = fileReferences.filter(f => 
+      const imageFiles = fileReferences.filter(f =>
         f.file_metadata.fileType?.startsWith('image/')
       );
       const targetFile = imageFiles.length > 0 ? imageFiles[0] : fileReferences[0];
       setDisplayOnlyFileReference(targetFile);
-      // URL generation is handled by useFileUrl hook or fileUrls map
     } else {
-      // Clear displayOnly files when not in displayOnly mode or when category is specified
       setDisplayOnlyFileReference(null);
     }
   }, [displayOnly, category, fileReferences, fileUrls]);
 
-  // Early return check after all hooks are called
   if (!supabase) {
     return (
       <figure className={className} title="Error">
@@ -876,12 +274,10 @@ function FileDisplayAuthenticated({
     );
   }
 
-  // Delete operation - implementation pending
   const handleDelete = async () => {
     // TODO: Implement delete via FileReferenceService when delete functionality is needed
   };
 
-  // Determine final file reference and URL based on mode
   let finalFileReference = fileReference;
   let finalFileUrl = fileUrl;
   let finalFileReferences = fileReferences;
@@ -890,12 +286,10 @@ function FileDisplayAuthenticated({
   let finalError = error;
 
   if (displayOnly && !category) {
-    // DisplayOnly mode: use state-managed file reference and URL
     finalFileReference = displayOnlyFileReference;
     finalFileUrl = displayOnlyFileUrl;
     finalFileReferences = displayOnlyFileReference ? [displayOnlyFileReference] : [];
     finalFileCount = displayOnlyFileReference ? 1 : 0;
-    // Include URL loading state in overall loading state
     if (!displayOnlyFileUrlFromMap) {
       finalIsLoading = isLoading || displayOnlyFileUrlHook.isLoading;
       finalError = error || displayOnlyFileUrlHook.error;
@@ -933,30 +327,10 @@ function FileDisplayAuthenticated({
   );
 }
 
-/**
- * Component for displaying file references with context-awareness
- * 
- * This component is context-aware and automatically detects whether it's being used
- * in a public or authenticated context. It fetches and displays files from storage.
- * 
- * The component automatically detects context and uses:
- * - PublicPageProvider context for public pages
- * - UnifiedAuthProvider context for authenticated pages
- * 
- * @param props - File display configuration
- * @param props.displayOnly - Display only a single file instead of all files. Uses first file (prefers images) from all files, without category filtering. When true:
- *   - **Image files**: Renders a simplified image-only display without metadata or wrapper divs
- *   - **Non-image files** (PDFs, Word docs, Excel files, etc.): Renders as clickable links that open in a new tab with document icon, filename, and external link icon. Links include proper security attributes (`rel="noopener noreferrer"`) and accessibility features (ARIA labels, keyboard navigation, visible focus states)
- *   - If `showDelete={true}`, uses standard wrapper behavior instead of simplified display
- * @param props.category - Optional category filter. When specified, only displays files matching this category and uses single file display variant.
- * @returns React element with file display
- */
 /**
  * File display component.
  * Renders files from the file reference system with support for previews, downloads, and public/private access.
- * 
- * @param props - File display configuration
- * @returns The rendered file display
+ * Context-aware: uses PublicPageProvider for public pages and UnifiedAuthProvider for authenticated pages.
  */
 export function FileDisplay({
   table_name,
@@ -978,10 +352,8 @@ export function FileDisplay({
   enableChildren,
   showMetadata
 }: FileDisplayProps) {
-  // Check which context we're in and route to the appropriate component
   const isPublicPage = useIsPublicPage();
-  
-  // If we're in a public page context, use the public component
+
   if (isPublicPage) {
     return (
       <FileDisplayPublic
@@ -1007,8 +379,6 @@ export function FileDisplay({
     );
   }
 
-  // Otherwise, use the authenticated component
-  // It will show an error if not in UnifiedAuthProvider
   return (
     <FileDisplayAuthenticated
       table_name={table_name}