@clicoh/orion-library 1.2.0-beta.20 → 1.2.0-beta.22

package/assets/css/expresivo.css

@@ -524,6 +524,59 @@
   clip-path: polygon(0 0, 100% 0, 100% 100%, 50% 68%, 0 100%);
 }
 
+/* ExpSearchField: the same relief as the field skin, with its action inside */
+
+.exp-search {
+  border: 1px solid var(--exp-field-line);
+  background: var(--exp-field-bg);
+  box-shadow:
+    0 4px 14px var(--exp-field-drop),
+    0 1px 2px rgba(34, 35, 41, 0.06),
+    inset 0 1px 0 var(--exp-field-gloss);
+  transition:
+    transform 260ms var(--exp-ease-spring),
+    box-shadow 260ms ease,
+    border-color 200ms ease,
+    background 200ms ease;
+}
+
+.exp-search[data-state='idle']:is(:hover, :focus-within) {
+  border-color: var(--exp-accent-soft);
+  background: var(--exp-field-bg-hover);
+  box-shadow:
+    0 10px 28px var(--exp-field-glow),
+    0 2px 6px rgba(106, 93, 249, 0.12),
+    inset 0 1px 0 var(--exp-field-gloss);
+}
+
+.exp-search[data-state='idle']:focus-within {
+  border-color: var(--exp-accent);
+}
+
+.exp-search[data-state][data-invalid] {
+  border-color: var(--color-error);
+}
+
+.exp-search[data-state='disabled'] {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.exp-search-input {
+  color: var(--exp-field-ink);
+}
+
+.exp-search-lens {
+  color: var(--exp-field-icon);
+  transition:
+    color 200ms ease,
+    transform 260ms var(--exp-ease-spring);
+}
+
+.exp-search[data-state='idle']:is(:hover, :focus-within) .exp-search-lens {
+  color: var(--exp-accent);
+}
+
 /* Skin: titles ---------------------------------------------------------- */
 
 :root:has(.exp-scope[data-exp-titles='playful']) [data-orion-part='heading'] {
@@ -817,15 +870,36 @@
     var(--exp-card-bg);
 }
 
+/* Skin: framed tables (DataTable card) ---------------------------------- */
+
+/* A framed table reads as one card: the brand band along the top, like
+   `Card` `accent`, and core rows inside even with tables="cards". */
+:root:has(.exp-scope) [data-orion-part='data-table'][data-modifier='card'] {
+  overflow: hidden;
+  border-color: var(--exp-card-edge);
+  border-radius: 16px;
+  padding-top: 4px;
+  background:
+    var(--exp-card-band) top / 100% 4px no-repeat,
+    var(--exp-card-bg);
+  box-shadow: var(--exp-card-drop);
+}
+
 /* Skin: table rows as cards (ExpScope tables="cards") ------------------- */
 
-:root:has(.exp-scope[data-exp-tables='cards']) [data-orion-part='table'] {
+:root:has(.exp-scope[data-exp-tables='cards'])
+  [data-orion-part='table']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  ) {
   margin-top: -8px;
   border-collapse: separate;
   border-spacing: 0 8px;
 }
 
-:root:has(.exp-scope[data-exp-tables='cards']) [data-orion-part='table-head'] {
+:root:has(.exp-scope[data-exp-tables='cards'])
+  [data-orion-part='table-head']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  ) {
   border: 0;
   background: transparent;
   color: var(--exp-field-label);
@@ -834,7 +908,9 @@
 }
 
 :root:has(.exp-scope[data-exp-tables='cards'])
-  [data-orion-part='table-head']
+  [data-orion-part='table-head']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  )
   > th {
   padding: 10px 16px 2px;
   font-weight: 400;
@@ -842,19 +918,26 @@
 }
 
 :root:has(.exp-scope[data-exp-tables='cards'][data-exp-titles='playful'])
-  [data-orion-part='table-head']
+  [data-orion-part='table-head']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  )
   > th {
   font-family: var(--exp-title-font);
 }
 
-:root:has(.exp-scope[data-exp-tables='cards']) [data-orion-part='table-row'] {
+:root:has(.exp-scope[data-exp-tables='cards'])
+  [data-orion-part='table-row']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  ) {
   border: 0;
   background: transparent;
   outline-offset: 2px;
 }
 
 :root:has(.exp-scope[data-exp-tables='cards'])
