zoooom 1.0.0

package/src/core/transform.ts

@@ -0,0 +1,146 @@
+import { MIN_SCALE, OVERSCALE_FACTOR, VELOCITY_DAMPING } from './constants.js';
+import type { ZoooomState, ZoooomElements } from '../types.js';
+
+/**
+ * Apply the current transform state to the image element.
+ * Uses translate(calc(-50% + Xpx), calc(-50% + Ypx)) scale(S) for center-anchored zoom.
+ */
+export function updateTransform(state: ZoooomState, elements: ZoooomElements): void {
+  if (!elements.image) return;
+  elements.image.style.transform =
+    `translate(calc(-50% + ${state.translateX}px), calc(-50% + ${state.translateY}px)) scale(${state.scale})`;
+}
+
+/**
+ * Animate momentum after pan release — velocity decays per frame via damping.
+ * Skipped when reduced motion is preferred.
+ */
+export function animateMovement(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  onPan?: (x: number, y: number) => void,
+): void {
+  if (state.reducedMotion) {
+    state.velocityX = 0;
+    state.velocityY = 0;
+    return;
+  }
+
+  state.isAnimating = true;
+
+  function step() {
+    state.translateX += state.velocityX;
+    state.translateY += state.velocityY;
+    state.velocityX *= VELOCITY_DAMPING;
+    state.velocityY *= VELOCITY_DAMPING;
+
+    updateTransform(state, elements);
+    onPan?.(state.translateX, state.translateY);
+
+    if (Math.abs(state.velocityX) > 0.1 || Math.abs(state.velocityY) > 0.1) {
+      requestAnimationFrame(step);
+    } else {
+      state.velocityX = 0;
+      state.velocityY = 0;
+      state.isAnimating = false;
+    }
+  }
+
+  requestAnimationFrame(step);
+}
+
+/** Center the image in the container (reset translate without changing scale) */
+export function centerImage(state: ZoooomState, elements: ZoooomElements): void {
+  if (!elements.container || !elements.image) return;
+  state.translateX = 0;
+  state.translateY = 0;
+  updateTransform(state, elements);
+}
+
+/** Reset view to scale=1, centered, zero velocity */
+export function resetView(state: ZoooomState, elements: ZoooomElements): void {
+  state.scale = 1;
+  state.translateX = 0;
+  state.translateY = 0;
+  state.velocityX = 0;
+  state.velocityY = 0;
+  updateTransform(state, elements);
+}
+
+/**
+ * Calculate the maximum zoom scale from the image's natural vs displayed dimensions.
+ * Allows zooming to full native resolution * overscale factor.
+ */
+export function calculateMaxScale(
+  elements: ZoooomElements,
+  overscaleFactor: number = OVERSCALE_FACTOR,
+): number {
+  if (!elements.image) return 10;
+
+  const naturalWidth = elements.image.naturalWidth;
+  const naturalHeight = elements.image.naturalHeight;
+  const displayWidth = elements.image.clientWidth;
+  const displayHeight = elements.image.clientHeight;
+
+  if (!naturalWidth || !naturalHeight || !displayWidth || !displayHeight) return 10;
+
+  const widthRatio = naturalWidth / displayWidth;
+  const heightRatio = naturalHeight / displayHeight;
+  const maxScaleFactor = Math.max(widthRatio, heightRatio);
+
+  // Higher overscale on mobile for full-res zoom
+  const mobileOverscale = window.innerWidth <= 768 ? overscaleFactor * 2 : overscaleFactor;
+  return Math.max(maxScaleFactor * mobileOverscale, MIN_SCALE);
+}
+
+/**
+ * Zoom toward a specific point (cursor, pinch center, or container center).
+ * Maintains the image point under the target coordinate.
+ */
+export function zoomTowardsPoint(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  delta: number,
+  pointX?: number,
+  pointY?: number,
+  onZoom?: (scale: number) => void,
+): void {
+  if (!elements.container || !elements.image) return;
+
+  const currentScale = state.scale;
+  const newScale = Math.max(MIN_SCALE, Math.min(state.scale * delta, state.maxScale));
+
+  if (newScale === currentScale) return;
+
+  const containerRect = elements.container.getBoundingClientRect();
+  const containerCenterX = containerRect.width / 2;
+  const containerCenterY = containerRect.height / 2;
+
+  const targetX = pointX ?? containerCenterX;
+  const targetY = pointY ?? containerCenterY;
+
+  // Calculate the image point under the target coordinate
+  const imageX = (targetX - containerCenterX - state.translateX) / currentScale;
+  const imageY = (targetY - containerCenterY - state.translateY) / currentScale;
+
+  // Update translation to keep that point stationary
+  state.translateX = targetX - containerCenterX - imageX * newScale;
+  state.translateY = targetY - containerCenterY - imageY * newScale;
+
+  // Smooth zoom transition (skipped for reduced motion)
+  if (!state.reducedMotion) {
+    elements.image.style.transition = 'transform 0.2s ease-out';
+  }
+
+  state.scale = newScale;
+  updateTransform(state, elements);
+  onZoom?.(state.scale);
+
+  if (!state.reducedMotion) {
+    setTimeout(() => {
+      if (elements.image) {
+        elements.image.style.transition = '';
+      }
+    }, 200);
+  }
+}

