@djangocfg/widget-media 0.1.12 → 0.1.14

package/README.md

@@ -17,7 +17,7 @@ and a host mounting a lightbox must not pay for any of them.
 
 | Subpath | What it is | What it costs |
 |---|---|---|
-| `.` | `ImageViewer`, `LazyImageViewer`, its hooks, types and constants | `react-zoom-pan-pinch` |
+| `.` | `ImageLightbox`, `LazyImageLightbox`, `ImageViewer`, `LazyImageViewer`, hooks, types, constants | `yet-another-react-lightbox` (lightbox), `react-zoom-pan-pinch` (viewer) |
 | `./diagram` | `LazyDiagram`, `DiagramSource`, `diagramPlugin` | mermaid (~2.5 MB) — **always deferred** |
 | `./markdown` | `Markdown` — for a reader, outside any conversation | streamdown |
 | `./code` | `Code` — a read-only listing | streamdown + shiki |
@@ -45,13 +45,39 @@ changing one label does not blank the rest.
 `MediaCopy` is the schema of record — a misspelled key is a `tsc` error, not
 `undefined` rendered into a toolbar button.
 
+## Image lightbox
+
+The modal gallery a click on a picture opens, on
+[yet-another-react-lightbox](https://github.com/igordanchenko/yet-another-react-lightbox):
+focus trap, swipe, preload of the neighbours, keyboard, wheel/pinch zoom,
+thumbnails and a counter. Double-click zooms in at the pointer and the next one
+zooms back out; the cursor is a magnifier at rest and a hand only while zoomed.
+The skin is `src/image-viewer/lightbox/lightbox.css`: YARL's `--yarl__*`
+variables mapped to ui-core tokens, so it follows light/dark and every preset.
+
+```tsx
+import { LazyImageLightbox } from '@djangocfg/widget-media';
+
+<LazyImageLightbox
+  images={[{ name: 'a.jpg', src, downloadSrc }]}
+  open={index !== null}
+  index={index ?? 0}
+  onIndexChange={setIndex}
+  onClose={() => setIndex(null)}
+/>
+```
+
+It takes addresses (`LightboxImage`), never raw bytes; an in-memory image goes
+through `ImageViewer`. `LazyImageLightbox` renders nothing until `open`.
+
 ## Image viewer
 
-Zoom (wheel + presets 25/50/100/200/400%), pan by drag, rotate 90°, flip H/V,
-fullscreen dialog, keyboard shortcuts (`+`/`-`, `0` reset, `r` rotate),
-progressive loading with LQIP, checkerboard transparency ground, and cached
-dimension display. `LazyImageViewer` ships from the same entry, so choosing it
-costs no extra subpath.
+The embedded editor: zoom (wheel + presets 25/50/100/200/400%), pan by drag,
+rotate 90°, flip H/V, fullscreen dialog, keyboard shortcuts (`+`/`-`, `0`
+reset, `r` rotate), progressive loading with LQIP, checkerboard transparency
+ground, cached dimension display. Double-click zooms to the pointer from fit and
+back to fit from anywhere else. The `lightbox` prop is the older fullscreen
+presentation, superseded by `ImageLightbox` and kept so existing hosts compile.
 
 ## Verify
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/widget-media",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Media viewers for a conversation or a file preview: zoom/pan image lightbox, mermaid diagrams, markdown and code listings",
   "keywords": [
     "image-viewer",
@@ -53,19 +53,20 @@
     "beautiful-mermaid": "^1.1.3",
     "react-zoom-pan-pinch": "^3.7.0",
     "rehype-harden": "^1.1.8",
+    "yet-another-react-lightbox": "^3.32.2",
     "zustand": "^5.0.0"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.586",
-    "@djangocfg/ui-core": "^2.1.586",
+    "@djangocfg/i18n": "^2.1.592",
+    "@djangocfg/ui-core": "^2.1.592",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "streamdown": "^2.6.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.586",
-    "@djangocfg/typescript-config": "^2.1.586",
-    "@djangocfg/ui-core": "^2.1.586",
+    "@djangocfg/i18n": "^2.1.592",
+    "@djangocfg/typescript-config": "^2.1.592",
+    "@djangocfg/ui-core": "^2.1.592",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

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

@@ -41,7 +41,8 @@ import {
   MAX_ZOOM,
   WHEEL_SMOOTH_STEP,
   PINCH_STEP,
-  DOUBLE_CLICK_STEP,
+  DOUBLE_CLICK_ZOOM,
+  FIT_EPSILON,
 } from '../utils';
 import type { ImageViewerProps } from '../types';
 
@@ -91,6 +92,7 @@ export function ImageViewer({
   const [imgDecoded, setImgDecoded] = useState(false);
   const containerRef = useRef<HTMLDivElement>(null);
   const controlsRef = useRef<ReactZoomPanPinchRef | null>(null);
+  const atRest = Math.abs(scale - 1) < FIT_EPSILON;
   const imgRef = useRef<HTMLImageElement>(null);
 
   // Idle-fading chrome (lightbox only). Pointer movement over the canvas keeps
@@ -161,6 +163,24 @@ export function ImageViewer({
     resetKey: current?.file.path ?? '',
   });
 
+  // Double-click / double-tap: zoom to the pointer from fit, back to fit from
+  // anywhere else. The point under the pointer stays put (focal-point zoom).
+  const handleDoubleClick = useCallback((event: React.MouseEvent<HTMLDivElement>) => {
+    const controls = controlsRef.current;
+    const wrapper = controls?.instance.wrapperComponent;
+    if (!controls || !wrapper) return;
+    const { scale: current, positionX, positionY } = controls.instance.transformState;
+    if (Math.abs(current - 1) >= FIT_EPSILON) {
+      controls.resetTransform(200);
+      return;
+    }
+    const rect = wrapper.getBoundingClientRect();
+    const px = event.clientX - rect.left;
+    const py = event.clientY - rect.top;
+    const ratio = DOUBLE_CLICK_ZOOM / current;
+    controls.setTransform(px - (px - positionX) * ratio, py - (py - positionY) * ratio, DOUBLE_CLICK_ZOOM, 200);
+  }, []);
+
   const handleZoomPreset = useCallback((value: number | 'fit') => {
     const controls = controlsRef.current;
     if (!controls) return;
@@ -353,7 +373,10 @@ export function ImageViewer({
         smooth
         wheel={{ smoothStep: WHEEL_SMOOTH_STEP }}
         pinch={{ step: PINCH_STEP }}
-        doubleClick={{ mode: 'toggle', step: DOUBLE_CLICK_STEP }}
+        // The library's `toggle` zooms in only at scale === 1 exactly, so after
+        // any zoom every double-click was another step OUT. Ours is handled in
+        // `handleDoubleClick`: at rest zoom to the pointer, otherwise back to fit.
+        doubleClick={{ disabled: true }}
         panning={{ velocityDisabled: false }}
         onTransformed={(ref, state) => {
           controlsRef.current = ref;
@@ -376,7 +399,11 @@ export function ImageViewer({
         )}
 
         <TransformComponent
-          wrapperClass="!w-full !h-full cursor-grab active:cursor-grabbing"
+          wrapperClass={cn(
+            '!w-full !h-full',
+            atRest ? 'cursor-zoom-in' : 'cursor-grab active:cursor-grabbing',
+          )}
+          wrapperProps={{ onDoubleClick: handleDoubleClick }}
           contentClass="!w-full !h-full flex items-center justify-center"
         >
           {/*

package/src/image-viewer/index.ts

@@ -24,6 +24,10 @@ export { ImageViewer, ImageToolbar, ImageInfo } from './components';
 // picture. Exported from the same entry so choosing it costs no extra subpath.
 export { LazyImageViewer } from './lazy';
 
+// The modal gallery (yet-another-react-lightbox). Prefer it to the `lightbox`
+// presentation of `ImageViewer`; `LazyImageLightbox` defers the engine.
+export { ImageLightbox, LazyImageLightbox } from './lightbox';
+
 // =============================================================================
 // HOOKS
 // =============================================================================
@@ -43,6 +47,8 @@ export type {
 export type {
   ImageFile,
   ImageViewerProps,
+  ImageLightboxProps,
+  LightboxImage,
   ImageToolbarProps,
   ImageInfoProps,
   ImageTransform,

package/src/image-viewer/lightbox/ImageLightbox.tsx

@@ -0,0 +1,129 @@
+'use client';
+
+/**
+ * ImageLightbox - modal gallery on yet-another-react-lightbox.
+ *
+ * The engine owns what is costly to get right: focus trap, swipe, preload of
+ * the neighbours, keyboard, wheel/pinch zoom, and a double-click that zooms in
+ * and back out. This file only configures it, themes it from tokens
+ * (`lightbox.css`) and adds the SAVE button with the same same-origin rule the
+ * embedded viewer has.
+ */
+
+import { Download } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import Lightbox, { IconButton, useLightboxState } from 'yet-another-react-lightbox';
+import Counter from 'yet-another-react-lightbox/plugins/counter';
+import Thumbnails from 'yet-another-react-lightbox/plugins/thumbnails';
+import Zoom from 'yet-another-react-lightbox/plugins/zoom';
+
+import 'yet-another-react-lightbox/styles.css';
+import 'yet-another-react-lightbox/plugins/counter.css';
+import 'yet-another-react-lightbox/plugins/thumbnails.css';
+import './lightbox.css';
+
+import { useMediaCopy } from '../../i18n';
+import type { ImageLightboxProps, LightboxImage } from '../types';
+
+declare module 'yet-another-react-lightbox' {
+  interface Labels {
+    /** Title of the SAVE button this widget adds to the toolbar. */
+    Save?: string;
+  }
+}
+
+/** Double-click: one stop in, the next one out. */
+const ZOOM = {
+  doubleClickMaxStops: 1,
+  zoomInMultiplier: 2.5,
+  maxZoomPixelRatio: 3,
+  scrollToZoom: true,
+} as const;
+
+export function ImageLightbox({
+  images,
+  open,
+  index = 0,
+  onClose,
+  onIndexChange,
+  thumbnails = true,
+  copy,
+}: ImageLightboxProps) {
+  const labels = useMediaCopy(copy);
+  const [zoomed, setZoomed] = useState(false);
+
+  const slides = useMemo(
+    () =>
+      images.map((image) => ({
+        src: image.src,
+        alt: image.name,
+        width: image.width,
+        height: image.height,
+      })),
+    [images],
+  );
+
+  const handleView = useCallback(
+    ({ index: next }: { index: number }) => onIndexChange?.(next),
+    [onIndexChange],
+  );
+
+  return (
+    <Lightbox
+      open={open}
+      close={onClose}
+      index={index}
+      slides={slides}
+      className={zoomed ? 'dj-lightbox dj-lightbox--zoomed' : 'dj-lightbox'}
+      plugins={thumbnails && slides.length > 1 ? [Counter, Thumbnails, Zoom] : [Counter, Zoom]}
+      zoom={ZOOM}
+      carousel={{ finite: true, preload: 2 }}
+      animation={{ swipe: 250 }}
+      controller={{ closeOnBackdropClick: true, closeOnPullDown: true }}
+      thumbnails={{ position: 'bottom', vignette: false, border: 0, gap: 8 }}
+      labels={{
+        Close: labels.close,
+        Next: labels.next,
+        Previous: labels.previous,
+        Save: labels.download,
+        'Zoom in': labels.zoomIn,
+        'Zoom out': labels.zoomOut,
+      }}
+      on={{ view: handleView, zoom: ({ zoom }) => setZoomed(zoom > 1.01) }}
+      toolbar={{
+        buttons: [<SaveButton key="save" images={images} />, 'close'],
+      }}
+      render={slides.length > 1 ? undefined : { buttonPrev: () => null, buttonNext: () => null }}
+    />
+  );
+}
+
+/**
+ * Saves the slide on screen. `download` is honoured only for a same-origin
+ * address, so a picture shown from a CDN is saved from `downloadSrc` when the
+ * host has one.
+ */
+function SaveButton({ images }: { images: LightboxImage[] }) {
+  const { currentIndex } = useLightboxState();
+  const image = images[currentIndex];
+  const save = useCallback(() => {
+    if (!image) return;
+    const link = document.createElement('a');
+    link.href = image.downloadSrc ?? image.src;
+    link.download = image.name;
+    link.rel = 'noopener';
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+  }, [image]);
+
+  if (!image) return null;
+  return (
+    <IconButton
+      label="Save"
+      icon={() => null}
+      renderIcon={() => <Download className="yarl__icon" aria-hidden />}
+      onClick={save}
+    />
+  );
+}

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

@@ -0,0 +1,2 @@
+export { ImageLightbox } from './ImageLightbox';
+export { LazyImageLightbox } from './lazy';

package/src/image-viewer/lightbox/lazy.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+/**
+ * Lazy ImageLightbox: the engine and its three plugins load when a reader first
+ * opens a picture, not with the page. Mounted only while `open`, so nothing is
+ * fetched (and nothing renders on the server) until then.
+ */
+
+import { lazy, Suspense } from 'react';
+
+import type { ImageLightboxProps } from '../types';
+
+const ImageLightboxImpl = lazy(() =>
+  import('./ImageLightbox').then((mod) => ({ default: mod.ImageLightbox })),
+);
+
+export function LazyImageLightbox(props: ImageLightboxProps) {
+  if (!props.open) return null;
+  return (
+    <Suspense fallback={null}>
+      <ImageLightboxImpl {...props} />
+    </Suspense>
+  );
+}

package/src/image-viewer/lightbox/lightbox.css

@@ -0,0 +1,84 @@
+/*
+ * Theme for ImageLightbox: yet-another-react-lightbox reads `--yarl__*`
+ * variables, so the whole skin is this one mapping onto ui-core tokens. It
+ * follows light/dark and every preset with no JS. Scoped to `.dj-lightbox` so a
+ * host's own YARL instance is untouched.
+ */
+.dj-lightbox {
+  /* Above dialogs (z-1300), below popovers (z-1400): a lightbox opened from a
+     dialog must cover it, a menu opened from the toolbar must cover the box. */
+  --yarl__portal_zindex: 1350;
+  --yarl__color_backdrop: color-mix(in oklab, var(--background) 94%, transparent);
+  --yarl__container_background_color: var(--yarl__color_backdrop);
+  --yarl__color_button: var(--foreground);
+  --yarl__color_button_active: var(--foreground);
+  --yarl__color_button_disabled: var(--muted-foreground);
+  /* No drop shadow behind icons: the backdrop is a token surface, not a photo. */
+  --yarl__button_filter: none;
+  --yarl__icon_size: 20px;
+  --yarl__button_padding: 10px;
+  --yarl__toolbar_padding: 12px;
+  --yarl__navigation_button_padding: 12px;
+  --yarl__slide_icon_loading_color: var(--muted-foreground);
+  --yarl__slide_icon_error_color: var(--destructive);
+  --yarl__counter_color: var(--foreground);
+  --yarl__counter_filter: none;
+  --yarl__counter_top: 12px;
+  --yarl__counter_left: 20px;
+  --yarl__thumbnails_container_background_color: transparent;
+  --yarl__thumbnails_thumbnail_background: var(--muted);
+  --yarl__thumbnails_thumbnail_border_color: transparent;
+  --yarl__thumbnails_thumbnail_active_border_color: var(--primary);
+  --yarl__thumbnails_thumbnail_border_radius: var(--radius-control, 8px);
+  --yarl__thumbnails_thumbnail_width: 72px;
+  --yarl__thumbnails_thumbnail_height: 52px;
+  --yarl__thumbnails_thumbnail_gap: 8px;
+  --yarl__thumbnails_thumbnail_padding: 2px;
+}
+
+.dj-lightbox .yarl__container {
+  backdrop-filter: blur(24px) saturate(1.2);
+}
+
+/* Round controls on a translucent token surface, so an icon or the counter stays
+   legible over any photo, bright or dark. */
+.dj-lightbox .yarl__button,
+.dj-lightbox .yarl__counter {
+  border-radius: 9999px;
+  background-color: color-mix(in oklab, var(--background) 60%, transparent);
+  backdrop-filter: blur(12px);
+  transition: background-color 150ms ease;
+}
+.dj-lightbox .yarl__toolbar {
+  gap: 8px;
+}
+.dj-lightbox .yarl__button:hover:not(:disabled) {
+  background-color: color-mix(in oklab, var(--foreground) 14%, var(--background) 60%);
+}
+.dj-lightbox .yarl__button:focus-visible {
+  box-shadow: 0 0 0 2px var(--ring);
+}
+.dj-lightbox .yarl__navigation_prev,
+.dj-lightbox .yarl__navigation_next {
+  margin: 0 12px;
+  padding: 12px;
+}
+
+.dj-lightbox .yarl__counter {
+  padding: 4px 12px;
+  color: var(--foreground);
+  font-size: var(--text-sm);
+  font-variant-numeric: tabular-nums;
+}
+
+/* The image says what a double-click does: zoom in at rest, a hand to pan once
+   zoomed. (A permanent hand promised a pan that had nowhere to go.) */
+.dj-lightbox .yarl__slide_image {
+  cursor: zoom-in;
+}
+.dj-lightbox--zoomed .yarl__slide_image {
+  cursor: grab;
+}
+.dj-lightbox--zoomed .yarl__slide_image:active {
+  cursor: grabbing;
+}

package/src/image-viewer/types.ts

@@ -87,6 +87,34 @@ export interface ImageViewerProps {
   copy?: Partial<MediaCopy>;
 }
 
+/** One slide of `ImageLightbox`: an address, never raw bytes. */
+export interface LightboxImage {
+  /** Image URL. */
+  src: string;
+  /** Shown as the alt text and used as the saved file's name. */
+  name: string;
+  /** Intrinsic size when known: lets the engine lay out before the bytes arrive. */
+  width?: number;
+  height?: number;
+  /** Same-origin address the SAVE button reads (see `ImageItem.downloadSrc`). */
+  downloadSrc?: string;
+}
+
+export interface ImageLightboxProps {
+  images: LightboxImage[];
+  /** Controlled visibility. */
+  open: boolean;
+  /** Slide on screen (default 0). */
+  index?: number;
+  /** Esc, backdrop click, pull-down or the close button. */
+  onClose: () => void;
+  onIndexChange?: (index: number) => void;
+  /** Thumbnail strip for more than one image (default true). */
+  thumbnails?: boolean;
+  /** Override any subset of the widget's English copy. */
+  copy?: Partial<MediaCopy>;
+}
+
 export interface ImageToolbarProps {
   /** Current zoom scale */
   scale: number;

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

@@ -62,8 +62,11 @@ 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;
+/** Scale a double-click / double-tap zooms to, centred on the pointer. */
+export const DOUBLE_CLICK_ZOOM = 2.5;
+
+/** Within this of fit (scale 1) the image counts as "at rest". */
+export const FIT_EPSILON = 0.02;
 
 /** Idle delay (ms) before the lightbox chrome fades out when the pointer rests. */
 export const CHROME_IDLE_MS = 2200;

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

@@ -14,7 +14,8 @@ export {
   KEYBOARD_PAN_STEP,
   WHEEL_SMOOTH_STEP,
   PINCH_STEP,
-  DOUBLE_CLICK_STEP,
+  DOUBLE_CLICK_ZOOM,
+  FIT_EPSILON,
   CHROME_IDLE_MS,
   ZOOM_PRESETS,
   DEFAULT_TRANSFORM,