@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/FileDisplay/FileDisplaySingleDocumentLinkView.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { FileText, ExternalLink } from 'lucide-react';
+import { formatFileSize } from './fileDisplayUtils';
+import type { FileReference } from '../../types/file-reference';
+
+export interface FileDisplaySingleDocumentLinkViewProps {
+  fileReference: FileReference;
+  stableFileUrl: string;
+  className: string;
+  showMetadata: boolean;
+}
+
+export function FileDisplaySingleDocumentLinkView({
+  fileReference,
+  stableFileUrl,
+  className,
+  showMetadata
+}: FileDisplaySingleDocumentLinkViewProps) {
+  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>
+  );
+}

package/src/components/FileDisplay/FileDisplaySingleFileWithActionsView.test.tsx

@@ -0,0 +1,111 @@
+import React from 'react';
+import { renderWithProviders, screen, userEvent } from '../../__tests__/helpers/test-utils';
+import { FileDisplaySingleFileWithActionsView } from './FileDisplaySingleFileWithActionsView';
+import type { FileReference } from '../../types/file-reference';
+import { FileCategory } from '../../types/file-reference';
+
+const fileRef: FileReference = {
+  id: 'fr-1',
+  table_name: 'person',
+  record_id: 'rec-1',
+  file_path: 'bucket/path/file.png',
+  organisation_id: 'org-1',
+  is_public: false,
+  file_metadata: { fileName: 'file.png', fileSize: 1024, fileType: 'image/png', category: FileCategory.IMAGES },
+  app_id: 'test-app' as FileReference['app_id'],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString()
+};
+
+const baseProps = {
+  fileReference: fileRef,
+  isImage: true,
+  stableFileUrl: 'https://example.com/file.png',
+  imageError: false,
+  showFallback: false,
+  showDelete: false,
+  showMetadata: true,
+  className: '',
+  fallbackClasses: 'grid place-items-center',
+  fallbackText: 'Fallback',
+  deleteDialogOpen: false,
+  onDeleteDialogOpenChange: vi.fn(),
+  onDeleteClick: vi.fn(),
+  onDeleteConfirm: vi.fn().mockResolvedValue(undefined),
+  onImageError: vi.fn()
+};
+
+describe('[component] FileDisplaySingleFileWithActionsView', () => {
+  beforeEach(() => {
+    HTMLDialogElement.prototype.showModal = vi.fn(function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+      this.dispatchEvent(new Event('show', { bubbles: true }));
+    });
+    HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+      this.dispatchEvent(new Event('close', { bubbles: true }));
+    });
+  });
+
+  it('renders image when isImage and stableFileUrl and !imageError', () => {
+    renderWithProviders(<FileDisplaySingleFileWithActionsView {...baseProps} />);
+    const img = screen.getByRole('img', { name: /file\.png/i });
+    expect(img).toBeInTheDocument();
+    expect(img).toHaveAttribute('src', 'https://example.com/file.png');
+  });
+
+  it('shows delete button when showDelete and calls onDeleteClick on click', async () => {
+    const onDeleteClick = vi.fn();
+    renderWithProviders(
+      <FileDisplaySingleFileWithActionsView
+        {...baseProps}
+        showDelete
+        onDeleteClick={onDeleteClick}
+      />
+    );
+    const deleteBtn = screen.getByRole('button', { name: /Delete file/i });
+    await userEvent.click(deleteBtn);
+    expect(onDeleteClick).toHaveBeenCalled();
+  });
+
+  it('renders fallback text when showFallback and (!stableFileUrl || imageError || !isImage)', () => {
+    renderWithProviders(
+      <FileDisplaySingleFileWithActionsView
+        {...baseProps}
+        showFallback
+        fallbackText="No preview"
+        stableFileUrl={null}
+      />
+    );
+    expect(screen.getByText('No preview')).toBeInTheDocument();
+  });
+
+  it('renders icon block for non-image', () => {
+    renderWithProviders(
+      <FileDisplaySingleFileWithActionsView
+        {...baseProps}
+        isImage={false}
+        stableFileUrl={null}
+      />
+    );
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+    expect(screen.getByText('file.png')).toBeInTheDocument();
+  });
+
+  it('calls onDeleteConfirm when dialog Confirm is clicked', async () => {
+    const onDeleteConfirm = vi.fn().mockResolvedValue(undefined);
+    renderWithProviders(
+      <FileDisplaySingleFileWithActionsView
+        {...baseProps}
+        showDelete
+        deleteDialogOpen
+        onDeleteConfirm={onDeleteConfirm}
+      />
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(dialog).toBeInTheDocument();
+    const confirmBtn = screen.getByRole('button', { name: 'Delete' });
+    await userEvent.click(confirmBtn);
+    expect(onDeleteConfirm).toHaveBeenCalled();
+  });
+});