package/src/full.ts

@@ -0,0 +1,8 @@
+export { Zoooom, Zoooom as default } from './core/Zoooom.js';
+export { ZoooomJoystick } from './joystick/index.js';
+export type {
+  ZoooomOptions,
+  ZoooomEvent,
+  ZoooomEventHandler,
+  JoystickOptions,
+} from './types.js';

package/src/iife-entry.ts

@@ -0,0 +1,2 @@
+// IIFE entry — exposes Zoooom constructor directly as window.Zoooom
+export { Zoooom as default } from './core/Zoooom.js';

package/src/iife-full-entry.ts

@@ -0,0 +1,3 @@
+// IIFE full entry — exposes Zoooom + ZoooomJoystick as window.Zoooom
+export { Zoooom as default } from './core/Zoooom.js';
+export { ZoooomJoystick } from './joystick/index.js';

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Zoooom } from './core/Zoooom.js';
+export type {
+  ZoooomOptions,
+  ZoooomEvent,
+  ZoooomEventHandler,
+  JoystickOptions,
+} from './types.js';
+
+// Default export for convenient usage: import Zoooom from 'zoooom'
+import { Zoooom } from './core/Zoooom.js';
+export default Zoooom;

package/src/input/gesture.ts

@@ -0,0 +1,49 @@
+import { ZOOM_FACTOR } from '../core/constants.js';
+import { zoomTowardsPoint } from '../core/transform.js';
+import type { ZoooomState, ZoooomElements, InputCleanup } from '../types.js';
+
+/**
+ * Attach Safari gesture events (gesturestart/change/end).
+ * Only activates in Safari where GestureEvent exists.
+ */
+export function attachGesture(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  onZoom?: (scale: number) => void,
+): InputCleanup {
+  const { container } = elements;
+
+  // Only Safari supports gesture events
+  if (!('ongesturestart' in window)) {
+    return () => {};
+  }
+
+  let startScale = 1;
+
+  function handleGestureStart(e: Event) {
+    e.preventDefault();
+    startScale = state.scale;
+  }
+
+  function handleGestureChange(e: Event) {
+    e.preventDefault();
+    const ge = e as unknown as { scale: number };
+    const rect = container.getBoundingClientRect();
+    const delta = ge.scale > 1 ? ZOOM_FACTOR : 1 / ZOOM_FACTOR;
+    zoomTowardsPoint(state, elements, delta, rect.width / 2, rect.height / 2, onZoom);
+  }
+
+  function handleGestureEnd(e: Event) {
+    e.preventDefault();
+  }
+
+  container.addEventListener('gesturestart', handleGestureStart, { passive: false } as EventListenerOptions);
+  container.addEventListener('gesturechange', handleGestureChange, { passive: false } as EventListenerOptions);
+  container.addEventListener('gestureend', handleGestureEnd, { passive: false } as EventListenerOptions);
+
+  return () => {
+    container.removeEventListener('gesturestart', handleGestureStart);
+    container.removeEventListener('gesturechange', handleGestureChange);
+    container.removeEventListener('gestureend', handleGestureEnd);
+  };
+}

