@boyernick/standard-ui-react 0.4.2-canary.68 → 0.4.2-canary.70

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyernick/standard-ui-react",
-  "version": "0.4.2-canary.68",
+  "version": "0.4.2-canary.70",
   "description": "React components for StandardUI",
   "license": "MIT",
   "type": "module",

package/src/icons.tsx

@@ -39,6 +39,8 @@ import { IconSun as IconSunBase } from "@central-icons-react/round-outlined-radi
 import { IconVolumeFull as IconVolumeFullBase } from "@central-icons-react/round-outlined-radius-2-stroke-2/IconVolumeFull"
 import { IconVolumeOff as IconVolumeOffBase } from "@central-icons-react/round-outlined-radius-2-stroke-2/IconVolumeOff"
 import { IconX as IconXBase } from "@central-icons-react/round-outlined-radius-2-stroke-2/IconX"
+import { IconZoomIn as IconZoomInBase } from "@central-icons-react/round-outlined-radius-2-stroke-2/IconZoomIn"
+import { IconZoomOut as IconZoomOutBase } from "@central-icons-react/round-outlined-radius-2-stroke-2/IconZoomOut"
 import type { ComponentType } from "react"
 
 /** Round outlined Central Icons: 2px radius, 2px stroke, default 20px. */
@@ -140,11 +142,15 @@ export const IconSun = withCentralIconDefaults(IconSunBase)
 export const IconVolumeFull = withCentralIconDefaults(IconVolumeFullBase)
 export const IconVolumeOff = withCentralIconDefaults(IconVolumeOffBase)
 export const IconX = withCentralIconDefaults(IconXBase)
