@inglorious/ui 8.2.4 → 8.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/ui",
-  "version": "8.2.4",
+  "version": "8.3.0",
   "description": "A design system for Inglorious Web with render-function components and customizable themes",
   "author": "Matteo Antony Mistretta <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -84,6 +84,11 @@
       "import": "./src/controls/icon-button/index.js"
     },
     "./icon-button.css": "./src/controls/icon-button/style.css",
+    "./image-cropper": {
+      "types": "./types/controls/image-cropper.d.ts",
+      "import": "./src/controls/image-cropper/index.js"
+    },
+    "./image-cropper.css": "./src/controls/image-cropper/style.css",
     "./input": {
       "types": "./types/controls/input.d.ts",
       "import": "./src/controls/input/index.js"
@@ -301,21 +306,21 @@
     "**/*.css"
   ],
   "peerDependencies": {
-    "@inglorious/store": "11.1.0",
+    "@inglorious/store": "11.2.0",
     "@inglorious/utils": "5.0.0",
-    "@inglorious/web": "6.7.0"
+    "@inglorious/web": "6.7.1"
   },
   "devDependencies": {
     "@iconify-icons/fa7-brands": "^2.0.0",
     "@iconify-icons/fa7-regular": "^2.0.0",
     "@iconify-icons/fa7-solid": "^2.0.0",
     "@iconify-icons/material-symbols": "^2.0.6",
-    "@inglorious/charts": "11.1.2",
+    "@inglorious/charts": "11.1.3",
     "@inglorious/eslint-config": "1.1.4",
-    "@inglorious/store": "11.1.0",
+    "@inglorious/store": "11.2.0",
     "@inglorious/vite-plugin-jsx": "2.0.4",
     "@inglorious/vite-plugin-vue": "1.0.5",
-    "@inglorious/web": "6.7.0",
+    "@inglorious/web": "6.7.1",
     "@storybook/addon-docs": "^10.6.0",
     "@storybook/web-components-vite": "^10.6.0",
     "happy-dom": "^20.14.0",

package/src/controls/controls.css

@@ -4,6 +4,7 @@
 @import "./combobox/style.css";
 @import "./fab/style.css";
 @import "./icon-button/style.css";
+@import "./image-cropper/style.css";
 @import "./input/style.css";
 @import "./radio-group/style.css";
 @import "./rating/style.css";

package/src/controls/image-cropper/handlers.js

@@ -0,0 +1,115 @@
+/**
+ * @typedef {import('../../../types/controls/image-cropper.js').ImageCropperProps} ImageCropperEntity
+ * @typedef {import('../../../types/controls/image-cropper.js').CropRect} CropRect
+ */
+
+import {
+  clampRect,
+  DEFAULT_MIN_SIZE,
+  DEFAULT_STEP,
+  fitRect,
+  FULL_RECT,
+  matchesAspect,
+  normalizeAspect,
+} from "./helpers.js"
+
+/**
+ * Initialize missing image cropper state defaults.
+ * The persistent state is `rect`, the frame in image fractions, plus the
+ * image's natural size once it has loaded. Everything else is configuration.
+ * @param {ImageCropperEntity} entity
+ */
+export function create(entity) {
+  entity.rect ??= { ...FULL_RECT }
+  entity.naturalWidth ??= 0
+  entity.naturalHeight ??= 0
+  entity.hasError ??= false
+
+  entity.src ??= ""
+  entity.alt ??= ""
+  entity.label ??= ""
+  entity.aspectRatio ??= null
+  entity.minSize ??= DEFAULT_MIN_SIZE
+  entity.step ??= DEFAULT_STEP
+  entity.isDisabled ??= false
+}
+
+/**
+ * The image failed to load: there is nothing to crop.
+ * @param {ImageCropperEntity} entity
+ */
+export function imageError(entity) {
+  entity.naturalWidth = 0
+  entity.naturalHeight = 0
+  entity.hasError = true
+}
+
+/**
+ * The image loaded: record its size, which is what turns `aspectRatio` into a
+ * frame shape. A frame that already has that shape is kept, so a previous crop
+ * can be restored; any other is replaced by the largest centred one.
+ * @param {ImageCropperEntity} entity
+ * @param {{ width: number, height: number }} size
+ */
+export function imageLoad(entity, { width, height } = {}) {
+  if (!width || !height) {
+    imageError(entity)
+    return
+  }
+
+  entity.naturalWidth = width
+  entity.naturalHeight = height
+  entity.hasError = false
+
+  const aspect = normalizeAspect(entity.aspectRatio, width, height)
+  const rect = entity.rect ?? FULL_RECT
+  entity.rect =
+    aspect && !matchesAspect(rect, aspect)
+      ? fitRect(aspect)
+      : clampRect(rect, { minSize: entity.minSize, aspect })
+}
+
+/**
+ * Move or resize the frame. The rect is clamped to the image, the minimum size
+ * and, once the image has loaded, the aspect ratio.
+ * @param {ImageCropperEntity} entity
+ * @param {CropRect} rect
+ */
+export function rectChange(entity, rect) {
+  if (entity.isDisabled || !rect) return
+
+  const aspect = normalizeAspect(
+    entity.aspectRatio,
+    entity.naturalWidth,
+    entity.naturalHeight,
+  )
+  entity.rect = clampRect(rect, { minSize: entity.minSize, aspect })
+}
+
+/**
+ * Show a different image. Its size is unknown until it loads, so the frame
+ * starts over on the whole image unless a rect is passed along with it.
+ * @param {ImageCropperEntity} entity
+ * @param {string | { src: string, rect?: CropRect }} payload
+ */
+export function srcChange(entity, payload) {
+  const { src = "", rect } =
+    typeof payload === "string" ? { src: payload } : (payload ?? {})
+
+  entity.rect = rect ? { ...rect } : { ...FULL_RECT }
+
+  // The same src never fires another load, so the size it has still holds and
+  // the frame is fitted to it right away.
+  if (src === entity.src && entity.naturalWidth) {
+    imageLoad(entity, {
+      width: entity.naturalWidth,
+      height: entity.naturalHeight,
+    })
+    return
+  }
+
+  entity.src = src
+  entity.naturalWidth = 0
+  entity.naturalHeight = 0
+  entity.hasError = false
+}

package/src/controls/image-cropper/helpers.js

@@ -0,0 +1,196 @@
+/**
+ * @typedef {import('../../../types/controls/image-cropper.js').CropRect} CropRect
+ * @typedef {{ minSize?: number, aspect?: number | null }} RectOptions
+ */
+
+import { clamp } from "@inglorious/utils/math/number.js"
+
+// Every rect is in fractions of the image (0-1 on both axes), so it survives
+// any display size and maps onto source pixels only when the image is cropped.
+export const DEFAULT_MIN_SIZE = 0.1
+export const DEFAULT_STEP = 0.02
+export const FULL_RECT = { x: 0, y: 0, w: 1, h: 1 }
+export const HANDLES = ["nw", "n", "ne", "e", "se", "s", "sw", "w"]
+export const PERCENT = 100
+
+const ASPECT_TOLERANCE = 0.01
+const HALF = 0.5
+
+/**
+ * Keep a rect inside the image, at least `minSize` on each side and, when an
+ * aspect is given, at that width/height ratio (in image fractions).
+ * @param {CropRect} rect
+ * @param {RectOptions} [options]
+ * @returns {CropRect}
+ */
+export function clampRect(rect, { minSize = DEFAULT_MIN_SIZE, aspect } = {}) {
+  let { w, h } = rect
+  if (aspect) {
+    h = clamp(h, Math.max(minSize, minSize / aspect), Math.min(1, 1 / aspect))
+    w = h * aspect
+  } else {
+    w = clamp(w, minSize, 1)
+    h = clamp(h, minSize, 1)
+  }
+  return {
+    x: clamp(rect.x, 0, 1 - w),
+    y: clamp(rect.y, 0, 1 - h),
+    w,
+    h,
+  }
+}
+
+/**
+ * The largest centred rect at the given aspect, or the whole image without one.
+ * @param {number | null} [aspect]
+ * @returns {CropRect}
+ */
+export function fitRect(aspect) {
+  if (!aspect) return { ...FULL_RECT }
+  const w = Math.min(1, aspect)
+  const h = w / aspect
+  return { x: (1 - w) * HALF, y: (1 - h) * HALF, w, h }
+}
+
+/**
+ * Which handle, if any, sits under a point; "move" inside the rect.
+ * @param {{ x: number, y: number }} point In image fractions.
+ * @param {CropRect} rect
+ * @param {{ x: number, y: number }} tolerance Hit distance, in image fractions.
+ * @returns {string | null}
+ */
+export function hitTest(point, rect, tolerance) {
+  const right = rect.x + rect.w
+  const bottom = rect.y + rect.h
+  const nearLeft = Math.abs(point.x - rect.x) <= tolerance.x
+  const nearRight = Math.abs(point.x - right) <= tolerance.x
+  const nearTop = Math.abs(point.y - rect.y) <= tolerance.y
+  const nearBottom = Math.abs(point.y - bottom) <= tolerance.y
+  const withinX =
+    point.x >= rect.x - tolerance.x && point.x <= right + tolerance.x
+  const withinY =
+    point.y >= rect.y - tolerance.y && point.y <= bottom + tolerance.y
+
+  if (!withinX || !withinY) return null
+  const vertical = (nearTop && "n") || (nearBottom && "s") || ""
+  const horizontal = (nearLeft && "w") || (nearRight && "e") || ""
+  return vertical + horizontal || "move"
+}
+
+/**
+ * Whether a rect already has the given aspect (in image fractions).
+ * @param {CropRect} rect
+ * @param {number} aspect
+ * @returns {boolean}
+ */
+export function matchesAspect(rect, aspect) {
+  return Math.abs(rect.w / rect.h / aspect - 1) <= ASPECT_TOLERANCE
+}
+
+/**
+ * Turn an output aspect ratio (width/height in pixels) into one in image
+ * fractions, which is what every other helper works with.
+ * @param {number | null | undefined} aspectRatio
+ * @param {number} width The image's natural width.
+ * @param {number} height The image's natural height.
+ * @returns {number | null}
+ */
+export function normalizeAspect(aspectRatio, width, height) {
+  if (!aspectRatio || !width || !height) return null
+  return (aspectRatio * height) / width
+}
+
+/**
+ * Move a rect without changing its size.
+ * @param {CropRect} rect
+ * @param {number} dx
+ * @param {number} dy
+ * @param {RectOptions} [options]
+ * @returns {CropRect}
+ */
+export function panRect(rect, dx, dy, options) {
+  return clampRect({ ...rect, x: rect.x + dx, y: rect.y + dy }, options)
+}
+
+/**
+ * Drag one edge or corner; the opposite one stays put. With an aspect, an edge
+ * keeps the rect centred on the other axis and a corner follows whichever axis
+ * moved further.
+ * @param {CropRect} start The rect when the drag began.
+ * @param {string} handle One of HANDLES.
+ * @param {number} dx Pointer travel since the drag began, in image fractions.
+ * @param {number} dy
+ * @param {RectOptions} [options]
+ * @returns {CropRect}
+ */
+export function resizeRect(start, handle, dx, dy, options = {}) {
+  const { minSize = DEFAULT_MIN_SIZE, aspect } = options
+  const east = handle.includes("e")
+  const west = handle.includes("w")
+  const south = handle.includes("s")
+  const north = handle.includes("n")
+  const right = start.x + start.w
+  const bottom = start.y + start.h
+
+  if (!aspect) {
+    const x = west ? clamp(start.x + dx, 0, right - minSize) : start.x
+    const y = north ? clamp(start.y + dy, 0, bottom - minSize) : start.y
+    const w = east ? clamp(start.w + dx, minSize, 1 - start.x) : right - x
+    const h = south ? clamp(start.h + dy, minSize, 1 - start.y) : bottom - y
+    return clampRect({ x, y, w, h }, options)
+  }
+
+  const centerX = start.x + start.w * HALF
+  const centerY = start.y + start.h * HALF
+  const widthFromX = east ? start.w + dx : west ? start.w - dx : null
+  const heightFromY = south ? start.h + dy : north ? start.h - dy : null
+  const widthFromY = heightFromY == null ? null : heightFromY * aspect
+  const followsX =
+    widthFromY == null ||
+    (widthFromX != null && Math.abs(dx) >= Math.abs(dy * aspect))
+
+  const maxWidth = east
+    ? 1 - start.x
+    : west
+      ? right
+      : 2 * Math.min(centerX, 1 - centerX)
+  const maxHeight = south
+    ? 1 - start.y
+    : north
+      ? bottom
+      : 2 * Math.min(centerY, 1 - centerY)
+  const w = clamp(
+    followsX ? widthFromX : widthFromY,
+    Math.max(minSize, minSize * aspect),
+    Math.min(maxWidth, maxHeight * aspect),
+  )
+  const h = w / aspect
+
+  return {
+    x: east ? start.x : west ? right - w : centerX - w * HALF,
+    y: south ? start.y : north ? bottom - h : centerY - h * HALF,
+    w,
+    h,
+  }
+}
+
+/**
+ * Grow or shrink a rect around its centre.
+ * @param {CropRect} rect
+ * @param {number} factor Above 1 grows, below 1 shrinks.
+ * @param {RectOptions} [options]
+ * @returns {CropRect}
+ */
+export function scaleRect(rect, factor, options) {
+  const w = rect.w * factor
+  const h = rect.h * factor
+  return clampRect(
+    {
+      x: rect.x + (rect.w - w) * HALF,
+      y: rect.y + (rect.h - h) * HALF,
+      w,
+      h,
+    },
+    options,
+  )
+}

package/src/controls/image-cropper/image-cropper.stories.js

@@ -0,0 +1,85 @@
+import {
+  createEntityRender,
+  notifyActionArgType,
+} from "../../stories/notifyStory.js"
+import { ImageCropper } from "./index.js"
+
+export default {
+  title: "Controls/ImageCropper",
+  tags: ["autodocs"],
+  render: createEntityRender({ ImageCropper }),
+  argTypes: {
+    ...notifyActionArgType,
+    label: { control: "text", description: "Accessible label for the stage." },
+    src: { control: "text", description: "Image URL, often a blob: URL." },
+    alt: { control: "text", description: "Alternative text for the image." },
+    aspectRatio: {
+      control: "number",
+      description:
+        "Output width/height in pixels to lock the frame to. Empty crops freely.",
+    },
+    minSize: {
+      control: { type: "range", min: 0.05, max: 1, step: 0.05 },
+      description: "Smallest frame side, as a fraction of the image.",
+    },
+    step: {
+      control: "number",
+      description: "Keyboard increment, as a fraction of the image.",
+    },
+    rect: {
+      control: "object",
+      description: "The frame { x, y, w, h } in image fractions (0-1).",
+    },
+    isDisabled: { control: "boolean", description: "Disable interaction." },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Movable, resizable crop frame over a whole image. The frame is kept in image fractions, so it maps onto the real pixels whatever the display size; `cropImage(file, rect, options)` then crops and encodes in the browser. Drag the frame to move it, its edges and corners to resize it, pinch or scroll to scale it. With focus: arrows move, Shift+arrows resize, +/- scale, Home resets.",
+      },
+    },
+  },
+}
+
+export const Default = {}
+Default.args = {
+  id: "image-cropper",
+  type: "ImageCropper",
+  label: "Crop the photo",
+  src: "https://picsum.photos/id/1015/1200/700",
+  alt: "River between mountains",
+  aspectRatio: null,
+  minSize: 0.1,
+  step: 0.02,
+  isDisabled: false,
+}
+
+export const Square = {}
+Square.args = {
+  ...Default.args,
+  id: "image-cropper-square",
+  aspectRatio: 1,
+}
+
+export const Banner = {}
+Banner.args = {
+  ...Default.args,
+  id: "image-cropper-banner",
+  aspectRatio: 21 / 9,
+}
+
+export const Restored = {}
+Restored.args = {
+  ...Default.args,
+  id: "image-cropper-restored",
+  rect: { x: 0.3, y: 0.2, w: 0.4, h: 0.5 },
+}
+
+export const Disabled = {}
+Disabled.args = {
+  ...Default.args,
+  id: "image-cropper-disabled",
+  rect: { x: 0.1, y: 0.1, w: 0.6, h: 0.6 },
+  isDisabled: true,
+}

