@djangocfg/ui-nextjs 2.1.65 → 2.1.67

package/src/tools/ImageViewer/components/ImageViewer.tsx

@@ -0,0 +1,235 @@
+'use client';
+
+/**
+ * ImageViewer - Image viewer with zoom, pan, rotate, flip
+ *
+ * Features:
+ * - Zoom with mouse wheel and presets
+ * - Pan with drag
+ * - Rotate 90°
+ * - Flip horizontal/vertical
+ * - Fullscreen dialog
+ * - Keyboard shortcuts (+/-, 0, r)
+ */
+
+import { useEffect, useState, useRef, useCallback } from 'react';
+import { ImageIcon, AlertCircle } from 'lucide-react';
+import { TransformWrapper, TransformComponent, useControls } from 'react-zoom-pan-pinch';
+import { cn, Dialog, DialogContent, Alert, AlertDescription } from '@djangocfg/ui-core';
+
+import { ImageToolbar } from './ImageToolbar';
+import { ImageInfo } from './ImageInfo';
+import { useImageTransform, useImageLoading } from '../hooks';
+import type { ImageViewerProps } from '../types';
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function ImageViewer({ file, content, inDialog = false }: ImageViewerProps) {
+  const [scale, setScale] = useState(1);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const controlsRef = useRef<ReturnType<typeof useControls> | null>(null);
+
+  // Loading state
+  const {
+    src,
+    lqip,
+    isFullyLoaded,
+    useProgressiveLoading,
+    error,
+    hasContent,
+  } = useImageLoading({ content, mimeType: file.mimeType });
+
+  // Transform state
+  const { transform, rotate, flipH, flipV, transformStyle } = useImageTransform({
+    resetKey: file.path,
+  });
+
+  // Zoom preset handler
+  const handleZoomPreset = useCallback((value: number | 'fit') => {
+    if (!controlsRef.current) return;
+    if (value === 'fit') {
+      controlsRef.current.resetTransform();
+    } else {
+      controlsRef.current.setTransform(0, 0, value);
+    }
+  }, []);
+
+  // Expand to fullscreen
+  const handleExpand = useCallback(() => {
+    setDialogOpen(true);
+  }, []);
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (!containerRef.current?.contains(document.activeElement) &&
+          document.activeElement !== containerRef.current) {
+        return;
+      }
+
+      const controls = controlsRef.current;
+      if (!controls) return;
+
+      switch (e.key) {
+        case '+':
+        case '=':
+          e.preventDefault();
+          controls.zoomIn();
+          break;
+        case '-':
+          e.preventDefault();
+          controls.zoomOut();
+          break;
+        case '0':
+          e.preventDefault();
+          controls.resetTransform();
+          break;
+        case 'r':
+          if (!e.metaKey && !e.ctrlKey) {
+            e.preventDefault();
+            rotate();
+          }
+          break;
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [rotate]);
+
+  // Show error for oversized images
+  if (error) {
+    return (
+      <div className="flex-1 flex flex-col items-center justify-center gap-3 bg-muted/30 p-4">
+        <AlertCircle className="w-12 h-12 text-destructive/70" />
+        <Alert variant="destructive" className="max-w-md">
+          <AlertCircle className="h-4 w-4" />
+          <AlertDescription>{error}</AlertDescription>
+        </Alert>
+      </div>
+    );
+  }
+
+  // No content
+  if (!hasContent) {
+    return (
+      <div className="flex-1 flex flex-col items-center justify-center gap-2 bg-muted/30">
+        <ImageIcon className="w-12 h-12 text-muted-foreground/50" />
+        <p className="text-sm text-muted-foreground">Failed to load image</p>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      tabIndex={0}
+      className={cn(
+        'flex-1 h-full relative overflow-hidden outline-none',
+        'bg-[length:16px_16px]',
+        '[background-color:hsl(var(--muted)/0.2)]',
+        '[background-image:linear-gradient(45deg,hsl(var(--muted)/0.4)_25%,transparent_25%),linear-gradient(-45deg,hsl(var(--muted)/0.4)_25%,transparent_25%),linear-gradient(45deg,transparent_75%,hsl(var(--muted)/0.4)_75%),linear-gradient(-45deg,transparent_75%,hsl(var(--muted)/0.4)_75%)]',
+        '[background-position:0_0,0_8px,8px_-8px,-8px_0px]'
+      )}
+    >
+      {src && <ImageInfo src={src} />}
+
+      {/* Progressive loading indicator */}
+      {useProgressiveLoading && !isFullyLoaded && (
+        <div className="absolute top-3 left-3 z-10 px-2 py-1 bg-background/80 backdrop-blur-sm border rounded text-[10px] text-muted-foreground font-mono flex items-center gap-1.5">
+          <div className="w-2 h-2 bg-blue-500 rounded-full animate-pulse" />
+          Loading...
+        </div>
+      )}
+
+      <TransformWrapper
+        initialScale={1}
+        minScale={0.1}
+        maxScale={8}
+        centerOnInit
+        onTransformed={(ref, state) => {
+          setScale(state.scale);
+          controlsRef.current = ref;
+        }}
+        onInit={(ref) => {
+          controlsRef.current = ref;
+        }}
+        wheel={{ step: 0.1 }}
+        doubleClick={{ mode: 'toggle', step: 2 }}
+        panning={{ velocityDisabled: false }}
+      >
+        <ImageToolbar
+          scale={scale}
+          transform={transform}
+          onRotate={rotate}
+          onFlipH={flipH}
+          onFlipV={flipV}
+          onZoomPreset={handleZoomPreset}
+          onExpand={!inDialog ? handleExpand : undefined}
+        />
+
+        <TransformComponent
+          wrapperClass="!w-full !h-full cursor-grab active:cursor-grabbing"
+          contentClass="!w-full !h-full flex items-center justify-center"
+        >
+          <div className="relative">
+            {/* LQIP Placeholder (blurred, shown while loading) */}
+            {useProgressiveLoading && lqip && !isFullyLoaded && (
+              <img
+                src={lqip}
+                alt=""
+                aria-hidden="true"
+                className="absolute inset-0 max-w-full max-h-full object-contain select-none"
+                style={{
+                  transform: transformStyle,
+                  filter: 'blur(20px)',
+                  transition: 'opacity 0.3s ease-out',
+                  opacity: isFullyLoaded ? 0 : 1,
+                }}
+                draggable={false}
+              />
+            )}
+
+            {/* Full Image */}
+            {src && (
+              <img
+                src={src}
+                alt={file.name}
+                className="max-w-full max-h-full object-contain select-none"
+                style={{
+                  transform: transformStyle,
+                  transition: useProgressiveLoading
+                    ? 'transform 0.15s ease-out, opacity 0.3s ease-out'
+                    : 'transform 0.15s ease-out',
+                  opacity: useProgressiveLoading && !isFullyLoaded ? 0 : 1,
+                }}
+                draggable={false}
+              />
+            )}
+          </div>
+        </TransformComponent>
+      </TransformWrapper>
+
+      {/* Fullscreen dialog */}
+      {!inDialog && (
+        <Dialog open={dialogOpen} onOpenChange={setDialogOpen}>
+          <DialogContent className="max-w-[95vw] max-h-[95vh] w-[95vw] h-[95vh] p-0 overflow-hidden [&>button]:hidden">
+            <div className="h-full flex flex-col">
+              <div className="flex items-center justify-between px-4 py-2 border-b shrink-0">
+                <span className="text-sm font-medium truncate">{file.name}</span>
+              </div>
+              <div className="flex-1 min-h-0 relative">
+                <div className="absolute inset-0">
+                  <ImageViewer file={file} content={content} inDialog />
+                </div>
+              </div>
+            </div>
+          </DialogContent>
+        </Dialog>
+      )}
+    </div>
+  );
+}

package/src/tools/ImageViewer/components/index.ts

@@ -0,0 +1,7 @@
+/**
+ * ImageViewer components - Public API
+ */
+
+export { ImageViewer } from './ImageViewer';
+export { ImageToolbar } from './ImageToolbar';
+export { ImageInfo } from './ImageInfo';

package/src/tools/ImageViewer/hooks/index.ts

@@ -0,0 +1,9 @@
+/**
+ * ImageViewer hooks - Public API
+ */
+
+export { useImageTransform } from './useImageTransform';
+export type { UseImageTransformOptions, UseImageTransformReturn } from './useImageTransform';
+
+export { useImageLoading } from './useImageLoading';
+export type { UseImageLoadingOptions, UseImageLoadingReturn } from './useImageLoading';

package/src/tools/ImageViewer/hooks/useImageLoading.ts

@@ -0,0 +1,153 @@
+'use client';
+
+/**
+ * useImageLoading - Manages image loading state with LQIP
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import { useImageCache, generateContentKey } from '../../../stores/mediaCache';
+import { createLQIP, MAX_IMAGE_SIZE, WARNING_IMAGE_SIZE, PROGRESSIVE_LOADING_THRESHOLD } from '../utils';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface UseImageLoadingOptions {
+  /** Image content (ArrayBuffer or string) */
+  content: string | ArrayBuffer;
+  /** MIME type for blob creation */
+  mimeType?: string;
+}
+
+export interface UseImageLoadingReturn {
+  /** Blob URL source for the image */
+  src: string | null;
+  /** Low-quality placeholder URL */
+  lqip: string | null;
+  /** Whether full image is loaded */
+  isFullyLoaded: boolean;
+  /** Whether to use progressive loading */
+  useProgressiveLoading: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** Content key for caching */
+  contentKey: string | null;
+  /** Image size in bytes */
+  size: number;
+  /** Whether content exists */
+  hasContent: boolean;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useImageLoading(options: UseImageLoadingOptions): UseImageLoadingReturn {
+  const { content, mimeType } = options;
+
+  const { getOrCreateBlobUrl, releaseBlobUrl } = useImageCache();
+
+  const [src, setSrc] = useState<string | null>(null);
+  const [lqip, setLqip] = useState<string | null>(null);
+  const [isFullyLoaded, setIsFullyLoaded] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const contentKeyRef = useRef<string | null>(null);
+
+  // Calculate size and flags
+  const size = content ? (typeof content === 'string' ? content.length : content.byteLength) : 0;
+  const hasContent = size > 0;
+  const useProgressiveLoading = size > PROGRESSIVE_LOADING_THRESHOLD;
+
+  // Create blob URL with caching and size validation
+  useEffect(() => {
+    // Reset error state
+    setError(null);
+
+    if (!hasContent) {
+      setSrc(null);
+      return;
+    }
+
+    // Size validation - reject oversized images
+    if (size > MAX_IMAGE_SIZE) {
+      const sizeMB = (size / 1024 / 1024).toFixed(1);
+      setError(`Image too large: ${sizeMB}MB (maximum: 50MB)`);
+      setSrc(null);
+      return;
+    }
+
+    // Warn about large images
+    if (size > WARNING_IMAGE_SIZE) {
+      const sizeMB = (size / 1024 / 1024).toFixed(1);
+      console.warn(`[ImageViewer] Large image: ${sizeMB}MB - may impact performance`);
+    }
+
+    // Handle string content (data URLs or binary strings)
+    if (typeof content === 'string') {
+      // Pass through data URLs directly
+      if (content.startsWith('data:')) {
+        setSrc(content);
+        return;
+      }
+
+      // Convert binary string to ArrayBuffer and use Blob URL
+      const encoder = new TextEncoder();
+      const buffer = encoder.encode(content).buffer;
+      const contentKey = generateContentKey(buffer);
+      contentKeyRef.current = contentKey;
+      const url = getOrCreateBlobUrl(contentKey, buffer, mimeType || 'image/png');
+      setSrc(url);
+      return;
+    }
+
+    // Handle ArrayBuffer with cached blob URL
+    const contentKey = generateContentKey(content);
+    contentKeyRef.current = contentKey;
+    const url = getOrCreateBlobUrl(contentKey, content, mimeType || 'image/png');
+    setSrc(url);
+
+    return () => {
+      if (contentKeyRef.current) {
+        releaseBlobUrl(contentKeyRef.current);
+        contentKeyRef.current = null;
+      }
+    };
+  }, [content, mimeType, hasContent, size, getOrCreateBlobUrl, releaseBlobUrl]);
+
+  // Create LQIP for progressive loading
+  useEffect(() => {
+    if (!src || !useProgressiveLoading) {
+      setLqip(null);
+      setIsFullyLoaded(true);
+      return;
+    }
+
+    setIsFullyLoaded(false);
+
+    // Create low-quality placeholder
+    createLQIP(src).then((placeholder) => {
+      if (placeholder) {
+        setLqip(placeholder);
+      }
+    });
+
+    // Pre-load full image
+    const img = new Image();
+    img.onload = () => {
+      setIsFullyLoaded(true);
+    };
+    img.src = src;
+  }, [src, useProgressiveLoading]);
+
+  return {
+    src,
+    lqip,
+    isFullyLoaded,
+    useProgressiveLoading,
+    error,
+    contentKey: contentKeyRef.current,
+    size,
+    hasContent,
+  };
+}

package/src/tools/ImageViewer/hooks/useImageTransform.ts

@@ -0,0 +1,101 @@
+'use client';
+
+/**
+ * useImageTransform - Manages image rotation and flip state
+ */
+
+import { useState, useCallback, useEffect, useMemo } from 'react';
+import type { ImageTransform } from '../types';
+import { DEFAULT_TRANSFORM } from '../utils';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface UseImageTransformOptions {
+  /** Reset transform when this key changes */
+  resetKey?: string;
+}
+
+export interface UseImageTransformReturn {
+  /** Current transform state */
+  transform: ImageTransform;
+  /** Rotate 90 degrees clockwise */
+  rotate: () => void;
+  /** Toggle horizontal flip */
+  flipH: () => void;
+  /** Toggle vertical flip */
+  flipV: () => void;
+  /** Reset all transforms */
+  reset: () => void;
+  /** CSS transform string for applying to image */
+  transformStyle: string;
+}
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useImageTransform(
+  options: UseImageTransformOptions = {}
+): UseImageTransformReturn {
+  const { resetKey } = options;
+
+  const [transform, setTransform] = useState<ImageTransform>(DEFAULT_TRANSFORM);
+
+  // Reset transform when key changes
+  useEffect(() => {
+    setTransform(DEFAULT_TRANSFORM);
+  }, [resetKey]);
+
+  const rotate = useCallback(() => {
+    setTransform((prev) => ({
+      ...prev,
+      rotation: (prev.rotation + 90) % 360,
+    }));
+  }, []);
+
+  const flipH = useCallback(() => {
+    setTransform((prev) => ({
+      ...prev,
+      flipH: !prev.flipH,
+    }));
+  }, []);
+
+  const flipV = useCallback(() => {
+    setTransform((prev) => ({
+      ...prev,
+      flipV: !prev.flipV,
+    }));
+  }, []);
+
+  const reset = useCallback(() => {
+    setTransform(DEFAULT_TRANSFORM);
+  }, []);
+
+  // Build CSS transform string
+  const transformStyle = useMemo(() => {
+    const transforms: string[] = [];
+
+    if (transform.rotation !== 0) {
+      transforms.push(`rotate(${transform.rotation}deg)`);
+    }
+    if (transform.flipH) {
+      transforms.push('scaleX(-1)');
+    }
+    if (transform.flipV) {
+      transforms.push('scaleY(-1)');
+    }
+
+    return transforms.join(' ') || 'none';
+  }, [transform]);
+
+  return {
+    transform,
+    rotate,
+    flipH,
+    flipV,
+    reset,
+    transformStyle,
+  };
+}

package/src/tools/ImageViewer/index.ts

@@ -0,0 +1,60 @@
+/**
+ * ImageViewer - Image viewer with zoom, pan, rotate, flip
+ *
+ * Features:
+ * - Zoom with mouse wheel and presets (25%, 50%, 100%, 200%, 400%)
+ * - Pan with drag
+ * - Rotate 90°
+ * - Flip horizontal/vertical
+ * - Fullscreen dialog mode
+ * - Keyboard shortcuts (+/-, 0 for reset, r for rotate)
+ * - Progressive loading with LQIP for large images
+ * - Checkerboard background for transparency
+ * - Image dimensions display with caching
+ */
+
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+
+export { ImageViewer, ImageToolbar, ImageInfo } from './components';
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+export { useImageTransform, useImageLoading } from './hooks';
+export type {
+  UseImageTransformOptions,
+  UseImageTransformReturn,
+  UseImageLoadingOptions,
+  UseImageLoadingReturn,
+} from './hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type {
+  ImageFile,
+  ImageViewerProps,
+  ImageToolbarProps,
+  ImageInfoProps,
+  ImageTransform,
+  ZoomPreset,
+} from './types';
+
+// =============================================================================
+// UTILS
+// =============================================================================
+
+export {
+  createLQIP,
+  MAX_IMAGE_SIZE,
+  WARNING_IMAGE_SIZE,
+  PROGRESSIVE_LOADING_THRESHOLD,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  ZOOM_PRESETS,
+  DEFAULT_TRANSFORM,
+} from './utils';

