zoooom 1.0.0

package/src/joystick/joystick.ts

@@ -0,0 +1,280 @@
+import type { JoystickOptions } from '../types.js';
+import { JOYSTICK_RADIUS, JOYSTICK_DEADZONE, MAX_JOYSTICK_SPEED, DWELL_TIMEOUT } from '../core/constants.js';
+import type { Zoooom } from '../core/Zoooom.js';
+import { createJoystickDOM, destroyJoystickDOM, type JoystickDOM } from './dom.js';
+import { injectJoystickStyles } from '../styles/joystick.js';
+
+const DIRECTIONS = [
+  'east', 'south-east', 'south', 'south-west',
+  'west', 'north-west', 'north', 'north-east',
+] as const;
+
+function angleToDirection(angle: number): string {
+  if (angle >= -22.5 && angle < 22.5) return 'east';
+  if (angle >= 22.5 && angle < 67.5) return 'south-east';
+  if (angle >= 67.5 && angle < 112.5) return 'south';
+  if (angle >= 112.5 && angle < 157.5) return 'south-west';
+  if (angle >= 157.5 || angle < -157.5) return 'west';
+  if (angle >= -157.5 && angle < -112.5) return 'north-west';
+  if (angle >= -112.5 && angle < -67.5) return 'north';
+  return 'north-east';
+}
+
+export class ZoooomJoystick {
+  private viewer: Zoooom;
+  private dom: JoystickDOM;
+  private options: Required<JoystickOptions>;
+  private visible = false;
+  private active = false;
+  private animationId: number | null = null;
+  private joystickX = 0;
+  private joystickY = 0;
+  private currentDirection = '';
+  private dwellTimer: ReturnType<typeof setTimeout> | null = null;
+  private isDwelling = false;
+  private hideTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(viewer: Zoooom, options?: JoystickOptions) {
+    this.viewer = viewer;
+    this.options = {
+      radius: options?.radius ?? JOYSTICK_RADIUS,
+      deadzone: options?.deadzone ?? JOYSTICK_DEADZONE,
+      maxSpeed: options?.maxSpeed ?? MAX_JOYSTICK_SPEED,
+      position: options?.position ?? 'bottom-center',
+      showToggle: options?.showToggle ?? true,
+      dwellTimeout: options?.dwellTimeout ?? DWELL_TIMEOUT,
+    };
+
+    injectJoystickStyles();
+
+    const elements = this.viewer.getElements();
+    this.dom = createJoystickDOM(elements.container);
+    this.bindEvents();
+  }
+
+  show(): void {
+    this.visible = true;
+    this.dom.wrap.classList.add('visible');
+    this.dom.wrap.setAttribute('aria-hidden', 'false');
+    this.dom.toggle.setAttribute('aria-expanded', 'true');
+    if (this.hideTimer) clearTimeout(this.hideTimer);
+  }
+
+  hide(): void {
+    this.visible = false;
+    this.dom.wrap.classList.remove('visible');
+    this.dom.wrap.setAttribute('aria-hidden', 'true');
+    this.dom.toggle.setAttribute('aria-expanded', 'false');
+    this.stopMovement();
+    this.clearDirection();
+  }
+
+  destroy(): void {
+    this.hide();
+    this.stopMovement();
+    if (this.dwellTimer) clearTimeout(this.dwellTimer);
+    if (this.hideTimer) clearTimeout(this.hideTimer);
+    destroyJoystickDOM(this.dom);
+  }
+
+  private bindEvents(): void {
+    const { toggle, disc, zoomIn, zoomOut, innerCircle } = this.dom;
+
+    // Toggle button
+    toggle.addEventListener('click', () => {
+      if (this.visible) this.hide();
+      else this.show();
+    });
+
+    toggle.addEventListener('mouseenter', () => this.show());
+    toggle.addEventListener('mouseleave', () => {
+      this.hideTimer = setTimeout(() => this.hide(), 15000);
+    });
+
+    // Disc — panning
+    disc.addEventListener('mousemove', (e) => {
+      if (e.target !== disc) return;
+      if (!this.isDwelling) {
+        this.startDwell(e);
+      } else {
+        this.handleMove(e);
+      }
+    });
+
+    disc.addEventListener('mousedown', (e) => {
+      if (e.target !== disc) return;
+      e.preventDefault();
+      this.handleMove(e);
+
+      const moveHandler = (me: MouseEvent) => this.handleMove(me);
+      document.addEventListener('mousemove', moveHandler);
+      document.addEventListener('mouseup', () => {
+        document.removeEventListener('mousemove', moveHandler);
+        this.stopDwell();
+        this.resetJoystick();
+      }, { once: true });
+    });
+
+    disc.addEventListener('mouseleave', () => {
+      this.stopDwell();
+      this.resetJoystick();
+    });
+
+    // Touch on disc
+    disc.addEventListener('touchstart', (e) => {
+      if (e.target !== disc) return;
+      e.preventDefault();
+      this.handleMove(e);
+
+      const moveHandler = (te: TouchEvent) => this.handleMove(te);
+      document.addEventListener('touchmove', moveHandler, { passive: false });
+      document.addEventListener('touchend', () => {
+        document.removeEventListener('touchmove', moveHandler);
+        this.stopDwell();
+        this.resetJoystick();
+      }, { once: true });
+    }, { passive: false });
+
+    // Zoom buttons
+    zoomIn.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.viewer.zoomIn();
+    });
+
+    zoomOut.addEventListener('click', (e) => {
+      e.stopPropagation();
+      this.viewer.zoomOut();
+    });
+
+    // Stop panning when entering inner circle
+    innerCircle.addEventListener('mouseenter', () => {
+      this.stopDwell();
+      this.resetJoystick();
+    });
+
+    innerCircle.addEventListener('mousedown', (e) => e.stopPropagation());
+    innerCircle.addEventListener('touchstart', (e) => e.stopPropagation(), { passive: false });
+  }
+
+  private handleMove(event: MouseEvent | TouchEvent): void {
+    if (!this.visible) return;
+
+    const clientX = 'clientX' in event ? event.clientX : event.touches[0]?.clientX ?? 0;
+    const clientY = 'clientY' in event ? event.clientY : event.touches[0]?.clientY ?? 0;
+
+    const rect = this.dom.disc.getBoundingClientRect();
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+    const distX = clientX - centerX;
+    const distY = clientY - centerY;
+    const distance = Math.sqrt(distX * distX + distY * distY);
+
+    // Normalize to -1..1
+    let normalizedX = distX / this.options.radius;
+    let normalizedY = distY / this.options.radius;
+
+    if (distance > this.options.radius) {
+      normalizedX = normalizedX * (this.options.radius / distance);
+      normalizedY = normalizedY * (this.options.radius / distance);
+    }
+
+    if (Math.abs(normalizedX) < this.options.deadzone) normalizedX = 0;
+    if (Math.abs(normalizedY) < this.options.deadzone) normalizedY = 0;
+
+    this.joystickX = normalizedX;
+    this.joystickY = normalizedY;
+
+    // Direction feedback
+    if (distance > this.options.radius * this.options.deadzone) {
+      const angle = Math.atan2(distY, distX) * 180 / Math.PI;
+      const dir = angleToDirection(angle);
+      if (dir !== this.currentDirection) {
+        this.clearDirection();
+        this.dom.disc.classList.add(dir);
+        this.currentDirection = dir;
+      }
+    } else {
+      this.clearDirection();
+    }
+
+    // Start movement if not already running
+    if (!this.animationId && (Math.abs(normalizedX) > this.options.deadzone || Math.abs(normalizedY) > this.options.deadzone)) {
+      this.active = true;
+      this.dom.disc.classList.add('active');
+      this.startMovement();
+      this.updateAria(normalizedX, normalizedY);
+    } else if (Math.abs(normalizedX) <= this.options.deadzone && Math.abs(normalizedY) <= this.options.deadzone) {
+      this.active = false;
+      this.dom.disc.classList.remove('active');
+      this.stopMovement();
+      this.dom.disc.setAttribute('aria-valuenow', '0');
+      this.dom.disc.setAttribute('aria-valuetext', 'Center position — not moving');
+    }
+  }
+
+  private startDwell(e: MouseEvent | TouchEvent): void {
+    if (this.dwellTimer) clearTimeout(this.dwellTimer);
+    this.dwellTimer = setTimeout(() => {
+      this.isDwelling = true;
+      this.handleMove(e);
+    }, this.options.dwellTimeout);
+  }
+
+  private stopDwell(): void {
+    if (this.dwellTimer) {
+      clearTimeout(this.dwellTimer);
+      this.dwellTimer = null;
+    }
+    this.isDwelling = false;
+  }
+
+  private startMovement(): void {
+    if (this.animationId) return;
+    const step = () => {
+      if (!this.active) { this.stopMovement(); return; }
+      const vx = -this.joystickX * this.options.maxSpeed;
+      const vy = -this.joystickY * this.options.maxSpeed;
+      this.viewer.applyVelocity(vx, vy);
+      this.animationId = requestAnimationFrame(step);
+    };
+    this.animationId = requestAnimationFrame(step);
+  }
+
+  private stopMovement(): void {
+    if (this.animationId) {
+      cancelAnimationFrame(this.animationId);
+      this.animationId = null;
+    }
+  }
+
+  private resetJoystick(): void {
+    this.joystickX = 0;
+    this.joystickY = 0;
+    this.active = false;
+    this.stopMovement();
+    this.clearDirection();
+    this.dom.disc.classList.remove('active');
+  }
+
+  private clearDirection(): void {
+    if (this.currentDirection) {
+      this.dom.disc.classList.remove(this.currentDirection);
+      this.currentDirection = '';
+    }
+  }
+
+  private updateAria(x: number, y: number): void {
+    const magnitude = Math.sqrt(x * x + y * y);
+    this.dom.disc.setAttribute('aria-valuenow', magnitude.toFixed(2));
+
+    let direction: string;
+    if (Math.abs(x) > Math.abs(y)) {
+      direction = x > 0 ? 'right' : 'left';
+    } else {
+      direction = y > 0 ? 'down' : 'up';
+    }
+
+    const intensity = magnitude > 0.7 ? 'fast' : magnitude > 0.3 ? 'medium' : 'slow';
+    this.dom.disc.setAttribute('aria-valuetext', `Moving ${intensity} ${direction}`);
+  }
+}