package/src/controls/image-cropper/image.js

@@ -0,0 +1,146 @@
+/**
+ * @typedef {import('../../../types/controls/image-cropper.js').CropRect} CropRect
+ * @typedef {import('../../../types/controls/image-cropper.js').CropImageOptions} CropImageOptions
+ */
+
+import { clampRect, fitRect, normalizeAspect } from "./helpers.js"
+
+const DEFAULT_QUALITY = 0.9
+const DEFAULT_TYPE = "image/jpeg"
+const OPAQUE_TYPES = ["image/jpeg"]
+
+/**
+ * Crop an image file to a rect and encode the result, all in the browser.
+ * Without a rect it takes the largest centred one at `aspectRatio`, or the
+ * whole image. The output is capped at `maxWidth` x `maxHeight` and never
+ * upscaled. Re-encoding also drops the camera metadata of the original.
+ * @param {Blob} file
+ * @param {CropRect | null} [rect] In image fractions, as the cropper reports it.
+ * @param {CropImageOptions} [options]
+ * @returns {Promise<Blob>}
+ */
+export async function cropImage(file, rect, options = {}) {
+  const {
+    aspectRatio = null,
+    maxWidth = Infinity,
+    maxHeight = Infinity,
+    type = DEFAULT_TYPE,
+    quality = DEFAULT_QUALITY,
+    background = "white",
+  } = options
+
+  const source = await decodeImage(file)
+  try {
+    const { width, height } = sizeOf(source)
+    const aspect = normalizeAspect(aspectRatio, width, height)
+    const crop = rect
+      ? clampRect(rect, { minSize: 0, aspect })
+      : fitRect(aspect)
+    const sw = crop.w * width
+    const sh = crop.h * height
+    const scale = Math.min(1, maxWidth / sw, maxHeight / sh)
+    const output = {
+      width: Math.max(1, Math.round(sw * scale)),
+      height: Math.max(1, Math.round(sh * scale)),
+    }
+
+    const canvas = document.createElement("canvas")
+    canvas.width = output.width
+    canvas.height = output.height
+    const context = canvas.getContext("2d")
+    if (!context) throw new Error("Canvas is unavailable")
+
+    // Formats without alpha would turn transparent pixels black.
+    if (OPAQUE_TYPES.includes(type) && background) {
+      context.fillStyle = background
+      context.fillRect(0, 0, output.width, output.height)
+    }
+    context.imageSmoothingEnabled = true
+    context.imageSmoothingQuality = "high"
+    context.drawImage(
+      source,
+      crop.x * width,
+      crop.y * height,
+      sw,
+      sh,
+      0,
+      0,
+      output.width,
+      output.height,
+    )
+    return await toBlob(canvas, type, quality)
+  } finally {
+    source.close?.()
+  }
+}
+
+/**
+ * Decode an image file once, honouring its EXIF orientation where the browser
+ * can. Falls back to an <img> element when `createImageBitmap` is missing or
+ * rejects the file.
+ * @param {Blob} file
+ * @returns {Promise<ImageBitmap | HTMLImageElement>}
+ */
+export async function decodeImage(file) {
+  if (typeof createImageBitmap === "function") {
+    try {
+      return await createImageBitmap(file, { imageOrientation: "from-image" })
+    } catch {
+      // Some engines reject the options object; try the plain decoder.
+      try {
+        return await createImageBitmap(file)
+      } catch {
+        // Fall through to the element decoder.
+      }
+    }
+  }
+  return decodeWithElement(file)
+}
+
+/**
+ * @param {Blob} file
+ * @returns {Promise<HTMLImageElement>}
+ */
+function decodeWithElement(file) {
+  return new Promise((resolve, reject) => {
+    const url = URL.createObjectURL(file)
+    const image = new Image()
+    image.onload = () => {
+      URL.revokeObjectURL(url)
+      resolve(image)
+    }
+    image.onerror = () => {
+      URL.revokeObjectURL(url)
+      reject(new Error("Could not read image"))
+    }
+    image.src = url
+  })
+}
+
+/**
+ * @param {ImageBitmap | HTMLImageElement} source
+ * @returns {{ width: number, height: number }}
+ */
+function sizeOf(source) {
+  return {
+    width: source.naturalWidth ?? source.width,
+    height: source.naturalHeight ?? source.height,
+  }
+}
+
+/**
+ * @param {HTMLCanvasElement} canvas
+ * @param {string} type
+ * @param {number} quality
+ * @returns {Promise<Blob>}
+ */
+function toBlob(canvas, type, quality) {
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) =>
+        blob ? resolve(blob) : reject(new Error("Could not encode image")),
+      type,
+      quality,
+    )
+  })
+}