package/src/tools/ImageViewer/types.ts

@@ -0,0 +1,75 @@
+/**
+ * ImageViewer type definitions
+ */
+
+// =============================================================================
+// FILE TYPES
+// =============================================================================
+
+export interface ImageFile {
+  /** Display name for the image */
+  name: string;
+  /** File path used for change detection and caching */
+  path: string;
+  /** Optional MIME type */
+  mimeType?: string;
+}
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ImageViewerProps {
+  /** File info (name, path, mimeType) */
+  file: ImageFile;
+  /** Image content as string (data URL or base64) or ArrayBuffer */
+  content: string | ArrayBuffer;
+  /** Hide expand button when already in dialog */
+  inDialog?: boolean;
+}
+
+export interface ImageToolbarProps {
+  /** Current zoom scale */
+  scale: number;
+  /** Current transform state */
+  transform: ImageTransform;
+  /** Rotate image callback */
+  onRotate: () => void;
+  /** Flip horizontal callback */
+  onFlipH: () => void;
+  /** Flip vertical callback */
+  onFlipV: () => void;
+  /** Zoom preset selection callback */
+  onZoomPreset: (value: number | 'fit') => void;
+  /** Expand to fullscreen callback (undefined hides button) */
+  onExpand?: () => void;
+}
+
+export interface ImageInfoProps {
+  /** Image source URL */
+  src: string;
+}
+
+// =============================================================================
+// STATE TYPES
+// =============================================================================
+
+export interface ImageTransform {
+  /** Rotation angle: 0, 90, 180, or 270 degrees */
+  rotation: number;
+  /** Horizontal flip state */
+  flipH: boolean;
+  /** Vertical flip state */
+  flipV: boolean;
+}
+
+// =============================================================================
+// UI TYPES
+// =============================================================================
+
+export interface ZoomPreset {
+  /** Display label (e.g., "100%", "Fit") */
+  label: string;
+  /** Zoom value or 'fit' for fit-to-view */
+  value: number | 'fit';
+}

