@djangocfg/widget-media 0.1.1

package/src/image-viewer/types.ts

@@ -0,0 +1,139 @@
+/**
+ * ImageViewer type definitions
+ */
+
+import type { MediaCopy } from '../i18n';
+
+// =============================================================================
+// 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;
+}
+
+export interface ImageItem {
+  /** File info for this image */
+  file: ImageFile;
+  /** Direct image URL (use when serving from CDN/server) */
+  src?: string;
+  /**
+   * Where the SAVE button reads its bytes, when that is not `src`.
+   *
+   * A browser honours `<a download>` only for a same-origin address; given a
+   * foreign one it silently drops both the attribute and the filename and
+   * navigates instead, so the picture opens in a tab. A host that can serve the
+   * same bytes from its own origin supplies that address here.
+   *
+   * Absent means `src` is already savable — the ordinary case for a blob this
+   * page hosts.
+   */
+  downloadSrc?: string;
+  /** Raw image content — ArrayBuffer or base64/binary string (use when serving from memory) */
+  content?: string | ArrayBuffer;
+}
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ImageViewerProps {
+  /**
+   * 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.
+   */
+  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;
+  /**
+   * Render the restrained macOS-grade fullscreen lightbox chrome instead of
+   * the embedded editing toolbar: a clean dark backdrop (no checkerboard),
+   * idle-fading floating controls (close + prev/next + status pill), and no
+   * rotate/flip slab. Intended for the click-to-expand image lightbox.
+   * Implies `inDialog`.
+   */
+  lightbox?: boolean;
+  /** Close request from the lightbox chrome (Esc / close button). */
+  onRequestClose?: () => void;
+  /**
+   * Fraction of the viewport the image may occupy at rest, in the LIGHTBOX
+   * presentation only (0 < fitScale ≤ 1). `1` (default) lets the image fill
+   * edge-to-edge; `0.8` caps it at 80% so it opens with a comfortable margin
+   * (Preview / Quick Look style) instead of slamming into the window edges.
+   * Zoom / pan still operate from this fitted size. Ignored in the embedded
+   * (non-lightbox) presentation.
+   */
+  fitScale?: number;
+  /** Focus the viewer container on mount so its keyboard scope is active
+   *  immediately (zoom/rotate/gallery hotkeys). Pair with `key={src}`
+   *  upstream when the parent wants a fresh focus per source change. */
+  autoFocus?: boolean;
+  /**
+   * Override any subset of the widget's English copy. Keys omitted fall back
+   * to the defaults, so a host translating one label does not blank the rest.
+   */
+  copy?: Partial<MediaCopy>;
+}
+
+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;
+  /**
+   * Override any subset of the widget's English copy. Keys omitted fall back
+   * to the defaults, so a host translating one label does not blank the rest.
+   */
+  copy?: Partial<MediaCopy>;
+}
+
+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/image-viewer/utils/constants.ts

