Pan and zoom

/**
 * A view onto a plane that is larger than the screen, or finer: a canvas, a
 * diagram, a map. The view is where its top-left corner is on the plane, and
 * how many screen pixels one unit of the plane takes. Everything else — where a
 * point on the plane is on the screen, what a pinch does — follows from those
 * three numbers, and all of it is arithmetic: nothing here allocates more than
 * the value it returns, and nothing knows about elements or events.
 *
 * - Panning moves the view by a distance measured on the screen.
 * - Zooming keeps one point still: the one under the pointer, or between the
 *   fingers. The plane grows or shrinks around it.
 * - Zoom multiplies. A wheel's clicks, a trackpad's pinch and a button's steps
 *   are all turned into a factor, so that each feels the same at any scale.
 * - Zoom is held between limits, and a view asked to go past one stays at it
 *   without moving.
 */
import type { Point, Rect, Size } from "../algorithms/geometry.ts";
import { autoScrollSpeed } from "./selection.ts";

export interface Viewport {
  /** The point of the plane at the view's top-left corner. */
  readonly x: number;
  readonly y: number;
  /** Screen pixels to one unit of the plane. */
  readonly zoom: number;
}

export interface ZoomLimits {
  readonly minimum: number;
  readonly maximum: number;
}

export const DEFAULT_ZOOM_LIMITS: ZoomLimits = { minimum: 0.02, maximum: 256 };

/** The stops that stepping in and out passes through: the scales people ask for by name. */
export const ZOOM_STOPS: readonly number[] = [
  0.02, 0.05, 0.1, 0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4, 8, 16, 32, 64, 128, 256,
];

export const IDENTITY: Viewport = Object.freeze({ x: 0, y: 0, zoom: 1 });

/** Where a point of the plane is on the screen, from the view's top-left corner. */
export function toScreen(view: Viewport, point: Point): Point {
  return { x: (point.x - view.x) * view.zoom, y: (point.y - view.y) * view.zoom };
}

/** The point of the plane at a place on the screen. */
export function toPlane(view: Viewport, point: Point): Point {
  return { x: point.x / view.zoom + view.x, y: point.y / view.zoom + view.y };
}

/** The part of the plane a view of the given size shows. */
export function visibleRect(view: Viewport, size: Size): Rect {
  return { x: view.x, y: view.y, width: size.width / view.zoom, height: size.height / view.zoom };
}

/** Where a part of the plane is on the screen, and how large: a selection's outline, a handle's place. */
export function toScreenRect(view: Viewport, rect: Rect): Rect {
  return {
    x: (rect.x - view.x) * view.zoom,
    y: (rect.y - view.y) * view.zoom,
    width: rect.width * view.zoom,
    height: rect.height * view.zoom,
  };
}

/**
 * A point of the plane near the view to measure from, so that what is drawn is
 * placed by small numbers however far from zero the view has travelled: a
 * browser places an element exactly only within a few million pixels. The view
 * is never `reach` screen pixels past it, and it stays the same point while the
 * view moves within one step of a coarse grid — so what is placed from it is
 * placed again only rarely.
 */
export function viewOrigin(view: Viewport, reach = 4096): Point {
  const step = 2 ** Math.floor(Math.log2(reach / view.zoom));
  return { x: Math.floor(view.x / step) * step, y: Math.floor(view.y / step) * step };
}

/** The view moved by a distance on the screen: what is shown moves with the pointer that drags it. */
export function pan(view: Viewport, dx: number, dy: number): Viewport {
  if (dx === 0 && dy === 0) return view;
  return { x: view.x - dx / view.zoom, y: view.y - dy / view.zoom, zoom: view.zoom };
}

function hold(zoom: number, { minimum, maximum }: ZoomLimits): number {
  return Math.min(Math.max(zoom, minimum), maximum);
}

/**
 * The view at a zoom, with the point of the plane under `anchor` — a place on
 * the screen — still under it. A zoom beyond the limits is the limit.
 */
export function zoomTo(
  view: Viewport,
  zoom: number,
  anchor: Point,
  limits: ZoomLimits = DEFAULT_ZOOM_LIMITS,
): Viewport {
  const next = hold(zoom, limits);
  if (!(next > 0) || next === view.zoom) return view;
  // The plane point under the anchor before and after is the same point.
  return {
    x: view.x + anchor.x / view.zoom - anchor.x / next,
    y: view.y + anchor.y / view.zoom - anchor.y / next,
    zoom: next,
  };
}

/** The view zoomed by a factor about a place on the screen. */
export function zoomBy(
  view: Viewport,
  factor: number,
  anchor: Point,
  limits: ZoomLimits = DEFAULT_ZOOM_LIMITS,
): Viewport {
  return zoomTo(view, view.zoom * factor, anchor, limits);
}

/**
 * The next stop in or out from a zoom: the next of the named scales, so that
 * stepping in from 87% goes to 100%, and from 100% to 150%.
 */