package/src/components/FileDisplay/FileDisplaySingleFileWithActionsView.tsx

@@ -0,0 +1,270 @@
+import React from 'react';
+import { Button } from '../Button/Button';
+import { FileDisplayDeleteConfirmDialog } from './FileDisplayDeleteConfirmDialog';
+import { getFileIcon, formatFileSize } from './fileDisplayUtils';
+import type { FileReference } from '../../types/file-reference';
+
+export interface FileDisplaySingleFileWithActionsViewProps {
+  fileReference: FileReference;
+  isImage: boolean;
+  stableFileUrl: string | null;
+  imageError: boolean;
+  showFallback: boolean;
+  showDelete: boolean;
+  showMetadata: boolean;
+  className: string;
+  imgClassName?: string;
+  fallbackClasses: string;
+  fallbackText: string;
+  children?: React.ReactNode;
+  deleteDialogOpen: boolean;
+  onDeleteDialogOpenChange: (open: boolean) => void;
+  onDeleteClick: () => void;
+  onDeleteConfirm: () => void | Promise<void>;
+  onImageError: () => void;
+}
+
+function SingleFileMetadataCaption({
+  fileReference,
+  showMetadata
+}: {
+  fileReference: FileReference;
+  showMetadata: boolean;
+}) {
+  if (!showMetadata) return null;
+  const fileName = fileReference.file_metadata.fileName || 'Unknown file';
+  const hasMetadata =
+    fileReference.file_metadata.fileSize || fileReference.file_metadata.fileType;
+  return (
+    <figcaption>
+      <p>{fileName}</p>
+      {hasMetadata && (
+        <p>
+          {fileReference.file_metadata.fileSize &&
+            formatFileSize(fileReference.file_metadata.fileSize)}
+          {fileReference.file_metadata.fileSize &&
+            fileReference.file_metadata.fileType &&
+            ' • '}
+          {fileReference.file_metadata.fileType}
+        </p>
+      )}
+    </figcaption>
+  );
+}
+
+function SingleFileImageBlock({
+  fileReference,
+  stableFileUrl,
+  imgClassName,
+  showDelete,
+  showMetadata,
+  children,
+  onDeleteClick,
+  onImageError,
+  deleteDialogOpen,
+  onDeleteDialogOpenChange,
+  onDeleteConfirm
+}: {
+  fileReference: FileReference;
+  stableFileUrl: string;
+  imgClassName?: string;
+  showDelete: boolean;
+  showMetadata: boolean;
+  children?: React.ReactNode;
+  onDeleteClick: () => void;
+  onImageError: () => void;
+  deleteDialogOpen: boolean;
+  onDeleteDialogOpenChange: (open: boolean) => void;
+  onDeleteConfirm: () => void | Promise<void>;
+}) {
+  return (
+    <>
+      <img
+        key={fileReference.id}
+        src={stableFileUrl}
+        alt={fileReference.file_metadata.fileName || 'File'}
+        className={imgClassName || 'object-cover size-full'}
+        onError={onImageError}
+        loading="lazy"
+      />
+      {showDelete && (
+        <>
+          <Button
+            variant="destructive"
+            size="icon"
+            onClick={onDeleteClick}
+            className="absolute top-2 right-2"
+            title="Delete file"
+            aria-label="Delete file"
+          >
+            ×
+          </Button>
+          <FileDisplayDeleteConfirmDialog
+            open={deleteDialogOpen}
+            onOpenChange={onDeleteDialogOpenChange}
+            onConfirm={onDeleteConfirm}
+            onCancel={() => onDeleteDialogOpenChange(false)}
+          />
+        </>
+      )}
+      {children}
+      <SingleFileMetadataCaption fileReference={fileReference} showMetadata={showMetadata} />
+    </>
+  );
+}
+
+function SingleFileFallbackBlock({
+  fileReference,
+  fallbackClasses,
+  fallbackText,
+  showMetadata,
+  children
+}: {
+  fileReference: FileReference;
+  fallbackClasses: string;
+  fallbackText: string;
+  showMetadata: boolean;
+  children?: React.ReactNode;
+}) {
+  return (
+    <>
+      <p className={fallbackClasses} title={fileReference.file_metadata.fileName || 'File'}>
+        {fallbackText}
+      </p>
+      {children}
+      <SingleFileMetadataCaption fileReference={fileReference} showMetadata={showMetadata} />
+    </>
+  );
+}
+
+function SingleFileIconBlock({
+  fileReference,
+  showDelete,
+  showMetadata,
+  children,
+  onDeleteClick,
+  deleteDialogOpen,
+  onDeleteDialogOpenChange,
+  onDeleteConfirm
+}: {
+  fileReference: FileReference;
+  showDelete: boolean;
+  showMetadata: boolean;
+  children?: React.ReactNode;
+  onDeleteClick: () => void;
+  deleteDialogOpen: boolean;
+  onDeleteDialogOpenChange: (open: boolean) => void;
+  onDeleteConfirm: () => void | Promise<void>;
+}) {
+  return (
+    <>
+      <section 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={onDeleteClick}
+              className="ml-auto"
+              title="Delete file"
+              aria-label="Delete file"
+            >
+              ×
+            </Button>
+            <FileDisplayDeleteConfirmDialog
+              open={deleteDialogOpen}
+              onOpenChange={onDeleteDialogOpenChange}
+              onConfirm={onDeleteConfirm}
+              onCancel={() => onDeleteDialogOpenChange(false)}
+            />
+          </>
+        )}
+      </section>
+      {children}
+      <SingleFileMetadataCaption fileReference={fileReference} showMetadata={showMetadata} />
+    </>
+  );
+}
+
+export function FileDisplaySingleFileWithActionsView({
+  fileReference,
+  isImage,
+  stableFileUrl,
+  imageError,
+  showFallback,
+  showDelete,
+  showMetadata,
+  className,
+  imgClassName,
+  fallbackClasses,
+  fallbackText,
+  children,
+  deleteDialogOpen,
+  onDeleteDialogOpenChange,
+  onDeleteClick,
+  onDeleteConfirm,
+  onImageError
+}: FileDisplaySingleFileWithActionsViewProps) {
+  if (showFallback && (!stableFileUrl || imageError || !isImage)) {
+    return (
+      <figure className={className} title={fileReference.file_metadata.fileName || 'File'}>
+        <p className={fallbackClasses}>{fallbackText}</p>
+      </figure>
+    );
+  }
+
+  const showImageSuccess = isImage && !!stableFileUrl && !imageError;
+  const showImageErrorFallback = isImage && imageError && showFallback;
+
+  if (showImageSuccess) {
+    return (
+      <figure className={`relative ${className}`}>
+        <SingleFileImageBlock
+          fileReference={fileReference}
+          stableFileUrl={stableFileUrl}
+          imgClassName={imgClassName}
+          showDelete={showDelete}
+          showMetadata={showMetadata}
+          children={children}
+          onDeleteClick={onDeleteClick}
+          onImageError={onImageError}
+          deleteDialogOpen={deleteDialogOpen}
+          onDeleteDialogOpenChange={onDeleteDialogOpenChange}
+          onDeleteConfirm={onDeleteConfirm}
+        />
+      </figure>
+    );
+  }
+
+  if (showImageErrorFallback) {
+    return (
+      <figure className={`relative ${className}`}>
+        <SingleFileFallbackBlock
+          fileReference={fileReference}
+          fallbackClasses={fallbackClasses}
+          fallbackText={fallbackText}
+          showMetadata={showMetadata}
+          children={children}
+        />
+      </figure>
+    );
+  }
+
+  return (
+    <figure className={`relative ${className}`}>
+      <SingleFileIconBlock
+        fileReference={fileReference}
+        showDelete={showDelete}
+        showMetadata={showMetadata}
+        children={children}
+        onDeleteClick={onDeleteClick}
+        deleteDialogOpen={deleteDialogOpen}
+        onDeleteDialogOpenChange={onDeleteDialogOpenChange}
+        onDeleteConfirm={onDeleteConfirm}
+      />
+    </figure>
+  );
+}

