Files
RenewCMS/docs/design/source/RenewCMS Screens Image variants.dc.html
T

347 lines
40 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="./support.js"></script>
</head>
<body>
<x-dc>
<helmet>
<meta name="design_doc_mode" content="canvas">
<link rel="icon" href="brand/favicon.svg">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;1,8..60,400&display=swap" rel="stylesheet">
<style>body{margin:0;font-family:'IBM Plex Sans',sans-serif;font-size:13px;line-height:20px}*{box-sizing:border-box}a{color:inherit;text-underline-offset:3px}a:hover{opacity:.8}code{font-family:'IBM Plex Mono',monospace;font-size:12px}</style>
</helmet>
<div ref="{{ rootRef }}" data-screen-label="Image variants" style="background:var(--rc-canvas);color:var(--ui-text);padding:64px;display:flex;flex-direction:column;gap:72px;width:max-content;min-width:100%">
<div style="display:flex;align-items:flex-end;gap:32px;max-width:1400px">
<div style="flex:1;display:flex;flex-direction:column;gap:10px">
<h1 style="margin:0;font:600 36px/44px 'IBM Plex Sans',sans-serif;letter-spacing:-0.02em;color:var(--ui-text-highlighted)">Feature: Image variants</h1>
<p style="margin:0;max-width:900px;font-size:16px;line-height:26px;color:var(--ui-text-toned);text-wrap:pretty">Named variants of an original image, requested as <code>/media/photo.png?v=thumb</code>. The original is never changed. Six screens in the AppFrame back-office frame, plus the request contract, activity log copy, states matrix, API error copy and component inventory. 1440 px at 50%, 390 px at 75%. The theme switch shows every state in dark mode. Related: <a href="RenewCMS Screens Back-office.dc.html">Back-office screens</a>.</p>
</div>
<div role="radiogroup" aria-label="Theme" style="display:flex;border:1px solid var(--ui-border-accented);background:var(--ui-bg)">
<sc-for list="{{ modes }}" as="m" hint-placeholder-count="3">
<button role="radio" aria-checked="{{ m.on }}" onClick="{{ m.pick }}" style="all:unset;cursor:pointer;height:36px;padding:0 14px;display:flex;align-items:center;font-weight:500;font-size:14px;background:{{ m.bg }};color:{{ m.fg }}" style-focus-visible="outline:2px solid var(--ui-primary);outline-offset:2px">{{ m.label }}</button>
</sc-for>
</div>
</div>
<sc-for list="{{ groups }}" as="g" hint-placeholder-count="6">
<section data-screen-label="{{ g.label }}" style="display:flex;flex-direction:column;gap:28px">
<div style="display:flex;flex-direction:column;gap:6px;max-width:1100px">
<h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ g.title }}</h2>
<div style="display:flex;gap:16px;flex-wrap:wrap;font:400 14px/22px 'IBM Plex Mono',monospace;color:var(--ui-text-toned)"><span>{{ g.route }}</span><span style="color:var(--ui-text-muted)">{{ g.api }}</span></div>
<p style="margin:4px 0 0;font-size:15px;line-height:24px;color:var(--ui-text-toned);text-wrap:pretty">{{ g.note }}</p>
</div>
<div style="display:flex;flex-wrap:wrap;gap:40px;align-items:flex-start">
<sc-for list="{{ g.states }}" as="st" hint-placeholder-count="4">
<div style="display:flex;flex-direction:column;gap:12px">
<div style="display:flex;flex-direction:column;gap:2px;max-width:1040px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ st.id }} · {{ st.name }}</span><span style="font-size:13px;color:var(--ui-text-muted)">{{ st.trigger }}</span></div>
<div style="display:flex;gap:24px;align-items:flex-start">
<div style="width:720px;height:450px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:1440px;height:900px;zoom:0.5"><dc-import name="VariantsFrame" s="{{ st.s }}" mobile="{{ false }}" hint-size="1440px,900px"></dc-import></div></div>
<div style="width:293px;height:633px;overflow:hidden;border:1px solid var(--ui-border);flex-shrink:0"><div style="width:390px;height:844px;zoom:0.75"><dc-import name="VariantsFrame" s="{{ st.m }}" mobile="{{ true }}" hint-size="390px,844px"></dc-import></div></div>
</div>
</div>
</sc-for>
</div>
<sc-for list="{{ g.tables }}" as="t" hint-placeholder-count="1">
<div style="display:flex;flex-direction:column;gap:8px;max-width:1240px"><span style="font:600 16px/24px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ t.title }}</span><div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><div style="display:grid;grid-template-columns:{{ t.tpl }};padding:8px 12px;gap:16px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><sc-for list="{{ t.cols }}" as="c" hint-placeholder-count="3"><span>{{ c }}</span></sc-for></div><sc-for list="{{ t.rows }}" as="r" hint-placeholder-count="3"><div style="display:grid;grid-template-columns:{{ t.tpl }};gap:16px;padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><sc-for list="{{ r }}" as="cell" hint-placeholder-count="3"><span style="color:{{ cell.fg }};font-weight:{{ cell.fw }};font-family:{{ cell.ff }};font-size:{{ cell.fs }};text-wrap:pretty;min-width:0">{{ cell.t }}</span></sc-for></div></sc-for></div></div>
</sc-for>
</section>
</sc-for>
<sc-for list="{{ specs }}" as="sp" hint-placeholder-count="5">
<section data-screen-label="{{ sp.label }}" style="display:flex;flex-direction:column;gap:16px;max-width:1240px">
<h2 style="margin:0;font:600 28px/36px 'IBM Plex Sans',sans-serif;color:var(--ui-text-highlighted)">{{ sp.title }}</h2>
<p style="margin:0;font-size:15px;line-height:24px;color:var(--ui-text-toned);text-wrap:pretty">{{ sp.note }}</p>
<sc-for list="{{ sp.tables }}" as="t" hint-placeholder-count="1">
<div style="background:var(--ui-bg);border:1px solid var(--ui-border)"><div style="display:grid;grid-template-columns:{{ t.tpl }};padding:8px 12px;gap:16px;background:var(--ui-bg-elevated);color:var(--ui-text-muted);font-weight:500"><sc-for list="{{ t.cols }}" as="c" hint-placeholder-count="3"><span>{{ c }}</span></sc-for></div><sc-for list="{{ t.rows }}" as="r" hint-placeholder-count="3"><div style="display:grid;grid-template-columns:{{ t.tpl }};gap:16px;padding:10px 12px;border-top:1px solid var(--ui-border);line-height:20px"><sc-for list="{{ r }}" as="cell" hint-placeholder-count="3"><span style="color:{{ cell.fg }};font-weight:{{ cell.fw }};font-family:{{ cell.ff }};font-size:{{ cell.fs }};text-wrap:pretty;min-width:0">{{ cell.t }}</span></sc-for></div></sc-for></div>
</sc-for>
</section>
</sc-for>
</div>
</x-dc>
<script type="text/x-dc" data-dc-script data-props="{&quot;theme&quot;:{&quot;editor&quot;:&quot;enum&quot;,&quot;options&quot;:[&quot;system&quot;,&quot;light&quot;,&quot;dark&quot;],&quot;default&quot;:&quot;system&quot;,&quot;tsType&quot;:&quot;'system' | 'light' | 'dark'&quot;}}">
class Component extends DCLogic {
state = { mode: this.props.theme ?? 'light' }
rootRef = React.createRef()
light = { '--ui-bg': '#ffffff', '--ui-bg-muted': '#fafafa', '--ui-bg-elevated': '#f3f2f0', '--ui-bg-accented': '#e6e4e0', '--ui-bg-inverted': '#111111', '--ui-text-dimmed': '#999999', '--ui-text-muted': '#666666', '--ui-text-toned': '#444444', '--ui-text': '#222222', '--ui-text-highlighted': '#111111', '--ui-text-inverted': '#ffffff', '--ui-border': '#e6e4e0', '--ui-border-muted': '#f3f2f0', '--ui-border-accented': '#8a8783', '--ui-primary': '#111111', '--ui-secondary': '#635643', '--ui-success': '#315b33', '--ui-info': '#34536d', '--ui-warning': '#6c4700', '--ui-error': '#882c21', '--rc-sand': '#e8dfd1', '--rc-on-sand': '#111111', '--rc-success-soft': '#eaefea', '--rc-info-soft': '#ebeef0', '--rc-warning-soft': '#f0ede6', '--rc-error-soft': '#f3eae9', '--rc-overlay': 'rgb(10 10 10 / 0.4)', '--rc-shadow-pop': '0 4px 16px rgb(17 17 17 / 0.08), 0 1px 2px rgb(17 17 17 / 0.06)', '--rc-shadow-modal': '0 16px 48px rgb(17 17 17 / 0.18)', '--rc-canvas': '#ecebe8' }
dark = { '--ui-bg': '#111111', '--ui-bg-muted': '#0a0a0a', '--ui-bg-elevated': '#1a1a1a', '--ui-bg-accented': '#222222', '--ui-bg-inverted': '#fafafa', '--ui-text-dimmed': '#666666', '--ui-text-muted': '#999999', '--ui-text-toned': '#cfccc7', '--ui-text': '#e6e4e0', '--ui-text-highlighted': '#fafafa', '--ui-text-inverted': '#111111', '--ui-border': '#333333', '--ui-border-muted': '#222222', '--ui-border-accented': '#666666', '--ui-primary': '#fafafa', '--ui-secondary': '#d4c5b0', '--ui-success': '#a3caa3', '--ui-info': '#a5c2db', '--ui-warning': '#dfb67d', '--ui-error': '#fba394', '--rc-sand': '#d4c5b0', '--rc-on-sand': '#111111', '--rc-success-soft': '#1f241f', '--rc-info-soft': '#202428', '--rc-warning-soft': '#2a251e', '--rc-error-soft': '#2c201f', '--rc-overlay': 'rgb(0 0 0 / 0.6)', '--rc-shadow-pop': '0 4px 16px rgb(0 0 0 / 0.5)', '--rc-shadow-modal': '0 16px 48px rgb(0 0 0 / 0.6)', '--rc-canvas': '#1c1c1c' }
resolved() {
if (this.state.mode === 'system') return window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
return this.state.mode
}
apply() {
const el = this.rootRef.current
if (!el) return
const vars = this.resolved() === 'dark' ? this.dark : this.light
for (const k in vars) el.style.setProperty(k, vars[k])
document.body.style.background = vars['--rc-canvas']
}
componentDidMount() { this.apply() }
componentDidUpdate(p) {
if (p.theme !== this.props.theme && this.props.theme) this.setState({ mode: this.props.theme })
this.apply()
}
cell(t, i, o = {}) { return { t, fg: i === 0 && !o.plain ? 'var(--ui-text-highlighted)' : o.muted ? 'var(--ui-text-muted)' : 'var(--ui-text-toned)', fw: i === 0 && !o.plain ? 500 : 400, ff: o.mono ? "'IBM Plex Mono',monospace" : "'IBM Plex Sans',sans-serif", fs: o.mono ? '12px' : '13px' } }
tbl(title, cols, tpl, rows, o = {}) { return { title, cols, tpl, rows: rows.map(r => r.map((t, i) => this.cell(t, i, { mono: o.mono && o.mono.includes(i), muted: t === '–' }))) } }
groups() {
const st = (id, name, trigger, s, ms = {}) => ({ id, name, trigger, s, m: { ...s, ...ms } })
const LB = { nav: 'settings', crumbs: ['Settings', 'Media', 'Variants'], mTitle: 'Variants' }
const CB = { nav: 'settings', crumbs: ['Settings', 'Media', 'Cache'], mTitle: 'Cache' }
const MB = { nav: 'media', crumbs: ['Media'], mTitle: 'Media' }
const l = (list, o = {}) => ({ kind: 'list', ...LB, list, ...o })
const cr = { mode: 'create', fit: 'cover', pos: 50 }
const hero = { ...cr, name: 'hero', w: '1200', h: '630', fmt: 'WebP', q: 82, qv: 82, gen: true, en: true, out: '1200×630', est: '96 KB' }
const ed = (e, o = {}) => ({ kind: 'edit', ...LB, ed: e, ...o })
const ET = this.tbl.bind(this)
const C3 = ['State', 'Where', 'Copy']
const T3 = '210px 260px minmax(0,1fr)'
const tb = (title, rows) => ET(title, C3, T3, rows)
return [
{ label: 'Variants list', title: '1. Settings → Media → Variants', 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 (proposed)', note: '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).',
states: [
st('1a', 'Loaded', 'Six variants, one of them disabled (print).', l({})),
st('1b', 'Loading', 'Skeleton rows appear after 150 ms.', l({ state: 'loading' })),
st('1c', 'Empty', 'No variants. Two templates pre-fill the Add variant form.', l({ state: 'empty' })),
st('1d', 'Error loading', 'A 500 or network failure on the list request.', l({ state: 'error' })),
st('1e', 'Forbidden', 'A signed-in user who is not an admin opens the URL.', { kind: 'list', ...LB, nav: null, role: 'user', forbidden: true }),
st('1f', 'Row menu', 'The ellipsis button on a row.', l({ menu: 2 })),
st('1g', 'Row action in progress', 'Purge cache was confirmed on hero. The row is dimmed and its controls are disabled.', l({ busy: 2 })),
st('1h', 'Purge confirm', 'Purge cache in the row menu.', l({}, { modal: 'purgeVariant' })),
st('1i', 'Delete confirm', 'Delete in the row menu.', l({}, { modal: 'deleteVariant' })),
st('1j', 'Delete in progress', 'Delete was confirmed. The button shows a spinner.', l({}, { modal: 'deleteVariant', loadingModal: true })),
st('1k', 'Request reference', 'Mobile scrolled to the reference card. On desktop it is visible below the table.', l({}), { scroll: 900 })
],
tables: [tb('Copy: Variants list', [
['Header', 'Title, description, button', 'Image variants · Named sizes and formats generated from your original images. Originals are never changed. · Add variant'],
['Table columns', 'Header row', 'Name · Dimensions · Fit · Format · Quality · Generated · Cache size · Status'],
['Dimensions', 'Cell', '400×300 · 800 × auto · auto × 2400'],
['Quality', 'Cell', '80 · — (PNG has no quality)'],
['Status', 'Switch + text', 'Enabled · Disabled (aria-label: "Enable variant hero")'],
['Row menu', 'Menu items', 'Edit · Purge cache · Delete'],
['Footer summary', 'Under the table', '6 variants · 1,284 generated files · 212 MB'],
['Footer summary (singular)', 'One variant', '1 variant · 1 generated file · 18 KB'],
['Loading', 'Skeleton', 'No text. Region announces "Loading variants".'],
['Empty', 'Title · text', 'No variants yet · A variant is a named size that an image can be requested in, like ?v=thumb. Start with one of these.'],
['Empty', 'Template cards', 'thumb · 400×300 · cover · WebP — hero · 1200×630 · cover · WebP — Use template'],
['Error', 'Alert', 'Couldn\'t load variants · Check your connection and try again. · Try again'],
['Forbidden', 'Title · text · button', 'You don\'t have access · Only admins can manage image variants. Ask an admin if you need one changed. · Back to Home'],
['Row in progress', 'Status cell', 'Purging…'],
['Purge success', 'Toast', 'Purged 244 files from “hero”'],
['Purge dialog', 'Title · text · buttons', 'Purge cache for “hero”? · This removes 244 generated files (84 MB). Files are generated again on the next request. · Cancel · Purge 244 files'],
['Delete dialog', 'Title · text · buttons', 'Delete variant “hero”? · This removes the variant and its 244 generated files (84 MB). Articles that use ?v=hero will start returning 400. This can\'t be undone. · Cancel · Delete variant'],
['Delete success', 'Toast', 'Variant “hero” deleted'],
['Request reference', 'Card', 'How requests are handled · Body of a 400 response · unsupported_parameter replaces unknown_variant when a raw parameter is sent. There is no arbitrary-size mode.']
])]
},
{ label: 'Add edit variant', title: '2. Add / edit variant', route: 'Slide-over on desktop · full page on mobile', api: 'POST /v1/image-variants · PUT /v1/image-variants/{name}', note: '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.',
states: [
st('2a', 'Create: pristine', 'Add variant just opened. Save is disabled.', ed({ ...cr, name: '', w: '', h: '', fmt: 'Original', q: 80, qv: 80, gen: false, en: true, disSave: true, focusName: true })),
st('2b', 'Create: dirty', 'Valid values. The divider has keyboard focus. Mobile is scrolled to the preview.', ed({ ...hero, dirty: true, focus: true }), { scroll: 560 }),
st('2c', 'Field errors', 'On blur and on submit. Name format, width above 8000, quality above 100.', ed({ ...cr, name: 'Hero banner', w: '9000', h: '630', fmt: 'WebP', q: 140, qv: 100, gen: false, en: true, dirty: true, err: { name: 'Use lowercase letters, numbers and dashes, 2 to 32 characters.', w: 'Enter a value from 1 to 8000.', q: 'Enter a value from 1 to 100.' } })),
st('2d', 'No dimension', 'Width and height are both empty on submit.', ed({ ...cr, name: 'banner', w: '', h: '', fmt: 'WebP', q: 80, qv: 80, gen: false, en: true, dirty: true, err: { dim: 'Set a width, a height, or both.' } })),
st('2e', 'Name already taken', 'POST returns 409.', ed({ ...hero, name: 'thumb', w: '400', h: '300', out: '400×300', est: '18 KB', dirty: true, err: { name: 'A variant named “thumb” already exists. Choose another name.' } })),
st('2f', 'Saving', 'Request in flight. Fields and buttons are disabled.', ed({ ...hero, dirty: true, saving: true })),
st('2g', 'Save error', 'A 500 or network failure. Values are kept.', ed({ ...hero, dirty: true, saveErr: true })),
st('2h', 'Edit: pristine', 'Opened from Edit. Name is locked. Save is disabled.', ed({ ...hero, mode: 'edit', files: 244, disSave: true })),
st('2i', 'Edit: dirty', 'Quality changed from 82 to 70.', ed({ ...hero, mode: 'edit', files: 244, q: 70, qv: 70, est: '71 KB', dirty: true })),
st('2j', 'Unsaved changes', 'Close, Cancel or Escape while dirty.', ed({ ...hero, mode: 'edit', files: 244, q: 70, qv: 70, est: '71 KB', dirty: true }, { modal: 'discard' })),
st('2k', 'PNG: no quality', 'Quality is hidden when the format is PNG.', ed({ ...hero, fmt: 'PNG', est: '310 KB', dirty: true }))
],
tables: [tb('Copy: Add / edit variant', [
['Titles', 'Slide-over header', 'Add variant · Edit variant: hero'],
['Name', 'Label · placeholder · help', 'Name · e.g. hero · Lowercase letters, numbers and dashes. Can\'t be changed later.'],
['Name (edit)', 'Help', 'The name can\'t be changed.'],
['Name error: format', 'Inline', 'Use lowercase letters, numbers and dashes, 2 to 32 characters.'],
['Name error: taken', 'Inline', 'A variant named “thumb” already exists. Choose another name.'],
['Width · Height', 'Label · suffix · placeholder · help', 'Width · Height · px · auto · Set a width, a height, or both. 1–8000 px. Images are never enlarged.'],
['Dimension error', 'Inline', 'Set a width, a height, or both.'],
['Dimension range error', 'Inline', 'Enter a value from 1 to 8000.'],
['Fit', 'Options · help', 'Cover: Fills the box and crops what overflows. · Contain: Whole image inside the box, padded to the box size. · Inside: Whole image inside the box, no padding.'],
['Format', 'Options · help', 'Original · JPEG · PNG · WebP · Keeps the format of each source image.'],
['Quality', 'Label · help · error', 'Quality · 1–100. Higher is sharper and larger. · Enter a value from 1 to 100.'],
['Toggles', 'Label · help', 'Generate on upload: Creates this variant when an image is uploaded. · Enabled: Disabled variants return 400 on the public site.'],
['Edit warning', 'Alert (edit only)', 'Changing dimensions, fit, format or quality purges 244 generated files; they will be regenerated on next request.'],
['Preview', 'Heading · labels · hint', 'Preview · Sample: north-wall.jpg · Original — 4032 × 3024 · 3.9 MB · hero — 1200×630 · about 96 KB · Drag the divider, or focus it and use the arrow keys. The estimate comes from a sample; output is never larger than the source.'],
['Preview (no size)', 'Over the image', 'Set a width or height to see a preview.'],
['Slider', 'aria-label · aria-valuetext', 'Compare original and hero · 50% hero'],
['URL', 'Label · button', 'URL · /media/north-wall.jpg?v=hero · Copy · Copied'],
['Footer', 'Status · buttons', 'Unsaved changes · Cancel · Add variant · Save changes · Saving…'],
['Save error', 'Alert', 'Couldn\'t save the variant · Check your connection and try again. · Try again'],
['Save success', 'Toast', 'Variant “hero” added · Variant “hero” saved. 244 files purged.'],
['Unsaved dialog', 'Title · text · buttons', 'Discard changes? · You have unsaved changes to “hero”. If you close now, they\'re lost. · Keep editing · Discard changes']
])]
},
{ label: 'Media library', title: '3. Media library', route: '/media', api: 'GET /v1/media?variants=with|without&sort=total_size (proposed)', note: 'The existing grid with three additions: a "N variants" badge on cards that have cached files, an All / With variants / Without filter, and the sort option "Largest total size (original + variants)". When sorted by total size, the meta line shows the total.',
states: [
st('3a', 'Grid with badges', 'Default view. Images with no cached variants have no badge.', { kind: 'media', ...MB, ml: { ann: 'New: badge' } }),
st('3b', 'Sort menu', 'The sort select is open. The new option is last.', { kind: 'media', ...MB, ml: { menu: true, sort: 'total', ann: 'New: sort option' } }),
st('3c', 'Filter: With variants, sorted by total size', 'The meta line becomes total · original + variants.', { kind: 'media', ...MB, ml: { filter: 'With variants', sort: 'total', ids: [1, 7, 9, 12, 5, 11, 2, 3, 10] } }),
st('3d', 'Filter: Without variants', 'Images no variant has been generated for.', { kind: 'media', ...MB, ml: { filter: 'Without', ids: [4, 6, 8] } }),
st('3e', 'Filter: nothing to show', 'With variants, and the cache is empty.', { kind: 'media', ...MB, ml: { filter: 'With variants', empty: true } }),
st('3f', 'Delete confirm', 'Delete on an image that has cached variants.', { kind: 'media', ...MB, ml: {}, modal: 'deleteImage' })
],
tables: [tb('Copy: Media library additions', [
['Badge', 'Card', '4 variants · 1 variant'],
['Filter', 'Segmented control', 'All · With variants · Without'],
['Sort', 'Select, new option', 'Largest total size (original + variants) · mobile label: Largest total size'],
['Meta line (sorted by total)', 'Card', '4.2 MB total · 3.9 MB + 260 KB'],
['Empty filter', 'Title · text · button', 'No images with variants · Variants are generated when an image is requested with ?v=<name>, or from its Variants tab. · Show all images'],
['Delete dialog', 'Title · text · note · buttons', 'Delete this image? · "north-wall.jpg" is used in 2 articles. If you delete it, they will show a broken image. This can\'t be undone. · Also removes 4 generated variants (260 KB) · Cancel · Delete image'],
['Bulk delete', 'Dialog line', 'Also removes 11 generated variants (1.1 MB)']
])]
},
{ label: 'Image detail', title: '4. Image detail: Variants tab', route: '/media (detail panel)', api: 'GET /v1/media/{id}/variants · POST /v1/media/{id}/variants/{name} · DELETE /v1/media/{id}/variants/{name} (proposed)', note: 'The detail panel gets a Variants tab with one row per enabled variant. On desktop the row actions are icon buttons with tooltips and accessible names; on mobile they are labeled buttons on their own line. Only actions that apply are shown: generated rows offer Copy URL, Preview and Purge; others offer Copy URL and Generate now. The tab shows output dimensions as they will be generated, capped at the source size.',
states: [
st('4a', 'Partly generated', 'Four of five generated. Saving is shown against the original.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'gen', 'gen', 'gen', 'none'] } }),
st('4b', 'Nothing generated yet', 'No cached files for this image.', { kind: 'detail', ...MB, dt: {} }),
st('4c', 'Generating', 'Generate all or Generate now was pressed. Rows show a spinner.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'busy', 'busy', 'none', 'none'] } }),
st('4d', 'Generation failed', 'The row shows the cause and Retry. Both causes are shown together for reference.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'fail', 'fail', 'gen', 'gen'], cause: [0, 'Unsupported source format', 'Image too large'] } }),
st('4e', 'No variants defined', 'There are no enabled variants.', { kind: 'detail', ...MB, dt: { none: true } }),
st('4f', 'Source is an SVG', 'Variants aren\'t generated for vector images.', { kind: 'detail', ...MB, dt: { id: 4, nofmt: 'SVG images are served as they are.' } }),
st('4g', 'Source is an animated GIF', 'Same rule as SVG.', { kind: 'detail', ...MB, dt: { id: 4, nofmt: 'Animated GIFs are served as they are.' } }),
st('4h', 'Preview dialog', 'Preview on a generated row. Both at actual size.', { kind: 'detail', ...MB, dt: { rows: ['gen', 'gen', 'gen', 'gen', 'none'], preview: true } })
],
tables: [tb('Copy: Variants tab', [
['Tabs', 'Panel', 'Details · Variants'],
['Original', 'Header block', 'Original · kept untouched · north-wall.jpg · JPEG · 4032 × 3024 · 3.9 MB'],
['Summary', 'Above the list', '4 of 5 generated · Nothing generated yet. · Generating variants…'],
['Generate all', 'Button', 'Generate all · Generating…'],
['Row status', 'Badge', 'Generated · Not generated · Generating · Failed'],
['Row meta (generated)', 'Under the name', '400×300 · WebP · 18 KB · -99% vs original'],
['Row meta (not generated)', 'Under the name', '400×300 · WebP'],
['Row actions', 'Tooltip · aria-label', 'Copy URL · Preview · Generate now · Purge · Retry'],
['Failed: cause', 'Row line', 'Unsupported source format · Image too large'],
['No variants defined', 'Title · text · link', 'No variants defined · Define a variant in Settings to get resized copies of this image. · Settings → Media → Variants'],
['SVG / GIF', 'Alert', 'Variants aren\'t generated for this format. · SVG images are served as they are. · Animated GIFs are served as they are.'],
['Preview dialog', 'Title · panes · hint', 'Preview: thumb · thumb · 400×300 · WebP — 18 KB · saves 99% · Original · 4032×3024 · JPEG — 3.9 MB · Both images are shown at actual size. Scroll to pan. · Close'],
['Toasts', 'After actions', 'Generated 5 variants · Generated thumb · Purged 4 files (260 KB) · Couldn\'t generate hero. Image too large.']
])]
},
{ label: 'Cache panel', title: '5. Settings → Media → Cache', route: '/settings/media/cache', api: 'GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge {scope: all|unused|variant|image} (proposed)', note: '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.',
states: [
st('5a', 'Loaded', 'Default view.', { kind: 'cache', ...CB }),
st('5b', 'Loading', 'Tiles and lists show skeletons.', { kind: 'cache', ...CB, cache: { state: 'loading' } }),
st('5c', 'Empty cache', 'Nothing generated. Purge buttons are disabled.', { kind: 'cache', ...CB, cache: { state: 'empty' } }),
st('5d', 'Purging', 'Progress for a purge in progress. Content is dimmed.', { kind: 'cache', ...CB, cache: { state: 'purging' } }),
st('5e', 'Purge done', 'The cache is empty and a toast reports the result.', { kind: 'cache', ...CB, cache: { state: 'empty' }, toasts: [['success', 'circle-check', 'Purged 1,284 files, freed 212 MB', '']] }),
st('5f', 'Purge failed', 'Part of the purge did not complete.', { kind: 'cache', ...CB, toasts: [['error', 'circle-x', 'Purge didn\'t finish', '640 of 1,284 files were removed. Try again.', 'Try again']] }),
st('5g', 'Error loading', 'A 500 or network failure.', { kind: 'cache', ...CB, cache: { state: 'error' } }),
st('5h', 'Purge all: confirm', 'The word is not typed yet. The button is disabled.', { kind: 'cache', ...CB, modal: 'purgeAll' }),
st('5i', 'Purge all: confirm, typed', 'The input matches "purge".', { kind: 'cache', ...CB, modal: 'purgeAllOk' }),
st('5j', 'Purge unused: confirm', 'Variants of enabled variants not requested for 30 days.', { kind: 'cache', ...CB, modal: 'purgeUnused' })
],
tables: [tb('Copy: Cache panel', [
['Header', 'Title · text · buttons', 'Cache · Generated variant files. Purged files are generated again on the next request. · Purge unused · Purge all variants'],
['Tiles', 'Label · sub text', 'Generated files · Across 6 variants — Disk used · Originals not included — Variants defined · 5 enabled, 1 disabled — Rejected requests · Last 7 days'],
['Bar list', 'Heading · row', 'By variant · hero 244 files · 84 MB · Disabled (badge on disabled variants)'],
['Top 10', 'Heading · row · button', 'Top 10 images by variant disk usage · north-wall.jpg · 6 variants · 5.8 MB · Purge'],
['Empty cache', 'Title · text', 'Nothing generated yet · Variants are generated on the first request with ?v=<name>, or from an image\'s Variants tab.'],
['Purging', 'Banner', 'Purging 1,284 files · 640 of 1,284 · 106 MB freed'],
['Purge done', 'Toast', 'Purged 1,284 files, freed 212 MB'],
['Purge failed', 'Toast', 'Purge didn\'t finish · 640 of 1,284 files were removed. Try again. · Try again'],
['Error', 'Alert', 'Couldn\'t load cache stats · Check your connection and try again. · Try again'],
['Purge all dialog', 'Title · text · field · buttons', 'Purge all variants? · This removes 1,284 generated files (212 MB) for every variant. Originals aren\'t touched. Files are generated again on request. · Type purge to confirm · Cancel · Purge all variants'],
['Purge unused dialog', 'Title · text · buttons', 'Purge unused variants? · This removes 312 files (41 MB) from enabled variants that haven\'t been requested for 30 days. Files are generated again on request. · Cancel · Purge 312 files'],
['Purge image (row)', 'Toast', 'Purged 6 files (5.8 MB) for north-wall.jpg']
])]
},
{ label: 'Editor picker', title: '6. Editor image picker', route: '/articles/{id}/edit', api: 'Inserted URL: /media/{file}?v={name}', note: 'The Library tab of the picker gets a Variant select. Options are Original plus the enabled variants, each with its dimensions and format. Once inserted, a block whose variant was deleted or disabled shows an inline warning with a way to fix it. Disabled variants do not appear in the select.',
states: [
st('6a', 'Variant select', 'An image is selected. The URL line shows what will be inserted.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { picker: true, cur: 3 } }),
st('6b', 'Select open', 'Original plus five enabled variants.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { picker: true, cur: 3, open: true } }),
st('6c', 'No variants defined', 'Only Original is offered.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { picker: true, none: true } }),
st('6d', 'Variant deleted', 'The block keeps its URL. Pick another variant opens the select.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { block: true, msg: 'Variant \'hero\' no longer exists.' } }),
st('6e', 'Variant disabled', 'Same block, different cause. Proposed copy.', { kind: 'editor', nav: 'articles', crumbs: ['Articles', 'How we price a bathroom renovation'], mTitle: 'Edit article', back: true, edr: { block: true, msg: 'Variant \'hero\' is disabled.' } })
],
tables: [tb('Copy: Editor picker', [
['Select', 'Label', 'Variant'],
['Options', 'Option label', 'Original · 4032×3024 · JPEG — Thumb · 400×300 · WebP — Card · 800 × auto · WebP — Hero · 1200×630 · WebP — Square · 600×600 · JPEG — Og · 1200×630 · JPEG'],
['URL line', 'Under the select', '/media/north-wall.jpg?v=hero'],
['No variants', 'Help', 'No variants defined. Add one in Settings → Media → Variants.'],
['Block warning: deleted', 'Inline warning', 'Variant \'hero\' no longer exists. This image returns an error on the public site. · Pick another variant'],
['Block warning: disabled', 'Inline warning (proposed)', 'Variant \'hero\' is disabled. This image returns an error on the public site. · Pick another variant'],
['Block label', 'Chip on the image', 'hero · 1200×630']
])]
}
]
}
specs() {
const T = (cols, tpl, rows, o = {}) => ({ cols, tpl, rows: rows.map(r => r.map((t, i) => this.cell(t, i, { mono: o.mono && o.mono.includes(i), muted: t === '–' }))) })
return [
{ label: 'Request contract', title: '7. Public request contract', note: 'Shown as the "How requests are handled" card in section 1. Only variants that exist and are enabled are served. There is no arbitrary-size mode.', tables: [T(['Request', 'Status', 'Body or result'], '320px 80px minmax(0,1fr)', [
['/media/photo.png?v=thumb', '200', 'The cached image. Generated on first request.'],
['/media/photo.png?v=unknown', '400', 'Unknown variant'],
['/media/photo.png?v=hero (disabled)', '400', 'Unknown variant'],
['/media/photo.png?width=400', '400', 'Unsupported parameter'],
['height, format or quality parameters', '400', 'Unsupported parameter'],
['/media/missing.png?v=thumb', '404', 'Not found'],
['400 body shape', '', '{ "status": 400, "error": "unknown_variant" | "unsupported_parameter", "message": "Unknown variant", "detail": "banner" }']
], { mono: [0] })] },
{ label: 'Activity log', title: '8. Activity log entries', note: 'Row copy for the existing activity log. The actor name is bold, the quoted name is the variant name, and the detail line is secondary text.', tables: [T(['Event', 'Row copy', 'Detail line'], '220px minmax(0,1fr) minmax(0,1fr)', [
['Variant created', 'Marta Alves created variant “hero”', '1200×630 · cover · WebP · quality 82'],
['Variant updated', 'Marta Alves updated variant “hero”', 'Quality 82 → 70 · purged 244 files'],
['Variant deleted', 'Marta Alves deleted variant “hero”', 'Removed 244 generated files (84 MB)'],
['Variant enabled', 'Marta Alves enabled variant “hero”', 'Requests for ?v=hero are served'],
['Variant disabled', 'Marta Alves disabled variant “hero”', 'Requests for ?v=hero return 400'],
['Cache purged: all', 'Marta Alves purged all variants', 'Removed 1,284 files (212 MB)'],
['Cache purged: unused', 'Marta Alves purged unused variants', 'Removed 312 files (41 MB) not requested for 30 days'],
['Cache purged: by variant', 'Marta Alves purged the cache of variant “hero”', 'Removed 244 files (84 MB)'],
['Cache purged: by image', 'Marta Alves purged the variants of north-wall.jpg', 'Removed 4 files (260 KB)'],
['Generate all', 'Marta Alves generated all variants of north-wall.jpg', '5 variants generated'],
['Generate all, with a failure', 'Marta Alves generated all variants of north-wall.jpg', '4 generated · 1 failed (Image too large)'],
['Image deleted', 'Marta Alves deleted north-wall.jpg', 'Also removed 4 generated variants (260 KB)']
])] },
{ label: 'States matrix', title: 'States matrix', note: 'Frame: a numbered state above. Copy: covered by the copy tables, with no separate frame. Existing: unchanged behavior of the existing screen.', tables: [T(['Screen', 'Loaded', 'Empty', 'Loading', 'Error', 'Forbidden', 'In progress', 'Confirm', 'Validation', 'Success'], '190px repeat(9, minmax(0,1fr))', [
['1 Variants list', 'Frame 1a', 'Frame 1c', 'Frame 1b', 'Frame 1d', 'Frame 1e', 'Frame 1g, 1j', 'Frame 1h, 1i', '–', 'Copy'],
['2 Add / edit', 'Frame 2a, 2h', '–', '–', 'Frame 2g', 'Copy', 'Frame 2f', 'Frame 2j', 'Frame 2c, 2d, 2e', 'Copy'],
['3 Media library', 'Frame 3a', 'Frame 3e', 'Existing', 'Existing', '–', '–', 'Frame 3f', '–', '–'],
['4 Image detail', 'Frame 4a', 'Frame 4b, 4e, 4f, 4g', 'Existing', 'Frame 4d', '–', 'Frame 4c', '–', '–', 'Copy'],
['5 Cache', 'Frame 5a', 'Frame 5c', 'Frame 5b', 'Frame 5g, 5f', 'Copy', 'Frame 5d', 'Frame 5h, 5i, 5j', 'Frame 5h, 5i', 'Frame 5e'],
['6 Editor picker', 'Frame 6a, 6b', 'Frame 6c', 'Existing', 'Frame 6d, 6e', '–', '–', '–', '–', '–']
])] },
{ label: 'API errors', title: 'Back-office API errors', note: 'Shown as a toast, or inline where a field is named. The first line is the title, the second the text. The public media URL does not use these; see section 7.', tables: [T(['Status', 'Title', 'Text', 'Where it shows'], '70px 200px minmax(0,1fr) 260px', [
['400', 'Check the request', 'A value in the request isn\'t valid. Reload the page and try again.', 'Toast'],
['401', 'Session expired', 'Sign in again to continue.', 'Redirect to sign in, then a toast'],
['403', 'You don\'t have access', 'Only admins can manage image variants.', 'Toast, or the forbidden state on the list'],
['404', 'Not found', 'This variant or image no longer exists. Refresh the page.', 'Toast'],
['409', 'Name already taken', 'A variant named “thumb” already exists. Choose another name.', 'Inline under Name'],
['413', 'Image too large', 'The source image is too large to generate this variant.', 'Row cause in the Variants tab'],
['422', 'Check the fields', 'Width and height must be between 1 and 8000, and one of them is required.', 'Inline under each field'],
['500', 'Something went wrong', 'The server couldn\'t finish. Try again. If it keeps happening, check the server log.', 'Alert or toast with Try again']
], { mono: [0] })] },
{ label: 'Component inventory', title: 'Component inventory', note: 'Existing components are reused as they are. New components are built on Nuxt UI parts and use only existing tokens. Every icon-only button needs an aria-label and a UTooltip.', tables: [T(['Component', 'Status', 'Nuxt UI mapping', 'Notes'], '190px 80px 300px minmax(0,1fr)', [
['Variants table', 'New', 'UTable', 'Cell slots for the status switch and actions. Below 640 px it renders as a list of UCard.'],
['Variant row (settings, mobile)', 'New', 'UCard + USwitch + UDropdownMenu', 'Name, spec line, counts, status switch and menu.'],
['Variant row (image detail)', 'New', 'UBadge + UButton + UTooltip', 'Status badge, meta line, contextual actions, error line. Spinner uses UIcon.'],
['Variant form', 'New', 'UForm, UFormField, UInput, USelect, USlider, USwitch, URadioGroup', 'Fit is a URadioGroup, horizontal, 3 options. Quality hides when the format is PNG.'],
['Slide-over / full page', 'New', 'USlideover (desktop) · routed page (mobile)', 'Close with unsaved changes opens the discard UModal.'],
['Split comparison slider', 'New', 'No match. Custom ImageCompare on a native range input', 'Two stacked images, clip-path on the top one. role="slider", arrow keys 1%, Shift 10%, Home and End. Handle ≥ 44 px on touch.'],
['Stat tile', 'New', 'UCard (default slot)', 'Icon, label, value, sub text. Skeleton uses USkeleton.'],
['Bar list', 'New', 'UProgress per row', 'Row with name, stats and a bar. Value is disk size over the largest variant.'],
['Top-N list', 'New', 'UCard + list rows + UButton', 'Thumbnail, name, count, size, Purge.'],
['Type-to-confirm dialog', 'New', 'UModal + UInput', 'Confirm button disabled until the input equals "purge".'],
['Variant select', 'New', 'USelectMenu', 'Item slot shows name, dimensions, format. Only enabled variants.'],
['Variants badge', 'New', 'UBadge (outline, icon layers)', 'Shown on media cards when count > 0.'],
['Filter', 'New', 'UTabs (variant link) or UButtonGroup', 'All, With variants, Without.'],
['Request reference card', 'New', 'UCard + code block', 'Table of responses and a JSON body.'],
['Alerts, toasts, dialogs, empty states, skeletons', 'Existing', 'UAlert, useToast, UModal, UEmpty pattern, USkeleton', 'Same copy patterns as the Media and API keys screens.']
])] },
{ label: 'Vocabulary and accessibility', title: 'Vocabulary and accessibility', note: 'Use "variant", "generated" and "purge" everywhere. Never "thumbnail preset", "version" or "rendition". Delete removes a variant definition; purge removes only its generated files. Every status is an icon plus text: Generated (circle-check), Not generated (circle-dashed), Generating (loader), Failed (circle-x), Enabled (circle-check), Disabled (circle-off). The comparison slider has a visible focus ring and works from the keyboard. Dialogs trap focus and return it to the opener. Progress is announced with aria-live="polite". Touch targets on mobile are at least 44 px. The only token not already in the system is --rc-on-sand (dark ink on the sand selection color), used for the active nav item in both themes.', tables: [] }
]
}
renderVals() {
const modes = [['system', 'System'], ['light', 'Light'], ['dark', 'Dark']].map(([k, label]) => {
const on = this.state.mode === k
return { label, on, bg: on ? 'var(--ui-primary)' : 'transparent', fg: on ? 'var(--ui-bg)' : 'var(--ui-text-toned)', pick: () => this.setState({ mode: k }) }
})
return { rootRef: this.rootRef, modes, groups: this.groups(), specs: this.specs() }
}
}
</script>
</body>
</html>