package/src/controls/image-cropper/index.js

@@ -0,0 +1,20 @@
+import * as handlers from "./handlers.js"
+import { ImageCropper as renderers } from "./template.js"
+
+export { cropImage, decodeImage } from "./image.js"
+
+export const ImageCropper = {
+  ...handlers,
+  ...renderers,
+  render(entity, api) {
+    const id = entity.id
+    const props = {
+      ...entity,
+      onImageError: () => api.notify(`#${id}:imageError`),
+      onImageLoad: (size) => api.notify(`#${id}:imageLoad`, size),
+      onRectChange: (rect) => api.notify(`#${id}:rectChange`, rect),
+    }
+
+    return this.renderImageCropper(props)
+  },
+}

package/src/controls/image-cropper/style.css

@@ -0,0 +1,127 @@
+.iw-image-cropper {
+  /* Set from the image's natural size once it loads. */
+  --iw-image-cropper-aspect: 16 / 9;
+  /* Caps the stage height; the width follows the image's proportions. */
+  --iw-image-cropper-max-height: 70vh;
+
+  /* Neutral in every theme on purpose, like the before/after divider: the
+     frame must read on any photo without competing with it. */
+  --iw-image-cropper-bg: var(--iw-color-gray-900);
+  --iw-image-cropper-overlay: rgb(0 0 0 / 55%);
+  --iw-image-cropper-frame-width: 2px;
+  --iw-image-cropper-frame-color: rgb(255 255 255 / 95%);
+  --iw-image-cropper-handle-size: 14px;
+  --iw-image-cropper-handle-bg: rgb(255 255 255 / 98%);
+  --iw-image-cropper-handle-border: rgb(0 0 0 / 35%);
+
+  position: relative;
+  display: block;
+  width: 100%;
+  max-width: calc(
+    var(--iw-image-cropper-max-height) * var(--iw-image-cropper-aspect)
+  );
+  aspect-ratio: var(--iw-image-cropper-aspect);
+  margin-inline: auto;
+  overflow: hidden;
+  border-radius: var(--iw-radius-md);
+  background: var(--iw-image-cropper-bg);
+  line-height: 0;
+  touch-action: none;
+  user-select: none;
+  -webkit-user-select: none;
+  outline: none;
+
+  &:focus-visible {
+    outline: 2px solid var(--iw-color-primary);
+    outline-offset: 2px;
+  }
+
+  &.iw-image-cropper-disabled {
+    --iw-image-cropper-overlay: rgb(0 0 0 / 35%);
+    --iw-image-cropper-frame-color: rgb(156 163 175 / 60%);
+    --iw-image-cropper-handle-bg: rgb(156 163 175 / 60%);
+
+    .iw-image-cropper-frame,
+    .iw-image-cropper-handle {
+      cursor: default;
+    }
+  }
+
+  .iw-image-cropper-image {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    pointer-events: none;
+    user-select: none;
+    -webkit-user-drag: none;
+  }
+
+  /* The events land on the stage either way; the frame and handles only take
+     pointer events so the cursor shows what a drag there would do. */
+  .iw-image-cropper-frame {
+    position: absolute;
+    box-sizing: border-box;
+    border: var(--iw-image-cropper-frame-width) solid
+      var(--iw-image-cropper-frame-color);
+    box-shadow: 0 0 0 9999px var(--iw-image-cropper-overlay);
+    cursor: move;
+  }
+
+  .iw-image-cropper-handle {
+    position: absolute;
+    box-sizing: border-box;
+    width: var(--iw-image-cropper-handle-size);
+    height: var(--iw-image-cropper-handle-size);
+    border: 1px solid var(--iw-image-cropper-handle-border);
+    border-radius: var(--iw-radius-sm);
+    background: var(--iw-image-cropper-handle-bg);
+    transform: translate(-50%, -50%);
+  }
+
+  .iw-image-cropper-handle-n,
+  .iw-image-cropper-handle-s {
+    left: 50%;
+    cursor: ns-resize;
+  }
+
+  .iw-image-cropper-handle-e,
+  .iw-image-cropper-handle-w {
+    top: 50%;
+    cursor: ew-resize;
+  }
+
+  .iw-image-cropper-handle-nw,
+  .iw-image-cropper-handle-se {
+    cursor: nwse-resize;
+  }
+
+  .iw-image-cropper-handle-ne,
+  .iw-image-cropper-handle-sw {
+    cursor: nesw-resize;
+  }
+
+  .iw-image-cropper-handle-n,
+  .iw-image-cropper-handle-ne,
+  .iw-image-cropper-handle-nw {
+    top: 0;
+  }
+
+  .iw-image-cropper-handle-s,
+  .iw-image-cropper-handle-se,
+  .iw-image-cropper-handle-sw {
+    top: 100%;
+  }
+
+  .iw-image-cropper-handle-w,
+  .iw-image-cropper-handle-nw,
+  .iw-image-cropper-handle-sw {
+    left: 0;
+  }
+
+  .iw-image-cropper-handle-e,
+  .iw-image-cropper-handle-ne,
+  .iw-image-cropper-handle-se {
+    left: 100%;
+  }
+}

