@djangocfg/ui-tools 2.1.207 → 2.1.209

package/src/tools/ImageViewer/README.md

@@ -1,6 +1,6 @@
 # ImageViewer
 
-Image viewer with zoom, pan, rotate, and flip functionality.
+Image viewer with zoom, pan, rotate, flip and gallery navigation.
 
 ## Features
 
@@ -10,26 +10,44 @@ Image viewer with zoom, pan, rotate, and flip functionality.
 - Rotate 90°
 - Flip horizontal/vertical
 - Fullscreen dialog mode
-- Keyboard shortcuts
+- **Gallery mode** — multiple images with prev/next buttons
+- **Keyboard shortcuts** — `+/-/0/r` for zoom/rotate, `←/→` for gallery navigation
 - Checkerboard background for transparency
 - Image dimensions display
 
 ## Installation
 
 ```tsx
-import { ImageViewer } from '@djangocfg/ui-nextjs';
+import { ImageViewer } from '@djangocfg/ui-tools';
 ```
 
 ## Basic Usage
 
 ```tsx
+// Single image — URL
 <ImageViewer
-  file={{
-    name: 'photo.jpg',
-    path: '/images/photo.jpg',
-    mimeType: 'image/jpeg',
-  }}
-  content={imageArrayBuffer}
+  images={[{
+    file: { name: 'photo.jpg', path: '/images/photo.jpg' },
+    src: 'https://example.com/photo.jpg',
+  }]}
+/>
+
+// Single image — raw bytes / base64
+<ImageViewer
+  images={[{
+    file: { name: 'photo.png', path: 'unique-key', mimeType: 'image/png' },
+    content: arrayBuffer,  // ArrayBuffer or base64 string
+  }]}
+/>
+
+// Gallery
+<ImageViewer
+  images={[
+    { file: { name: 'Photo 1', path: 'p1' }, src: 'https://example.com/1.jpg' },
+    { file: { name: 'Photo 2', path: 'p2' }, src: 'https://example.com/2.jpg' },
+    { file: { name: 'Photo 3', path: 'p3' }, src: 'https://example.com/3.jpg' },
+  ]}
+  initialIndex={0}
 />
 ```
 
@@ -37,66 +55,51 @@ import { ImageViewer } from '@djangocfg/ui-nextjs';
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `file` | `ImageFile` | required | File info (name, path, mimeType) |
-| `content` | `string \| ArrayBuffer` | required | Image data |
-| `src` | `string` | - | Direct URL (bypasses content→blob conversion) |
+| `images` | `ImageItem[]` | required | Array of images to display |
+| `initialIndex` | `number` | `0` | Index of the image to show first |
 | `inDialog` | `boolean` | `false` | Hide expand button (for nested usage) |
 
-## ImageFile Type
+## Types
 
 ```typescript
+interface ImageItem {
+  file: ImageFile;
+  src?: string;                    // URL (CDN / server)
+  content?: string | ArrayBuffer;  // Raw bytes or base64 (memory / blob)
+}
+
 interface ImageFile {
   name: string;       // Display name
-  path: string;       // File path (for state tracking)
+  path: string;       // File path (for state tracking / cache key)
   mimeType?: string;  // MIME type (e.g., 'image/png')
 }
 ```
 
-## Content Formats
+Both `src` and `content` are optional — supply whichever you have. When both are provided, `src` takes precedence (passed directly to `useImageLoading` as the direct URL).
 
-The `content` prop accepts:
+### content support
 
-- **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..." />
-
-// Direct URL (HTTP streaming for large files)
-<ImageViewer
-  file={file}
-  content=""
-  src="https://api.example.com/images/large-photo.jpg"
-/>
-```
+| Value | Behaviour |
+|-------|-----------|
+| `data:image/...` string | used directly as `<img src>` |
+| binary string | encoded → Blob URL via `TextEncoder` |
+| `ArrayBuffer` | converted to Blob URL with caching |
 
-## HTTP Streaming
+## Gallery Navigation
 
-For large images, use the `src` prop to stream directly from a URL instead of loading the entire file into memory:
+When `images` has more than one item, prev/next buttons appear and keyboard navigation is enabled:
 
 ```tsx