+export const IconZoomIn = withCentralIconDefaults(IconZoomInBase)
+export const IconZoomOut = withCentralIconDefaults(IconZoomOutBase)
 
 export const iconGallery = [
   { name: "IconHome", Icon: IconHome },
   { name: "IconCalendar1", Icon: IconCalendar1 },
   { name: "IconMagnifyingGlass", Icon: IconMagnifyingGlass },
+  { name: "IconZoomIn", Icon: IconZoomIn },
+  { name: "IconZoomOut", Icon: IconZoomOut },
   { name: "IconSettingsGear1", Icon: IconSettingsGear1 },
   { name: "IconBell", Icon: IconBell },
   { name: "IconPeople", Icon: IconPeople },

package/src/index.ts

@@ -1007,6 +1007,8 @@ export {
   IconVolumeFull,
   IconVolumeOff,
   IconX,
+  IconZoomIn,
+  IconZoomOut,
   type CentralIconProps,
   type CentralIconComponent,
 } from "./icons";

package/src/lib/image-zoom.ts

@@ -0,0 +1,86 @@
+/**
+ * Magnify an image in place and pan it under the pointer.
+ *
+ * The image scales from its top-left corner and moves with `translate`, so
+ * the zoom can ease while panning stays instant. Crossing the frame maps to
+ * the image's whole travel: the pointer reaches every edge at any size, and
+ * the image never parks with an edge out of reach.
+ */
+
+export const IMAGE_ZOOM = 2
+
+export interface ZoomAxis {
+  /** Pointer position, in client pixels. */
+  cursor: number
+  /** Start and size of the frame the image is seen through. */
+  frameStart: number
+  frameSize: number
+  /** Where the unmoved image starts, in client pixels. */
+  layoutStart: number
+  /** The magnified image's size, in client pixels. */
+  rendered: number
+  /** Client pixels per image pixel from ancestors (an opening dialog's scale). */
+  ancestor: number
+}
+
+/** The translate, in the image's own pixels, for one axis. */
+export function zoomTranslate({
+  cursor,
+  frameStart,
+  frameSize,
+  layoutStart,
+  rendered,
+  ancestor,
+}: ZoomAxis) {
+  const unit = ancestor || 1
+  // Smaller than the frame: centre it, nothing to pan.
+  if (rendered <= frameSize) {
+    return (frameStart + frameSize / 2 - layoutStart - rendered / 2) / unit
+  }
+  const atStart = (frameStart - layoutStart) / unit
+  const atEnd = (frameStart + frameSize - rendered - layoutStart) / unit
+  const progress = Math.max(0, Math.min(1, (cursor - frameStart) / frameSize))
+  return atStart + (atEnd - atStart) * progress
+}
+
+/** The presented scale and translate, including an in-flight transition. */
+function presented(image: HTMLElement) {
+  const style = getComputedStyle(image)
+  const scale = Number.parseFloat(style.scale) || 1
+  const [x = 0, y = 0] = (style.translate || "").split(" ").map(Number.parseFloat)
+  return { scale, x: Number.isFinite(x) ? x : 0, y: Number.isFinite(y) ? y : 0 }
+}
+
+/** Move a magnified image so the point under the pointer comes into view. */
+export function panZoomedImage(
+  image: HTMLElement,
+  frame: DOMRect,
+  clientX: number,
+  clientY: number,
+  scale = IMAGE_ZOOM,
+) {
+  const width = image.offsetWidth
+  const height = image.offsetHeight
+  if (!width || !height) return
+
+  const applied = presented(image)
+  const rect = image.getBoundingClientRect()
+  const ancestor = rect.width / (applied.scale * width) || 1
+  const x = zoomTranslate({
+    cursor: clientX,
+    frameStart: frame.left,
+    frameSize: frame.width,
+    layoutStart: rect.left - ancestor * applied.x,
+    rendered: ancestor * scale * width,
+    ancestor,
+  })
+  const y = zoomTranslate({
+    cursor: clientY,
+    frameStart: frame.top,
+    frameSize: frame.height,
+    layoutStart: rect.top - ancestor * applied.y,
+    rendered: ancestor * scale * height,
+    ancestor,
+  })
+  image.style.translate = `${x}px ${y}px`
+}

package/src/modal.tsx

@@ -39,6 +39,7 @@ import {
 } from "./icons"
 import { cn } from "./lib/cn"
 import { focusRing, focusRingBorder } from "./lib/focus"
+import { IMAGE_ZOOM, panZoomedImage } from "./lib/image-zoom"
 import { motion } from "./lib/motion"
 import {
   Tooltip,
@@ -86,6 +87,8 @@ export type ModalContentProps = Omit<
     downloadName?: string
     imgProps?: Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt">
     children?: ReactNode
+    /** Magnification when the image is clicked. `false` turns zoom off. Default 2. */
+    zoom?: number | false
   }
 
 export type GalleryItem = {
@@ -176,18 +179,24 @@ const ModalImage = ({
   alt,
   imgProps,
   fit = "viewport",
+  imageRef,
+  zoom,
 }: Pick<GalleryItem, "src" | "alt" | "imgProps"> & {
   fit?: "viewport" | "contain"
+  imageRef?: { current: HTMLImageElement | null }
+  /** Zoom state and toggle, for an image that magnifies in place. */
+  zoom?: { scale: number; zoomed: boolean; toggle: (x: number, y: number) => void }
 }) => {
-  const { className, onLoad, onError, ...props } = imgProps ?? {}
+  const { className, onLoad, onError, onClick, style, ...props } = imgProps ?? {}
   // Held transparent until decoded, then faded in: a large file otherwise
   // paints in top-down bands inside the lightbox. The ref catches an image the
   // browser already has (a cached file, or the one the trigger just showed)
   // before first paint, so it appears at once with nothing to fade.
   const [loaded, setLoaded] = useState(false)
   const catchLoaded = useCallback((image: HTMLImageElement | null) => {
+    if (imageRef) imageRef.current = image
     if (image?.complete && image.naturalWidth > 0) setLoaded(true)
-  }, [])
+  }, [imageRef])
 
   return (
     // eslint-disable-next-line @next/next/no-img-element
@@ -208,16 +217,32 @@ const ModalImage = ({
         // Reveal the broken image rather than leave an invisible one.
         setLoaded(true)
       }}
+      onClick={(event) => {
+        onClick?.(event)
+        if (!event.defaultPrevented) zoom?.toggle(event.clientX, event.clientY)
+      }}
       className={cn(
-        // Linear, like every fade in `motion` — see the note there.
-        "transition-opacity duration-[var(--duration-lg)] ease-linear motion-reduce:transition-none",
+        // Linear, like every fade in `motion` — see the note there. The zoom
+        // eases scale and translate; while the pointer pans, translate
+        // follows it without easing.
+        zoom
+          ? "motion-safe:[transition:opacity_var(--duration-lg)_linear,scale_var(--duration-md)_var(--ease-move),translate_var(--duration-md)_var(--ease-move)] motion-safe:data-[panning]:[transition-property:opacity,scale]"
+          : "transition-opacity duration-[var(--duration-lg)] ease-linear motion-reduce:transition-none",
         !loaded && "opacity-0",
-        "rounded-lg object-contain shadow-lg select-none",
+        // Sized by the image itself: width and height attributes with
+        // separate max caps made a box of another shape, which object-contain
+        // letterboxed, leaving the rounded corners on empty space.
+        "h-auto w-auto rounded-lg object-contain shadow-lg select-none",
+        // Scaled from the top-left, so the pan lands the image exactly where
+        // it is measured.
+        zoom && "origin-top-left",
+        zoom && (zoom.zoomed ? "cursor-zoom-out touch-none" : "cursor-zoom-in"),
         fit === "contain"
           ? "max-h-full max-w-full"
           : "max-h-[82dvh] max-w-[88vw] max-sm:max-h-[calc(100dvh-2rem)] max-sm:max-w-[calc(100vw-2rem)]",
         className,
       )}
+      style={zoom ? { ...style, scale: zoom.zoomed ? String(zoom.scale) : "1" } : style}
       {...props}
     />
   )
@@ -298,12 +323,104 @@ const ModalDismiss = () => (
   </ModalControlTooltip>
 )
 
-const ModalCaption = ({ children }: { children: ReactNode }) => (
-  <p className="mt-3 max-w-[min(40rem,88vw)] shrink-0 px-4 text-center text-sm text-fg-scrim-secondary">
+const ModalCaption = ({ children, hidden }: { children: ReactNode; hidden?: boolean }) => (
+  <p
+    className={cn(
+      "mt-3 max-w-[min(40rem,88vw)] shrink-0 px-4 text-center text-sm text-fg-scrim-secondary",
+      "transition-opacity duration-[var(--duration-sm)] ease-linear motion-reduce:transition-none",
+      // The magnified image covers the caption's place; don't show through it.
+      hidden && "opacity-0",
+    )}
+  >
     {children}
   </p>
 )
 
+/**
+ * Zoom for one image: a click magnifies at the point, then the image pans
+ * under the pointer. A mouse or pen pans by moving; a finger drags.
+ */
+function useImageZoom(scale: number | false) {
+  const [zoomed, setZoomed] = useState(false)
+  const imageRef = useRef<HTMLImageElement | null>(null)
+  const frameRef = useRef<HTMLDivElement | null>(null)
+  // Where the pan is aimed, in client pixels.
+  const aim = useRef({ x: 0, y: 0 })
+
+  const toggle = useCallback(
+    (x: number, y: number) => {
+      const image = imageRef.current
+      const frame = frameRef.current
+      if (!scale || !image || !frame) return
+      // The zoom itself eases, towards the point.
+      delete image.dataset.panning
+      if (zoomed) {
+        image.style.translate = "0px 0px"
+      } else {
+        aim.current = { x, y }
+        panZoomedImage(image, frame.getBoundingClientRect(), x, y, scale)
+      }
+      setZoomed(!zoomed)
+    },
+    [scale, zoomed],
+  )
+
+  useEffect(() => {
+    const image = imageRef.current
+    const frame = frameRef.current
+    if (!zoomed || !scale || !image || !frame) return
+    let pending = 0
+    let drag: { x: number; y: number } | null = null
+    const pan = () => {
+      pending = 0
+      image.dataset.panning = ""
+      panZoomedImage(image, frame.getBoundingClientRect(), aim.current.x, aim.current.y, scale)
+    }
+    const schedule = () => {
+      if (!pending) pending = requestAnimationFrame(pan)
+    }
+    const down = (event: PointerEvent) => {
+      if (event.pointerType === "touch") drag = { x: event.clientX, y: event.clientY }
+    }
+    const move = (event: PointerEvent) => {
+      if (event.pointerType !== "touch") {
+        aim.current = { x: event.clientX, y: event.clientY }
+        schedule()
+        return
+      }
+      if (!drag) return
+      // A finger carries the image: aim the opposite way, by the ratio of
+      // the frame to the image's travel past it.
+      const bounds = frame.getBoundingClientRect()
+      const rendered = image.getBoundingClientRect()
+      const travelX = Math.max(1, rendered.width - bounds.width)
+      const travelY = Math.max(1, rendered.height - bounds.height)
+      aim.current = {
+        x: Math.max(bounds.left, Math.min(bounds.right, aim.current.x - ((event.clientX - drag.x) * bounds.width) / travelX)),
+        y: Math.max(bounds.top, Math.min(bounds.bottom, aim.current.y - ((event.clientY - drag.y) * bounds.height) / travelY)),
+      }
+      drag = { x: event.clientX, y: event.clientY }
+      schedule()
+    }
+    const up = () => {
+      drag = null
+    }
+    document.addEventListener("pointerdown", down, { passive: true })
+    document.addEventListener("pointermove", move, { passive: true })
+    document.addEventListener("pointerup", up, { passive: true })
+    document.addEventListener("pointercancel", up, { passive: true })
+    return () => {
+      document.removeEventListener("pointerdown", down)
+      document.removeEventListener("pointermove", move)
+      document.removeEventListener("pointerup", up)
+      document.removeEventListener("pointercancel", up)
+      cancelAnimationFrame(pending)
+    }
+  }, [scale, zoomed])
+
+  return { zoomed, toggle, imageRef, frameRef }
+}
+
 export const ModalContent = ({
   src,
   alt,
@@ -314,8 +431,11 @@ export const ModalContent = ({
   className,
   imgProps,
   children,
+  zoom = IMAGE_ZOOM,
   ...props
-}: ModalContentProps) => (
+}: ModalContentProps) => {
+  const { zoomed, toggle, imageRef, frameRef } = useImageZoom(zoom)
+  return (
   <DialogPortal>
     <ModalBackdrop />
     <DialogPopup
@@ -332,12 +452,19 @@ export const ModalContent = ({
           <ModalBackground src={src} />
           <DialogTitle className="sr-only">{alt}</DialogTitle>
           <div
+            ref={frameRef}
             data-slot="modal-stage"
             className="relative z-10 flex size-full flex-col items-center justify-center p-4"
           >
-            <ModalImage src={src} alt={alt} imgProps={imgProps} />
+            <ModalImage
+              src={src}
+              alt={alt}
+              imgProps={imgProps}
+              imageRef={imageRef}
+              zoom={zoom ? { scale: zoom, zoomed, toggle } : undefined}
+            />
             {variant === "caption" && (caption || children) ? (
-              <ModalCaption>{caption ?? children}</ModalCaption>
+              <ModalCaption hidden={zoomed}>{caption ?? children}</ModalCaption>
             ) : null}
           </div>
           <ModalDismiss />
@@ -349,7 +476,8 @@ export const ModalContent = ({
       </TooltipProvider>
     </DialogPopup>
   </DialogPortal>
-)
+  )
+}
 
 export const GalleryTrigger = ({
   index,