package/src/input/keyboard.ts

@@ -0,0 +1,60 @@
+import { PAN_STEP, ZOOM_FACTOR } from '../core/constants.js';
+import { zoomTowardsPoint, animateMovement, resetView } from '../core/transform.js';
+import type { ZoooomState, ZoooomElements, InputCleanup } from '../types.js';
+
+/**
+ * Attach keyboard navigation handlers.
+ * Arrows pan, +/- zoom, R resets, Escape is reserved for parent contexts.
+ */
+export function attachKeyboard(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  panStep: number = PAN_STEP,
+  zoomFactor: number = ZOOM_FACTOR,
+  onPan?: (x: number, y: number) => void,
+  onZoom?: (scale: number) => void,
+): InputCleanup {
+  const { container } = elements;
+
+  function handleKeyDown(e: KeyboardEvent) {
+    let handled = true;
+
+    switch (e.key) {
+      case 'ArrowLeft':
+        state.velocityX = panStep * 0.2;
+        animateMovement(state, elements, onPan);
+        break;
+      case 'ArrowRight':
+        state.velocityX = -panStep * 0.2;
+        animateMovement(state, elements, onPan);
+        break;
+      case 'ArrowUp':
+        state.velocityY = panStep * 0.2;
+        animateMovement(state, elements, onPan);
+        break;
+      case 'ArrowDown':
+        state.velocityY = -panStep * 0.2;
+        animateMovement(state, elements, onPan);
+        break;
+      case '+': case '=':
+        zoomTowardsPoint(state, elements, zoomFactor, undefined, undefined, onZoom);
+        break;
+      case '-':
+        zoomTowardsPoint(state, elements, 1 / zoomFactor, undefined, undefined, onZoom);
+        break;
+      case 'r': case 'R':
+        resetView(state, elements);
+        break;
+      default:
+        handled = false;
+    }
+
+    if (handled) e.preventDefault();
+  }
+
+  container.addEventListener('keydown', handleKeyDown);
+
+  return () => {
+    container.removeEventListener('keydown', handleKeyDown);
+  };
+}

package/src/input/mouse.ts

@@ -0,0 +1,54 @@
+import type { ZoooomState, ZoooomElements, InputCleanup } from '../types.js';
+import { updateTransform } from '../core/transform.js';
+
+/**
+ * Attach mouse drag-to-pan handlers.
+ * Returns a cleanup function to remove all listeners.
+ */
+export function attachMouse(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  onPan?: (x: number, y: number) => void,
+): InputCleanup {
+  const { container } = elements;
+
+  function handleMouseDown(e: MouseEvent) {
+    if (e.button !== 0) return; // Left button only
+    state.isDragging = true;
+    state.startX = e.clientX;
+    state.startY = e.clientY;
+    container.style.cursor = 'grabbing';
+    e.preventDefault();
+  }
+
+  function handleMouseMove(e: MouseEvent) {
+    if (!state.isDragging) return;
+    const dx = e.clientX - state.startX;
+    const dy = e.clientY - state.startY;
+    state.translateX += dx;
+    state.translateY += dy;
+    state.startX = e.clientX;
+    state.startY = e.clientY;
+    updateTransform(state, elements);
+    onPan?.(state.translateX, state.translateY);
+  }
+
+  function handleMouseUp() {
+    if (state.isDragging) {
+      state.isDragging = false;
+      container.style.cursor = 'grab';
+    }
+  }
+
+  container.addEventListener('mousedown', handleMouseDown);
+  container.addEventListener('mousemove', handleMouseMove);
+  container.addEventListener('mouseup', handleMouseUp);
+  container.addEventListener('mouseleave', handleMouseUp);
+
+  return () => {
+    container.removeEventListener('mousedown', handleMouseDown);
+    container.removeEventListener('mousemove', handleMouseMove);
+    container.removeEventListener('mouseup', handleMouseUp);
+    container.removeEventListener('mouseleave', handleMouseUp);
+  };
+}