export function zoomStop(zoom: number, direction: 1 | -1, stops: readonly number[] = ZOOM_STOPS): number {
  // A zoom a hair off a stop — arrived at by arithmetic — is at that stop.
  const near = 1e-9;
  if (direction === 1) return stops.find((stop) => stop > zoom * (1 + near)) ?? stops.at(-1) ?? zoom;
  return stops.findLast((stop) => stop < zoom * (1 - near)) ?? stops[0] ?? zoom;
}

/**
 * The view that shows the whole of a part of the plane, as large as it will go,
 * in the middle, with `padding` screen pixels around it. A part with no size is
 * shown at the zoom the view has, centred.
 */
export function fit(
  rect: Rect,
  size: Size,
  { padding = 0, limits = DEFAULT_ZOOM_LIMITS, zoom: current = 1 } = {},
): Viewport {
  const width = Math.max(size.width - padding * 2, 1);
  const height = Math.max(size.height - padding * 2, 1);
  const wanted = Math.min(
    rect.width > 0 ? width / rect.width : Infinity,
    rect.height > 0 ? height / rect.height : Infinity,
  );
  const zoom = hold(Number.isFinite(wanted) ? wanted : current, limits);
  return {
    x: rect.x + rect.width / 2 - size.width / zoom / 2,
    y: rect.y + rect.height / 2 - size.height / zoom / 2,
    zoom,
  };
}

/**
 * The view moved by the least that brings a part of the plane into it, with
 * `margin` screen pixels to spare — and not moved at all if it is already
 * there. A part larger than the view is shown from its start.
 */
export function reveal(view: Viewport, rect: Rect, size: Size, margin = 0): Viewport {
  const along = (start: number, extent: number, at: number, span: number): number => {
    const room = span / view.zoom;
    const edge = Math.min(margin / view.zoom, Math.max((room - extent) / 2, 0));
    if (extent + edge * 2 > room || start - edge < at) return start - edge;
    if (start + extent + edge > at + room) return start + extent + edge - room;
    return at;
  };
  const x = along(rect.x, rect.width, view.x, size.width);
  const y = along(rect.y, rect.height, view.y, size.height);
  return x === view.x && y === view.y ? view : { x, y, zoom: view.zoom };
}

/** What a wheel event carries, of all that it does. */
export interface WheelInput {
  readonly deltaX: number;
  readonly deltaY: number;
  /** 0 for pixels, 1 for lines, 2 for pages. */
  readonly deltaMode: number;
  /** Set by a trackpad's pinch, which browsers report as a wheel with Control held. */
  readonly ctrlKey: boolean;
  readonly metaKey: boolean;
  readonly shiftKey: boolean;
}

export type WheelIntent =
  | { readonly kind: "pan"; readonly dx: number; readonly dy: number }
  | { readonly kind: "zoom"; readonly factor: number };

const LINE = 16;

/**
 * What a turn of the wheel means on a canvas. A pinch, or the wheel with the
 * command or Control key, zooms; anything else scrolls — sideways with Shift,
 * where the device has one axis. Lines and pages are turned into pixels first,
 * so that a mouse that reports in lines moves as far as one that reports in
 * pixels.
 */
export function wheelIntent(event: WheelInput, pageSize: Size): WheelIntent {
  const unit = event.deltaMode === 1 ? LINE : event.deltaMode === 2 ? pageSize.height : 1;
  const dx = event.deltaX * unit;
  const dy = event.deltaY * unit;
  if (event.ctrlKey || event.metaKey) {
    // A pinch's deltas are small and many; a wheel's click is large. One curve
    // serves both: equal turns multiply the zoom equally. A click is held to
    // what one notch should do, however large the device says it was.
    const turn = Math.max(-100, Math.min(100, dy));
    return { kind: "zoom", factor: Math.exp(-turn * 0.01) };
  }
  // With Shift, a one-axis wheel scrolls sideways.
  if (event.shiftKey && dx === 0) return { kind: "pan", dx: -dy, dy: 0 };
  return { kind: "pan", dx: -dx, dy: -dy };
}

/**
 * How fast a drag held near the edge of a view moves the view along, in screen
 * pixels a second each way: negative toward the left and the top. Nothing while
 * the pointer is clear of the edges; at a walk once it is within `margin` of
 * one, and faster the further it goes, past the edge too. An edge pulls only a
 * drag that has travelled toward it — `travelled` is how far the drag has come
 * from its press — so that one begun beside an edge moves nothing until it
 * heads for it.
 */
export function edgePan(point: Point, size: Size, travelled: Point, margin = 32): Point {
  const along = (at: number, extent: number, come: number): number => {
    // A view too small to have a middle clear of both bands has narrower bands.
    const band = Math.min(margin, extent / 4);
    if (come < 0 && at < band) return -autoScrollSpeed(band - at);
    if (come > 0 && at > extent - band) return autoScrollSpeed(at - (extent - band));
    return 0;
  };
  return { x: along(point.x, size.width, travelled.x), y: along(point.y, size.height, travelled.y) };
}