@djangocfg/ui-nextjs 2.1.66 → 2.1.68

package/src/tools/ImageViewer/@refactoring/01-TYPES.md

@@ -0,0 +1,121 @@
+# Phase 1: Types Extraction
+
+## Goal
+
+Extract all type definitions from ImageViewer.tsx into a dedicated types.ts file.
+
+## Types to Extract
+
+### ImageFile (Props)
+```typescript
+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;
+}
+```
+
+### ImageViewerProps (Props)
+```typescript
+export interface ImageViewerProps {
+  /** Image file metadata */
+  file: ImageFile;
+  /** Image content as string or ArrayBuffer */
+  content: string | ArrayBuffer;
+  /** Whether viewer is inside a dialog (hides expand button) */
+  inDialog?: boolean;
+}
+```
+
+### ImageTransform (State)
+```typescript
+export interface ImageTransform {
+  /** Rotation angle: 0, 90, 180, or 270 degrees */
+  rotation: number;
+  /** Horizontal flip state */
+  flipH: boolean;
+  /** Vertical flip state */
+  flipV: boolean;
+}
+```
+
+### ZoomPreset (UI)
+```typescript
+export interface ZoomPreset {
+  /** Zoom level (1 = 100%) */
+  value: number;
+  /** Display label (e.g., "100%") */
+  label: string;
+}
+```
+
+### ImageToolbarProps (Internal)
+```typescript
+export interface ImageToolbarProps {
+  /** Current zoom scale */
+  scale: number;
+  /** Expand to fullscreen callback */
+  onExpand: () => void;
+  /** Rotate image callback */
+  onRotate: () => void;
+  /** Flip horizontal callback */
+  onFlipH: () => void;
+  /** Flip vertical callback */
+  onFlipV: () => void;
+  /** Whether horizontal flip is active */
+  flipH: boolean;
+  /** Whether vertical flip is active */
+  flipV: boolean;
+  /** Whether inside dialog (hides expand) */
+  inDialog?: boolean;
+}
+```
+
+### ImageInfoProps (Internal)
+```typescript
+export interface ImageInfoProps {
+  /** Blob URL source of the image */
+  src: string;
+  /** Content key for cache lookup */
+  contentKey: string;
+}
+```
+
+## File Structure
+
+```typescript
+// types.ts
+
+/**
+ * ImageViewer type definitions
+ */
+
+// =============================================================================
+// FILE TYPES
+// =============================================================================
+
+export interface ImageFile { ... }
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ImageViewerProps { ... }
+export interface ImageToolbarProps { ... }
+export interface ImageInfoProps { ... }
+
+// =============================================================================
+// STATE TYPES
+// =============================================================================
+
+export interface ImageTransform { ... }
+
+// =============================================================================
+// UI TYPES
+// =============================================================================
+
+export interface ZoomPreset { ... }
+```

package/src/tools/ImageViewer/@refactoring/02-UTILS.md

@@ -0,0 +1,143 @@
+# Phase 2: Utils Extraction
+
+## Goal
+
+Extract constants and utility functions into dedicated files.
+
+## Files to Create
+
+### utils/constants.ts
+
+```typescript
+/**
+ * ImageViewer constants
+ */
+
+import type { ZoomPreset } 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 WARN_IMAGE_SIZE = 10 * 1024 * 1024;
+
+// =============================================================================
+// ZOOM CONFIGURATION
+// =============================================================================
+
+/** Minimum zoom level */
+export const MIN_ZOOM = 0.25;
+
+/** Maximum zoom level */
+export const MAX_ZOOM = 4;
+
+/** Available zoom presets */
+export const ZOOM_PRESETS: ZoomPreset[] = [
+  { value: 0.25, label: '25%' },
+  { value: 0.5, label: '50%' },
+  { value: 1, label: '100%' },
+  { value: 2, label: '200%' },
+  { value: 4, label: '400%' },
+  { value: -1, label: 'Fit' }, // Special value for fit-to-view
+];
+
+// =============================================================================
+// DEFAULT VALUES
+// =============================================================================
+
+/** Default transform state */
+export const DEFAULT_TRANSFORM: ImageTransform = {
+  rotation: 0,
+  flipH: false,
+  flipV: false,
+};
+```
+
+### utils/lqip.ts
+
+```typescript
+/**
+ * LQIP (Low-Quality Image Placeholder) generator
+ *
+ * Creates a tiny blurred preview image for progressive loading.
+ */
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const LQIP_SIZE = 32;
+const LQIP_QUALITY = 0.5;
+
+// =============================================================================
+// GENERATOR
+// =============================================================================
+
+/**
+ * Create a low-quality image placeholder from source URL
+ *
+ * @param src - Full quality image URL
+ * @returns Data URL of tiny preview, or null on error
+ */
+export async function createLQIP(src: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const img = new Image();
+
+    img.onload = () => {
+      try {
+        // Calculate aspect-preserving dimensions
+        const aspectRatio = img.width / img.height;
+        const width = aspectRatio >= 1 ? LQIP_SIZE : Math.round(LQIP_SIZE * aspectRatio);
+        const height = aspectRatio >= 1 ? Math.round(LQIP_SIZE / aspectRatio) : LQIP_SIZE;
+
+        // Create tiny canvas
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+
+        // Draw and export as JPEG
+        const ctx = canvas.getContext('2d');
+        if (ctx) {
+          ctx.drawImage(img, 0, 0, width, height);
+          resolve(canvas.toDataURL('image/jpeg', LQIP_QUALITY));
+        } else {
+          resolve(null);
+        }
+      } catch {
+        resolve(null);
+      }
+    };
+
+    img.onerror = () => resolve(null);
+    img.src = src;
+  });
+}
+```
+
+### utils/index.ts
+
+```typescript
+/**
+ * ImageViewer utilities - Public API
+ */
+
+export { createLQIP } from './lqip';
+export {
+  MAX_IMAGE_SIZE,
+  WARN_IMAGE_SIZE,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  ZOOM_PRESETS,
+  DEFAULT_TRANSFORM,
+} from './constants';
+```
+
+## Notes
+
+- Constants are separated for easy modification
+- LQIP is async and handles errors gracefully
+- No dependencies on React in utils

