@djangocfg/ui-nextjs 2.1.65 → 2.1.67

package/src/tools/ImageViewer/@refactoring/05-EXECUTION-CHECKLIST.md

@@ -0,0 +1,126 @@
+# Execution Checklist
+
+## Pre-flight
+
+- [ ] Read current ImageViewer.tsx
+- [ ] Backup or rename original file
+- [ ] Create folder structure
+
+## Phase 1: Folder Structure
+
+- [ ] Create `components/` directory
+- [ ] Create `hooks/` directory
+- [ ] Create `utils/` directory
+
+```bash
+mkdir -p components hooks utils
+```
+
+## Phase 2: Types
+
+- [ ] Create `types.ts` with all interfaces
+  - ImageFile
+  - ImageViewerProps
+  - ImageTransform
+  - ZoomPreset
+  - ImageToolbarProps
+  - ImageInfoProps
+- [ ] Run `pnpm check`
+
+## Phase 3: Utils
+
+- [ ] Create `utils/constants.ts`
+  - MAX_IMAGE_SIZE, WARN_IMAGE_SIZE
+  - MIN_ZOOM, MAX_ZOOM
+  - ZOOM_PRESETS
+  - DEFAULT_TRANSFORM
+- [ ] Create `utils/lqip.ts`
+  - createLQIP function
+- [ ] Create `utils/index.ts`
+  - Re-export all
+- [ ] Run `pnpm check`
+
+## Phase 4: Hooks
+
+- [ ] Create `hooks/useImageTransform.ts`
+  - Transform state management
+  - rotate, flipH, flipV callbacks
+  - transformStyle computed value
+- [ ] Create `hooks/useImageLoading.ts`
+  - Blob URL management
+  - LQIP generation
+  - Loading/error states
+- [ ] Create `hooks/index.ts`
+  - Re-export all
+- [ ] Run `pnpm check`
+
+## Phase 5: Components
+
+- [ ] Create `components/ImageToolbar.tsx`
+  - Zoom controls
+  - Rotate/flip buttons
+  - Preset dropdown
+- [ ] Create `components/ImageInfo.tsx`
+  - Dimensions display
+- [ ] Create `components/ImageViewer.tsx`
+  - Main component (simplified)
+  - Uses hooks
+  - Includes fullscreen dialog
+- [ ] Create `components/index.ts`
+  - Re-export all
+- [ ] Run `pnpm check`
+
+## Phase 6: Main Index
+
+- [ ] Update `index.ts` with new imports
+  - Export ImageViewer from components
+  - Export types
+  - Export hooks (if public)
+- [ ] Run `pnpm check`
+
+## Phase 7: Cleanup
+
+- [ ] Delete old `ImageViewer.tsx`
+- [ ] Verify all exports work
+- [ ] Run `pnpm check`
+- [ ] Run `pnpm build` (optional)
+
+## Post-flight
+
+- [ ] Test in browser
+- [ ] Verify zoom/pan/rotate work
+- [ ] Verify fullscreen works
+- [ ] Verify LQIP loads for large images
+- [ ] Verify error states display
+
+## Final Structure
+
+```
+ImageViewer/
+├── index.ts
+├── types.ts
+├── README.md
+├── components/
+│   ├── index.ts
+│   ├── ImageViewer.tsx
+│   ├── ImageToolbar.tsx
+│   └── ImageInfo.tsx
+├── hooks/
+│   ├── index.ts
+│   ├── useImageTransform.ts
+│   └── useImageLoading.ts
+└── utils/
+    ├── index.ts
+    ├── constants.ts
+    └── lqip.ts
+```
+
+## Metrics
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Main file lines | 589 | ~150 |
+| Total files | 3 | 12 |
+| Sub-components | 2 inline | 2 separate |
+| Custom hooks | 0 | 2 |
+| Utility files | 0 | 2 |

package/src/tools/ImageViewer/README.md