package/src/controls/image-cropper/template.js

@@ -0,0 +1,374 @@
+/**
+ * @typedef {import('../../../types/controls/image-cropper.js').ImageCropperProps} ImageCropperProps
+ * @typedef {import('../../../types/controls/image-cropper.js').CropRect} CropRect
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
+ */
+
+import { html } from "@inglorious/web"
+import { classMap } from "@inglorious/web/directives/class-map"
+
+import {
+  DEFAULT_MIN_SIZE,
+  DEFAULT_STEP,
+  fitRect,
+  FULL_RECT,
+  HANDLES,
+  hitTest,
+  normalizeAspect,
+  panRect,
+  PERCENT,
+  resizeRect,
+  scaleRect,
+} from "./helpers.js"
+
+const HANDLE_HIT_PX = 22
+const MIN_PINCH_POINTERS = 2
+const PRIMARY_BUTTON = 0
+const WHEEL_SCALE_RATE = 0.0015
+
+const ARROW_MOVES = {
+  ArrowLeft: [-1, 0],
+  ArrowRight: [1, 0],
+  ArrowUp: [0, -1],
+  ArrowDown: [0, 1],
+}
+
+// Pointers and the drag in progress belong to one element and never reach the
+// store: they change on every move and are meaningless once the gesture ends.
+/** @type {WeakMap<Element, { pointers: Map<number, { x: number, y: number }>, drag: object | null, pinch: object | null }>} */
+const gestures = new WeakMap()
+
+export const ImageCropper = {
+  /**
+   * Main entrypoint for the image cropper template. It delegates to the base renderer so overrides can still reuse it.
+   * The image cropper shows the whole image with a movable, resizable frame on top.
+   * @param {ImageCropperProps} props The image cropper props.
+   * @returns {TemplateResult} The rendered control.
+   */
+  render(props) {
+    return this.renderImageCropper(props)
+  },
+
+  /**
+   * Renders the stage and wires the pointer, wheel and keyboard interactions.
+   * This is the canonical renderer that custom `render()` overrides should call.
+   * @param {ImageCropperProps} props The image cropper props.
+   * @returns {TemplateResult} The rendered control.
+   */
+  renderImageCropper(props) {
+    const { label, isDisabled = false, hasError = false } = props
+    const isLoaded = isImageLoaded(props)
+
+    const classes = {
+      "iw-image-cropper": true,
+      "iw-image-cropper-loaded": isLoaded,
+      "iw-image-cropper-error": hasError,
+      "iw-image-cropper-disabled": isDisabled,
+    }
+    const style = isLoaded
+      ? `--iw-image-cropper-aspect: ${props.naturalWidth / props.naturalHeight};`
+      : ""
+
+    return html`<div
+      class=${classMap(classes)}
+      style=${style}
+      role="group"
+      aria-roledescription="crop area"
+      aria-label=${label || "Crop area"}
+      tabindex=${isDisabled ? -1 : 0}
+      aria-disabled=${isDisabled}
+      @pointerdown=${handlePointerDown(props)}
+      @pointermove=${handlePointerMove(props)}
+      @pointerup=${handlePointerUp}
+      @pointercancel=${handlePointerUp}
+      @keydown=${handleKeyDown(props)}
+      @wheel=${handleWheel(props)}
+    >
+      ${this.renderImage?.(props)} ${isLoaded ? this.renderFrame?.(props) : ""}
+    </div>`
+  },
+
+  /**
+   * Renders the frame over the image. Its outline shadow dims everything
+   * outside of it, and the stage clips the shadow.
+   * @param {ImageCropperProps} props The image cropper props.
+   * @returns {TemplateResult} The rendered frame.
+   */
+  renderFrame(props) {
+    const { x, y, w, h } = props.rect ?? FULL_RECT
+
+    return html`<div
+      class="iw-image-cropper-frame"
+      style="left: ${x * PERCENT}%; top: ${y * PERCENT}%; width: ${
+        w * PERCENT
+      }%; height: ${h * PERCENT}%;"
+    >
+      ${HANDLES.map((handle) => this.renderHandle?.(props, handle))}
+    </div>`
+  },
+
+  /**
+   * Renders the grip on one edge or corner of the frame.
+   * Override this to supply a custom handle, or return nothing to hide them.
+   * @param {ImageCropperProps} props The image cropper props.
+   * @param {string} handle Which grip: n, ne, e, se, s, sw, w or nw.
+   * @returns {TemplateResult} The rendered handle.
+   */
+  renderHandle(props, handle) {
+    return html`<span
+      class="iw-image-cropper-handle iw-image-cropper-handle-${handle}"
+      aria-hidden="true"
+    ></span>`
+  },
+
+  /**
+   * Renders the whole image, which also gives the stage its proportions.
+   * @param {ImageCropperProps} props The image cropper props.
+   * @returns {TemplateResult} The rendered image.
+   */
+  renderImage(props) {
+    return html`<img
+      class="iw-image-cropper-image"
+      src=${props.src ?? ""}
+      alt=${props.alt ?? ""}
+      draggable="false"
+      @load=${handleLoad(props)}
+      @error=${() => props.onImageError?.()}
+    />`
+  },
+}
+
+/**
+ * Distance between the first two active pointers, for pinch scaling.
+ * @param {Map<number, { x: number, y: number }>} pointers
+ * @returns {number}
+ */
+function distanceBetween(pointers) {
+  const [first, second] = pointers.values()
+  return Math.hypot(first.x - second.x, first.y - second.y)
+}
+
+/**
+ * The gesture state of an element, created on first use.
+ * @param {Element} element
+ */
+function gestureOf(element) {
+  let gesture = gestures.get(element)
+  if (!gesture) {
+    gesture = { pointers: new Map(), drag: null, pinch: null }
+    gestures.set(element, gesture)
+  }
+  return gesture
+}
+
+/**
+ * Arrows move the frame, Shift+arrows resize it from the bottom-right corner,
+ * +/- scale it, and Home resets it to the largest frame that fits.
+ * @param {ImageCropperProps} props
+ * @returns {(event: KeyboardEvent) => void}
+ */
+function handleKeyDown(props) {
+  return (event) => {
+    if (props.isDisabled || !isImageLoaded(props)) return
+
+    const rect = props.rect ?? FULL_RECT
+    const step = props.step ?? DEFAULT_STEP
+    const options = rectOptions(props)
+
+    let next
+    if (event.key in ARROW_MOVES) {
+      const [dx, dy] = ARROW_MOVES[event.key].map((sign) => sign * step)
+      next = event.shiftKey
+        ? resizeRect(rect, "se", dx, dy, options)
+        : panRect(rect, dx, dy, options)
+    } else if (event.key === "+" || event.key === "=") {
+      next = scaleRect(rect, 1 + step, options)
+    } else if (event.key === "-" || event.key === "_") {
+      next = scaleRect(rect, 1 / (1 + step), options)
+    } else if (event.key === "Home") {
+      next = fitRect(options.aspect)
+    } else {
+      return
+    }
+
+    event.preventDefault()
+    props.onRectChange?.(next)
+  }
+}
+
+/**
+ * Report the image's natural size once it has loaded.
+ * @param {ImageCropperProps} props
+ * @returns {(event: Event) => void}
+ */
+function handleLoad(props) {
+  return (event) => {
+    const image = /** @type {HTMLImageElement} */ (event.currentTarget)
+    props.onImageLoad?.({
+      width: image.naturalWidth,
+      height: image.naturalHeight,
+    })
+  }
+}
+
+/**
+ * Start a gesture: a second finger turns any drag into a pinch; otherwise the
+ * handle under the pointer decides between moving and resizing the frame.
+ * @param {ImageCropperProps} props
+ * @returns {(event: PointerEvent) => void}
+ */
+function handlePointerDown(props) {
+  return (event) => {
+    if (props.isDisabled || !isImageLoaded(props)) return
+    if (event.pointerType === "mouse" && event.button !== PRIMARY_BUTTON) return
+
+    const element = /** @type {Element} */ (event.currentTarget)
+    element.setPointerCapture?.(event.pointerId)
+
+    const gesture = gestureOf(element)
+    gesture.pointers.set(event.pointerId, {
+      x: event.clientX,
+      y: event.clientY,
+    })
+    const rect = props.rect ?? FULL_RECT
+
+    if (gesture.pointers.size >= MIN_PINCH_POINTERS) {
+      gesture.drag = null
+      gesture.pinch = { distance: distanceBetween(gesture.pointers), rect }
+      return
+    }
+
+    const point = pointFromEvent(event)
+    if (!point) return
+    const handle = hitTest(point, rect, hitTolerance(element))
+    gesture.drag = handle ? { handle, origin: point, rect } : null
+  }
+}
+
+/**
+ * Follow the gesture. Every step is computed from where it started, so it does
+ * not drift while the store catches up.
+ * @param {ImageCropperProps} props
+ * @returns {(event: PointerEvent) => void}
+ */
+function handlePointerMove(props) {
+  return (event) => {
+    const gesture = gestures.get(/** @type {Element} */ (event.currentTarget))
+    if (!gesture?.pointers.has(event.pointerId)) return
+
+    gesture.pointers.set(event.pointerId, {
+      x: event.clientX,
+      y: event.clientY,
+    })
+    const options = rectOptions(props)
+
+    if (gesture.pinch) {
+      if (gesture.pointers.size < MIN_PINCH_POINTERS) return
+      const { distance, rect } = gesture.pinch
+      if (!distance) return
+      const factor = distanceBetween(gesture.pointers) / distance
+      props.onRectChange?.(scaleRect(rect, factor, options))
+      return
+    }
+
+    const { drag } = gesture
+    const point = drag && pointFromEvent(event)
+    if (!point) return
+
+    const dx = point.x - drag.origin.x
+    const dy = point.y - drag.origin.y
+    props.onRectChange?.(
+      drag.handle === "move"
+        ? panRect(drag.rect, dx, dy, options)
+        : resizeRect(drag.rect, drag.handle, dx, dy, options),
+    )
+  }
+}
+
+/**
+ * End the gesture for this pointer. Lifting one finger of a pinch ends the
+ * pinch without starting a drag, so the frame does not jump.
+ * @param {PointerEvent} event
+ */
+function handlePointerUp(event) {
+  const element = /** @type {Element} */ (event.currentTarget)
+  element.releasePointerCapture?.(event.pointerId)
+
+  const gesture = gestures.get(element)
+  if (!gesture) return
+  gesture.pointers.delete(event.pointerId)
+  gesture.drag = null
+  if (!gesture.pointers.size) gesture.pinch = null
+}
+
+/**
+ * The wheel scales the frame: scrolling down grows it, scrolling up shrinks it.
+ * @param {ImageCropperProps} props
+ * @returns {(event: WheelEvent) => void}
+ */
+function handleWheel(props) {
+  return (event) => {
+    if (props.isDisabled || !isImageLoaded(props) || !event.deltaY) return
+
+    event.preventDefault()
+    const factor = Math.exp(event.deltaY * WHEEL_SCALE_RATE)
+    props.onRectChange?.(
+      scaleRect(props.rect ?? FULL_RECT, factor, rectOptions(props)),
+    )
+  }
+}
+
+/**
+ * How close to an edge, in image fractions, still counts as grabbing it.
+ * @param {Element} element
+ * @returns {{ x: number, y: number }}
+ */
+function hitTolerance(element) {
+  const { width, height } = element.getBoundingClientRect()
+  return {
+    x: width ? HANDLE_HIT_PX / width : 0,
+    y: height ? HANDLE_HIT_PX / height : 0,
+  }
+}
+
+/**
+ * Whether the image has reported its size, which is when the frame shows.
+ * @param {ImageCropperProps} props
+ * @returns {boolean}
+ */
+function isImageLoaded(props) {
+  return props.naturalWidth > 0 && props.naturalHeight > 0
+}
+
+/**
+ * Convert a pointer event into image fractions, relative to the element the
+ * listener is attached to. Null when it has no measurable size.
+ * @param {PointerEvent} event
+ * @returns {{ x: number, y: number } | null}
+ */
+function pointFromEvent(event) {
+  const bounds = /** @type {Element} */ (
+    event.currentTarget
+  ).getBoundingClientRect()
+  if (!bounds.width || !bounds.height) return null
+
+  return {
+    x: (event.clientX - bounds.left) / bounds.width,
+    y: (event.clientY - bounds.top) / bounds.height,
+  }
+}
+
+/**
+ * The constraints every frame change obeys.
+ * @param {ImageCropperProps} props
+ */
+function rectOptions(props) {
+  return {
+    minSize: props.minSize ?? DEFAULT_MIN_SIZE,
+    aspect: normalizeAspect(
+      props.aspectRatio,
+      props.naturalWidth,
+      props.naturalHeight,
+    ),
+  }
+}