package/src/components/FileDisplay/FileDisplaySingleImageView.test.tsx

@@ -0,0 +1,78 @@
+import React from 'react';
+import { renderWithProviders, screen } from '../../__tests__/helpers/test-utils';
+import { FileDisplaySingleImageView } from './FileDisplaySingleImageView';
+import type { FileReference } from '../../types/file-reference';
+import { FileCategory } from '../../types/file-reference';
+
+const fileRef: FileReference = {
+  id: 'fr-1',
+  table_name: 'person',
+  record_id: 'rec-1',
+  file_path: 'bucket/path/file.png',
+  organisation_id: 'org-1',
+  is_public: false,
+  file_metadata: { fileName: 'file.png', fileSize: 1024, fileType: 'image/png', category: FileCategory.IMAGES },
+  app_id: 'test-app' as FileReference['app_id'],
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString()
+};
+
+const baseProps = {
+  fileReference: fileRef,
+  stableFileUrl: 'https://example.com/file.png',
+  imageError: false,
+  showFallback: false,
+  className: '',
+  fallbackClasses: 'grid place-items-center',
+  fallbackText: 'Fallback',
+  onImageError: vi.fn(),
+  onImageLoadStart: vi.fn(),
+  onImageLoad: vi.fn()
+};
+
+describe('[component] FileDisplaySingleImageView', () => {
+  it('renders fallback text when imageError and showFallback', () => {
+    renderWithProviders(
+      <FileDisplaySingleImageView
+        {...baseProps}
+        imageError
+        showFallback
+        fallbackText="Broken"
+      />
+    );
+    expect(document.querySelector('figure[title="file.png"]')).toBeInTheDocument();
+    expect(screen.getByText('Broken')).toBeInTheDocument();
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('renders loading placeholder when !stableFileUrl', () => {
+    renderWithProviders(
+      <FileDisplaySingleImageView {...baseProps} stableFileUrl={null} />
+    );
+    expect(document.querySelector('figure[title="Loading"]')).toBeInTheDocument();
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('renders img with correct src/alt when stableFileUrl and no error', async () => {
+    renderWithProviders(<FileDisplaySingleImageView {...baseProps} />);
+    const img = screen.getByRole('img', { name: /file\.png/i });
+    expect(img).toBeInTheDocument();
+    expect(img).toHaveAttribute('src', 'https://example.com/file.png');
+    expect(img).toHaveAttribute('alt', 'file.png');
+  });
+
+  it('calls onImageError when image fires error', async () => {
+    const onImageError = vi.fn();
+    renderWithProviders(<FileDisplaySingleImageView {...baseProps} onImageError={onImageError} />);
+    const img = screen.getByRole('img', { name: /file\.png/i });
+    img.dispatchEvent(new Event('error', { bubbles: true }));
+    expect(onImageError).toHaveBeenCalled();
+  });
+
+  it('attaches imgRef when provided', () => {
+    const imgRef = React.createRef<HTMLImageElement | null>();
+    renderWithProviders(<FileDisplaySingleImageView {...baseProps} imgRef={imgRef} />);
+    expect(imgRef.current).toBeInstanceOf(HTMLImageElement);
+    expect(imgRef.current?.alt).toBe('file.png');
+  });
+});

package/src/components/FileDisplay/FileDisplaySingleImageView.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { LoadingSpinner } from '../LoadingSpinner/LoadingSpinner';
+import type { FileReference } from '../../types/file-reference';
+
+export interface FileDisplaySingleImageViewProps {
+  fileReference: FileReference;
+  stableFileUrl: string | null;
+  imageError: boolean;
+  showFallback: boolean;
+  className: string;
+  imgClassName?: string;
+  fallbackClasses: string;
+  fallbackText: string;
+  onImageError: () => void;
+  onImageLoadStart: () => void;
+  onImageLoad: () => void;
+  imgRef?: React.RefObject<HTMLImageElement | null>;
+}
+
+export function FileDisplaySingleImageView({
+  fileReference,
+  stableFileUrl,
+  imageError,
+  showFallback,
+  className,
+  imgClassName,
+  fallbackClasses,
+  fallbackText,
+  onImageError,
+  onImageLoadStart,
+  onImageLoad,
+  imgRef
+}: FileDisplaySingleImageViewProps) {
+  if (imageError && showFallback) {
+    return (
+      <figure className={className} title={fileReference.file_metadata.fileName || 'File'}>
+        <p className={fallbackClasses}>{fallbackText}</p>
+      </figure>
+    );
+  }
+
+  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 ?? undefined}
+        key={fileReference.id}
+        src={stableFileUrl || undefined}
+        alt={fileReference.file_metadata.fileName || 'File'}
+        className={imgClassName || 'object-cover size-full'}
+        onError={onImageError}
+        onLoadStart={onImageLoadStart}
+        onLoad={onImageLoad}
+        loading="lazy"
+      />
+    </figure>
+  );
+}

package/src/components/FileDisplay/fallbackUtils.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getFallbackClasses,
+  defaultGenerateFallbackText,
+  fallbackSizeClasses,
+  fallbackBaseClasses
+} from './fallbackUtils';
+
+describe('fallbackUtils', () => {
+  describe('getFallbackClasses', () => {
+    it('returns base classes plus size class for each size', () => {
+      const sizes = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const;
+      for (const size of sizes) {
+        const result = getFallbackClasses(size);
+        expect(result).toContain(fallbackBaseClasses);
+        expect(result).toContain(fallbackSizeClasses[size]);
+      }
+    });
+
+    it('defaults to md when no size provided', () => {
+      const result = getFallbackClasses();
+      expect(result).toContain(fallbackSizeClasses.md);
+    });
+  });
+
+  describe('defaultGenerateFallbackText', () => {
+    it('returns FL when fileName is undefined or empty', () => {
+      expect(defaultGenerateFallbackText(undefined)).toBe('FL');
+      expect(defaultGenerateFallbackText('')).toBe('FL');
+    });
+
+    it('extracts initials from single word filename without extension', () => {
+      expect(defaultGenerateFallbackText('Document')).toBe('D');
+    });
+
+    it('extracts initials from multi-word filename', () => {
+      expect(defaultGenerateFallbackText('My Report')).toBe('MR');
+      expect(defaultGenerateFallbackText('annual-report-2024')).toBe('AR2');
+    });
+
+    it('strips extension before extracting initials', () => {
+      expect(defaultGenerateFallbackText('report.pdf')).toBe('R');
+      expect(defaultGenerateFallbackText('My File Name.docx')).toBe('MFN');
+    });
+
+    it('caps at 3 characters', () => {
+      expect(defaultGenerateFallbackText('One Two Three Four')).toBe('OTT');
+    });
+  });
+});

package/src/components/FileDisplay/fallbackUtils.ts

@@ -0,0 +1,44 @@
+/**
+ * Size classes for fallback display
+ */
+export const fallbackSizeClasses: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl', string> = {
+  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
+ */
+export const fallbackBaseClasses =
+  'size-full grid place-items-center text-center text-sec-600 font-semibold';
+
+export type FallbackSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/**
+ * Helper function to compute fallback classes for a given size
+ */
+export function getFallbackClasses(size: FallbackSize = 'md'): string {
+  const sizeClass = fallbackSizeClasses[size];
+  return `${fallbackBaseClasses} ${sizeClass}`.trim();
+}
+
+/**
+ * Default fallback text generator - extracts initials from file name
+ */
+export function defaultGenerateFallbackText(fileName?: string): string {
+  if (!fileName) return 'FL';
+
+  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);
+}

package/src/components/FileDisplay/fetchFileDisplayData.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Fetch File Display Data (Authenticated)
+ * @package @jmruthers/pace-core
+ * @module Components/FileDisplay
+ *
+ * Fetches file references from core_file_references for authenticated contexts.
+ * Implementation lives in useFileDisplayData (data access behind hooks).
+ * Used by useFileDisplay when loading file data. RLS applies to the query.
+ */
+
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+import { FileCategory } from '../../types/file-reference';
+
+export interface FetchFileDisplayDataParams {
+  table_name: string;
+  record_id: string;
+  organisation_id: string | undefined;
+  category: FileCategory | undefined;
+  supabase: SupabaseClient<Database> | null;
+}
+
+/** Re-export so callers and tests use the hook module implementation; no data fetching in this file. */
+export { fetchFileDisplayDataInternal as fetchFileDisplayData } from './useFileDisplayData';