package/src/tools/ImageViewer/@refactoring/03-HOOKS.md

@@ -0,0 +1,261 @@
+# Phase 3: Hooks Extraction
+
+## Goal
+
+Extract state management logic into reusable custom hooks.
+
+## Files to Create
+
+### hooks/useImageTransform.ts
+
+Manages rotation and flip transformations.
+
+```typescript
+'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';
+
+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;
+}
+
+export function useImageTransform(
+  options: UseImageTransformOptions = {}
+): UseImageTransformReturn {
+  const { resetKey } = options;
+
+  const [transform, setTransform] = useState<ImageTransform>(DEFAULT_TRANSFORM);
+
+  // Reset transform when key changes
+  useEffect(() => {
+    if (resetKey) {
+      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(' ');
+  }, [transform]);
+
+  return {
+    transform,
+    rotate,
+    flipH,
+    flipV,
+    reset,
+    transformStyle,
+  };
+}
+```
+
+### hooks/useImageLoading.ts
+
+Manages image loading, blob URLs, and LQIP generation.
+
+```typescript
+'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, WARN_IMAGE_SIZE } from '../utils';
+
+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 image is loading */
+  isLoading: boolean;
+  /** Whether high-quality image is ready */
+  isReady: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** Content key for caching */
+  contentKey: string;
+  /** Image size in bytes */
+  size: number;
+  /** Whether image exceeds size limit */
+  isOversized: boolean;
+  /** Whether image exceeds warning threshold */
+  isLarge: boolean;
+}
+
+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 [isLoading, setIsLoading] = useState(true);
+  const [isReady, setIsReady] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const contentKeyRef = useRef<string>('');
+
+  // Calculate size and limits
+  const size = content instanceof ArrayBuffer
+    ? content.byteLength
+    : content.length;
+  const isOversized = size > MAX_IMAGE_SIZE;
+  const isLarge = size > WARN_IMAGE_SIZE;
+
+  // Generate content key
+  const contentKey = generateContentKey(content);
+  contentKeyRef.current = contentKey;
+
+  // Create blob URL and LQIP
+  useEffect(() => {
+    if (isOversized) {
+      setError(`Image too large (${(size / 1024 / 1024).toFixed(1)}MB). Maximum: 50MB`);
+      setIsLoading(false);
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+    setIsReady(false);
+    setLqip(null);
+
+    // Create blob URL
+    const blobUrl = getOrCreateBlobUrl(content, mimeType);
+    setSrc(blobUrl);
+
+    // Generate LQIP for progressive loading
+    if (isLarge) {
+      createLQIP(blobUrl).then((placeholder) => {
+        if (contentKeyRef.current === contentKey) {
+          setLqip(placeholder);
+        }
+      });
+    }
+
+    // Preload full image
+    const img = new Image();
+    img.onload = () => {
+      if (contentKeyRef.current === contentKey) {
+        setIsReady(true);
+        setIsLoading(false);
+      }
+    };
+    img.onerror = () => {
+      if (contentKeyRef.current === contentKey) {
+        setError('Failed to load image');
+        setIsLoading(false);
+      }
+    };
+    img.src = blobUrl;
+
+    // Cleanup
+    return () => {
+      releaseBlobUrl(blobUrl);
+    };
+  }, [content, contentKey, mimeType, isOversized, isLarge, size, getOrCreateBlobUrl, releaseBlobUrl]);
+
+  return {
+    src,
+    lqip,
+    isLoading,
+    isReady,
+    error,
+    contentKey,
+    size,
+    isOversized,
+    isLarge,
+  };
+}
+```
+
+### hooks/index.ts
+
+```typescript
+/**
+ * ImageViewer hooks - Public API
+ */
+
+export { useImageTransform } from './useImageTransform';
+export type { UseImageTransformOptions, UseImageTransformReturn } from './useImageTransform';
+
+export { useImageLoading } from './useImageLoading';
+export type { UseImageLoadingOptions, UseImageLoadingReturn } from './useImageLoading';
+```
+
+## Benefits
+
+1. **Reusable** - Hooks can be used in other components
+2. **Testable** - Easy to unit test state logic
+3. **Clean** - Main component becomes much simpler
+4. **Separated** - Transform logic independent of loading logic