// Geometry for the avatar crop dialog. The dialog shows a square viewport; the // picked image is scaled to cover it and can then be panned and zoomed until the // user sees exactly the section they want as their picture. The math lives here, // free of React and the DOM, so the clamping rules stay testable. export type CropGeometry = { /** Natural size of the picked image, in source pixels. */ imageWidth: number; imageHeight: number; /** Edge length of the square viewport, in CSS pixels. */ viewport: number; /** 1 = the image exactly covers the viewport, higher means zoomed in. */ zoom: number; }; export type CropOffset = { /** Position of the image's top-left corner relative to the viewport, in CSS pixels. */ x: number; y: number; }; export type CropRegion = { /** Top-left corner of the visible section, in source pixels. */ sx: number; sy: number; /** Edge length of the visible square section, in source pixels. */ size: number; }; export const MIN_ZOOM = 1; export const MAX_ZOOM = 4; export const ZOOM_STEP = 0.05; /** Edge length of the stored picture. Square, so every avatar renders the same. */ export const OUTPUT_SIZE = 512; function clamp(value: number, min: number, max: number): number { if (Number.isNaN(value)) return min; return normalizeZero(Math.min(Math.max(value, min), max)); } /** Turn -0 into 0. Both render identically, but only one compares cleanly in tests. */ function normalizeZero(value: number): number { return value + 0; } export function clampZoom(zoom: number): number { return clamp(zoom, MIN_ZOOM, MAX_ZOOM); } /** Scale that makes the image cover the square viewport at the given zoom. */ export function coverScale(geometry: CropGeometry): number { const shortestEdge = Math.min(geometry.imageWidth, geometry.imageHeight); if (shortestEdge <= 0 || geometry.viewport <= 0) return 0; return (geometry.viewport / shortestEdge) * clampZoom(geometry.zoom); } /** * Keep the viewport covered: panning must never slide an empty gap into view. * `Math.min(…, 0)` absorbs the float wobble where a scaled edge lands a hair * below the viewport and would otherwise produce an inverted range. */ export function clampOffset(geometry: CropGeometry, offset: CropOffset): CropOffset { const scale = coverScale(geometry); if (scale <= 0) return { x: 0, y: 0 }; const minX = Math.min(geometry.viewport - geometry.imageWidth * scale, 0); const minY = Math.min(geometry.viewport - geometry.imageHeight * scale, 0); return { x: clamp(offset.x, minX, 0), y: clamp(offset.y, minY, 0) }; } /** Offset that centres the image in the viewport — the state a fresh pick starts in. */ export function centeredOffset(geometry: CropGeometry): CropOffset { const scale = coverScale(geometry); if (scale <= 0) return { x: 0, y: 0 }; return clampOffset(geometry, { x: (geometry.viewport - geometry.imageWidth * scale) / 2, y: (geometry.viewport - geometry.imageHeight * scale) / 2, }); } /** * Offset after a zoom change that keeps whatever sits in the middle of the * viewport in the middle. Zooming that drifts away from the chosen section would * force the user to re-aim after every slider nudge. */ export function offsetAfterZoom(geometry: CropGeometry, offset: CropOffset, nextZoom: number): CropOffset { const nextGeometry = { ...geometry, zoom: clampZoom(nextZoom) }; const currentScale = coverScale(geometry); const nextScale = coverScale(nextGeometry); if (currentScale <= 0 || nextScale <= 0) return centeredOffset(nextGeometry); const centre = geometry.viewport / 2; const sourceX = (centre - offset.x) / currentScale; const sourceY = (centre - offset.y) / currentScale; return clampOffset(nextGeometry, { x: centre - sourceX * nextScale, y: centre - sourceY * nextScale }); } /** The section of the source image the user currently sees, in source pixels. */ export function cropRegion(geometry: CropGeometry, offset: CropOffset): CropRegion { const scale = coverScale(geometry); if (scale <= 0) return { sx: 0, sy: 0, size: 0 }; const clamped = clampOffset(geometry, offset); return { sx: normalizeZero(-clamped.x / scale), sy: normalizeZero(-clamped.y / scale), size: geometry.viewport / scale }; }