package/src/styles/core.ts

@@ -0,0 +1,101 @@
+export const ZOOOOM_CSS = `
+[data-zoooom] {
+  --zoooom-bg: #000;
+  --zoooom-spinner-color: #2196f3;
+  --zoooom-spinner-track: rgba(255, 255, 255, 0.3);
+  --zoooom-spinner-size: 40px;
+  --zoooom-loading-bg: rgba(0, 0, 0, 0.85);
+  --zoooom-loading-radius: 10px;
+  --zoooom-cursor: grab;
+  --zoooom-cursor-active: grabbing;
+  --zoooom-transition-speed: 0.2s;
+  --zoooom-fade-speed: 0.3s;
+
+  position: relative;
+  width: 100%;
+  height: 100%;
+  background: var(--zoooom-bg);
+  overflow: hidden;
+  touch-action: none;
+  cursor: var(--zoooom-cursor);
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+[data-zoooom]:focus-visible {
+  outline: 2px solid var(--zoooom-spinner-color);
+  outline-offset: -2px;
+}
+
+[data-zoooom] .zoooom-image {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%) scale(1);
+  max-width: 100%;
+  max-height: 100%;
+  object-fit: contain;
+  user-select: none;
+  -webkit-user-select: none;
+  pointer-events: none;
+}
+
+[data-zoooom] .zoooom-loading {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  background: var(--zoooom-loading-bg);
+  padding: 20px;
+  border-radius: var(--zoooom-loading-radius);
+  z-index: 10;
+  min-width: 120px;
+}
+
+[data-zoooom] .zoooom-spinner {
+  width: var(--zoooom-spinner-size);
+  height: var(--zoooom-spinner-size);
+  border: 4px solid var(--zoooom-spinner-track);
+  border-radius: 50%;
+  border-top-color: var(--zoooom-spinner-color);
+  animation: zoooom-spin 1s linear infinite;
+}
+
+[data-zoooom] .zoooom-loading-text {
+  margin-top: 12px;
+  font-size: 14px;
+  color: #fff;
+  font-family: system-ui, -apple-system, sans-serif;
+}
+
+@keyframes zoooom-spin {
+  to { transform: rotate(360deg); }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-zoooom] .zoooom-spinner {
+    animation: none;
+    border-top-color: var(--zoooom-spinner-track);
+    border-right-color: var(--zoooom-spinner-color);
+  }
+
+  [data-zoooom] .zoooom-image {
+    transition: none !important;
+  }
+}
+`;
+
+let injected = false;
+
+export function injectCoreStyles(): void {
+  if (injected || typeof document === 'undefined') return;
+  const style = document.createElement('style');
+  style.setAttribute('data-zoooom-core', '');
+  style.textContent = ZOOOOM_CSS;
+  document.head.appendChild(style);
+  injected = true;
+}