@@ -0,0 +1,174 @@
+# ImageViewer
+
+Image viewer with zoom, pan, rotate, and flip functionality.
+
+## Features
+
+- Mouse wheel zoom
+- Drag to pan
+- Zoom presets (25%, 50%, 100%, 200%, 400%)
+- Rotate 90°
+- Flip horizontal/vertical
+- Fullscreen dialog mode
+- Keyboard shortcuts
+- Checkerboard background for transparency
+- Image dimensions display
+
+## Installation
+
+```tsx
+import { ImageViewer } from '@djangocfg/ui-nextjs';
+```
+
+## Basic Usage
+
+```tsx
+<ImageViewer
+  file={{
+    name: 'photo.jpg',
+    path: '/images/photo.jpg',
+    mimeType: 'image/jpeg',
+  }}
+  content={imageArrayBuffer}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `file` | `ImageFile` | required | File info (name, path, mimeType) |
+| `content` | `string \| ArrayBuffer` | required | Image data |
+| `inDialog` | `boolean` | `false` | Hide expand button (for nested usage) |
+
+## ImageFile Type
+
+```typescript
+interface ImageFile {
+  name: string;       // Display name
+  path: string;       // File path (for state tracking)
+  mimeType?: string;  // MIME type (e.g., 'image/png')
+}
+```
+
+## Content Formats
+
+The `content` prop accepts:
+
+- **ArrayBuffer**: Binary image data (creates blob URL)
+- **Data URL**: Base64 encoded string starting with `data:`
+- **Base64 string**: Raw base64 (auto-prefixed with data URL)
+
+```tsx
+// ArrayBuffer (from fetch or file read)
+const response = await fetch('/image.png');
+const buffer = await response.arrayBuffer();
+<ImageViewer file={file} content={buffer} />
+
+// Data URL
+<ImageViewer file={file} content="data:image/png;base64,iVBORw0KGgo..." />
+
+// Base64 string (auto-converted to data URL)
+<ImageViewer file={file} content="iVBORw0KGgo..." />
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `+` / `=` | Zoom in |
+| `-` | Zoom out |
+| `0` | Reset to fit |
+| `R` | Rotate 90° |
+
+## Toolbar Controls
+
+The floating toolbar at the bottom provides:
+
+- **Zoom out** button
+- **Zoom level** dropdown with presets
+- **Zoom in** button
+- **Fit to view** button
+- **Flip horizontal** toggle
+- **Flip vertical** toggle
+- **Rotate 90°** button
+- **Expand** fullscreen button
+
+## Fullscreen Mode
+
+Click the expand button to open the image in a fullscreen dialog. The dialog includes the same toolbar and supports all interactions.
+
+```tsx
+// Fullscreen is automatically available unless inDialog is true
+<ImageViewer file={file} content={content} />
+
+// When embedding in your own dialog, disable the expand button
+<Dialog>
+  <ImageViewer file={file} content={content} inDialog />
+</Dialog>
+```
+
+## Styling
+
+The component fills its container and displays a checkerboard pattern behind transparent images.
+
+```tsx
+<div className="w-full h-[500px]">
+  <ImageViewer file={file} content={content} />
+</div>
+```
+
+## Error State
+
+When content is empty or invalid, displays an error placeholder:
+
+```tsx
+// Shows "Failed to load image" with icon
+<ImageViewer file={file} content="" />
+```
+
+## Example: File Browser Integration
+
+```tsx
+function FilePreview({ file, content }: { file: OpenFile; content: ArrayBuffer }) {
+  const imageFile: ImageFile = {
+    name: file.name,
+    path: file.path,
+    mimeType: file.mimeType,
+  };
+
+  return (
+    <div className="h-full">
+      <ImageViewer file={imageFile} content={content} />
+    </div>
+  );
+}
+```
+
+## Architecture
+
+```
+ImageViewer/
+├── index.ts                    # Public API exports
+├── types.ts                    # Type definitions
+├── components/
+│   ├── index.ts                # Component exports
+│   ├── ImageViewer.tsx         # Main viewer component
+│   ├── ImageToolbar.tsx        # Zoom/rotate/flip controls
+│   └── ImageInfo.tsx           # Dimensions display
+├── hooks/
+│   ├── index.ts
+│   ├── useImageLoading.ts      # Blob URL & LQIP management
+│   └── useImageTransform.ts    # Rotation/flip state
+├── utils/
+│   ├── index.ts
+│   ├── constants.ts            # Size limits, zoom presets
+│   └── lqip.ts                 # Low-Quality Image Placeholder
+└── README.md
+```
+
+## Dependencies
+
+- `react-zoom-pan-pinch` - Zoom and pan functionality
+- `lucide-react` - Icons
+- `@djangocfg/ui-core` - UI components (Button, Dialog, etc.)

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

@@ -0,0 +1,44 @@
+'use client';
+
+/**
+ * ImageInfo - Displays image dimensions badge
+ */
+
+import { useEffect, useState } from 'react';
+import { useImageCache } from '../../../stores/mediaCache';
+import type { ImageInfoProps } from '../types';
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function ImageInfo({ src }: ImageInfoProps) {
+  const { getDimensions, cacheDimensions } = useImageCache();
+  const [dimensions, setDimensions] = useState<{ w: number; h: number } | null>(null);
+
+  useEffect(() => {
+    // Check cache first
+    const cached = getDimensions(src);
+    if (cached) {
+      setDimensions({ w: cached.width, h: cached.height });
+      return;
+    }
+
+    // Load and cache dimensions
+    const img = new Image();
+    img.onload = () => {
+      const dims = { w: img.naturalWidth, h: img.naturalHeight };
+      setDimensions(dims);
+      cacheDimensions(src, { width: dims.w, height: dims.h });
+    };
+    img.src = src;
+  }, [src, getDimensions, cacheDimensions]);
+
+  if (!dimensions) return null;
+
+  return (
+    <div className="absolute top-3 right-3 z-10 px-2 py-1 bg-background/80 backdrop-blur-sm border rounded text-[10px] text-muted-foreground font-mono">
+      {dimensions.w} × {dimensions.h}
+    </div>
+  );
+}

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

