7.2 KiB
Image variants
Route: /settings/media/variants, Slide-over on desktop · full page on mobile, /settings/media/cache, /settings · /settings/media/variants · /settings/media/cache. API: GET /v1/image-variants · PATCH /v1/image-variants/{name} · DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge · POST /v1/image-variants · PUT /v1/image-variants/{name} · GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge {scope: all|unused|variant|image}.
Admin-only page under Settings → Media, with two tabs: Variants and Cache. Desktop shows a table; mobile stacks each variant as a card. The status switch always pairs with an icon and the words Enabled or Disabled. The reference card "How requests are handled" sits under the table (section 7 of the brief).
Visual reference: RenewCMS Screens Back-office.dc.html, groups "Variants list", "Add edit variant", "Cache panel", "Settings navigation". Frames: AppFrame.dc.html (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
Copy per state (generated from the board source, pass 2)
Every state below is drawn in light and dark (theme switch on the board), at 1440×900 and 390×844 (both frames sit side by side). Board: RenewCMS Screens Back-office.dc.html. Copy is exact; where a cell is empty the state reuses the fixed copy.
1. Settings → Media → Variants (group "Variants list", 12 states)
Route: /settings/media/variants. API: GET /v1/image-variants · PATCH /v1/image-variants/{name} · DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge.
Admin-only page under Settings → Media, with two tabs: Variants and Cache. Desktop shows a table; mobile stacks each variant as a card. The status switch always pairs with an icon and the words Enabled or Disabled. The reference card "How requests are handled" sits under the table (section 7 of the brief).
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Loaded | Six variants, one of them disabled (print). | |
| 2 | Loading | Skeleton rows appear after 150 ms. | |
| 3 | Empty | No variants. Two templates pre-fill the Add variant form. | |
| 4 | Error loading | A 500 or network failure on the list request. | |
| 5 | Forbidden | A signed-in user who is not an admin opens the URL. | |
| 6 | Row menu | The ellipsis button on a row. | |
| 7 | Row action in progress | Purge cache was confirmed on hero. The row is dimmed and its controls are disabled. | |
| 8 | Purge confirm | Purge cache in the row menu. | "purgeVariant" |
| 9 | Delete confirm | Delete in the row menu. | "deleteVariant" |
| 10 | Delete in progress | Delete was confirmed. The button shows a spinner. | "deleteVariant" |
| 11 | Entry: sidebar | From any page, Settings expands in the sidebar to Media: Variants and Cache. Admin only. On mobile the menu button opens it as a drawer. | |
| 12 | Request reference | Mobile scrolled to the reference card. On desktop it is visible below the table. |
2. Add / edit variant (group "Add edit variant", 11 states)
Route: Slide-over on desktop · full page on mobile. API: POST /v1/image-variants · PUT /v1/image-variants/{name}.
Form on the left, live preview on the right (stacked on mobile). The preview uses a sample image with a before/after divider. The divider is a slider: arrow keys move it by 1%, Shift+arrow by 10%, Home and End jump to the ends. Name is locked in edit mode. The edit warning is always visible in edit mode. Preview images are placeholders.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Create: pristine | Add variant just opened. Save is disabled. | "Original" |
| 2 | Create: dirty | Valid values. The divider has keyboard focus. Mobile is scrolled to the preview. | |
| 3 | Field errors | On blur and on submit. Name format, width above 8000, quality above 100. | "Hero banner" / "WebP" / "Use lowercase letters, numbers and dashes, 2 to 32 characters." / "Enter a value from 1 to 8000." / "Enter a value from 1 to 100." |
| 4 | No dimension | Width and height are both empty on submit. | "WebP" / "Set a width, a height, or both." |
| 5 | Name already taken | POST returns 409. | "18 KB" / "A variant named “thumb” already exists. Choose another name." |
| 6 | Saving | Request in flight. Fields and buttons are disabled. | |
| 7 | Save error | A 500 or network failure. Values are kept. | |
| 8 | Edit: pristine | Opened from Edit. Name is locked. Save is disabled. | |
| 9 | Edit: dirty | Quality changed from 82 to 70. | "71 KB" |
| 10 | Unsaved changes | Close, Cancel or Escape while dirty. | "71 KB" |
| 11 | PNG: no quality | Quality is hidden when the format is PNG. | "PNG" / "310 KB" |
5. Settings → Media → Cache (group "Cache panel", 10 states)
Route: /settings/media/cache. API: GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge {scope: all|unused|variant|image}.
Stat tiles, a per-variant bar list (bar length is the disk size relative to the largest variant) and the ten images with the most variant disk usage. Purge all needs the word "purge" typed. Purge unused removes files of enabled variants not requested in 30 days.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Loaded | Default view. | |
| 2 | Loading | Tiles and lists show skeletons. | |
| 3 | Empty cache | Nothing generated. Purge buttons are disabled. | |
| 4 | Purging | Progress for a purge in progress. Content is dimmed. | |
| 5 | Purge done | The cache is empty and a toast reports the result. | "Purged 1,284 files, freed 212 MB" |
| 6 | Purge failed | Part of the purge did not complete. | "Purge didn't finish" / "640 of 1,284 files were removed. Try again." / "Try again" |
| 7 | Error loading | A 500 or network failure. | |
| 8 | Purge all: confirm | The word is not typed yet. The button is disabled. | "purgeAll" |
| 9 | Purge all: confirm, typed | The input matches "purge". | "purgeAllOk" |
| 10 | Purge unused: confirm | Variants of enabled variants not requested for 30 days. | "purgeUnused" |
Settings navigation: parent and child selected (group "Settings navigation", 5 states)
Route: /settings · /settings/media/variants · /settings/media/cache. API: none.
One sidebar for the whole Settings area. Settings is the parent row and expands to a Media group with Variants and Cache. Parent selected: the Settings row uses --rc-sand with --rc-on-sand. Child selected: the Settings row is not filled (--ui-text-highlighted, weight 500, chevron down) and only the child row uses --rc-sand with --rc-on-sand. Use the theme switch for dark. Hover, focus-visible and active on a selected row keep --rc-sand and --rc-on-sand; see foundations.md.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | N1 · Parent selected | /settings. Settings row filled, Media group visible, children unselected. | |
| 2 | N2 · Child selected: Variants | /settings/media/variants. Settings row unfilled and bold, Variants filled. | |
| 3 | N3 · Child selected: Cache | /settings/media/cache. Settings row unfilled and bold, Cache filled. | |
| 4 | N4 · Mobile drawer, parent selected | Menu button on /settings. Drawer rows are 44 px tall. | "Settings" |
| 5 | N5 · Mobile drawer, child selected | Menu button on /settings/media/variants. | "Settings" / "Media" / "Variants" |