package/src/styles/joystick.ts

@@ -0,0 +1,213 @@
+export const JOYSTICK_CSS = `
+.zoooom-joystick-wrap {
+  position: fixed;
+  bottom: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 100;
+  touch-action: none;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s ease-out, transform 0.3s ease-out;
+}
+
+.zoooom-joystick-wrap.visible {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.zoooom-joystick-toggle {
+  position: fixed;
+  bottom: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 56px;
+  height: 56px;
+  border-radius: 50%;
+  background: rgba(0, 0, 0, 0.5);
+  border: 2px solid rgba(255, 255, 255, 0.6);
+  cursor: pointer;
+  z-index: 99;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  color: #fff;
+  font-size: 20px;
+  font-weight: bold;
+  backdrop-filter: blur(4px);
+  transition: background 0.2s, box-shadow 0.2s;
+}
+
+.zoooom-joystick-toggle:hover {
+  background: rgba(0, 0, 0, 0.7);
+  box-shadow: 0 0 12px rgba(0, 0, 0, 0.4);
+}
+
+.zoooom-joystick-toggle:focus-visible {
+  outline: 2px solid #2196f3;
+  outline-offset: 2px;
+}
+
+.zoooom-disc {
+  width: 200px;
+  height: 200px;
+  border-radius: 50%;
+  background: rgba(0, 0, 0, 0.4);
+  border: 2px solid rgba(255, 255, 255, 0.6);
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  touch-action: none;
+  box-shadow: 0 0 10px rgba(0, 0, 0, 0.3);
+}
+
+.zoooom-disc.active {
+  border-color: rgba(255, 255, 255, 0.9);
+}
+
+.zoooom-inner-circle {
+  width: 72px;
+  height: 72px;
+  border-radius: 50%;
+  background: rgba(255, 255, 255, 0.15);
+  border: 1px solid rgba(255, 255, 255, 0.5);
+  display: flex;
+  position: relative;
+  z-index: 3;
+}
+
+.zoooom-zoom-half {
+  width: 50%;
+  height: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  font-weight: bold;
+  font-size: 22px;
+  color: #fff;
+  user-select: none;
+  transition: background 0.15s;
+}
+
+.zoooom-zoom-half:hover {
+  background: rgba(255, 255, 255, 0.25);
+}
+
+.zoooom-zoom-out {
+  border-radius: 36px 0 0 36px;
+  border-right: 1px solid rgba(255, 255, 255, 0.4);
+}
+
+.zoooom-zoom-in {
+  border-radius: 0 36px 36px 0;
+}
+
+.zoooom-arrows {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  border-radius: 50%;
+  pointer-events: none;
+  overflow: hidden;
+}
+
+.zoooom-arrow {
+  position: absolute;
+  width: 0;
+  height: 0;
+  opacity: 0;
+  transition: opacity 0.2s;
+}
+
+.zoooom-arrow-n {
+  top: 14px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-left: 10px solid transparent;
+  border-right: 10px solid transparent;
+  border-bottom: 14px solid rgba(255, 255, 255, 0.7);
+}
+
+.zoooom-arrow-e {
+  top: 50%;
+  right: 14px;
+  transform: translateY(-50%);
+  border-top: 10px solid transparent;
+  border-bottom: 10px solid transparent;
+  border-left: 14px solid rgba(255, 255, 255, 0.7);
+}
+
+.zoooom-arrow-s {
+  bottom: 14px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-left: 10px solid transparent;
+  border-right: 10px solid transparent;
+  border-top: 14px solid rgba(255, 255, 255, 0.7);
+}
+
+.zoooom-arrow-w {
+  top: 50%;
+  left: 14px;
+  transform: translateY(-50%);
+  border-top: 10px solid transparent;
+  border-bottom: 10px solid transparent;
+  border-right: 14px solid rgba(255, 255, 255, 0.7);
+}
+
+.zoooom-disc.north .zoooom-arrow-n,
+.zoooom-disc.south .zoooom-arrow-s,
+.zoooom-disc.east .zoooom-arrow-e,
+.zoooom-disc.west .zoooom-arrow-w,
+.zoooom-disc.north-east .zoooom-arrow-n,
+.zoooom-disc.north-east .zoooom-arrow-e,
+.zoooom-disc.south-east .zoooom-arrow-s,
+.zoooom-disc.south-east .zoooom-arrow-e,
+.zoooom-disc.south-west .zoooom-arrow-s,
+.zoooom-disc.south-west .zoooom-arrow-w,
+.zoooom-disc.north-west .zoooom-arrow-n,
+.zoooom-disc.north-west .zoooom-arrow-w {
+  opacity: 1;
+}
+
+@media (max-width: 768px) {
+  .zoooom-disc {
+    width: 140px;
+    height: 140px;
+  }
+
+  .zoooom-inner-circle {
+    width: 56px;
+    height: 56px;
+  }
+
+  .zoooom-joystick-toggle {
+    width: 48px;
+    height: 48px;
+    font-size: 16px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .zoooom-joystick-wrap {
+    transition: none;
+  }
+
+  .zoooom-arrow {
+    transition: none;
+  }
+}
+`;
+
+let injected = false;
+
+export function injectJoystickStyles(): void {
+  if (injected || typeof document === 'undefined') return;
+  const style = document.createElement('style');
+  style.setAttribute('data-zoooom-joystick', '');
+  style.textContent = JOYSTICK_CSS;
+  document.head.appendChild(style);
+  injected = true;
+}

