Feat/image crop hotspot

[SvenAlHamad]

Non-destructive image crop + focal point + a first-class Asset field

Base: release/6.5.0 · Head: feat/image-crop-hotspot · 103 files, +5,270 / −302

Summary

Adds non-destructive image editing (crop, focal point, alt/caption) across File
Manager, Headless CMS, and Website Builder, plus a new first-class Headless
CMS Asset field to replace the bare-URL file field. Framing is applied
server-side in the delivery pipeline and delivered as a URL, so it works with any
frontend (Next.js, React, Vue, Nuxt, and future Angular / mobile / vanilla) — not
just React DOM.

Nothing mutates the original upload. Edits are stored as resolution-independent
(0..1) values and applied at delivery time, so they survive re-encoding, resizing,
and CDN caching.

Why

• The file field stores only a URL — no crop, focal point, or accessibility text.
• Cropping needs to be non-destructive (originals preserved, edits reversible).
• Framing has to be framework-agnostic — an early CSS-based approach only worked
  in React DOM; a delivery-URL contract works everywhere.

What's included

1. Unified WebinyAsset value

A single MIME-discriminated shape shared by File Manager, CMS, and Website Builder:

{ id, src, name, type, size, image?, document?, video? }
image = { width, height, crop{top,left,bottom,right}, focalPoint{x,y}, alt, caption }

normalizeToAsset upgrades every legacy shape (flat WB file value, WebinyImageValue
with edit, mimeType→type, hotspot→focalPoint) so existing content keeps
working with no migration.

2. First-class Headless CMS Asset field

• fields.asset() (with .imagesOnly() / .accept([...])), implemented as an
  object field with a fixed nested schema so it reuses all object-field machinery
  (types, storage, indexing, validation, AST). Tagged wby:asset.
• Admin: dedicated asset picker + image editor renderer (single and multi), replacing
  the generic object form; no nested-field modelling.
• Resolved url field (read API): the stored src with the per-usage crop baked
  in as a delivery param, so headless consumers get a turnkey URL without knowing the
  param contract. src stays the pristine original.

3. Image editor (crop + focal point + alt/caption)

• Sanity/imgix-style model: crop is a hard rectangle; focalPoint stays in frame
  when a target aspect ratio forces further cutting.
• Available on the File Manager file details, the CMS file field, and the CMS Asset
  input. Aspect-ratio presets + custom ratios; live preview.

4. Server-side delivery framing (@webiny/api-file-manager[-s3|-server])

• Delivery URL params: ?crop=t,l,b,r, ?aspectRatio=16:9, ?focal=x,y, plus the
  existing ?width / ?format (incl. auto via Accept) / ?quality.
• getVisibleRect / extractFramedRegion compute the largest aspect-ratio rect
  inside the crop, centered on the focal point; Sharp is confined to the transform
  strategies (never imported into the GraphQL handler path).
• Asset-level crop (File Manager metadata.imageEdit) is applied automatically on any
  GET; a per-usage crop replaces it (crop ?? asset.getImageEdit()?.crop).
• Cache key folds crop+focal+aspectRatio in while preserving the legacy crop-only
  key — no invalidation of existing cached variants.

5. Website Builder framework-agnostic core (@webiny/website-builder-sdk)

• getWebinyAssetUrl(asset, { width, format, quality, crop, aspectRatio, focal }) —
  the one URL builder every framework uses.
• IMAGE_RESIZE_WIDTHS (aligned to the server ladder → cache hits),
  getWebinyImageDimensions, and getWebinyImageSrcSet (crop/focal/format baked into
  every width; trims the ladder to a fixed CSS width).
• Next.js renderer uses next/image + a delivery-URL loader and the shared
  dimensions helper (responsive plain-<img> fallback when dims are unknown).
• Removed the client CSS rendering layer (WebinyImage, WebinyBackgroundImage,
  getWebinyImageProps) and the SDK geometry modules.

Backwards compatibility

• Existing Website Builder pages: the Image element still accepts the legacy flat
  value; normalizeToAsset upgrades it at render time. No page migration.
• Existing file fields are untouched; asset is additive.
• Delivery: URLs without the new params behave exactly as before; the legacy
  crop-only cache key is preserved.

Testing

• api-file-manager: 129 passing (delivery option parsing, framing signature,
  crop/frame extraction).
• api-headless-cms: modelBuilder suite incl. Asset field + resolveAssetUrl.
• website-builder-sdk: normalizeToAsset, getWebinyAssetUrl/getAssetCropParam,
  getWebinyImageDimensions/getWebinyImageSrcSet.
• Full gate green: adio, oxfmt, oxlint, sync-dependencies, tsconfig sync.
• Manually verified: admin modelling + Asset input, File Manager crop → WB insert,
  CMS Asset crop re-adjust → GraphQL, WB runtime render, deploy.

Reviewer guide

• Value shape + normalizer — website-builder-sdk/src/asset/types.ts, .../normalize.ts
• Delivery URL + srcSet core — website-builder-sdk/src/asset/deliveryUrl.ts, .../imageSrcSet.ts
• Server framing — api-file-manager/src/features/assetDelivery/transformation/, api-file-manager-s3/src/assetDelivery/, api-file-manager-server/src/assetDelivery/
• Delivery params — api-file-manager/src/features/assetDelivery/normalizeImageOptions.ts, .../delivery/AssetDelivery/AssetRequest.ts
• CMS Asset field + url — api-headless-cms/src/features/modelBuilder/fields/, .../features/graphql/fields/base/ObjectToGraphQL.ts
• Admin editor + renderers — admin-ui/, app-file-manager/, app-headless-cms/
• Next renderer — website-builder-nextjs/src/editorComponents/Image.tsx

Suggested order: value shape → delivery params/framing → cache key → CMS field +
url → SDK URL/srcSet → Next renderer → admin editor/renderers.

Out of scope / follow-ups

• Migrate the React / Vue / Nuxt WB renderers onto the SDK core (they still use
  the legacy flat value and ignore crop today). Until then, crop/focal render on
  Next and via the CMS url field.
• Extract a lean @webiny/image package; Angular / React Native adapters.
• Optionally give the CMS url field arguments (url(width:, format:)).

Notes for reviewers testing locally

• Set the PR base to release/6.5.0 (not next).
• After pulling: rebuild the changed API + admin packages; feature-package code
  (e.g. app-headless-cms-common) must be rebuilt too — rebuilding admin-ui alone
  leaves it stale.