@djangocfg/widget-media 0.1.1

package/src/image-viewer/components/MiddleEllipsis.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+/**
+ * MiddleEllipsis - Finder/Quick-Look-style middle truncation for filenames.
+ *
+ * macOS truncates a too-long filename in the MIDDLE so the start AND the
+ * extension stay readable ("screencapture-referee…very-long-name.png"),
+ * unlike a plain CSS `truncate` which clips the (most meaningful) extension.
+ *
+ * This is a CSS-only technique — no JS measurement, no ResizeObserver:
+ *   - The "head" span flex-shrinks and truncates with an end-ellipsis.
+ *   - The "tail" span is pinned (flex-shrink-0) and always shows the last
+ *     `tailChars` characters, which include the extension.
+ * When the name fits, the head shows in full and no ellipsis appears; when it
+ * overflows, the head clips while the tail (extension) is preserved.
+ */
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+interface MiddleEllipsisProps {
+  /** Full text to display. The container caps the width; CSS does the rest. */
+  text: string;
+  /**
+   * How many trailing characters to keep pinned (and thus always visible).
+   * Sized to comfortably cover an extension plus a little of the name tail.
+   */
+  tailChars?: number;
+  className?: string;
+}
+
+export function MiddleEllipsis({ text, tailChars = 8, className }: MiddleEllipsisProps) {
+  // Split so the tail keeps the extension visible. Guard against short names
+  // (where head/tail would overlap) by rendering them whole in the head.
+  const splitAt = Math.max(0, text.length - tailChars);
+  const head = text.slice(0, splitAt);
+  const tail = text.slice(splitAt);
+  const short = splitAt === 0;
+
+  return (
+    // `title` gives the full, lossless name on hover.
+    <span className={cn('flex min-w-0 items-center', className)} title={text}>
+      <span className="min-w-0 flex-1 truncate">{short ? text : head}</span>
+      {!short && <span className="flex-shrink-0 whitespace-pre">{tail}</span>}
+    </span>
+  );
+}

package/src/image-viewer/components/index.ts

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

package/src/image-viewer/hooks/index.ts

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

package/src/image-viewer/hooks/useIdleChrome.ts