-// When src is provided, content is ignored
 <ImageViewer
-  file={{ name: 'large-photo.jpg', path: '/photos/large.jpg' }}
-  content=""  // Empty - not used when src is provided
-  src={streamingUrl}
+  images={photos}
+  initialIndex={2}  // open at 3rd photo
 />
 ```
 
-This is useful for:
-- Large images that shouldn't be loaded into memory
-- HTTP Range request streaming
-- Pre-signed URLs with authentication tokens
+| Key | Action |
+|-----|--------|
+| `←` | Previous image |
+| `→` | Next image |
 
 ## Keyboard Shortcuts
 
@@ -106,10 +109,12 @@ This is useful for:
 | `-` | Zoom out |
 | `0` | Reset to fit |
 | `R` | Rotate 90° |
+| `←` | Previous image (gallery) |
+| `→` | Next image (gallery) |
 
 ## Toolbar Controls
 
-The floating toolbar at the bottom provides:
+The floating toolbar provides:
 
 - **Zoom out** button
 - **Zoom level** dropdown with presets
@@ -122,63 +127,38 @@ The floating toolbar at the bottom provides:
 
 ## Fullscreen Mode
 
-Click the expand button to open the image in a fullscreen dialog. The dialog includes the same toolbar and supports all interactions.
+Click the expand button to open in a fullscreen dialog. Gallery navigation works inside the dialog too.
 
 ```tsx
-// Fullscreen is automatically available unless inDialog is true
-<ImageViewer file={file} content={content} />
+// Fullscreen available by default
+<ImageViewer images={images} />
 
-// When embedding in your own dialog, disable the expand button
+// Disable expand button when embedding in your own dialog
 <Dialog>
-  <ImageViewer file={file} content={content} inDialog />
+  <ImageViewer images={images} inDialog />
 </Dialog>
 ```
 
 ## Styling
 
-The component fills its container and displays a checkerboard pattern behind transparent images.
+The component fills its container. Wrap in a sized element:
 
 ```tsx
 <div className="w-full h-[500px]">
-  <ImageViewer file={file} content={content} />
+  <ImageViewer images={images} />
 </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
+├── ImageViewer.story.tsx       # Playground stories
+├── README.md
 ├── components/
-│   ├── index.ts                # Component exports
+│   ├── index.ts
 │   ├── ImageViewer.tsx         # Main viewer component
 │   ├── ImageToolbar.tsx        # Zoom/rotate/flip controls
 │   └── ImageInfo.tsx           # Dimensions display
@@ -186,15 +166,15 @@ ImageViewer/
 │   ├── 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
