Per-field aspect ratio and per-usage crop for image fields

[afonsojramos]

Kept current with the thread below. The first version put the aspect ratio on the field, which forces one field per usage and lets an editor pick a different image in each. It is now one field carrying named crops. Settled since: the media-level focal point is the fallback when a crop is added or changed, crops apply at render time with no stored derivative, definitions live in options rather than validation and carry an editor-facing label and description, and assuming crop names in a frontend is no worse than the assumptions frontends already make about collection and field names. One question is open — see the end. Earlier wording is in this post's edit history.

Splitting this out of #990 as @MA2153 suggested there, and picking up @rob-j-oliver's point that a focal point wants to be "per usage".

Problem

The same photo gets used in slots with different shapes — a wide banner, a 4:3 slide, a tall card. One focal point stored on the media item cannot serve all three: the point that keeps a subject centred in a 7:4 banner is not the one that keeps it centred in a 2:3 card. #990 §4 proposes a normalized { x, y } on the media item, which is the right primitive but resolves to one answer per image rather than one per place it appears.

There is also nothing telling an editor what shape a slot expects, or why. A portrait photo dropped into a banner field is accepted happily, and the page either letterboxes it or crops it somewhere unfortunate. The first anyone knows is when they look at the published page.

Proposal

1. One field, named crops. A crop is a framing of one image, not a separate image, so the field declares the usages rather than the schema growing a field per usage. These are not constraints on a value, so they sit in options beside the other widget configuration rather than in validation:

{
  slug: "photo",
  type: "image",
  options: {
    crops: {
      banner: {
        label: "Page banner",
        description: "Full-width across the top of the page. Keep faces away from the lower edge, the title sits there.",
        ratio: "7:4",
        minWidth: 2000,
      },
      card: {
        label: "Hover card",
        description: "Small portrait card shown when someone hovers a row in the index.",
        ratio: "2:3",
        minWidth: 540,
      },
    },
  },
}

The slug is the stable identifier templates ask for. The label and description are only ever shown to editors, and the description is what stops someone centring a face exactly where the title will land.

2. One selection, one dialog. The editor picks a single image and adjusts each named crop against that same picture — a preview per usage. Where a field declares no crops, behaviour is unchanged.

3. The crop is stored as fractions of the source. All four numbers are in the range 0–1: x, y are the top-left corner of the crop rectangle, w, h its size. The region in pixels is (x·W, y·H, w·W, h·H) for a source of W × H:

{
  "id": "01J5...",
  "crops": {
    "banner": { "x": 0.12, "y": 0.08, "w": 0.76, "h": 0.62 },
    "card":   { "x": 0.55, "y": 0.10, "w": 0.40, "h": 0.90 }
  }
}

Fractions rather than pixels so a crop survives its source being replaced by a different resolution of the same image. The ratio is not stored, because the definition fixes it: the editor can move and scale the frame, never reshape it. A stored value whose implied ratio no longer matches its definition is how a changed definition is detected — the focal point covers until someone re-crops.

Any crop the editor has not adjusted falls back to the media-level focal point from #990.

4. Templates ask by name.

<EmDashImage src={entry.photo} crop="banner" />

Applied at render time — no derivative is stored. On Cloudflare that means the IMAGES binding's fit/gravity; #2228 was a prerequisite, since the endpoint dropped fit entirely and cover-crops silently did not happen on that platform.

Per-field ratios still make sense where the images genuinely differ: a portrait headshot beside a landscape hero are two fields because they are two photos, not two framings of one. The two ideas compose.

5. A minimum crop size, stored with the ratio. minWidth is the smallest useful crop width in source pixels — in practice the largest width a template ever renders that crop at, below which the renderer is upscaling. Height needs no storing; the ratio implies it. One number drives both checks:

• At selection, an image narrower than a declared crop's minWidth cannot satisfy it however it is framed, so the picker says so before the editor invests any effort.
• While cropping, the frame is clamped so it cannot be dragged below minWidth for that usage.

Current state, for anyone picking this up

There is no cropper in the admin today. The aspectRatio that appears in the bundle belongs to the rich-text image block's width/height lock, and crop appears only as an icon name, so this is a new surface rather than an extension of an existing one.

Open: does a crop value belong to the field or the media item?

A maintainer call, since it changes the storage shape.

On the field value — the same photo can be framed differently in two entries. Maximum control, and the editor re-crops every time they reuse an image.

On the media item — one crop per template per image, reused everywhere that image appears. Far less repetitive, and an image's banner framing is decided once. The cost is that two entries cannot frame the same photo differently, which may well be a feature.