-  [data-orion-part='table-row']
+  [data-orion-part='table-row']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  )
   > td {
   padding: 14px 16px;
   border-top: 1px solid var(--exp-row-edge);
@@ -868,21 +951,27 @@
 }
 
 :root:has(.exp-scope[data-exp-tables='cards'])
-  [data-orion-part='table-row']
+  [data-orion-part='table-row']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  )
   > td:first-child {
   border-left: 1px solid var(--exp-row-edge);
   border-radius: 14px 0 0 14px;
 }
 
 :root:has(.exp-scope[data-exp-tables='cards'])
-  [data-orion-part='table-row']
+  [data-orion-part='table-row']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  )
   > td:last-child {
   border-right: 1px solid var(--exp-row-edge);
   border-radius: 0 14px 14px 0;
 }
 
 :root:has(.exp-scope[data-exp-tables='cards'])
-  [data-orion-part='table-row']:is(:hover, :focus-visible, [data-selected])
+  [data-orion-part='table-row']:not(
+    [data-orion-part='data-table'][data-modifier='card'] *
+  ):is(:hover, :focus-visible, [data-selected])
   > td {
   border-color: var(--exp-row-edge-hover);
   background: var(--exp-row-bg-hover);
@@ -916,6 +1005,14 @@
     transform: translateY(-2px);
   }
 
+  .exp-search[data-state='idle']:is(:hover, :focus-within) {
+    transform: translateY(-2px);
+  }
+
+  .exp-search[data-state='idle']:is(:hover, :focus-within) .exp-search-lens {
+    transform: rotate(-8deg) scale(1.06);
+  }
+
   :root:has(.exp-scope)
     button[data-orion-part='field-control']:not(:disabled):is(
       :hover,
@@ -927,7 +1024,9 @@
   }
 
   :root:has(.exp-scope[data-exp-tables='cards'])
-    [data-orion-part='table-row']:is(:hover, :focus-visible, [data-selected])
+    [data-orion-part='table-row']:not(
+      [data-orion-part='data-table'][data-modifier='card'] *
+    ):is(:hover, :focus-visible, [data-selected])
     > td {
     transform: translateY(-2px);
   }
@@ -954,6 +1053,8 @@
   .exp-rotor,
   .exp-enter-arrow,
   .exp-arrow,
+  .exp-search,
+  .exp-search-lens,
   :root:has(.exp-scope) [data-orion-part='field-box'],
   :root:has(.exp-scope) textarea[data-orion-part='field-control'],
   :root:has(.exp-scope) [data-orion-part='field-icon'],

package/dist/components/02-molecules/ImageViewer/ImageViewer.d.ts

@@ -1,11 +1,15 @@
 import { type HTMLAttributes, type ReactNode } from 'react';
+import { type TImageViewerDocumentLabels } from './ImageViewerDocument';
 import { type TImageCrop } from './ImageViewerImage';
 export type { TImageCrop } from './ImageViewerImage';
+export type { TImageViewerDocumentLabels } from './ImageViewerDocument';
+export type TImageViewType = 'image' | 'pdf';
 export type TImageView = {
     id: string;
     label: string;
     src: string;
     alt: string;
+    type?: TImageViewType;
     indicator?: ReactNode;
     crop?: TImageCrop;
 };