package/src/examples/dashboard/app-drawer.js

@@ -152,6 +152,11 @@ function getDefaultItems() {
           primary: "Icon Button",
           href: "/controls/icon-button",
         },
+        {
+          id: "image-cropper",
+          primary: "Image Cropper",
+          href: "/controls/image-cropper",
+        },
         { id: "input", primary: "Input", href: "/controls/input" },
         {
           id: "file-upload",

package/src/examples/dashboard/primitive-content.js

@@ -20,6 +20,7 @@ import { Combobox } from "../../controls/combobox/index.js"
 import { Fab } from "../../controls/fab/index.js"
 import { FileUpload } from "../../controls/file-upload/index.js"
 import { IconButton } from "../../controls/icon-button/index.js"
+import { ImageCropper } from "../../controls/image-cropper/index.js"
 import { Input } from "../../controls/input/index.js"
 import { RadioGroup } from "../../controls/radio-group/index.js"
 import { Rating } from "../../controls/rating/index.js"
@@ -496,6 +497,40 @@ IconButton.render({
         ]),
     },
   },
+  "/controls/image-cropper": {
+    name: "Image Cropper",
+    summary: "Movable, resizable crop frame over a whole image.",
+    description:
+      "Image Cropper shows the whole image with a frame the user moves, resizes, pinches and scrolls, freely or locked to an aspect ratio. The frame is kept in image fractions, and cropImage turns it into an encoded Blob in the browser.",
+    useCases: [
+      "Profile photos",
+      "Cover images",
+      "Uploads framed before saving",
+    ],
+    example: {
+      code: `import { cropImage, ImageCropper } from "@inglorious/ui/image-cropper"
+
+ImageCropper.render({
+  id: "demo",
+  src: URL.createObjectURL(file),
+  aspectRatio: 1
+})
+
+// Later, with the entity's rect:
+const blob = await cropImage(file, entity.rect, { maxWidth: 512, maxHeight: 512 })`,
+      preview: () =>
+        livePreview(
+          { ImageCropper },
+          {
+            id: "imageCropper",
+            type: "ImageCropper",
+            label: "Crop the photo",
+            src: beforeAfterImages.after.src,
+            aspectRatio: 1,
+          },
+        ),
+    },
+  },
   "/controls/input": {
     summary: "Text input with labeling, validation, and helper text.",
     description:

package/src/index.js

@@ -4,6 +4,11 @@ export { Checkbox } from "./controls/checkbox/index.js"
 export { Fab } from "./controls/fab/index.js"
 export { FileUpload } from "./controls/file-upload/index.js"
 export { IconButton } from "./controls/icon-button/index.js"
+export {
+  cropImage,
+  decodeImage,
+  ImageCropper,
+} from "./controls/image-cropper/index.js"
 export { Input } from "./controls/input/index.js"
 export { RadioGroup } from "./controls/radio-group/index.js"
 export { Rating } from "./controls/rating/index.js"

package/types/controls/image-cropper.d.ts

@@ -0,0 +1,83 @@
+import type { TemplateResult, Api } from "@inglorious/web"
+
+/** A crop frame in fractions of the image: 0-1 on both axes. */
+export interface CropRect {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+export interface ImageCropperProps {
+  id?: string
+  type?: string
+  label?: string
+
+  src?: string
+  alt?: string
+
+  /** The crop frame in image fractions. The persistent state. */
+  rect?: CropRect
+  /** Output width/height in pixels to lock the frame to; null crops freely. */
+  aspectRatio?: number | null
+  /** Smallest frame side, as a fraction of the image. */
+  minSize?: number
+  /** Keyboard increment, as a fraction of the image. */
+  step?: number
+
+  /** The image's natural size, set when it loads. 0 until then. */
+  naturalWidth?: number
+  naturalHeight?: number
+  hasError?: boolean
+
+  isDisabled?: boolean
+
+  onImageError?: () => void
+  onImageLoad?: (size: { width: number; height: number }) => void
+  onRectChange?: (rect: CropRect) => void
+  [key: string]: unknown
+}
+
+export interface CropImageOptions {
+  /** Used when no rect is given: crop the largest centred frame at this ratio. */
+  aspectRatio?: number | null
+  maxWidth?: number
+  maxHeight?: number
+  /** Output MIME type. Defaults to "image/jpeg". */
+  type?: string
+  /** Encoder quality, 0-1. Defaults to 0.9. */
+  quality?: number
+  /** Fill behind transparent pixels for opaque formats. Defaults to "white". */
+  background?: string | null
+}
+
+export type ImageCropperType = {
+  create(entity: ImageCropperProps): void
+  imageError(entity: ImageCropperProps): void
+  imageLoad(
+    entity: ImageCropperProps,
+    size: { width: number; height: number },
+  ): void
+  rectChange(entity: ImageCropperProps, rect: CropRect): void
+  srcChange(
+    entity: ImageCropperProps,
+    payload: string | { src: string; rect?: CropRect },
+  ): void
+  render(entity: ImageCropperProps, api: Api): TemplateResult
+  renderImageCropper(props: ImageCropperProps): TemplateResult
+  renderImage(props: ImageCropperProps): TemplateResult
+  renderFrame(props: ImageCropperProps): TemplateResult
+  renderHandle(props: ImageCropperProps, handle: string): TemplateResult
+}
+
+export declare const ImageCropper: ImageCropperType
+
+export declare function cropImage(
+  file: Blob,
+  rect?: CropRect | null,
+  options?: CropImageOptions,
+): Promise<Blob>
+
+export declare function decodeImage(
+  file: Blob,
+): Promise<ImageBitmap | HTMLImageElement>

package/types/index.d.ts

@@ -4,6 +4,7 @@ export { Checkbox } from "./controls/checkbox"
 export { Fab } from "./controls/fab"
 export { FileUpload } from "./controls/file-upload"
 export { IconButton } from "./controls/icon-button"
+export { cropImage, decodeImage, ImageCropper } from "./controls/image-cropper"
 export { Input } from "./controls/input"
 export { RadioGroup } from "./controls/radio-group"
 export { Rating } from "./controls/rating"
@@ -58,6 +59,12 @@ export type {
 } from "./controls/combobox"
 export type { FabProps, FabType } from "./controls/fab"
 export type { IconButtonProps, IconButtonType } from "./controls/icon-button"
+export type {
+  CropImageOptions,
+  CropRect,
+  ImageCropperProps,
+  ImageCropperType,
+} from "./controls/image-cropper"
 export type { InputProps, InputType } from "./controls/input"
 export type {
   RadioGroupProps,