feat: add aspect ratio lock for ImageCrop widget (#8533)

## Summary

Add ratio preset dropdown (1:1, 3:4, 4:3, 16:9, 9:16, custom) and lock
toggle to the ImageCrop widget. When locked, only corner handles are
shown and resizing maintains the selected aspect ratio using diagonal
projection for smooth, jump-free interaction.
Locking with custom selected captures the current crop's ratio.

## Screenshots (if applicable)


https://github.com/user-attachments/assets/a7b5c0a0-c18c-4785-940f-59793702e892

┆Issue is synchronized with this [Notion
page](https://www.notion.so/PR-8533-feat-add-aspect-ratio-lock-for-ImageCrop-widget-2fa6d73d365081a98546e43ed0d7d4fe)
by [Unito](https://www.unito.io)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Image crop widget adds a ratio selector with preset and custom
options, plus a lock/unlock toggle to preserve aspect while cropping.
* Constrained corner-resize behavior enforces locked aspect ratios
during resizing.

* **Documentation**
* Added UI text entries for ratio controls (labels for ratio,
lock/unlock, custom).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

src/composables/useImageCrop.ts

@@ -22,6 +22,15 @@ const CORNER_SIZE = 10
 const MIN_CROP_SIZE = 16
 const CROP_BOX_BORDER = 2
 
+export const ASPECT_RATIOS = {
+  '1:1': 1,
+  '3:4': 3 / 4,
+  '4:3': 4 / 3,
+  '16:9': 16 / 9,
+  '9:16': 9 / 16,
+  custom: null
+} as const
+
 interface UseImageCropOptions {
   imageEl: Ref<HTMLImageElement | null>
   containerEl: Ref<HTMLDivElement | null>
@@ -88,6 +97,55 @@ export function useImageCrop(nodeId: NodeId, options: UseImageCropOptions) {
   const resizeStartCropWidth = ref(0)
   const resizeStartCropHeight = ref(0)
 
+  const lockedRatio = ref<number | null>(null)
+
+  const selectedRatio = computed({
+    get: () => {
+      if (lockedRatio.value == null) return 'custom'
+      const entry = Object.entries(ASPECT_RATIOS).find(
+        ([, v]) => v === lockedRatio.value
+      )
+      return entry ? entry[0] : 'custom'
+    },
+    set: (key: string) => {
+      if (key === 'custom') {
+        lockedRatio.value = null
+        return
+      }
+      lockedRatio.value =
+        ASPECT_RATIOS[key as keyof typeof ASPECT_RATIOS] ?? null
+      applyLockedRatio()
+    }
+  })
+
+  const isLockEnabled = computed({
+    get: () => lockedRatio.value != null,
+    set: (locked: boolean) => {
+      if (locked && lockedRatio.value == null) {
+        lockedRatio.value = cropWidth.value / cropHeight.value
+      }
+      if (!locked) {
+        lockedRatio.value = null
+      }
+    }
+  })
+
+  function applyLockedRatio() {
+    if (lockedRatio.value == null) return
+
+    const ratio = lockedRatio.value
+    const w = cropWidth.value
+    let newHeight = Math.round(w / ratio)
+
+    if (cropY.value + newHeight > naturalHeight.value) {
+      newHeight = naturalHeight.value - cropY.value
+      const newWidth = Math.round(newHeight * ratio)
+      cropWidth.value = Math.max(MIN_CROP_SIZE, newWidth)
+    }
+
+    cropHeight.value = Math.max(MIN_CROP_SIZE, newHeight)
+  }
+
   useResizeObserver(containerEl, () => {
     if (imageEl.value && imageUrl.value) {
       updateDisplayedDimensions()
@@ -200,7 +258,9 @@ export function useImageCrop(nodeId: NodeId, options: UseImageCropOptions) {
     }
   }
 
-  const resizeHandles = computed<ResizeHandle[]>(() => {
+  const CORNER_DIRECTIONS = new Set<ResizeDirection>(['nw', 'ne', 'sw', 'se'])
+
+  const allResizeHandles = computed<ResizeHandle[]>(() => {
     const x = imageOffsetX.value + cropX.value * scaleFactor.value
     const y = imageOffsetY.value + cropY.value * scaleFactor.value
     const w = cropWidth.value * scaleFactor.value
@@ -286,6 +346,13 @@ export function useImageCrop(nodeId: NodeId, options: UseImageCropOptions) {
     ]
   })
 
+  const resizeHandles = computed<ResizeHandle[]>(() => {
+    if (!isLockEnabled.value) return allResizeHandles.value
+    return allResizeHandles.value.filter((h) =>
+      CORNER_DIRECTIONS.has(h.direction)
+    )
+  })
+
   const handleImageLoad = () => {
     isLoading.value = false
     updateDisplayedDimensions()
@@ -366,6 +433,13 @@ export function useImageCrop(nodeId: NodeId, options: UseImageCropOptions) {
     const deltaX = (e.clientX - resizeStartX.value) / effectiveScale
     const deltaY = (e.clientY - resizeStartY.value) / effectiveScale
 
+    const ratioValue = isLockEnabled.value ? lockedRatio.value : null
+
+    if (ratioValue != null && CORNER_DIRECTIONS.has(dir)) {
+      handleConstrainedResize(dir, deltaX, deltaY, ratioValue)
+      return
+    }
+
     const affectsLeft = dir === 'left' || dir === 'nw' || dir === 'sw'
     const affectsRight = dir === 'right' || dir === 'ne' || dir === 'se'
     const affectsTop = dir === 'top' || dir === 'nw' || dir === 'ne'
@@ -414,6 +488,70 @@ export function useImageCrop(nodeId: NodeId, options: UseImageCropOptions) {
     }
   }
 
+  function handleConstrainedResize(
+    dir: ResizeDirection,
+    deltaX: number,
+    deltaY: number,
+    ratio: number
+  ) {
+    const affectsLeft = dir === 'nw' || dir === 'sw'
+    const affectsTop = dir === 'nw' || dir === 'ne'
+
+    const sx = affectsLeft ? -1 : 1
+    const sy = affectsTop ? -1 : 1
+
+    const invRatio = 1 / ratio
+    const dot = deltaX * sx + deltaY * sy * invRatio
+    const lenSq = 1 + invRatio * invRatio
+    const widthDelta = dot / lenSq
+
+    let newWidth = Math.round(resizeStartCropWidth.value + widthDelta)
+    let newHeight = Math.round(newWidth / ratio)
+
+    if (newWidth < MIN_CROP_SIZE) {
+      newWidth = MIN_CROP_SIZE
+      newHeight = Math.round(newWidth / ratio)
+    }
+    if (newHeight < MIN_CROP_SIZE) {
+      newHeight = MIN_CROP_SIZE
+      newWidth = Math.round(newHeight * ratio)
+    }
+
+    let newX = resizeStartCropX.value
+    let newY = resizeStartCropY.value
+
+    if (affectsLeft) {
+      newX = resizeStartCropX.value + resizeStartCropWidth.value - newWidth
+    }
+    if (affectsTop) {
+      newY = resizeStartCropY.value + resizeStartCropHeight.value - newHeight
+    }
+
+    if (newX < 0) {
+      newWidth += newX
+      newX = 0
+      newHeight = Math.round(newWidth / ratio)
+    }
+    if (newY < 0) {
+      newHeight += newY
+      newY = 0
+      newWidth = Math.round(newHeight * ratio)
+    }
+    if (newX + newWidth > naturalWidth.value) {
+      newWidth = naturalWidth.value - newX
+      newHeight = Math.round(newWidth / ratio)
+    }
+    if (newY + newHeight > naturalHeight.value) {
+      newHeight = naturalHeight.value - newY
+      newWidth = Math.round(newHeight * ratio)
+    }
+
+    cropX.value = Math.round(newX)
+    cropY.value = Math.round(newY)
+    cropWidth.value = Math.max(MIN_CROP_SIZE, newWidth)
+    cropHeight.value = Math.max(MIN_CROP_SIZE, newHeight)
+  }
+
   const handleResizeEnd = (e: PointerEvent) => {
     if (!isResizing.value) return
 
@@ -453,6 +591,9 @@ export function useImageCrop(nodeId: NodeId, options: UseImageCropOptions) {
     cropWidth,
     cropHeight,
 
+    selectedRatio,
+    isLockEnabled,
+
     cropBoxStyle,
     cropImageStyle,
     resizeHandles,