package/src/input/touch.ts

@@ -0,0 +1,111 @@
+import { MIN_SCALE } from '../core/constants.js';
+import { calculateMaxScale, updateTransform } from '../core/transform.js';
+import type { ZoooomState, ZoooomElements, InputCleanup } from '../types.js';
+
+function getDistance(e: TouchEvent): number {
+  const t1 = e.touches[0];
+  const t2 = e.touches[1];
+  const dx = t1.clientX - t2.clientX;
+  const dy = t1.clientY - t2.clientY;
+  return Math.sqrt(dx * dx + dy * dy);
+}
+
+/**
+ * Attach touch pan and pinch-to-zoom handlers.
+ * Returns a cleanup function to remove all listeners.
+ */
+export function attachTouch(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  overscaleFactor: number,
+  onPan?: (x: number, y: number) => void,
+  onZoom?: (scale: number) => void,
+): InputCleanup {
+  const { container } = elements;
+
+  function handleTouchStart(e: TouchEvent) {
+    if (e.touches.length === 1) {
+      state.isDragging = true;
+      state.startX = e.touches[0].clientX;
+      state.startY = e.touches[0].clientY;
+      state.initialDistance = 0;
+    } else if (e.touches.length === 2) {
+      state.isDragging = false;
+      state.initialDistance = getDistance(e);
+      state.initialScale = state.scale;
+      state.initialTranslateX = state.translateX;
+      state.initialTranslateY = state.translateY;
+
+      const t1 = e.touches[0];
+      const t2 = e.touches[1];
+      const rect = container.getBoundingClientRect();
+      state.pinchCenter = {
+        x: ((t1.clientX + t2.clientX) / 2) - rect.left,
+        y: ((t1.clientY + t2.clientY) / 2) - rect.top,
+      };
+    }
+  }
+
+  function handleTouchMove(e: TouchEvent) {
+    e.preventDefault();
+
+    if (e.touches.length === 1 && state.isDragging) {
+      const dx = e.touches[0].clientX - state.startX;
+      const dy = e.touches[0].clientY - state.startY;
+      state.translateX += dx;
+      state.translateY += dy;
+      state.startX = e.touches[0].clientX;
+      state.startY = e.touches[0].clientY;
+      updateTransform(state, elements);
+      onPan?.(state.translateX, state.translateY);
+    } else if (e.touches.length === 2 && state.initialDistance > 0) {
+      const currentDistance = getDistance(e);
+      const scaleFactor = currentDistance / state.initialDistance;
+      const targetScale = state.initialScale * scaleFactor;
+      state.maxScale = calculateMaxScale(elements, overscaleFactor);
+      const newScale = Math.max(MIN_SCALE, Math.min(targetScale, state.maxScale));
+
+      if (newScale === state.scale) return;
+
+      const t1 = e.touches[0];
+      const t2 = e.touches[1];
+      const rect = container.getBoundingClientRect();
+      const currentPinchCenter = {
+        x: ((t1.clientX + t2.clientX) / 2) - rect.left,
+        y: ((t1.clientY + t2.clientY) / 2) - rect.top,
+      };
+
+      const containerCenterX = rect.width / 2;
+      const containerCenterY = rect.height / 2;
+
+      const imageX = (state.pinchCenter.x - containerCenterX - state.initialTranslateX) / state.initialScale;
+      const imageY = (state.pinchCenter.y - containerCenterY - state.initialTranslateY) / state.initialScale;
+
+      state.translateX = currentPinchCenter.x - containerCenterX - imageX * newScale;
+      state.translateY = currentPinchCenter.y - containerCenterY - imageY * newScale;
+
+      state.scale = newScale;
+      updateTransform(state, elements);
+      onZoom?.(state.scale);
+
+      state.pinchCenter = currentPinchCenter;
+    }
+  }
+
+  function handleTouchEnd() {
+    state.isDragging = false;
+    state.initialDistance = 0;
+  }
+
+  container.addEventListener('touchstart', handleTouchStart, { passive: false });
+  container.addEventListener('touchmove', handleTouchMove, { passive: false });
+  container.addEventListener('touchend', handleTouchEnd);
+  container.addEventListener('touchcancel', handleTouchEnd);
+
+  return () => {
+    container.removeEventListener('touchstart', handleTouchStart);
+    container.removeEventListener('touchmove', handleTouchMove);
+    container.removeEventListener('touchend', handleTouchEnd);
+    container.removeEventListener('touchcancel', handleTouchEnd);
+  };
+}