@@ -0,0 +1,73 @@
+'use client';
+
+/**
+ * useIdleChrome - Auto-hides floating lightbox chrome when the pointer rests.
+ *
+ * macOS Quick Look / Preview hide their controls after a short idle period and
+ * bring them back on the slightest pointer movement. This hook tracks that
+ * "active" flag and gives back the pointer handlers to wire onto the canvas.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { CHROME_IDLE_MS } from '../utils';
+
+export interface UseIdleChromeReturn {
+  /** True while the chrome should be visible (recent pointer activity). */
+  active: boolean;
+  /** Pointer-move handler — call to mark activity (resets the idle timer). */
+  onActivity: () => void;
+  /** Pin the chrome open (e.g. while hovering a control) regardless of idle. */
+  setPinned: (pinned: boolean) => void;
+}
+
+export function useIdleChrome(enabled: boolean): UseIdleChromeReturn {
+  const [active, setActive] = useState(true);
+  const pinnedRef = useRef(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clear = useCallback(() => {
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  const schedule = useCallback(() => {
+    clear();
+    if (!enabled) return;
+    timerRef.current = setTimeout(() => {
+      if (!pinnedRef.current) setActive(false);
+    }, CHROME_IDLE_MS);
+  }, [clear, enabled]);
+
+  const onActivity = useCallback(() => {
+    setActive(true);
+    schedule();
+  }, [schedule]);
+
+  const setPinned = useCallback(
+    (pinned: boolean) => {
+      pinnedRef.current = pinned;
+      if (pinned) {
+        clear();
+        setActive(true);
+      } else {
+        schedule();
+      }
+    },
+    [clear, schedule],
+  );
+
+  // Start the idle countdown on mount; chrome shows briefly then fades.
+  useEffect(() => {
+    if (!enabled) {
+      setActive(true);
+      return;
+    }
+    schedule();
+    return clear;
+  }, [enabled, schedule, clear]);
+
+  return { active, onActivity, setPinned };
+}

package/src/image-viewer/hooks/useImageLoading.ts

@@ -0,0 +1,220 @@
+'use client';
+
+/**
+ * useImageLoading - Manages image loading state with LQIP
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+import { generateContentKey, useMediaCacheStore } from '../../internal/media-cache';
+import {
+    createLQIP, imageDebug, MAX_IMAGE_SIZE, PROGRESSIVE_LOADING_THRESHOLD, WARNING_IMAGE_SIZE
+} from '../utils';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface UseImageLoadingOptions {
+  /** Image content (ArrayBuffer or string) */
+  content: string | ArrayBuffer;
+  /** MIME type for blob creation */
+  mimeType?: string;
+  /**
+   * Direct image URL (bypasses content→blob conversion).
+   * When provided, content is ignored and URL is used directly.
+   */
+  src?: 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, src: directSrc } = options;
+
+  // Get stable function references from store (not from hook to avoid re-renders)
+  const getOrCreateBlobUrl = useMediaCacheStore.getState().getOrCreateBlobUrl;
+  const releaseBlobUrl = useMediaCacheStore.getState().releaseBlobUrl;
+
+  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);
+  const isMountedRef = useRef(true);
+
+  // Calculate size and flags
+  const size = content ? (typeof content === 'string' ? content.length : content.byteLength) : 0;
+  // When directSrc is provided, we have content (the URL itself)
+  const hasContent = directSrc ? true : size > 0;
+  const useProgressiveLoading = directSrc ? false : size > PROGRESSIVE_LOADING_THRESHOLD;
+
+  // Track unmount for cleanup
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+      // Release blob URL only on actual unmount
+      if (contentKeyRef.current) {
+        useMediaCacheStore.getState().releaseBlobUrl(contentKeyRef.current);
+        contentKeyRef.current = null;
+      }
+    };
+  }, []);
+
+  // Create blob URL with caching and size validation
+  useEffect(() => {
+    // Reset error state
+    setError(null);
+
+    // Direct URL mode - use as-is without blob conversion
+    if (directSrc) {
+      imageDebug.load(directSrc, 'url');
+      setSrc(directSrc);
+      setIsFullyLoaded(true);
+      return;
+    }
+
+    if (!hasContent) {
+      setSrc(null);
+      return;
+    }
+
+    // Size validation - reject oversized images
+    if (size > MAX_IMAGE_SIZE) {
+      const sizeMB = (size / 1024 / 1024).toFixed(1);
+      const errorMsg = `Image too large: ${sizeMB}MB (maximum: 50MB)`;
+      imageDebug.error(errorMsg, { size, sizeMB, maxSize: MAX_IMAGE_SIZE });
+      setError(errorMsg);
+      setSrc(null);
+      return;
+    }
+
+    // Warn about large images
+    if (size > WARNING_IMAGE_SIZE) {
+      const sizeMB = (size / 1024 / 1024).toFixed(1);
+      imageDebug.warn(`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:')) {
+        imageDebug.load(content.slice(0, 50) + '...', 'data-url');
+        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);
+
+      // Release previous blob URL if content changed
+      if (contentKeyRef.current && contentKeyRef.current !== contentKey) {
+        releaseBlobUrl(contentKeyRef.current);
+      }
+
+      contentKeyRef.current = contentKey;
+      const url = getOrCreateBlobUrl(contentKey, buffer, mimeType || 'image/png');
+      imageDebug.load(url, 'blob');
+      imageDebug.state('loaded', { size, mimeType, contentKey });
+      setSrc(url);
+      return;
+    }
+
+    // Handle ArrayBuffer with cached blob URL
+    const contentKey = generateContentKey(content);
+
+    // Release previous blob URL if content changed
+    if (contentKeyRef.current && contentKeyRef.current !== contentKey) {
+      releaseBlobUrl(contentKeyRef.current);
+    }
+
+    contentKeyRef.current = contentKey;
+    const url = getOrCreateBlobUrl(contentKey, content, mimeType || 'image/png');
+    imageDebug.load(url, 'blob');
+    imageDebug.state('loaded', { size, mimeType, contentKey });
+    setSrc(url);
+
+    // No cleanup here - cleanup happens in unmount effect above
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [content, mimeType, hasContent, size, directSrc]);
+
+  // Create LQIP for progressive loading
+  useEffect(() => {
+    if (!src || !useProgressiveLoading) {
+      setLqip(null);
+      setIsFullyLoaded(true);
+      return;
+    }
+
+    setLqip(null);
+    setIsFullyLoaded(false);
+    imageDebug.state('progressive loading', { size });
+
+    // Guard against state updates after src change / unmount
+    let cancelled = false;
+
+    // Create low-quality placeholder
+    createLQIP(src).then((placeholder) => {
+      if (cancelled || !isMountedRef.current) return;
+      if (placeholder) {
+        imageDebug.debug('LQIP created');
+        setLqip(placeholder);
+      }
+    });
+
+    // Pre-load full image
+    const img = new Image();
+    img.onload = () => {
+      if (cancelled || !isMountedRef.current) return;
+      imageDebug.state('fully loaded');
+      setIsFullyLoaded(true);
+    };
+    img.onerror = () => {
+      imageDebug.error('Failed to load full image');
+    };
+    img.src = src;
+
+    return () => {
+      cancelled = true;
+      img.onload = null;
+      img.onerror = null;
+      img.src = '';
+    };
+  }, [src, useProgressiveLoading, size]);
+
+  return {
+    src,
+    lqip,
+    isFullyLoaded,
+    useProgressiveLoading,
+    error,
+    contentKey: contentKeyRef.current,
+    size,
+    hasContent,
+  };
+}

package/src/image-viewer/hooks/useImageTransform.ts

@@ -0,0 +1,102 @@
+'use client';
+
+/**
+ * useImageTransform - Manages image rotation and flip state
+ */
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { DEFAULT_TRANSFORM } from '../utils';
+
+import type { ImageTransform } from '../types';
+// =============================================================================
+// 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/image-viewer/index.ts

@@ -0,0 +1,65 @@
+/**
+ * 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';
+
+// The lazy wrapper is what every caller here imports: the viewer carries
+// react-zoom-pan-pinch, and no chat turn needs it until a reader opens a
+// picture. Exported from the same entry so choosing it costs no extra subpath.
+export { LazyImageViewer } from './lazy';
+
+// =============================================================================
+// 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/image-viewer/lazy.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+/**
+ * Lazy-loaded ImageViewer.
+ *
+ * The viewer carries react-zoom-pan-pinch (~50KB), which no chat turn needs
+ * until a reader actually opens a picture — so it is split out and mounted on
+ * demand rather than shipped in the first paint.
+ */
+
+import { lazy, Suspense } from 'react';
+
+import type { ImageViewerProps } from './types';
+
+export type { ImageViewerProps };
+
+const ImageViewerImpl = lazy(() =>
+  import('./components').then((mod) => ({ default: mod.ImageViewer })),
+);
+
+// Reserves the viewer's minimum height while the chunk arrives: a zero-height
+// fallback collapses the dialog and the image then pops it back open.
+function Fallback() {
+  return <div aria-hidden className="min-h-[200px]" />;
+}
+
+export function LazyImageViewer(props: ImageViewerProps) {
+  return (
+    <Suspense fallback={<Fallback />}>
+      <ImageViewerImpl {...props} />
+    </Suspense>
+  );
+}