package/src/tools/ImageViewer/utils/constants.ts

@@ -0,0 +1,59 @@
+/**
+ * ImageViewer constants
+ */
+
+import type { ZoomPreset, ImageTransform } from '../types';
+
+// =============================================================================
+// SIZE LIMITS
+// =============================================================================
+
+/** Maximum image size before blocking (50MB) */
+export const MAX_IMAGE_SIZE = 50 * 1024 * 1024;
+
+/** Image size threshold for warning (10MB) */
+export const WARNING_IMAGE_SIZE = 10 * 1024 * 1024;
+
+/** Progressive loading threshold - use LQIP for images > 500KB */
+export const PROGRESSIVE_LOADING_THRESHOLD = 500 * 1024;
+
+// =============================================================================
+// LQIP CONFIGURATION
+// =============================================================================
+
+/** Low-quality placeholder size (32x32) */
+export const LQIP_SIZE = 32;
+
+/** LQIP JPEG quality */
+export const LQIP_QUALITY = 0.5;
+
+// =============================================================================
+// ZOOM CONFIGURATION
+// =============================================================================
+
+/** Minimum zoom level */
+export const MIN_ZOOM = 0.1;
+
+/** Maximum zoom level */
+export const MAX_ZOOM = 8;
+
+/** Available zoom presets */
+export const ZOOM_PRESETS: readonly ZoomPreset[] = [
+  { label: 'Fit', value: 'fit' },
+  { label: '25%', value: 0.25 },
+  { label: '50%', value: 0.5 },
+  { label: '100%', value: 1 },
+  { label: '200%', value: 2 },
+  { label: '400%', value: 4 },
+] as const;
+
+// =============================================================================
+// DEFAULT VALUES
+// =============================================================================
+
+/** Default transform state */
+export const DEFAULT_TRANSFORM: ImageTransform = {
+  rotation: 0,
+  flipH: false,
+  flipV: false,
+};