+└── utils/
+    ├── index.ts
+    ├── constants.ts            # Size limits, zoom presets
+    └── lqip.ts                 # Low-Quality Image Placeholder
 ```
 
 ## Dependencies
 
-- `react-zoom-pan-pinch` - Zoom and pan functionality
-- `lucide-react` - Icons
-- `@djangocfg/ui-core` - UI components (Button, Dialog, etc.)
+- `react-zoom-pan-pinch` — zoom and pan
+- `lucide-react` — icons
+- `@djangocfg/ui-core` — UI components (Button, Dialog, etc.)
+- `@djangocfg/ui-core/hooks` — `useHotkey` for keyboard navigation

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

@@ -1,7 +1,7 @@
 'use client';
 
 /**
- * ImageViewer - Image viewer with zoom, pan, rotate, flip
+ * ImageViewer - Image viewer with zoom, pan, rotate, flip, gallery navigation
  *
  * Features:
  * - Zoom with mouse wheel and presets
@@ -9,26 +9,45 @@
  * - Rotate 90°
  * - Flip horizontal/vertical
  * - Fullscreen dialog
- * - Keyboard shortcuts (+/-, 0, r)
+ * - Keyboard shortcuts (+/-, 0, r, ←/→ for gallery)
+ * - Gallery mode: pass images[] with multiple items
  */
 
 import { useEffect, useState, useRef, useCallback, useMemo } from 'react';
-import { ImageIcon, AlertCircle } from 'lucide-react';
+import { ImageIcon, AlertCircle, ChevronLeft, ChevronRight } from 'lucide-react';
 import { TransformWrapper, TransformComponent, useControls } from 'react-zoom-pan-pinch';
 import { cn, Dialog, DialogContent, DialogTitle, Alert, AlertDescription } from '@djangocfg/ui-core';
 import { useTypedT, type I18nTranslations } from '@djangocfg/i18n';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
 
 import { ImageToolbar } from './ImageToolbar';
 import { ImageInfo } from './ImageInfo';
 import { useImageTransform, useImageLoading } from '../hooks';
-import type { ImageViewerProps } from '../types';
+import type { ImageViewerProps, ImageItem } from '../types';
 
 // =============================================================================
 // COMPONENT
 // =============================================================================
 
-export function ImageViewer({ file, content, src: directSrc, inDialog = false }: ImageViewerProps) {
+export function ImageViewer({
+  images,
+  initialIndex = 0,
+  inDialog = false,
+}: ImageViewerProps) {
   const t = useTypedT<I18nTranslations>();
+
+  const [currentIndex, setCurrentIndex] = useState(() =>
+    Math.max(0, Math.min(initialIndex, images.length - 1))
+  );
+
+  // Reset index when initialIndex changes (e.g. opening different image)
+  useEffect(() => {
+    setCurrentIndex(Math.max(0, Math.min(initialIndex, images.length - 1)));
+  }, [initialIndex, images.length]);
+
+  const current = images[currentIndex];
+  const hasMultiple = images.length > 1;
+
   const [scale, setScale] = useState(1);
   const [dialogOpen, setDialogOpen] = useState(false);
   const [loadError, setLoadError] = useState(false);
@@ -41,7 +60,6 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
     loading: t('ui.form.loading'),
   }), [t]);
 
-  // Loading state
   const {
     src,
     lqip,
@@ -49,72 +67,67 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
     useProgressiveLoading,
     error,
     hasContent,
-  } = useImageLoading({ content, mimeType: file.mimeType, src: directSrc });
+  } = useImageLoading({
+    content: current?.content ?? '',
+    mimeType: current?.file.mimeType,
+    src: current?.src,
+  });
 
-  // Reset load error when src changes
-  useEffect(() => {
-    setLoadError(false);
-  }, [src]);
+  useEffect(() => { setLoadError(false); }, [src]);
 
-  // Transform state
   const { transform, rotate, flipH, flipV, transformStyle } = useImageTransform({
-    resetKey: file.path,
+    resetKey: current?.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);
-    }
+    if (value === 'fit') controlsRef.current.resetTransform();
+    else controlsRef.current.setTransform(0, 0, value);
   }, []);
 
-  // Expand to fullscreen
-  const handleExpand = useCallback(() => {
-    setDialogOpen(true);
-  }, []);
+  const handleExpand = useCallback(() => setDialogOpen(true), []);
 
-  // Keyboard shortcuts
+  const prev = useCallback(() =>
+    setCurrentIndex((i) => (i - 1 + images.length) % images.length),
+    [images.length]
+  );
+
+  const next = useCallback(() =>
+    setCurrentIndex((i) => (i + 1) % images.length),
+    [images.length]
+  );
+
+  // Keyboard: zoom/rotate (only when container focused)
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
       if (!containerRef.current?.contains(document.activeElement) &&
-          document.activeElement !== containerRef.current) {
-        return;
-      }
-
+          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;
+        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 or load errors
+  // Keyboard: gallery navigation (global when open)
+  useHotkey('ArrowLeft', prev, { enabled: hasMultiple, preventDefault: true });
+  useHotkey('ArrowRight', next, { enabled: hasMultiple, preventDefault: true });
+
+  if (!current) {
+    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">{labels.noImage}</p>
+      </div>
+    );
+  }
+
   if (error || loadError) {
     return (
       <div className="flex-1 flex flex-col items-center justify-center gap-3 bg-muted/30 p-4">
@@ -127,7 +140,6 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
     );
   }
 
-  // No content
   if (!hasContent) {
     return (
       <div className="flex-1 flex flex-col items-center justify-center gap-2 bg-muted/30">
@@ -151,7 +163,6 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
     >
       {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" />
@@ -165,13 +176,8 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
         maxScale={8}
         centerOnInit
         centerZoomedOut
-        onTransformed={(ref, state) => {
-          setScale(state.scale);
-          controlsRef.current = ref;
-        }}
-        onInit={(ref) => {
-          controlsRef.current = ref;
-        }}
+        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 }}
@@ -191,34 +197,24 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
           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,
-                }}
+                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}
+                alt={current.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',
+                  transition: useProgressiveLoading ? 'transform 0.15s ease-out, opacity 0.3s ease-out' : 'transform 0.15s ease-out',
                   opacity: useProgressiveLoading && !isFullyLoaded ? 0 : 1,
                 }}
                 draggable={false}
@@ -230,16 +226,39 @@ export function ImageViewer({ file, content, src: directSrc, inDialog = false }:
         </TransformComponent>
       </TransformWrapper>
 
+      {/* Gallery navigation */}
+      {hasMultiple && (
+        <>
+          <button
+            type="button"
+            onClick={prev}
+            className="absolute left-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors"
+          >
+            <ChevronLeft className="h-5 w-5" />
+          </button>
+          <button
+            type="button"
+            onClick={next}
+            className="absolute right-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors"
+          >
+            <ChevronRight className="h-5 w-5" />
+          </button>
+          <div className="absolute bottom-2 left-1/2 -translate-x-1/2 z-10 bg-black/50 text-white text-xs px-2 py-0.5 rounded-full pointer-events-none">
+            {currentIndex + 1} / {images.length}
+          </div>
+        </>
+      )}
+
       {/* 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 flex flex-col">
-            <DialogTitle className="sr-only">{file.name}</DialogTitle>
+            <DialogTitle className="sr-only">{current.file.name}</DialogTitle>
             <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>
+              <span className="text-sm font-medium truncate">{current.file.name}</span>
             </div>
             <div className="flex-1 min-h-0">
-              <ImageViewer file={file} content={content} src={directSrc} inDialog />
+              <ImageViewer images={images} initialIndex={currentIndex} inDialog />
             </div>
           </DialogContent>
         </Dialog>

package/src/tools/ImageViewer/types.ts

@@ -15,21 +15,32 @@ export interface ImageFile {
   mimeType?: string;
 }
 
+export interface ImageItem {
+  /** File info for this image */
+  file: ImageFile;
+  /** Direct image URL (use when serving from CDN/server) */
+  src?: string;
+  /** Raw image content — ArrayBuffer or base64/binary string (use when serving from memory) */
+  content?: string | ArrayBuffer;
+}
+
 // =============================================================================
 // 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;
   /**
-   * Direct image URL for HTTP streaming.
-   * When provided, bypasses content→blob conversion and uses URL directly.
-   * Useful for large files loaded via HTTP Range requests.
+   * Gallery images array.
+   * When provided, enables gallery mode with prev/next navigation.
+   * Single-image mode: pass one item.
+   * Each item can have `src` (URL) or `content` (ArrayBuffer/base64) or both.
    */
-  src?: string;
+  images: ImageItem[];
+  /**
+   * Initial index to show (default: 0).
+   * Useful when opening a specific image from a grid.
+   */
+  initialIndex?: number;
   /** Hide expand button when already in dialog */
   inDialog?: boolean;
 }