package/src/types.ts

@@ -0,0 +1,118 @@
+/** Configuration options for the Zoooom viewer */
+export interface ZoooomOptions {
+  /** Image URL to display (required) */
+  src: string;
+  /** Alt text for the image */
+  alt?: string;
+
+  // Zoom behavior
+  /** Minimum zoom scale (default: 0.8) */
+  minScale?: number;
+  /** Maximum zoom scale — 'auto' calculates from natural dimensions (default: 'auto') */
+  maxScale?: number | 'auto';
+  /** Multiplier beyond native resolution for max zoom (default: 2) */
+  overscaleFactor?: number;
+  /** Zoom multiplier per discrete step (default: 1.5) */
+  zoomFactor?: number;
+
+  // Pan behavior
+  /** Keyboard pan distance in pixels (default: 50) */
+  panStep?: number;
+  /** Momentum friction coefficient, 0-1 (default: 0.85) */
+  velocityDamping?: number;
+
+  // Trackpad
+  /** Sensitivity for continuous trackpad zoom (default: 0.002) */
+  trackpadSensitivity?: number;
+
+  // Input methods
+  /** Enable mouse drag/wheel (default: true) */
+  mouse?: boolean;
+  /** Enable touch pan/pinch (default: true) */
+  touch?: boolean;
+  /** Enable wheel/trackpad zoom (default: true) */
+  wheel?: boolean;
+  /** Enable keyboard navigation (default: true) */
+  keyboard?: boolean;
+
+  // Loading
+  /** Show loading spinner — true for default, string for custom HTML, false to disable */
+  loading?: boolean | string;
+
+  // CSS
+  /** Auto-inject bundled CSS (default: true) */
+  injectStyles?: boolean;
+
+  // Accessibility
+  /** Honor prefers-reduced-motion (default: true) */
+  respectReducedMotion?: boolean;
+
+  // Callbacks
+  onLoad?: () => void;
+  onError?: (error: Error) => void;
+  onZoom?: (scale: number) => void;
+  onPan?: (x: number, y: number) => void;
+}
+
+/** Internal mutable state for the viewer */
+export interface ZoooomState {
+  scale: number;
+  translateX: number;
+  translateY: number;
+  velocityX: number;
+  velocityY: number;
+  maxScale: number;
+  isDragging: boolean;
+  isAnimating: boolean;
+  isLoaded: boolean;
+  startX: number;
+  startY: number;
+  initialDistance: number;
+  initialScale: number;
+  initialTranslateX: number;
+  initialTranslateY: number;
+  pinchCenter: { x: number; y: number };
+  wheelTimeout: ReturnType<typeof setTimeout> | null;
+  reducedMotion: boolean;
+}
+
+/** Event types emitted by Zoooom */
+export type ZoooomEvent = 'load' | 'error' | 'zoom' | 'pan' | 'reset' | 'destroy';
+
+/** Event handler function */
+export type ZoooomEventHandler = (...args: unknown[]) => void;
+
+/** Resolved options with defaults applied */
+export type ZoooomResolvedOptions = Required<Omit<ZoooomOptions, 'onLoad' | 'onError' | 'onZoom' | 'onPan' | 'maxScale'>> & {
+  maxScale: number | 'auto';
+  onLoad?: () => void;
+  onError?: (error: Error) => void;
+  onZoom?: (scale: number) => void;
+  onPan?: (x: number, y: number) => void;
+};
+
+/** DOM elements managed by the viewer */
+export interface ZoooomElements {
+  container: HTMLElement;
+  image: HTMLImageElement;
+  loadingOverlay: HTMLElement | null;
+}
+
+/** Cleanup function returned by input handlers */
+export type InputCleanup = () => void;
+
+/** Joystick plugin options */
+export interface JoystickOptions {
+  /** Panning zone radius in pixels (default: 60) */
+  radius?: number;
+  /** Center deadzone as fraction 0-1 (default: 0.1) */
+  deadzone?: number;
+  /** Max panning speed in px/frame (default: 10) */
+  maxSpeed?: number;
+  /** Position of the joystick (default: 'bottom-center') */
+  position?: 'bottom-center' | 'bottom-left' | 'bottom-right';
+  /** Show compass toggle button (default: true) */
+  showToggle?: boolean;
+  /** Milliseconds before dwell activates panning (default: 100) */
+  dwellTimeout?: number;
+}