@@ -0,0 +1,90 @@
+/**
+ * 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;
+
+/** Pixels to pan per arrow-key press */
+export const KEYBOARD_PAN_STEP = 60;
+
+// =============================================================================
+// GESTURE SENSITIVITY (macOS-grade pinch / trackpad zoom)
+// =============================================================================
+//
+// react-zoom-pan-pinch computes the per-event wheel zoom magnitude as
+// `smoothStep * |event.deltaY|` (its `smooth` path), which means the scale
+// tracks the gesture 1:1 — a harder pinch / faster wheel moves more. The
+// library default `smoothStep` is `0.001`, which on a macOS trackpad
+// (whose pinch `deltaY` arrives as small ~±1–6 values with `ctrlKey=true`)
+// produces ~0.005 scale/frame — imperceptible, the "weak pinch" symptom.
+//
+// We raise it so a natural trackpad pinch reaches a meaningful zoom in a
+// single gesture while a mouse-wheel-with-ctrl notch (large |deltaY| ~100)
+// stays a sensible discrete step. The library clamps to min/max scale, so
+// the larger coefficient cannot overshoot the bounds.
+
+/** Wheel/trackpad-pinch zoom sensitivity. scaleΔ = WHEEL_SMOOTH_STEP * |deltaY|. */
+export const WHEEL_SMOOTH_STEP = 0.0055;
+
+/** Touch pinch sensitivity (two-finger pinch on touchscreens). */
+export const PINCH_STEP = 5;
+
+/** Double-click / double-tap zoom multiplier (fit ↔ zoomed toward the point). */
+export const DOUBLE_CLICK_STEP = 1.4;
+
+/** Idle delay (ms) before the lightbox chrome fades out when the pointer rests. */
+export const CHROME_IDLE_MS = 2200;
+
+/** 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,
+};

package/src/image-viewer/utils/debug.ts

@@ -0,0 +1,14 @@
+'use client';
+
+/**
+ * ImageViewer Debug Logger
+ *
+ * Uses universal logger with media-specific helpers.
+ * Logs go to both console (dev) and zustand store (for Console panel).
+ */
+
+import { createMediaLogger } from '@djangocfg/ui-core/lib';
+
+export const imageDebug = createMediaLogger('ImageViewer');
+
+export default imageDebug;

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

@@ -0,0 +1,22 @@
+/**
+ * ImageViewer utilities - Public API
+ */
+
+export { createLQIP } from './lqip';
+export {
+  MAX_IMAGE_SIZE,
+  WARNING_IMAGE_SIZE,
+  PROGRESSIVE_LOADING_THRESHOLD,
+  LQIP_SIZE,
+  LQIP_QUALITY,
+  MIN_ZOOM,
+  MAX_ZOOM,
+  KEYBOARD_PAN_STEP,
+  WHEEL_SMOOTH_STEP,
+  PINCH_STEP,
+  DOUBLE_CLICK_STEP,
+  CHROME_IDLE_MS,
+  ZOOM_PRESETS,
+  DEFAULT_TRANSFORM,
+} from './constants';
+export { imageDebug } from './debug';

package/src/image-viewer/utils/lqip.ts

@@ -0,0 +1,47 @@
+/**
+ * LQIP (Low-Quality Image Placeholder) generator
+ *
+ * Creates a tiny blurred preview image for progressive loading.
+ */
+
+import { LQIP_QUALITY, LQIP_SIZE } from './constants';
+
+/**
+ * Create a low-quality image placeholder from source URL
+ *
+ * @param imageSrc - Full quality image URL
+ * @returns Data URL of tiny preview, or null on error
+ */
+export async function createLQIP(imageSrc: string): Promise<string | null> {
+  try {
+    // Load the full image
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+
+    await new Promise<void>((resolve, reject) => {
+      img.onload = () => resolve();
+      img.onerror = () => reject(new Error('Failed to load image for LQIP'));
+      img.src = imageSrc;
+    });
+
+    // Calculate aspect ratio preserving dimensions
+    const aspect = img.naturalWidth / img.naturalHeight;
+    const width = aspect >= 1 ? LQIP_SIZE : Math.round(LQIP_SIZE * aspect);
+    const height = aspect >= 1 ? Math.round(LQIP_SIZE / aspect) : LQIP_SIZE;
+
+    // Create canvas for downscaling
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return null;
+
+    // Draw scaled down image
+    ctx.drawImage(img, 0, 0, width, height);
+
+    // Return as data URL (very small, ~1-2KB)
+    return canvas.toDataURL('image/jpeg', LQIP_QUALITY);
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// Viewers presented inside a conversation or a file preview.
+//
+// The root barrel exports the image viewer ONLY. `./diagram`, `./markdown` and
+// `./code` are subpath-only on purpose: each pulls a parser or a highlighter
+// (mermaid ~2.5 MB, shiki, katex), and a host mounting a lightbox must not pay
+// for any of them. A barrel re-export is a static edge — naming them here would
+// undo the split silently.
+export * from "./image-viewer";
+export type { MediaCopy } from "./i18n";
+export { DEFAULT_MEDIA_COPY } from "./i18n";