@@ -0,0 +1,150 @@
+'use client';
+
+/**
+ * ImageToolbar - Floating toolbar for image controls
+ */
+
+import { useMemo, useCallback } from 'react';
+import { ZoomIn, ZoomOut, RotateCw, FlipHorizontal, FlipVertical, Maximize2, Expand } from 'lucide-react';
+import { useControls } from 'react-zoom-pan-pinch';
+import { Button, cn } from '@djangocfg/ui-core';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '../../../components/dropdown-menu';
+import { ZOOM_PRESETS } from '../utils';
+import type { ImageToolbarProps } from '../types';
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function ImageToolbar({
+  scale,
+  transform,
+  onRotate,
+  onFlipH,
+  onFlipV,
+  onZoomPreset,
+  onExpand,
+}: ImageToolbarProps) {
+  const { zoomIn, zoomOut, resetTransform } = useControls();
+
+  const zoomLabel = useMemo(() => {
+    const percent = Math.round(scale * 100);
+    return `${percent}%`;
+  }, [scale]);
+
+  return (
+    <div className="absolute bottom-4 left-1/2 -translate-x-1/2 z-10 flex items-center gap-0.5 bg-background/90 backdrop-blur-sm border rounded-lg p-1 shadow-lg">
+      {/* Zoom controls */}
+      <Button
+        variant="ghost"
+        size="icon"
+        className="h-7 w-7"
+        onClick={() => zoomOut()}
+        title="Zoom out"
+      >
+        <ZoomOut className="h-3.5 w-3.5" />
+      </Button>
+
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="ghost" size="sm" className="h-7 px-2 min-w-[52px] font-mono text-xs">
+            {zoomLabel}
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="center" className="min-w-[80px]">
+          {ZOOM_PRESETS.map((preset) => (
+            <DropdownMenuItem
+              key={preset.label}
+              onClick={() => onZoomPreset(preset.value)}
+              className="text-xs justify-center"
+            >
+              {preset.label}
+            </DropdownMenuItem>
+          ))}
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      <Button
+        variant="ghost"
+        size="icon"
+        className="h-7 w-7"
+        onClick={() => zoomIn()}
+        title="Zoom in"
+      >
+        <ZoomIn className="h-3.5 w-3.5" />
+      </Button>
+
+      <div className="w-px h-4 bg-border mx-1" />
+
+      {/* Fit to view */}
+      <Button
+        variant="ghost"
+        size="icon"
+        className="h-7 w-7"
+        onClick={() => resetTransform()}
+        title="Fit to view"
+      >
+        <Maximize2 className="h-3.5 w-3.5" />
+      </Button>
+
+      <div className="w-px h-4 bg-border mx-1" />
+
+      {/* Transform controls */}
+      <Button
+        variant="ghost"
+        size="icon"
+        className={cn('h-7 w-7', transform.flipH && 'bg-accent')}
+        onClick={onFlipH}
+        title="Flip horizontal"
+      >
+        <FlipHorizontal className="h-3.5 w-3.5" />
+      </Button>
+
+      <Button
+        variant="ghost"
+        size="icon"
+        className={cn('h-7 w-7', transform.flipV && 'bg-accent')}
+        onClick={onFlipV}
+        title="Flip vertical"
+      >
+        <FlipVertical className="h-3.5 w-3.5" />
+      </Button>
+
+      <Button
+        variant="ghost"
+        size="icon"
+        className="h-7 w-7"
+        onClick={onRotate}
+        title="Rotate 90°"
+      >
+        <RotateCw className="h-3.5 w-3.5" />
+      </Button>
+
+      {transform.rotation !== 0 && (
+        <span className="text-[10px] text-muted-foreground font-mono pl-1">
+          {transform.rotation}°
+        </span>
+      )}
+
+      {onExpand && (
+        <>
+          <div className="w-px h-4 bg-border mx-1" />
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-7 w-7"
+            onClick={onExpand}
+            title="Open in fullscreen"
+          >
+            <Expand className="h-3.5 w-3.5" />
+          </Button>
+        </>
+      )}
+    </div>
+  );
+}