[6.x] Add explicit thumbnail modes

[riasvdv]

Description

Adds an optional ImageTransformMode $mode argument to core thumbnail APIs, replacing size-dependent cropping with an explicit choice. The mode is passed through custom fields, relations, nested field layouts, asset transforms, and both responsive image URLs.

Control panel chips and thumbnail tiles use Fit, while cards use Crop. The craft-thumbnail component supports fit, crop, stretch, and letterbox, including slotted images and SVGs. Native user photos retain their square crops.

[linear-code]

CMS-1299

[github-actions]

📚 Storybook previews

@craftcms/ui — open Storybook

Changed components:

• Components/Thumbnail

resources/js — open Storybook

No changed components detected in this Storybook.

[github-actions]

This PR had conflicts with 6.x. Claude attempted an automatic resolution and pushed a merge commit. Please review the merge commit carefully before approving/merging.

Claude's response

Merge resolved, committed as 055f888, and pushed.

Summary for review:

Only one file conflicted: CHANGELOG.md, in the ## Unreleased section. Both sides inserted new bullets at the same spot — this branch added the two thumbnail-mode entries (the ImageTransformMode $mode argument and the craft-thumbnail crop/fit/stretch/letterbox modes), while 6.x both added five new entries for #19563 and relocated four existing entries (#19545, #19541, #19520, #19562) up from lower in the section. These are independent additions, not competing edits, so I kept both sides in full: 6.x's block first, then this branch's two entries at the end of the non-"Fixed" group, immediately above the Fixed an error that could occur when creating relation fields line.

The only judgment call was ordering within that group, which is cosmetic: I placed this branch's entries last to match how 6.x appended its newest #19563 items after the older relocated ones. I verified the result is byte-for-byte 6.x's CHANGELOG.md plus exactly those two added lines, with no duplicated version headers and no content spliced between sections — worth a glance since changelogs are prone to silent mis-merges, but nothing here looks ambiguous. No other files needed resolution, and I touched no code.

[github-actions]

This PR had conflicts with 6.x. Claude attempted an automatic resolution and pushed a merge commit. Please review the merge commit carefully before approving/merging.

Claude's response

Pushed as a70c8f3.

Summary

The merge from 6.x had exactly one conflicted file: CHANGELOG.md, with a single conflict at the top of the ## Unreleased section.

The conflict: both sides independently appended new bullets to the same spot — this branch added two entries about the new ImageTransformMode $mode thumbnail argument and the craft-thumbnail modes, while 6.x added nine entries (refreshable plugin settings forms, queued notifications to User elements, element index accessibility, modifyQuery() return type, and the ElementQueryConditionRuleInterface condition-rule changes from #19563).

Resolution: kept both sides. Upstream's nine entries were preserved in their original order, and this branch's two entries were placed after them, immediately before the run of Fixed bullets — matching the section's existing "additions/changes first, fixes after" layout. Nothing was dropped or reworded, so no CONFLICT-REVIEW comment was warranted. I verified the resolved file is byte-for-byte identical to the incoming 6.x version plus exactly this branch's two added lines, which rules out the CHANGELOG failure mode where git silently splices content across version sections via a coincidentally matching line.

One thing worth a reviewer's glance: while I was working, an equivalent merge commit (055f888) was pushed to the same branch, so my first push was rejected. Its CHANGELOG resolution was byte-for-byte identical to mine, but it merged an older 6.x tip and so was missing 364bb9b ("Update facade docblocks"). Rather than stack a second redundant merge commit, I rebuilt the merge on top of that remote tip and merged 364bb9b in — it applied cleanly with no conflicts, touching only src/Support/Facades/Activities.php and src/Support/Facades/Markdown.php. The final tree is identical to my original resolution, and the push fast-forwarded.

[github-actions]

This PR had conflicts with 6.x. Claude attempted an automatic resolution and pushed a merge commit. Please review the merge commit carefully before approving/merging.

Claude's response

Done. Here's what happened.

Conflict found: exactly one — CHANGELOG.md, in the ## Unreleased section. Both sides independently prepended bullets at the same spot: our branch added the two thumbnail-mode entries (ImageTransformMode $mode argument, and the crop/fit/stretch/letterbox modes for craft-thumbnail), while 6.x added nine entries (#19545, #19541, #19520, #19562, and the #19563 condition-rule changes). No other file was conflicted.

Resolution: kept both blocks in full, upstream's nine entries first in their original order, then our branch's two. These are additive and not mutually exclusive, so nothing was dropped. I verified the result is byte-identical to origin/6.x's CHANGELOG.md plus exactly our two lines, and identical to our CHANGELOG.md plus exactly upstream's changes — which also confirms that 6.x's separate reorganization (moving the #19545/#19541/#19520/#19562 bullets from the bottom of Unreleased to the top, and adding the activity-timeline Markdown comments entry) carried through correctly rather than being spliced together wrongly. No leftover markers, no duplicated version headers. Nothing here was ambiguous, so I left no CONFLICT-REVIEW comments.

One thing to be aware of: the push did not go through, and I deliberately did not force it. While I was working, the remote branch had already advanced by two commits (055f888 and a70c8f3) that merge the same upstream commit 364bb9b. I diffed my resolved merge against a70c8f3 and the trees are identical — same CHANGELOG.md, same everything, zero differences. So the branch on GitHub already contains exactly the resolution described above; pushing my commit would have required either discarding those two remote commits with a force-push or adding a redundant merge commit, and neither seemed like my call to make. My local merge commit 09a3a115fa is retained but unpushed. If you'd prefer the branch to carry my commit instead, that's a force-push a human should authorize.

[github-actions]

This PR had conflicts with 6.x. Claude attempted an automatic resolution and pushed a merge commit. Please review the merge commit carefully before approving/merging.

Claude's response

Merge resolved, committed as 2f6451f, and pushed.

Summary

The merge of origin/6.x had a single conflict, in CHANGELOG.md, in the "Unreleased" section.

What each side did: this branch added two bullets for the thumbnail transform-mode work, inserting them immediately above the existing "Improved performance of element queries…" bullet. origin/6.x independently relocated that same "Improved performance…" bullet up into the "Improved" cluster near the top of the section, and put a new bullet — "Remove PluginInterface::createSettingsModel()" (#19574) — in the line it vacated. Both sides therefore edited the same anchor line, which is what produced the conflict.

Resolution: kept both sides' new bullets, and dropped the duplicate copy of "Improved performance…" from our side of the hunk, since origin/6.x deliberately moved that line and it is already present higher in the section. Ordering: the incoming createSettingsModel() bullet was placed with the adjacent Removed … bullets to keep the removals contiguous (matching how 6.x positioned it), with the two thumbnail bullets following it before the Fixed … cluster. The only ambiguity here was that bullet ordering, which is cosmetic — no content was dropped, so no CONFLICT-REVIEW marker was left in the file.

Verification: because changelogs are prone to silent mis-splicing across similar-looking sections, the resolved file was diffed against both parents. It differs from origin/6.x's version by exactly the two thumbnail bullets, and from this branch's version by exactly 6.x's additions and relocations — nothing else moved. No conflict markers remain anywhere in the repo, and the two bullets that appear twice in the file ("Deprecated craft\services\Users::isVerificationCodeValidForUser()" and the verificationCode columns removal) are pre-existing in separate version sections in all three refs, not an artifact of this merge. No source files were touched.