The media item is the more natural home to my eye — how a photo should be framed as a banner is usually a property of the photo rather than of the page, and #990's focal point already lives there, so fallback and override would sit together.

Why bother

Aspect ratio is the one image property a CMS can enforce that an editor cannot reason about from a file picker. Format and size are fixable after the fact by a delivery pipeline (#1547); a badly framed crop is not, because the information about what mattered in the frame is gone.

[MA2153]

This sounds good. For the open questions:

• I would keep the focal point as a fallback for new / updated aspect ratios
• No derivative is stored - keep it render-time only

Now for "where the ratio is stored", that's where I would like to dive deeper. In the current proposal, admins must create fields for each usage that requires a different aspect ratio / crop. I am imagining collections with 5+ image fields that editors have to fill in. Not only is it annoying but it can also be a data integrity issue where editors (accidentally or intentionally) select different images for those usage-based fields, when the admin intended them to be the same image just with a customized crop.

The other thing I would mention, which could be out-of-scope, is a minimum size for the crop so editors don't end up cropping it in a way that makes it blurry. That might also constrain the image selection itself if it can't satisfy all the usages.

Otherwise I think this a good addition. Thank you!

[afonsojramos]

Agreed on both settled points — focal point as the fallback when a ratio is added or changed, and render-time only with no stored derivative.

On where the ratio lives: your objection convinces me the per-field primitive is wrong for the common case. Declaring the ratio on the field only works when each usage is a different image. The moment the same photo appears in three shapes, that model forces three fields, and then nothing in the schema says they are meant to hold the same picture. The proliferation is annoying; the divergence is a correctness bug, and it is one an editor can introduce without doing anything obviously wrong.

What the schema is missing is not "a ratio per field" but one image, many framings.

One field, named crops

{
  slug: "photo",
  type: "image",
  validation: {
    crops: {
      banner: "7:4",
      card:   "2:3",
      thumb:  "1:1",
    },
  },
}

One field, one selection, one dialog with a preview per named crop against the same picture. The stored value carries the media reference plus a crop per name, falling back to the media-level focal point for any name the editor has not adjusted:

{
  "id": "01J5...",
  "crops": {
    "banner": { "x": 0.42, "y": 0.31, "w": 0.8, "h": 0.65 },
    "card":   { "x": 0.55, "y": 0.10, "w": 0.4, "h": 0.9 }
  }
}

Templates ask for one by name:

<EmDashImage src={entry.photo} crop="banner" />

Divergence becomes unrepresentable rather than merely discouraged, which is the part I care about more than the field count. A wrong crop name at render is the one new failure mode, and it degrades to the focal point instead of breaking.

Per-field ratios still earn their place where the images genuinely differ — a portrait headshot beside a landscape hero are two fields because they are two photos, not two framings of one. The two ideas compose; they are answers to different questions.

Minimum crop size

I do not think this is out of scope: it is the difference between a crop UI that prevents blurry output and one that merely enables it.

The bound needs no new configuration, because the render sizes already imply it. For a named crop, the largest width any template requests is the smallest useful crop width in source pixels — below that, the renderer is upscaling.

That gives two checks at the two moments they are cheap:

• At selection, reject or warn when the source cannot satisfy every declared crop at its minimum, before the editor invests effort in framing. This is your point that it constrains selection itself: a 900px-wide photo cannot serve a 2000px banner crop, and the honest time to say so is when it is chosen.
• While cropping, clamp the frame so it cannot be dragged below the minimum for that usage, rather than letting it be drawn and rejected afterwards.

Both need the admin to know each usage's maximum render width — the same information the crop names need, which is what makes the next question the load-bearing one.

Which side of the line does this belong on?

The remaining question is less about syntax than about who owns these definitions, and EmDash already draws that line in a particular place.

A crop's ratio and its maximum render width are not really content model. They are facts about the templates: the banner is 7:4 because a component says so, and 2000px is the widest it is ever rendered at. But field configuration is editable in the admin, so putting them on the field means an admin can change a ratio in the UI while the component that motivated it stays as it was. The schema would then be describing a shape nothing renders, and every crop stored against the old ratio becomes quietly wrong.

Site-level definitions that fields reference by name keep those facts in one place and keep a rename honest — it becomes a migration instead of a silent divergence — but they only stay true if they ship with the templates that imply them, which makes them developer-owned in a way most field configuration is not.

So the question I would put here is where EmDash wants this to sit: is a crop usage part of the content model an admin curates, or part of the design system a deploy carries? The minimum-size rule pushes me towards the second, since render widths come from components and duplicating them per field guarantees drift. But that is a judgement about how EmDash is meant to be managed, and I am probably not the person to make that call.

[MA2153]

EmDash frontends make assumptions about collection names, fields, etc. It is not totally out of place to make an assumption about available crop templates. You are right that ideally this should be synced somehow so admins can't delete currently used definitions in the frontend, but I think this is out of scope for this feature. You should just accept that the frontend can break if an admin makes the wrong move.

Two things I want clarity on before this could proceed:

• Where is where the minimum crop size is stored? In the current model, they should probably be stored along the aspect ratios, but I don't see them in the examples.
• What does each property in { "x": 0.42, "y": 0.31, "w": 0.8, "h": 0.65 } do? They appear like percentages but it is not clear how they model the data.

Finally, a maintainer should make a judgement call about whether the crop templates are stored onto the fields or onto the media items themselves.

Otherwise, this looks good to go, and I am happy to bring it to the maintainers' attention once the points above are addressed.

[MA2153]

One more thing I noticed: While the crops can have slugs, I think the data model should allow for a user-facing name and description so editors can clearly identify what they are cropping for. I don't think it is good to put this in the "validation" property.

[afonsojramos]

That settles the ownership question then — frontends already assume collection and field names, so assuming crop names is no worse, and guarding against an admin deleting a definition in use is a separate problem. I have dropped it from the proposal rather than leaving it open.

Crop definitions are not validation

You are right that validation is the wrong home. These are not constraints on a value, they are a description of what the editor is being asked to do, and an editor needs to know what "banner" means without reading a template. Moving them to options alongside the other widget configuration, and giving each one a label and a description:

{
  slug: "photo",
  type: "image",
  options: {
    crops: {
      banner: {
        label: "Page banner",
        description: "Full-width across the top of the page. Keep faces away from the lower edge, the title sits there.",
        ratio: "7:4",
        minWidth: 2000,
      },
      card: {
        label: "Hover card",
        description: "Small portrait card shown when someone hovers a row in the index.",
        ratio: "2:3",
        minWidth: 540,
      },
    },
  },
}

The slug stays the stable identifier templates ask for; the label and description are only ever shown to editors. A description that explains why a crop is shaped the way it is — as above — is the thing that stops an editor centring a face exactly where the title will land.

Minimum crop size lives with the ratio

Agreed, and you are right that it was missing: I described how to derive the bound and never said where it goes. It belongs on the definition, as minWidth above.

minWidth is the smallest useful crop width in source pixels, which in practice is the largest width a template ever renders that crop at. Below it the renderer is upscaling. Height does not need storing: the ratio already implies it.

That single number drives both checks:

• At selection, an image narrower than a declared crop's minWidth cannot satisfy it however it is framed, so the picker can say so before the editor invests any effort.
• While cropping, the frame is clamped so it cannot be dragged below minWidth for that usage.

What { x, y, w, h } means

Fair — they are fractions, and I should have said so rather than leaving it to be inferred.

All four are fractions of the source image, in the range 0–1:

• x, y — the top-left corner of the crop rectangle
• w, h — its width and height

So the region in pixels is (x·W, y·H, w·W, h·H) for a source of W × H. The example crop { "x": 0.12, "y": 0.08, "w": 0.76, "h": 0.62 } on a 2000 × 1500 source is the rectangle at (240, 120) measuring 1520 × 930.

Fractions rather than pixels so a crop survives its source being replaced by a different resolution of the same image, and so the same value means the same framing regardless of what the original happens to measure.

The ratio is not stored in the value because the definition already fixes it: w·W / h·H always equals the declared ratio, and the editor can only move and scale the frame, never reshape it. A stored value whose implied ratio no longer matches its definition is how you detect a definition that changed after the fact — at which point the focal-point fallback takes over until someone re-crops.

The fork for a maintainer

The question is whether a crop value belongs to the field or to the media item, and it is a real fork rather than a detail:

On the field value — the same photo can be framed differently in two entries. Maximum control, and the editor re-crops every time they reuse an image.

On the media item — one crop per template per image, reused everywhere that image appears. Far less repetitive, and an image's banner framing is decided once. The cost is that two entries cannot frame the same photo differently, which may be a feature.

My instinct is the media item, on the grounds that "how this photo should be framed as a banner" is usually a property of the photo rather than of the page — and #990's focal point already lives there, so the fallback and the override would sit together. But this is exactly the call you say a maintainer should make, and it changes the storage shape, so I would rather not assume it.

I will update the proposal body to match whichever way that goes. Everything else above is folded in already.