@@ -16,7 +20,7 @@ export type TImageViewerLabels = {
     rotate: string;
     enterFullscreen: string;
     exitFullscreen: string;
-};
+} & TImageViewerDocumentLabels;
 type ImageViewerProps = {
     views: TImageView[];
     labels: TImageViewerLabels;
@@ -34,6 +38,12 @@ type ImageViewerProps = {
  * changes, whether the user picked a tab or the consumer moved `activeId`: a
  * transform that made sense for one angle rarely makes sense for the next.
  *
+ * Once zoomed in, the image can be panned: by dragging it with the pointer
+ * (mouse, touch or pen) or with the arrow keys while the panel has focus. The
+ * pan never leaves a gap between the image and the frame; zooming in keeps the
+ * point under inspection centered, zooming out to the minimum, rotating and
+ * toggling full screen center the image again.
+ *
  * Uncontrolled by default. Passing `activeId` makes the consumer own the active
  * view, so something outside the viewer (a side panel, a "next pending" action)
  * can follow or drive it; `onViewChange` reports tab picks in both modes.
@@ -49,6 +59,14 @@ type ImageViewerProps = {
  * A view's `crop` draws only that region of its image, fitted to the frame
  * like the whole image would be — a face inside a document, for instance.
  *
+ * A view with `type: 'pdf'` is rendered page by page into images with pdf.js,
+ * loaded on first use, so zoom, rotation and pan work on it exactly as on a
+ * photo and there is a single toolbar. A document with several pages shows a
+ * pager over the page; the toolbar gains an "open in a new tab" action for
+ * the original file. The browser fetches the PDF itself, so its origin must
+ * allow CORS; when it cannot be loaded, the view shows its description and
+ * the same link.
+ *
  * @component
  * @example
  * const [viewId, setViewId] = useState('front');
@@ -94,9 +112,23 @@ type ImageViewerProps = {
  *   labels={labels}
  * />
  *
+ * @example
+ * <ImageViewer
+ *   title="Insurance policy"
+ *   views={[
+ *     { id: 'policy', label: 'Policy', src: '/policy.pdf', alt: 'Insurance policy', type: 'pdf' },
+ *   ]}
+ *   labels={{
+ *     ...labels,
+ *     openDocument: 'Open PDF',
+ *     previousPage: 'Previous page',
+ *     nextPage: 'Next page',
+ *   }}
+ * />
+ *
  * @param {Object} props - The properties of the ImageViewer component.
- * @param {TImageView[]} props.views - Images to display. In `tabs`, more than one renders a tab per view; in `split`, a pane per view. A view's optional `indicator` sits after its label and becomes part of the tab's accessible name, so give it its own (for an icon, `role="img"` and `aria-label`). In `tabs` with a single view there are no tabs, so no indicator is shown. A view's optional `crop` (`left`, `top`, `width`, `height` as fractions from 0 to 1 of the image) shows only that region; a crop outside the image is clamped to it, and one with no area left falls back to the whole image.
- * @param {TImageViewerLabels} props.labels - Accessible names of the toolbar actions.
+ * @param {TImageView[]} props.views - Files to display. In `tabs`, more than one renders a tab per view; in `split`, a pane per view. A view's optional `indicator` sits after its label and becomes part of the tab's accessible name, so give it its own (for an icon, `role="img"` and `aria-label`). In `tabs` with a single view there are no tabs, so no indicator is shown. A view's optional `crop` (`left`, `top`, `width`, `height` as fractions from 0 to 1 of the image) shows only that region; a crop outside the image is clamped to it, and one with no area left falls back to the whole image. A view's `type` is `image` unless set to `pdf`; `crop` is ignored on a `pdf`.
+ * @param {TImageViewerLabels} props.labels - Accessible names of the toolbar actions. With `pdf` views, `openDocument` names the action that opens the original file in a new tab, and `previousPage` / `nextPage` name the pager of a document with several pages; without the pair, only the first page is reachable.
  * @param {TImageViewerLayout} [props.layout='tabs'] - `tabs` shows one view at a time; `split` shows every view at once, one pane each.
  * @param {ReactNode} [props.title] - Optional heading rendered on the left of the toolbar.
  * @param {ReactNode} [props.emptyState] - Content rendered when there is no image.

package/dist/components/02-molecules/ImageViewer/ImageViewer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImageViewer.d.ts","sourceRoot":"","sources":["../../../../src/components/02-molecules/ImageViewer/ImageViewer.tsx"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEvE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC;AAiB5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,MAAM,EACN,MAAe,EACf,KAAK,EACL,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,GAAG,SAAS,EACb,EAAE,gBAAgB,GAAG,SAAS,CAqP9B"}
+{"version":3,"file":"ImageViewer.d.ts","sourceRoot":"","sources":["../../../../src/components/02-molecules/ImageViewer/ImageViewer.tsx"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,cAAc,EAGnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAaf,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAExE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,KAAK,CAAC;AAE7C,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB,GAAG,0BAA0B,CAAC;AAE/B,KAAK,gBAAgB,GAAG;IACtB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,GAAG,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC;AA0E5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2GG;AACH,wBAAgB,WAAW,CAAC,EAC1B,KAAK,EACL,MAAM,EACN,MAAe,EACf,KAAK,EACL,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,GAAG,SAAS,EACb,EAAE,gBAAgB,GAAG,SAAS,CA6X9B"}

package/dist/components/02-molecules/ImageViewer/ImageViewer.jsx

@@ -1,19 +1,57 @@
 'use client';
 import clsx from 'clsx';
-import { useEffect, useId, useState, } from 'react';
+import { useEffect, useId, useRef, useState, } from 'react';
 import { createPortal } from 'react-dom';
-import { MdFullscreen, MdFullscreenExit, MdRotateRight, MdZoomIn, MdZoomOut, } from 'react-icons/md';
+import { MdFullscreen, MdFullscreenExit, MdOpenInNew, MdRotateRight, MdZoomIn, MdZoomOut, } from 'react-icons/md';
 import { Each, Show } from '../../00-base';
 import { List, Paragraph } from '../../01-atoms';
 import { TabItem } from '../Tab/TabItem';
-import { ImageViewerImage } from './ImageViewerImage';
+import { ImageViewerDocument, } from './ImageViewerDocument';
+import { IMAGE_VIEWER_IMAGE_ATTRIBUTE, ImageViewerImage, } from './ImageViewerImage';
 const MIN_ZOOM = 1;
 const MAX_ZOOM = 3;
 const ZOOM_STEP = 0.5;
 const QUARTER_TURN = 90;
 const FULL_TURN = 360;
-const INITIAL_TRANSFORM = { zoom: MIN_ZOOM, rotation: 0 };
+const KEYBOARD_PAN_STEP = 40;
+const NO_OFFSET = { x: 0, y: 0 };
+const INITIAL_TRANSFORM = {
+    zoom: MIN_ZOOM,
+    rotation: 0,
+    offset: NO_OFFSET,
+};
+/**
+ * Arrow keys move the viewport, so the image travels the opposite way, like
+ * scrolling.
+ */
+const PAN_DIRECTIONS = {
+    ArrowLeft: { x: 1, y: 0 },
+    ArrowRight: { x: -1, y: 0 },
+    ArrowUp: { x: 0, y: 1 },
+    ArrowDown: { x: 0, y: -1 },
+};
 const TOOL_CLASSNAME = 'hover:bg-gray-5 focus-visible:ring-lavender disabled:text-gray-3 dark:disabled:text-gray-1 dark:hover:bg-gray-1 flex h-8 w-8 cursor-pointer items-center justify-center rounded-sm text-lg text-black focus-visible:ring-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:hover:bg-transparent dark:text-white';
+/**
+ * How far the images may leave the center before their edge enters the pane:
+ * half the overflow on each axis, none when the image already fits. Read from
+ * the rendered elements so it holds for any crop, rotation and zoom; `scale`
+ * anticipates a zoom that has not been painted yet. In `split`, the pane that
+ * overflows the most wins, so every image can be reached.
+ */
+const measurePanBounds = (panel, scale = 1) => Array.from(panel.querySelectorAll(`[${IMAGE_VIEWER_IMAGE_ATTRIBUTE}]`)).reduce((bounds, image) => {
+    const pane = image.parentElement?.getBoundingClientRect();
+    if (!pane)
+        return bounds;
+    const { width, height } = image.getBoundingClientRect();
+    return {
+        x: Math.max(bounds.x, (width * scale - pane.width) / 2),
+        y: Math.max(bounds.y, (height * scale - pane.height) / 2),
+    };
+}, NO_OFFSET);
+const clampOffset = (offset, bounds) => ({
+    x: Math.min(Math.max(offset.x, -bounds.x), bounds.x),
+    y: Math.min(Math.max(offset.y, -bounds.y), bounds.y),
+});
 /**
  * ImageViewer component for inspecting one or more images of the same subject.
  *
@@ -22,6 +60,12 @@ const TOOL_CLASSNAME = 'hover:bg-gray-5 focus-visible:ring-lavender disabled:tex
  * changes, whether the user picked a tab or the consumer moved `activeId`: a
  * transform that made sense for one angle rarely makes sense for the next.
  *
+ * Once zoomed in, the image can be panned: by dragging it with the pointer
+ * (mouse, touch or pen) or with the arrow keys while the panel has focus. The
+ * pan never leaves a gap between the image and the frame; zooming in keeps the
+ * point under inspection centered, zooming out to the minimum, rotating and
+ * toggling full screen center the image again.
+ *
  * Uncontrolled by default. Passing `activeId` makes the consumer own the active
  * view, so something outside the viewer (a side panel, a "next pending" action)
  * can follow or drive it; `onViewChange` reports tab picks in both modes.
@@ -37,6 +81,14 @@ const TOOL_CLASSNAME = 'hover:bg-gray-5 focus-visible:ring-lavender disabled:tex
  * A view's `crop` draws only that region of its image, fitted to the frame
  * like the whole image would be — a face inside a document, for instance.
  *
+ * A view with `type: 'pdf'` is rendered page by page into images with pdf.js,
+ * loaded on first use, so zoom, rotation and pan work on it exactly as on a
+ * photo and there is a single toolbar. A document with several pages shows a
+ * pager over the page; the toolbar gains an "open in a new tab" action for
+ * the original file. The browser fetches the PDF itself, so its origin must
+ * allow CORS; when it cannot be loaded, the view shows its description and
+ * the same link.
+ *
  * @component
  * @example
  * const [viewId, setViewId] = useState('front');
@@ -82,9 +134,23 @@ const TOOL_CLASSNAME = 'hover:bg-gray-5 focus-visible:ring-lavender disabled:tex
  *   labels={labels}
  * />
  *
+ * @example
+ * <ImageViewer
+ *   title="Insurance policy"
+ *   views={[
+ *     { id: 'policy', label: 'Policy', src: '/policy.pdf', alt: 'Insurance policy', type: 'pdf' },
+ *   ]}
+ *   labels={{
+ *     ...labels,
+ *     openDocument: 'Open PDF',
+ *     previousPage: 'Previous page',
+ *     nextPage: 'Next page',
+ *   }}
+ * />
+ *
  * @param {Object} props - The properties of the ImageViewer component.
- * @param {TImageView[]} props.views - Images to display. In `tabs`, more than one renders a tab per view; in `split`, a pane per view. A view's optional `indicator` sits after its label and becomes part of the tab's accessible name, so give it its own (for an icon, `role="img"` and `aria-label`). In `tabs` with a single view there are no tabs, so no indicator is shown. A view's optional `crop` (`left`, `top`, `width`, `height` as fractions from 0 to 1 of the image) shows only that region; a crop outside the image is clamped to it, and one with no area left falls back to the whole image.
- * @param {TImageViewerLabels} props.labels - Accessible names of the toolbar actions.
+ * @param {TImageView[]} props.views - Files to display. In `tabs`, more than one renders a tab per view; in `split`, a pane per view. A view's optional `indicator` sits after its label and becomes part of the tab's accessible name, so give it its own (for an icon, `role="img"` and `aria-label`). In `tabs` with a single view there are no tabs, so no indicator is shown. A view's optional `crop` (`left`, `top`, `width`, `height` as fractions from 0 to 1 of the image) shows only that region; a crop outside the image is clamped to it, and one with no area left falls back to the whole image. A view's `type` is `image` unless set to `pdf`; `crop` is ignored on a `pdf`.
+ * @param {TImageViewerLabels} props.labels - Accessible names of the toolbar actions. With `pdf` views, `openDocument` names the action that opens the original file in a new tab, and `previousPage` / `nextPage` name the pager of a document with several pages; without the pair, only the first page is reachable.
  * @param {TImageViewerLayout} [props.layout='tabs'] - `tabs` shows one view at a time; `split` shows every view at once, one pane each.
  * @param {ReactNode} [props.title] - Optional heading rendered on the left of the toolbar.
  * @param {ReactNode} [props.emptyState] - Content rendered when there is no image.
@@ -98,6 +164,9 @@ export function ImageViewer({ views, labels, layout = 'tabs', title, emptyState,
     const [internalIndex, setInternalIndex] = useState(0);
     const [transform, setTransform] = useState(INITIAL_TRANSFORM);
     const [isFullscreen, setIsFullscreen] = useState(false);
+    const [isDragging, setIsDragging] = useState(false);
+    const panelRef = useRef(null);
+    const dragRef = useRef(null);
     const generatedId = useId();
     /**
      * Se sigue la firma de las vistas y no el arreglo: un consumidor que lo
@@ -106,6 +175,7 @@ export function ImageViewer({ views, labels, layout = 'tabs', title, emptyState,
      */
     const viewsSignature = views.map(({ id }) => id).join('|');
     useEffect(() => {
+        // eslint-disable-next-line react-hooks/set-state-in-effect -- a different set of views starts again from the first one, without zoom or rotation
         setInternalIndex(0);
         setTransform(INITIAL_TRANSFORM);
     }, [viewsSignature]);
@@ -124,11 +194,17 @@ export function ImageViewer({ views, labels, layout = 'tabs', title, emptyState,
         ? Math.max(views.findIndex(({ id }) => id === activeId), 0)
         : internalIndex;
     const activeView = views[activeIndex] ?? views[0];
-    const hasImage = Boolean(activeView);
+    const hasView = Boolean(activeView);
     const isSplit = layout === 'split';
     const hasTabs = !isSplit && views.length > 1;
-    const { zoom, rotation } = transform;
-    const imageStyle = { transform: `rotate(${rotation}deg) scale(${zoom})` };
+    const shownViews = isSplit ? views : activeView ? [activeView] : [];
+    const documentHref = !isSplit && activeView?.type === 'pdf' ? activeView.src : undefined;
+    const panelLabel = shownViews.map(({ alt }) => alt).join(', ') || undefined;
+    const { zoom, rotation, offset } = transform;
+    const canPan = hasView && zoom > MIN_ZOOM;
+    const imageStyle = {
+        transform: `translate(${offset.x}px, ${offset.y}px) rotate(${rotation}deg) scale(${zoom})`,
+    };
     /**
      * En modo controlado la vista puede cambiar sin pasar por `selectView`, asi
      * que el reinicio se ata a la vista activa y no al clic. Guardar el zoom por
@@ -149,6 +225,98 @@ export function ImageViewer({ views, labels, layout = 'tabs', title, emptyState,
         if (view.id !== activeView?.id)
             onViewChange?.(view.id);
     };
+    /**
+     * El desplazamiento se escala con el zoom para que el punto que se estaba
+     * mirando siga en el centro. Al acercar siempre cabe; al alejar puede quedar
+     * fuera del nuevo limite, asi que se acota midiendo con la escala destino.
+     */
+    const changeZoom = (delta) => {
+        const panel = panelRef.current;
+        setTransform((current) => {
+            const nextZoom = Math.min(Math.max(current.zoom + delta, MIN_ZOOM), MAX_ZOOM);
+            if (nextZoom === MIN_ZOOM) {
+                return { ...current, zoom: nextZoom, offset: NO_OFFSET };
+            }
+            const scale = nextZoom / current.zoom;
+            const scaled = {
+                x: current.offset.x * scale,
+                y: current.offset.y * scale,
+            };
+            return {
+                ...current,
+                zoom: nextZoom,
+                offset: panel
+                    ? clampOffset(scaled, measurePanBounds(panel, scale))
+                    : scaled,
+            };
+        });
+    };
+    const rotate = () => setTransform((current) => ({
+        ...current,
+        rotation: (current.rotation + QUARTER_TURN) % FULL_TURN,
+        offset: NO_OFFSET,
+    }));
+    const recenter = () => setTransform((current) => ({ ...current, offset: NO_OFFSET }));
+    const toggleFullscreen = () => {
+        setIsFullscreen((current) => !current);
+        recenter();
+    };
+    /**
+     * Los controles que viven sobre la imagen (el paginador de un PDF) deben
+     * recibir su clic: capturar el puntero aqui se lo quitaria.
+     */
+    const isControl = (target) => target instanceof Element && target.closest('button, a') !== null;
+    const startDrag = (event) => {
+        if (!canPan || event.button !== 0 || isControl(event.target))
+            return;
+        event.currentTarget.setPointerCapture(event.pointerId);
+        dragRef.current = {
+            pointerId: event.pointerId,
+            startX: event.clientX,
+            startY: event.clientY,
+            origin: offset,
+            bounds: measurePanBounds(event.currentTarget),
+        };
+        setIsDragging(true);
+    };
+    const moveDrag = (event) => {
+        const drag = dragRef.current;
+        if (drag?.pointerId !== event.pointerId)
+            return;
+        const next = clampOffset({
+            x: drag.origin.x + event.clientX - drag.startX,
+            y: drag.origin.y + event.clientY - drag.startY,
+        }, drag.bounds);
+        setTransform((current) => ({ ...current, offset: next }));
+    };
+    const endDrag = (event) => {
+        if (dragRef.current?.pointerId !== event.pointerId)
+            return;
+        dragRef.current = null;
+        setIsDragging(false);
+    };
+    const panWithKeyboard = (event) => {
+        const direction = PAN_DIRECTIONS[event.key];
+        if (!direction || !canPan)
+            return;
+        event.preventDefault();
+        const bounds = measurePanBounds(event.currentTarget);
+        setTransform((current) => ({
+            ...current,
+            offset: clampOffset({
+                x: current.offset.x + direction.x * KEYBOARD_PAN_STEP,
+                y: current.offset.y + direction.y * KEYBOARD_PAN_STEP,
+            }, bounds),
+        }));
+    };
+    const renderView = (view) => (<Show key={view.id}>
+      <Show.When isTrue={view.type === 'pdf'}>
+        <ImageViewerDocument src={view.src} alt={view.alt} style={imageStyle} isAnimated={!isDragging} labels={labels} onPageChange={recenter}/>
+      </Show.When>
+      <Show.Else>
+        <ImageViewerImage src={view.src} alt={view.alt} crop={view.crop} style={imageStyle} isAnimated={!isDragging}/>
+      </Show.Else>
+    </Show>);
     const frame = (<section {...restProps} className={clsx('border-gray-5 dark:border-gray-1 flex min-h-0 flex-col overflow-hidden rounded-lg border', isFullscreen ? 'h-full w-full bg-white dark:bg-black' : undefined, !isFullscreen ? restProps.className : undefined)}>
       <div className="border-gray-5 bg-gray-6 dark:border-gray-1 dark:bg-black-1 flex flex-none items-center justify-between gap-4 border-b px-4 py-3">
         <Show>
@@ -159,25 +327,19 @@ export function ImageViewer({ views, labels, layout = 'tabs', title, emptyState,
           </Show.When>
         </Show>
         <div className="ml-auto flex items-center gap-1.5">
-          <button type="button" aria-label={labels.zoomOut} disabled={!hasImage || zoom <= MIN_ZOOM} onClick={() => setTransform((current) => ({
-            ...current,
-            zoom: current.zoom - ZOOM_STEP,
-        }))} className={TOOL_CLASSNAME}>
+          {!!documentHref && !!labels.openDocument && (<a href={documentHref} target="_blank" rel="noopener noreferrer" aria-label={labels.openDocument} className={TOOL_CLASSNAME}>
+              <MdOpenInNew aria-hidden="true"/>
+            </a>)}
+          <button type="button" aria-label={labels.zoomOut} disabled={!hasView || zoom <= MIN_ZOOM} onClick={() => changeZoom(-ZOOM_STEP)} className={TOOL_CLASSNAME}>
             <MdZoomOut aria-hidden="true"/>
           </button>
-          <button type="button" aria-label={labels.zoomIn} disabled={!hasImage || zoom >= MAX_ZOOM} onClick={() => setTransform((current) => ({
-            ...current,
-            zoom: current.zoom + ZOOM_STEP,
-        }))} className={TOOL_CLASSNAME}>
+          <button type="button" aria-label={labels.zoomIn} disabled={!hasView || zoom >= MAX_ZOOM} onClick={() => changeZoom(ZOOM_STEP)} className={TOOL_CLASSNAME}>
             <MdZoomIn aria-hidden="true"/>
           </button>
-          <button type="button" aria-label={labels.rotate} disabled={!hasImage} onClick={() => setTransform((current) => ({
-            ...current,
-            rotation: (current.rotation + QUARTER_TURN) % FULL_TURN,
-        }))} className={TOOL_CLASSNAME}>
+          <button type="button" aria-label={labels.rotate} disabled={!hasView} onClick={rotate} className={TOOL_CLASSNAME}>
             <MdRotateRight aria-hidden="true"/>
           </button>
-          <button type="button" aria-label={isFullscreen ? labels.exitFullscreen : labels.enterFullscreen} aria-pressed={isFullscreen} disabled={!hasImage} onClick={() => setIsFullscreen((current) => !current)} className={TOOL_CLASSNAME}>
+          <button type="button" aria-label={isFullscreen ? labels.exitFullscreen : labels.enterFullscreen} aria-pressed={isFullscreen} disabled={!hasView} onClick={toggleFullscreen} className={TOOL_CLASSNAME}>
             {isFullscreen ? (<MdFullscreenExit aria-hidden="true"/>) : (<MdFullscreen aria-hidden="true"/>)}
           </button>
         </div>
@@ -200,27 +362,27 @@ export function ImageViewer({ views, labels, layout = 'tabs', title, emptyState,
         </Show.When>
       </Show>
 
-      <div id={`${generatedId}-panel`} role={hasTabs ? 'tabpanel' : undefined} aria-labelledby={hasTabs ? `${generatedId}-tab-${activeIndex}` : undefined} className="bg-gray-7 dark:bg-black-2 flex min-h-0 flex-1 items-center justify-center overflow-hidden p-5">
+      <div ref={panelRef} id={`${generatedId}-panel`} role={hasTabs ? 'tabpanel' : 'group'} aria-labelledby={hasTabs ? `${generatedId}-tab-${activeIndex}` : undefined} aria-label={hasTabs ? undefined : panelLabel} tabIndex={canPan ? 0 : undefined} onPointerDown={startDrag} onPointerMove={moveDrag} onPointerUp={endDrag} onPointerCancel={endDrag} onKeyDown={panWithKeyboard} className={clsx('bg-gray-7 dark:bg-black-2 focus-visible:ring-lavender flex min-h-0 flex-1 items-center justify-center overflow-hidden p-5 focus-visible:ring-2 focus-visible:outline-none focus-visible:ring-inset', canPan && 'touch-none select-none', canPan && (isDragging ? 'cursor-grabbing' : 'cursor-grab'))}>
         <Show>
-          <Show.When isTrue={!!hasImage && isSplit}>
+          <Show.When isTrue={!!hasView && isSplit}>
             <div className="grid h-full w-full auto-rows-fr grid-cols-1 gap-5 sm:auto-cols-fr sm:grid-flow-col sm:grid-cols-none sm:grid-rows-1">
-              <Each of={views} render={({ id, label, indicator, src, alt, crop }) => (<figure key={id} className="flex min-h-0 min-w-0 flex-col gap-2">
+              <Each of={views} render={(view) => (<figure key={view.id} className="flex min-h-0 min-w-0 flex-col gap-2">
                     <figcaption className="flex flex-none items-center gap-1.5">
                       <Paragraph size="subtitle-2" className="dark:text-white">
-                        {label}
+                        {view.label}
                       </Paragraph>
-                      {!!indicator && (<span className="flex flex-none items-center">
-                          {indicator}
+                      {!!view.indicator && (<span className="flex flex-none items-center">
+                          {view.indicator}
                         </span>)}
                     </figcaption>
                     <div className="flex min-h-0 flex-1 items-center justify-center overflow-hidden">
-                      <ImageViewerImage src={src} alt={alt} crop={crop} style={imageStyle}/>
+                      {renderView(view)}
                     </div>
                   </figure>)}/>
             </div>
           </Show.When>
-          <Show.When isTrue={hasImage}>
-            {!!activeView && (<ImageViewerImage key={activeView.id} src={activeView.src} alt={activeView.alt} crop={activeView.crop} style={imageStyle}/>)}
+          <Show.When isTrue={hasView}>
+            {!!activeView && renderView(activeView)}
           </Show.When>
           <Show.Else>{emptyState}</Show.Else>
         </Show>