package/src/input/wheel.ts

@@ -0,0 +1,65 @@
+import { ZOOM_FACTOR, TRACKPAD_SENSITIVITY } from '../core/constants.js';
+import { zoomTowardsPoint } from '../core/transform.js';
+import type { ZoooomState, ZoooomElements, InputCleanup } from '../types.js';
+
+/**
+ * Attach wheel/trackpad zoom handler.
+ * Detects trackpad vs mouse wheel via delta magnitude.
+ * Handles Ctrl+wheel for pinch gestures on Windows/Linux.
+ */
+export function attachWheel(
+  state: ZoooomState,
+  elements: ZoooomElements,
+  zoomFactor: number = ZOOM_FACTOR,
+  trackpadSensitivity: number = TRACKPAD_SENSITIVITY,
+  onZoom?: (scale: number) => void,
+): InputCleanup {
+  const { container } = elements;
+
+  function handleWheel(e: WheelEvent) {
+    e.preventDefault();
+
+    const rect = container.getBoundingClientRect();
+    const pointX = e.clientX - rect.left;
+    const pointY = e.clientY - rect.top;
+
+    let zoomDelta: number;
+
+    if (e.ctrlKey) {
+      // Pinch gesture (Ctrl+wheel on Windows/Linux)
+      zoomDelta = e.deltaY < 0 ? zoomFactor : 1 / zoomFactor;
+    } else {
+      // Normalize delta based on deltaMode
+      let normalizedDelta: number;
+      switch (e.deltaMode) {
+        case 1: normalizedDelta = e.deltaY * 20; break;   // LINE
+        case 2: normalizedDelta = e.deltaY * 100; break;  // PAGE
+        default: normalizedDelta = e.deltaY;               // PIXEL
+      }
+
+      if (Math.abs(normalizedDelta) < 40) {
+        // Trackpad — continuous zoom
+        zoomDelta = Math.exp(-normalizedDelta * trackpadSensitivity);
+      } else {
+        // Mouse wheel — discrete steps
+        zoomDelta = normalizedDelta > 0 ? 1 / zoomFactor : zoomFactor;
+      }
+    }
+
+    // Manage scroll state class for CSS transition control
+    container.classList.add('zoooom-scrolling');
+    if (state.wheelTimeout) clearTimeout(state.wheelTimeout);
+    state.wheelTimeout = setTimeout(() => {
+      container.classList.remove('zoooom-scrolling');
+    }, 200);
+
+    zoomTowardsPoint(state, elements, zoomDelta, pointX, pointY, onZoom);
+  }
+
+  container.addEventListener('wheel', handleWheel, { passive: false });
+
+  return () => {
+    container.removeEventListener('wheel', handleWheel);
+    if (state.wheelTimeout) clearTimeout(state.wheelTimeout);
+  };
+}

package/src/joystick/dom.ts

@@ -0,0 +1,81 @@
+/**
+ * Create the joystick DOM structure.
+ * Returns references to key elements for event binding.
+ */
+export interface JoystickDOM {
+  wrap: HTMLElement;
+  toggle: HTMLButtonElement;
+  disc: HTMLElement;
+  innerCircle: HTMLElement;
+  zoomIn: HTMLElement;
+  zoomOut: HTMLElement;
+}
+
+export function createJoystickDOM(container: HTMLElement): JoystickDOM {
+  // Toggle button (compass)
+  const toggle = document.createElement('button');
+  toggle.className = 'zoooom-joystick-toggle';
+  toggle.setAttribute('aria-label', 'Toggle navigation joystick');
+  toggle.setAttribute('aria-expanded', 'false');
+  toggle.textContent = '\u2316'; // ⌖ position indicator
+  container.appendChild(toggle);
+
+  // Joystick wrapper
+  const wrap = document.createElement('div');
+  wrap.className = 'zoooom-joystick-wrap';
+  wrap.setAttribute('aria-hidden', 'true');
+
+  // Disc (outer pan area)
+  const disc = document.createElement('div');
+  disc.className = 'zoooom-disc';
+  disc.setAttribute('role', 'slider');
+  disc.setAttribute('aria-label', 'Pan navigation control');
+  disc.setAttribute('aria-valuenow', '0');
+  disc.setAttribute('aria-valuemin', '0');
+  disc.setAttribute('aria-valuemax', '1');
+  disc.setAttribute('aria-valuetext', 'Center position — not moving');
+  disc.setAttribute('tabindex', '0');
+
+  // Inner circle (zoom)
+  const innerCircle = document.createElement('div');
+  innerCircle.className = 'zoooom-inner-circle';
+
+  const zoomOut = document.createElement('div');
+  zoomOut.className = 'zoooom-zoom-half zoooom-zoom-out';
+  zoomOut.setAttribute('role', 'button');
+  zoomOut.setAttribute('aria-label', 'Zoom out');
+  zoomOut.setAttribute('tabindex', '0');
+  zoomOut.textContent = '\u2212'; // −
+
+  const zoomIn = document.createElement('div');
+  zoomIn.className = 'zoooom-zoom-half zoooom-zoom-in';
+  zoomIn.setAttribute('role', 'button');
+  zoomIn.setAttribute('aria-label', 'Zoom in');
+  zoomIn.setAttribute('tabindex', '0');
+  zoomIn.textContent = '+';
+
+  innerCircle.appendChild(zoomOut);
+  innerCircle.appendChild(zoomIn);
+
+  // Direction arrows
+  const arrows = document.createElement('div');
+  arrows.className = 'zoooom-arrows';
+  arrows.setAttribute('aria-hidden', 'true');
+  for (const dir of ['n', 'e', 's', 'w']) {
+    const arrow = document.createElement('div');
+    arrow.className = `zoooom-arrow zoooom-arrow-${dir}`;
+    arrows.appendChild(arrow);
+  }
+
+  disc.appendChild(innerCircle);
+  disc.appendChild(arrows);
+  wrap.appendChild(disc);
+  container.appendChild(wrap);
+
+  return { wrap, toggle, disc, innerCircle, zoomIn, zoomOut };
+}
+
+export function destroyJoystickDOM(dom: JoystickDOM): void {
+  dom.wrap.remove();
+  dom.toggle.remove();
+}

package/src/joystick/index.ts

@@ -0,0 +1,2 @@
+export { ZoooomJoystick } from './joystick.js';
+export type { JoystickOptions } from '../types.js';