fsylvain/RenewCMS
1
1 Fork 0
Code Issues Pull Requests Packages Projects Releases 20 Wiki Activity

chore: 2 big design passes to harmonize and fix stuff

Browse Source
This commit is contained in:
Florian Sylvain committed 2026-10-11 07:45:17 +02:00
1 parent 67b3ff03d0
commit 5e05b606a7
43 files changed
+2167 -4183
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/design/screens/accept-invite.md
+26 -103
View File
@@ -1,114 +1,37 @@
# Accept invite
- **Route:** `/invite/accept?c=CODE`
- **API:** GET /v1/auth/invite?c=CODE (pending) · POST /v1/auth/invite/accept (pending)
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Accept invite" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/invite/accept?c=CODE`. API: GET /v1/auth/invite?c= (pending) · POST /v1/auth/invite/accept (pending).
Opened from the invitation email. The link carries only the code, so the invited email is looked up on load and shown read-only. Username and password follow the Register rules, including PasswordStrengthHint, with no confirm field. On success the person is logged in and sent to /home with a toast. The account is already verified, because the invite went to their email, so it skips the pending and verify screens.
Opened from the invitation email. The link carries only the code, so the invited email is looked up on load and shown read-only. Username and password follow the Register rules, including PasswordStrengthHint. On success the person is logged in and sent to /home with a toast; they are already verified because the invite went to their email.
Neither endpoint exists yet:
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Accept invite". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
- `GET /v1/auth/invite?c=CODE` returns `{ email }`, or 404 or 410.
- `POST /v1/auth/invite/accept` takes `{ code, username, password }`. It returns 200 with the session cookie, 409 for a taken username, or 404 or 410 as above.
## Copy per state (generated from the board source, pass 2)
Registration stays closed to everyone else: [register.md](register.md) "Registration closed" still applies to `/register`. The board does not draw the case of a logged-in person opening the link; it is not specified.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
## States
### Base copy
- Accept your invite
- Choose a username and password to finish setting up your account.
- Accept invite
- Already have an account?
- Log in
### Checking the link
### Accept invite (group "Accept invite", 10 states)
**Trigger:** On load, while the invite is looked up.
Route: `/invite/accept?c=CODE`. API: GET /v1/auth/invite?c= (pending) · POST /v1/auth/invite/accept (pending).
- Full-card spinner: "Checking your invite…"
Opened from the invitation email. The link carries only the code, so the invited email is looked up on load and shown read-only. Username and password follow the Register rules, including PasswordStrengthHint. On success the person is logged in and sent to /home with a toast; they are already verified because the invite went to their email.
### Default
**Trigger:** The code is valid and unused.
- Heading: **Accept your invite**
- Description: "Choose a username and password to finish setting up your account."
- Field `Email`: placeholder "you@example.com"; value "lea.martin@renew.example"; read-only; help "From your invitation."
- Field `Username`: placeholder "e.g. lea"; counter "0 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Password`: password with show/hide; checklist "At least 8 characters" (unmet)
- Submit button: "Accept invite"
- Footer: Already have an account? [Log in]
### Validation errors
**Trigger:** Checked on blur and on submit, using the same rules as Register. Nothing is sent.
- Heading: **Accept your invite**
- Description: "Choose a username and password to finish setting up your account."
- Field `Email`: placeholder "you@example.com"; value "lea.martin@renew.example"; read-only; help "From your invitation."
- Field `Username`: placeholder "e.g. lea"; value "ma"; counter "2 / 20" in error; **error "Use 3 to 20 characters."**
- Field `Password`: value "lime"; password with show/hide; checklist "At least 8 characters" (err)
- Submit button: "Accept invite"
- Footer: Already have an account? [Log in]
### Filled, valid
**Trigger:** Every rule is met and the checklist item turns green.
- Heading: **Accept your invite**
- Description: "Choose a username and password to finish setting up your account."
- Field `Email`: placeholder "you@example.com"; value "lea.martin@renew.example"; read-only; help "From your invitation."
- Field `Username`: placeholder "e.g. lea"; value "lea"; counter "3 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Password`: value "limewash2026"; password with show/hide; password shown; checklist "At least 8 characters" (met)
- Submit button: "Accept invite"
- Footer: Already have an account? [Log in]
### Submitting
**Trigger:** Fields and button are disabled.
- Heading: **Accept your invite**
- Description: "Choose a username and password to finish setting up your account."
- Field `Email`: placeholder "you@example.com"; value "lea.martin@renew.example"; read-only; help "From your invitation."
- Field `Username`: placeholder "e.g. lea"; value "lea"; counter "3 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Submit button: "Creating account…", loading
- Footer: Already have an account? [Log in]
### Username taken (409)
**Trigger:** Another user has that username. The value is kept and the field gets focus.
- Heading: **Accept your invite**
- Description: "Choose a username and password to finish setting up your account."
- Field `Email`: placeholder "you@example.com"; value "lea.martin@renew.example"; read-only; help "From your invitation."
- Field `Username`: placeholder "e.g. lea"; value "marta"; counter "5 / 20"; focused; **error "That username is taken. Try another."**
- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Submit button: "Accept invite"
- Footer: Already have an account? [Log in]
### Invalid or used link (404)
**Trigger:** The code is wrong, was already accepted, or is missing from the URL. No form is shown.
- ResultPanel (error, link-2-off): **This invite link doesn't work**; text "It may be incomplete, or it may already have been used. If you already set up your account, log in instead."; note "Open the link from your email again, or copy the full address into your browser."; actions "Go to log in" (primary)
### Expired link (410)
**Trigger:** The invite is older than 3 days.
- ResultPanel (error, clock): **This invite has expired**; text "Invites work once, for 3 days. Ask the person who invited you to send a new one."; actions "Go to log in" (secondary)
### Server error
**Trigger:** A 500 or no response. The values are kept.
- Alert (error, circle-x): **Couldn't create the account** "Something went wrong on the server. Try again in a moment."
- Heading: **Accept your invite**
- Description: "Choose a username and password to finish setting up your account."
- Field `Email`: placeholder "you@example.com"; value "lea.martin@renew.example"; read-only; help "From your invitation."
- Field `Username`: placeholder "e.g. lea"; value "lea"; counter "3 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Submit button: "Accept invite"
- Footer: Already have an account? [Log in]
### Success
**Trigger:** 200 sets the session cookie → /home after 800 ms, with a toast. No verification step.
- ResultPanel (success, circle-check): **Your account is ready**; text "Taking you to your dashboard…"
- Toast (circle-check): **Welcome to RenewCMS** "You're logged in as lea."
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Checking the link | On load, while the invite is looked up. | "Checking your invite…" |
| 2 | Default | The code is valid and unused. | |
| 3 | Validation errors | Checked on blur and on submit, using the same rules as Register. Nothing is sent. | "Use 3 to 20 characters." |
| 4 | Filled, valid | Every rule is met and the checklist item turns green. | |
| 5 | Submitting | Fields and button are disabled. | "Creating account…" |
| 6 | Username taken (409) | Another user has that username. The value is kept and the field gets focus. | "That username is taken. Try another." |
| 7 | Invalid or used link (404) | The code is wrong, was already accepted, or is missing from the URL. No form is shown. | "This invite link doesn't work" / "It may be incomplete, or it may already have been used. If you already set up your account, log in instead." / "Open the link from your email again, or copy the full address into your browser." / "Go to log in" |
| 8 | Expired link (410) | The invite is older than 3 days. | "This invite has expired" / "Invites work once, for 3 days. Ask the person who invited you to send a new one." / "Go to log in" |
| 9 | Server error | A 500 or no response. The values are kept. | "Couldn't create the account" / "Something went wrong on the server. Try again in a moment." |
| 10 | Success | 200 sets the session cookie → /home after 800 ms, with a toast. No verification step. | "Your account is ready" / "Taking you to your dashboard…" / "Welcome to RenewCMS" / "You're logged in as lea." |
docs/design/screens/activity.md
+71 -159
View File
@@ -1,183 +1,95 @@
# Activity
- **Route:** `/activity`
- **API:** GET /v1/activity · GET /v1/activity/summary · GET /v1/activity/export (see "API contract" below)
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Activity" (the same board also has the groups "Activity details" and "My activity"), drawn by `source/AppFrame.dc.html` with the page from `source/ActivityFrame.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle). The frame is `source/ActivityFrame.dc.html`; its copy, component mapping and API tables are `source/activity-spec.js`.
Route: `/activity`, `Row click`. API: GET /v1/activity · GET /v1/activity/summary · GET /v1/activity?outcome=failed · ?type=security · GET /v1/activity/export (shipped: CSV only, synchronous streamed download, owner and admin only, 403 otherwise). Same filters as the list: q, actor, category, outcome, security, range, from, to. JSON is proposed. · Uses the item from GET /v1/activity · GET /v1/activity (server scoped to the user).
The audit log of the back-office: who did what, and when, across articles, media, users and invites, API keys, authentication and system tasks. It is for non-technical owners, so every row reads as a sentence, not a log line. Events are append-only: nothing in the app edits or deletes them. Only the retention period removes them (Settings, "Retention").
New route in the sidebar after Users. Owner and admin see everything; regular users get "My activity". Copy, component mapping and API calls are at the bottom of this board.
Other groups of the same board:
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Activity", "Activity: filter cards", "Activity: export", "Activity details", "My activity". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
| Group | What it draws | Written up in |
|---|---|---|
| Details slide-over | The slide-over and its bottom-sheet variant, six events | this file, "Details slide-over" |
| My activity | The same screen for a user who is not owner or admin | this file, "My activity" |
| Home section | The Recent activity section on Home | `screens/home.md`, "Recent activity" |
| Settings retention | The Retention card, last on Settings | `screens/settings.md`, "Activity retention" |
## Copy per state (generated from the board source, pass 2)
## Roles
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.
Owner and admin see every event, the summary strip, the Person filter and Export. Any other role sees only its own events: the title becomes "My activity", the strip, the Person filter and Export are hidden, and the server scopes the list to that user (asking for another actor answers 403).
### Activity, owner and admin (group "Activity", 9 states)
Today the product has only `owner` and `admin` (see `screens/users.md`, "Roles"), so "My activity" and the scoped answer cannot be reached by a real account yet. They are specified and tested now so a future role needs no rework. The board's sample "Editor" role and the nav it draws for a regular user (Home, Articles, Media, Activity) are illustrative.
Route: `/activity`. API: GET /v1/activity · GET /v1/activity/summary.
## Sidebar
New route in the sidebar after Users. Owner and admin see everything; regular users get "My activity". Copy, component mapping and API calls are at the bottom of this board.
"Activity" (icon `history`) sits between Users and Integration for owner and admin: Home, Articles, Media, Users, Activity, Integration, Settings. The board draws the order that way. It is visible to every verified user. The mobile drawer gets the same item.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default, large dataset | Newest first, day separators, a security row, 1,284 events across 52 pages. Hover on the first row shows the exact time. | |
| 2 | Loading | Skeleton strip and table while both requests are in flight. | |
| 3 | Zero-value summary strip | Quiet period: Failed and Security show a calm 0. | |
| 4 | Filtered, card applied | Failed actions card clicked, chips and Clear all. Mobile shows the count on Filters. | |
| 5 | Mobile filters sheet | Filters open as a bottom sheet (desktop uses the inline bar above). | "Custom" |
| 6 | Empty, no activity yet | New site. Export is disabled. | |
| 7 | Empty, filters match nothing | Offers Clear filters. | "Media" / "Failed" |
| 8 | Error with retry | Request failed. The summary strip still shows if its call succeeded. | |
| 9 | Forbidden (403) | API returned 403 for this role or filter. | |
## The page
### Activity: failed-action cards as toggles (group "Activity: filter cards", 10 states)
Title "Activity" (regular users: "My activity"). Subtitle "Who did what, and when, across your site." (regular users: "Everything you've done on this site."). Page padding 24 px desktop, 16 px mobile; the sidebar and top bar are the existing DashboardShell.
Route: `/activity`. API: GET /v1/activity?outcome=failed · ?type=security.
1. **Header action** (owner and admin): outline `UButton` with icon `download`, "Export CSV". While the file is prepared: "Preparing file…" and disabled. Success toast "Export started. Your file will download shortly." Error toast "Couldn't export activity. Try again." Disabled in "Empty, no activity yet".
2. **Summary strip** (owner and admin): four `UCard`, each a `button`. Labels: "Total actions", "Active people", "Failed actions", "Security events". Each shows the number, a sub-line and a seven-bar sparkline (seven `div` bars, no chart library, oldest left).
- Total: "12% vs previous 7 days" with `trending-up` / `trending-down` (the comparison is against the equal-length period just before the selected range). Click clears the filters.
- Active people: "7 people, 2 API keys". Click does nothing (no equivalent filter).
- Failed: "0.5% of all actions". Emphasis with `--rc-error-soft` and `--ui-error`, icon `circle-x`. Click applies Outcome = Failed.
- Security: "5 failed logins". Emphasis with `--rc-warning-soft` and `--ui-warning`, icon `shield-alert`. Click applies the security filter (auth, role changes, API key create and revoke).
- Zero: Failed shows "0" with "Nothing failed" and `circle-check`; Security shows "0" with "Nothing to flag" and `circle-check`; both drop the emphasis fill. No data at all: every card reads "0" with the sub-line "No data yet" (Failed and Security keep their calm lines).
- The strip follows the date range filter. Mobile: a 2×2 grid.
3. **Filter bar**: `UInput` (icon `search`, clearable, "Search activity"), Person `USelectMenu` (grouped: users, API keys, "System"; "All people"), Category `USelectMenu` ("All categories": Articles, Media, Users and invites, API keys, Authentication, System), Outcome button group (All / Succeeded / Failed; `soft` is the selected one), date presets (Today / 7 days / 30 days / Custom; Custom opens a date-range popover). Mobile: the bar collapses to a search field and a "Filters" button with a count badge; the controls move to a bottom sheet.
4. **Active filter chips**: `UBadge` (subtle) with a trailing ghost `x` button: "Search: spring", "Person: Marta Alves", "Category: Authentication", "Outcome: Failed", "Dates: 1 – 30 Sep 2026", then a `link` button "Clear all". The default date range (7 days) is not a chip.
5. **Timeline table**: newest first, grouped by day with full-width separator rows ("Today", "Yesterday", "3 Oct 2026"). Columns: When (relative within the day, clock time before; the full time is the cell's `title`), Actor (`UAvatar` with initials, a key icon for API keys or a cog for System, plus the name; badges "API key" / "System"; a signed-out actor reads "Not signed in"), Action (category icon and the sentence with the target name in semibold; a `shield` marker on security rows), Target (a link when it still exists; struck through with a "Deleted" badge when it does not), Outcome (`UBadge` "Succeeded" / "Failed"). Row click and Enter open the details.
6. **Pagination**: "Showing 1–25 of 1,284", `UPagination`, "Rows per page" select (25, 50, 100). Mobile: "Page 1 of 52" with previous and next.
7. **Mobile list**: below `md` the table is a stacked list of `UCard` rows (actor, sentence, time, outcome, "Target deleted" when relevant), 44 px touch targets.
The Failed actions and Security events cards are toggle buttons with aria-pressed. Pressing one applies its filter and shows it in the chip row; pressing the active card again removes it. Three controls always agree: the card, the chip with its × and "Clear all". Removing the filter with any of them returns the card to its default look, removes the chip and sets the Outcome segment back to All. The active card uses --rc-sand with --rc-on-sand; the hint line changes from "Filtering. Click to clear" to "Click to clear this filter" on hover.
Sentences are composed in the SPA from a stable `action` code and the event params, in the user's language (English and French), never stored as text. The target name and the typed values in a diff stay as the user wrote them.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default, no filter | Both cards unpressed, no chips. | |
| 2 | Card hover | Pointer over Failed actions. Background --ui-bg-elevated, hint "Click to filter the list". | |
| 3 | Card focus-visible | Keyboard focus on the card: 2 px --ui-primary outline, 2 px offset. Enter or Space toggles. | |
| 4 | Failed card active | aria-pressed="true". Outcome chip, Outcome segment on Failed, list reduced to failed events. | |
| 5 | Active card hover | Hint reads "Click to clear this filter" with an × icon. | |
| 6 | Security card active | Chip "Type: Security events". The Outcome segment stays on All. | |
| 7 | Chip × hover | Dismissing the chip also unpresses the card. | |
| 8 | Clear all hover | Clears the chips, the card and every other filter together. | |
| 9 | Clear all focus-visible | Keyboard focus on Clear all. | |
| 10 | Card plus other filters | Failed card with Category and Dates. Unpressing the card removes only its chip. | "Authentication" / "30 days" |
## States
### Activity: export menu and dialogs (group "Activity: export", 15 states)
### Default, large dataset
**Trigger:** Both requests resolved with 1,284 events over 52 pages. Newest first, day separators, a security row. Hover on the first row shows its exact time.
Route: `/activity`. API: GET /v1/activity/export (shipped: CSV only, synchronous streamed download, owner and admin only, 403 otherwise). Same filters as the list: q, actor, category, outcome, security, range, from, to. JSON is proposed..
### Loading
**Trigger:** Both requests in flight. Skeleton strip and table rows after 150 ms.
Export is one menu button with two items. Export current view: the same endpoint with the active filters, across all pages. Export all activity: the same endpoint with no filters and an optional date range (from, to), default all time. There is no server job, progress or later notification. On mobile the menu and dialog are bottom sheets. Dialogs: secondary left, primary right.
### Zero-value summary strip
**Trigger:** A quiet period. Failed and Security show a calm 0.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Menu open | Export pressed. Both items available. Owners and admins only; other roles never see the button. | |
| 2 | Menu, item hover | Pointer over Export all activity. | |
| 3 | Menu, filtered view | Failed card applied. The first item states the matching count. | |
| 4 | Menu, nothing to export | Filters match nothing. Export current view is disabled with the reason. | "Media" / "Failed" |
| 5 | Menu, no permission | The role was lowered while the page was open. Item disabled with the reason; the API answers 403. | |
| 6 | Export button focus-visible | 2 px --ui-primary outline, 2 px offset. Enter or ArrowDown opens the menu; Esc closes it. | |
| 7 | Dialog: configure, CSV only | Export all activity…. CSV is the only format. Date range defaults to All time. | |
| 8 | Dialog: configure, CSV or JSON (proposed) | Needs the JSON backend feature. Format control appears only when it ships. | |
| 9 | Dialog: preparing download | Request in flight. Indeterminate bar, no percentage: the server streams one file and reports no progress. | |
| 10 | Dialog: download started | The browser received the file. Only Close is offered. | |
| 11 | Dialog: failed | 500 or network failure. Retry restarts the export. | |
| 12 | Dialog: nothing to export | The chosen date range has no events. Only Close. | |
| 13 | Dialog: not allowed (403) | Owner or admin only. | |
| 14 | Toast: current view | The response started streaming and the browser saved the file. | "Download started" / "activity-2026-10-06.csv is downloading." |
| 15 | Toast: export all | Dialog closed after the download started. | "Download started" / "activity-all-2026-10-06.csv is downloading." |
### Filtered, card applied
**Trigger:** The Failed actions card was clicked. Chips plus "Clear all"; mobile shows the count on Filters. Six results.
### Activity: details slide-over and bottom sheet (group "Activity details", 6 states)
### Mobile filters sheet
**Trigger:** Filters open as a bottom sheet on mobile. The desktop frame keeps the inline bar. Sheet: title "Filters", Person (owner and admin), Category, Outcome, Dates (two date fields when Custom), footer "Clear all" and "Show 23 results".
Route: `Row click`. API: Uses the item from GET /v1/activity.
### Empty, no activity yet
**Trigger:** A new site. `UEmpty` with icon `history`, title "No activity yet", description "Actions on articles, media, users and API keys will appear here." Export disabled.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Edit with a diff | Title change and "Body edited (+312 characters)". No body text. | |
| 2 | Settings diff, long text | Long values clamp to two lines with Show more. | |
| 3 | Failed action, very long target title | Failure reason shown, target title wraps. | |
| 4 | Deleted target, no diff | Struck-through target with a Deleted badge. | |
| 5 | System-initiated, no human actor | Scheduler with a System badge. IP and browser not applicable. | |
| 6 | Security event, failed login | Actor not signed in. Restrained shield marker. | |
### Empty, filters match nothing
**Trigger:** Filters with zero results. Title "No activity matches these filters", description "Try a different search or a wider date range.", action "Clear filters".
### My activity, regular user (group "My activity", 3 states)
### Error with retry
**Trigger:** The list request failed (500 or network). `UEmpty` in the table area: "Couldn't load activity", "Check your connection and try again.", action "Try again". The strip still shows if its own call succeeded.
Route: `/activity`. API: GET /v1/activity (server scoped to the user).
### Forbidden (403)
**Trigger:** The API answered 403 for this role or filter. "You can't view this activity.", "Your role doesn't include this page. Ask an owner or admin if you need access.", action "Back to home". The 401 is global.
## Details slide-over
`USlideover`, right side on desktop (about 440 px wide), bottom sheet on mobile. Opens from a row (click or Enter), closes with Escape, the close button or the scrim; focus returns to the row. Title "Activity details".
Body, in `UCard` sections:
- The full sentence, with the target name in semibold.
- When: the user's local time, then a muted "UTC" line.
- Actor (with the same badges), Source ("Web app", "API key", "System task"), IP address, Browser. For a system event, IP address and Browser read "Not applicable".
- Target: name (struck through with a "Deleted" badge, plus "This item was deleted. Its name is kept for reference." when it no longer exists), and a link when it exists.
- Why it failed (failed events only): the plain-language reason from the API, never a stack trace.
- Changes (edits only): rows of field, Before, After. Values longer than two lines clamp with "Show more" / "Show less". A body edit is a single row "Body edited (+312 characters)" and never shows text.
- Footer: "Previous event" and "Next event" buttons and "Event 2 of 1,284". They move through the current filtered list, across page boundaries.
### Edit with a diff
**Trigger:** A title change and a body edit. Title Before and After, then "Body edited (+312 characters)".
### Settings diff, long text
**Trigger:** Long values clamp to two lines with "Show more".
### Failed action, very long target title
**Trigger:** A failed publish. The reason is shown and the long target title wraps.
### Deleted target, no diff
**Trigger:** A deleted image. Struck-through target, "Deleted" badge, no Changes section.
### System-initiated, no human actor
**Trigger:** A scheduled task. "System" badge, source "System task", IP and Browser "Not applicable".
### Security event, failed login
**Trigger:** The actor was not signed in. "Not signed in", a restrained `shield` marker, the reason, the IP and browser.
## My activity
The same screen for a role that is not owner or admin. No summary strip, no Person filter, no Export. The list is the user's own events (server scoped).
### Default
**Trigger:** The user has events. Title "My activity".
### Empty
**Trigger:** No events yet: "No activity yet", "Your actions will appear here once you start working on the site."
### Details
**Trigger:** The slide-over on one of the user's own events.
## API contract
401 and 403 on every route follow `states.md`, "HTTP status to copy". The board's table in `source/activity-spec.js` is the source; this section fixes the parts it leaves open.
**`GET /v1/activity`**
- Query: `q`, `actor` (`user:ID`, `key:ID`, `system`), `category` (`articles`, `media`, `users`, `api_keys`, `auth`, `system`), `outcome` (`all`, `success`, `failed`), `security` (`true`), `range` (`today`, `7d`, `30d`, `custom`), `from`, `to` (ISO dates, with `custom`), `page` (from 1), `size` (25, 50 or 100; default 25). Sorted by `created_at` descending, then `id` descending. Invalid values answer 400 "The request cannot be processed due to a mismatch in the format of the body."
- `security=true` is what the Security card applies; it is a flag on the event, not a category.
- Response: `{ items, total, page, size }`. An item:
```json
{
"id": 4821,
"created_at": "2026-10-06T10:42:18Z",
"action": "article.publish",
"category": "articles",
"actor": { "type": "user", "id": 3, "name": "Marta Alves" },
"target": { "type": "article", "id": "8", "name": "Spring release", "exists": true },
"outcome": "success",
"failure_reason": null,
"security": false,
"source": "web",
"ip": "203.0.113.12",
"user_agent": "Chrome 129 on Windows",
"changes": [{ "field": "online", "kind": "text", "before": "false", "after": "true" }]
}
```
- `actor.type` is `user`, `api_key`, `system` or `anonymous` (a failed login). `actor.name` is a snapshot taken when the event was recorded, so a renamed or deleted user still reads correctly. `target.name` is a snapshot too; `target.exists` is resolved when the list is read.
- `action` is a stable dotted code. The SPA owns the wording, in English and French. `params` holds extra values a sentence needs (for example `{ "merged": 3, "articles_updated": 5 }` on a media purge); they are never secrets.
- `changes[].kind` is `text` or `body`. A `body` change has `delta` (a signed number of characters) and no `before` or `after`. Only allowlisted fields ever appear in `changes`, and never a password, hash, API key, token or article body.
- `source` is `web`, `api_key` or `system`. `ip` and `user_agent` are `null` for `system`.
- A caller who is not owner or admin is scoped to its own events; `actor` other than itself answers 403.
**`GET /v1/activity/summary`** (owner and admin; 403 otherwise)
Same `range`, `from`, `to`. Response: `total`, `previous_total`, `active_people: { users, api_keys }`, `failed`, `security`, and `series` with seven daily counts for `total`, `active`, `failed` and `security`. The previous period is the equal-length period immediately before the range.
**`GET /v1/activity/export`** (owner and admin; 403 otherwise)
The same filters without `page` or `size`. Streams `text/csv; charset=utf-8` with `Content-Disposition: attachment`. Columns: `when` (RFC3339 UTC), `actor`, `action` (the code), `target`, `outcome`, `source`, `ip`. No changes, no user agent, no secrets. Cells that start with `=`, `+`, `-` or `@` are prefixed with a quote so a spreadsheet does not evaluate them.
**`GET /v1/settings` and `PATCH /v1/settings`**: see `screens/settings.md`, "Activity retention".
These routes are session only: with an API key they answer 403 "This action needs a real session." (A key never reads the audit trail.)
## What is recorded
Every row of the board is a sample. The real catalogue is the set of actions that exist in the product, in these categories:
| Category | Events |
|---|---|
| `articles` | create, edit (title, publish state, body size delta), publish, unpublish, delete |
| `media` | upload, rename, delete, merge, purge (manual; the scheduled run is a `system` event) |
| `users` | register, verify account, update profile (display name), invite create, cancel, renew, accept |
| `api_keys` | create, revoke |
| `auth` | login succeeded, login failed (security), logout, password reset requested (security), password reset completed (security) |
| `system` | update checked, update downloaded, restart requested, scheduled media purge, activity retention changed, activity cleanup |
Not drawn as real events: the "Editor" role and role changes, a "Site description" or "Comments" setting, "Ran the nightly backup" (backups are a step of the update job, not a schedule), "Removed 3 expired invites" and an administrator resetting another user's password. They stay in the board as sample data and are only recorded if the matching feature exists.
Read requests are not recorded (no "article viewed"), and neither are public API reads.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | No summary strip, no actor filter, no Export. Title becomes My activity. | |
| 2 | Empty | The user has not done anything yet. | |
| 3 | Details | Same slide-over, own event. | |
docs/design/screens/articles.md
+55 -106
View File
@@ -1,122 +1,71 @@
# Articles
- **Route:** `/article`
- **API:** GET /v1/article/ · PATCH …/publish · PATCH …/unpublish · DELETE /v1/article/{id}
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Articles" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/article`, `/articles?page=2&size=50`. API: GET /v1/article/ · PATCH …/publish · PATCH …/unpublish · DELETE /v1/article/{id} · GET /v1/article/?page=&size=&q=&status= (proposed: needs backend page, size, total in the response).
Rows update when the server responds, not optimistically. Search, tab and sort are stored in the query string.
## States
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Articles", "Articles: pagination". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** The list loaded, sorted by last updated.
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.
- Breadcrumbs: Articles (mobile title "Articles")
### Fixed copy in the frame
- Articles
- Everything you've written, online and in draft.
- New article
- Retry
- Title
- Status
- Created
- Updated
- Online
- Draft
- Edit
- Copy API URL
- Delete…
- Previous
- Next
### Row menu open
### Articles (group "Articles", 14 states)
**Trigger:** The ellipsis button, or Enter on the focused menu button.
Route: `/article`. API: GET /v1/article/ · PATCH …/publish · PATCH …/unpublish · DELETE /v1/article/{id}.
- Breadcrumbs: Articles (mobile title "Articles")
- Row "Winter checklist for timber windows": menu true, online false, updated "5 days ago"
Rows update when the server responds, not optimistically. Search, tab and sort are stored in the query string.
### Loading
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | The list loaded, sorted by last updated. | |
| 2 | Row menu open | The ellipsis button, or Enter on the focused menu button. | |
| 3 | Loading | The first load, or a retry. | |
| 4 | Empty | The list is empty. | "No articles yet" / "Write your first one. It stays a draft until you publish it." / "New article" |
| 5 | No results | Search matched nothing. The tab counts still show the full list. | "No articles match "tiles"" / "Check the spelling, or search for a shorter part of the title." / "Clear search" |
| 6 | No drafts | Drafts tab with nothing in it. The "Online" tab has an equivalent "Nothing is online yet" state. | "Everything you've written is online." / "New article" |
| 7 | Action in progress | Publish chosen from the row menu. That row is disabled. | "Publishing…" |
| 8 | Published | 200: the row updates in place and a toast confirms. | "Just now" / "Article published" / ""Winter checklist for timber windows" is now online." |
| 9 | Action failed | A 500 or network error. The row stays as it was, and the toast stays until retried or dismissed. | "Couldn't unpublish" / "The server didn't respond. Nothing changed." / "Retry" |
| 10 | Row vanished (404) | Any row action gets a 404. | "That article no longer exists" / "It was deleted somewhere else, so we removed it from the list." |
| 11 | Delete: confirm | Delete… from the row menu. | |
| 12 | Delete: in progress | DELETE in flight. The dialog can't be dismissed. | |
| 13 | Delete: failed | 500, a partial failure where the article is kept. The error shows inside the dialog. | "Couldn't delete the article, so it's still there. Try again in a moment." |
| 14 | Deleted | 204: the row is removed and focus moves to the next row. This is also where a delete from the editor ends up. | "Article deleted" / ""Winter checklist for timber windows" and its images are gone." |
**Trigger:** The first load, or a retry.
### Articles: pagination (group "Articles: pagination", 11 states)
- Breadcrumbs: Articles (mobile title "Articles")
- List: loading skeleton
Route: `/articles?page=2&size=50`. API: GET /v1/article/?page=&size=&q=&status= (proposed: needs backend page, size, total in the response).
### Empty
Page and page size live in the URL as page and size. Defaults (page 1, size 25) are omitted. Allowed sizes 5, 25, 50, 100. Search, tab or sort changes reset to page 1. Rows equal the page size; the frames draw at most 10 rows. The paginator hides when everything fits on one page; the summary stays. Mobile shows Previous, "Page N of M" and Next. Keyboard: Tab reaches page size, first, previous, each page, next, last; Enter or Space activates; the current page has aria-current="page"; ArrowDown opens the page-size list, Enter selects, Esc closes.
**Trigger:** The list is empty.
- Breadcrumbs: Articles (mobile title "Articles")
- Tab counts (All, Online, Drafts): 0, 0, 0
- EmptyState (file-text): **No articles yet** "Write your first one. It stays a draft until you publish it.", action "New article" (primary)
### No results
**Trigger:** Search matched nothing. The tab counts still show the full list.
- Breadcrumbs: Articles (mobile title "Articles")
- Search query: "tiles"
- EmptyState (search): **No articles match "tiles"** "Check the spelling, or search for a shorter part of the title.", action "Clear search"
### No drafts
**Trigger:** Drafts tab with nothing in it. The "Online" tab has an equivalent "Nothing is online yet" state.
- Breadcrumbs: Articles (mobile title "Articles")
- Active tab index: 2 (0 All, 1 Online, 2 Drafts)
- Tab counts (All, Online, Drafts): 4, 4, 0
- EmptyState (pencil-line): **No drafts** "Everything you've written is online.", action "New article"
### Action in progress
**Trigger:** Publish chosen from the row menu. That row is disabled.
- Breadcrumbs: Articles (mobile title "Articles")
- Row "Winter checklist for timber windows": busy "Publishing…", online false, updated "5 days ago"
### Published
**Trigger:** 200: the row updates in place and a toast confirms.
- Breadcrumbs: Articles (mobile title "Articles")
- Toast (success, circle-check): **Article published** ""Winter checklist for timber windows" is now online."
### Action failed
**Trigger:** A 500 or network error. The row stays as it was, and the toast stays until retried or dismissed.
- Breadcrumbs: Articles (mobile title "Articles")
- Toast (error, circle-x): **Couldn't unpublish** "The server didn't respond. Nothing changed." with action "Retry"
### Row vanished (404)
**Trigger:** Any row action gets a 404.
- Breadcrumbs: Articles (mobile title "Articles")
- Toast (info, info): **That article no longer exists** "It was deleted somewhere else, so we removed it from the list."
- Tab counts (All, Online, Drafts): 5, 4, 1
### Delete: confirm
**Trigger:** Delete… from the row menu.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **Delete this article?**
- text ""Winter checklist for timber windows" will be deleted. Its images stay in your library. This can't be undone."
- cancel "Cancel"
- confirm "Delete article" (danger)
### Delete: in progress
**Trigger:** DELETE in flight. The dialog can't be dismissed.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **Delete this article?**
- text ""Winter checklist for timber windows" will be deleted. Its images stay in your library. This can't be undone."
- cancel "Cancel"
- confirm "Deleting…" (danger), loading, not dismissible
### Delete: failed
**Trigger:** 500, a partial failure where the article is kept. The error shows inside the dialog.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **Delete this article?**
- text ""Winter checklist for timber windows" will be deleted. Its images stay in your library. This can't be undone."
- Alert: "Couldn't delete the article, so it's still there. Try again in a moment."
- cancel "Cancel"
- confirm "Delete article" (danger)
### Deleted
**Trigger:** 204: the row is removed and focus moves to the next row. This is also where a delete from the editor ends up.
- Breadcrumbs: Articles (mobile title "Articles")
- Toast (success, circle-check): **Article deleted** ""Winter checklist for timber windows" is gone."
- Tab counts (All, Online, Drafts): 5, 4, 1
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | First page | /articles. Previous and First are disabled. Summary "Showing 1–25 of 312". | |
| 2 | Middle page | /articles?page=7. Current page uses --rc-sand and --rc-on-sand; ellipses mark skipped ranges. | |
| 3 | Last page | /articles?page=13. Next and Last are disabled. Summary "Showing 301–312 of 312". | |
| 4 | Single page | Total fits in one page. Paginator hidden; summary "Showing 1–6 of 6" and the page-size select stay. | |
| 5 | Loading next page | Next was pressed. Skeleton rows keep the table height, controls are disabled, summary reads "Loading page 7…". | |
| 6 | Error loading a page | 500 or network failure on page change. Previous rows stay; Retry sits in the notice. | "Couldn't load page 7. Showing page 6." |
| 7 | Page out of range | /articles?page=99 is replaced with ?page=13 and this notice is shown. | "That page doesn't exist. Showing the last page." |
| 8 | Search resets to page 1 | Searching "plaster" from page 7 goes to /articles?q=plaster (page omitted). Same for tab, sort and size changes. | |
| 9 | Empty after search | Zero results. Paginator and summary are hidden. | "No articles match "tiles"" / "Check the spelling, or search for a shorter part of the title." / "Clear search" |
| 10 | Page size menu | The select opens upward. 5, 25, 50 or 100; the chosen size is saved as size and the page resets to 1. | |
| 11 | Focus-visible | Keyboard focus on Next: 2 px --ui-primary outline, 2 px offset. Same ring on every paginator control. | |
docs/design/screens/boot.md
+17 -9
View File
@@ -1,16 +1,24 @@
# App boot
# Boot
- **Route:** `any route, first load`
- **API:** GET /v1/auth/me (pending)
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Boot" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `any route, first load`. API: GET /v1/auth/me (pending).
While the session is checked, the shell renders with skeletons, never a spinner. The possible outcomes are: 200 with a verified user, which renders the route; 200 with an unverified user, which goes to /register/pending; and 401, which goes to /login?redirect=<path>. Public routes skip this check.
## States
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Boot". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Checking session
## Copy per state (generated from the board source, pass 2)
**Trigger:** The first paint on any back-office URL, and usually visible for well under a second.
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.
- Breadcrumbs: Home (mobile title "Home")
- boot: true
### Fixed copy in the frame
- API pending · GET /v1/auth/me
### App boot (group "Boot", 1 states)
Route: `any route, first load`. API: GET /v1/auth/me (pending).
While the session is checked, the shell renders with skeletons, never a spinner. The possible outcomes are: 200 with a verified user, which renders the route; 200 with an unverified user, which goes to /register/pending; and 401, which goes to /login?redirect=<path>. Public routes skip this check.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Checking session | The first paint on any back-office URL, and usually visible for well under a second. | |
docs/design/screens/editor.md
+93 -214
View File
@@ -1,219 +1,98 @@
# Editor
- **Route:** `/article/:id/edit`
- **API:** GET /v1/article/{id} · PATCH /v1/article/{id} · PATCH …/publish|unpublish · POST …/image · DELETE
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Editor" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/article/:id/edit`. API: GET /v1/article/{id} · PATCH /v1/article/{id} · PATCH …/publish|unpublish · POST …/image · DELETE.
On mobile, Save and Publish sit in a sticky bottom bar and the details panel opens as a slideover. A session expiry mid-edit keeps the draft in sessionStorage and goes to /login?redirect=/article/12/edit. After logging in, the editor restores the draft and shows "Unsaved changes".
## States
### Loading
**Trigger:** GET in flight. Skeletons for the title, content and details.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "saved", loading true
- Mobile: leading arrow-left button, trailing ellipsis
### Saved
**Trigger:** Just opened or just saved. Save is disabled.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "saved"
- Mobile: leading arrow-left button, trailing ellipsis
### Unsaved changes
**Trigger:** Any edit. Publish becomes "Save and publish". Leaving asks for confirmation.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Saving
**Trigger:** Save, or Ctrl/⌘ S.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "saving"
- Mobile: leading arrow-left button, trailing ellipsis
### Save failed
**Trigger:** 500 or network failure. The changes are kept and Retry resends them.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "error"
- Mobile: leading arrow-left button, trailing ellipsis
### Near the limit
**Trigger:** 90% of 10 000 HTML characters.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "dirty", len 9240
- Mobile: leading arrow-left button, trailing ellipsis
### Too long
**Trigger:** Over 10 000. Save and Publish are disabled until it's shorter.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "dirty", len 10214
- Mobile: leading arrow-left button, trailing ellipsis
### Preview
**Trigger:** The Preview switch. Shows the title and body in the content scale, the way a public site might.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "saved", preview true
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: choose
**Trigger:** The image button in the toolbar, or a file dropped on the editor.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Add an image**
- upload state: state "idle"
- cancel "Cancel"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: crop and resize
**Trigger:** A JPEG, PNG or WEBP passed the checks, and nothing is sent yet. The crop starts as the whole image and the width defaults to 1600 px. SVGs skip this step.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Crop and resize** "north-wall.jpg · 3.9 MB"
- crop: ratio "Original", width "1600 px"
- cancel "Choose another file"
- confirm "Upload image"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: crop to a ratio
**Trigger:** 16:9 chosen. The frame keeps the ratio while it's dragged or resized. Arrow keys move it; Shift and arrow keys resize it.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Crop and resize** "north-wall.jpg · 3.9 MB"
- crop: ratio "16:9", width "1600 px"
- cancel "Choose another file"
- confirm "Upload image"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: crop narrower than the width
**Trigger:** The crop is smaller than the chosen width, so it keeps its own size.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Crop and resize** "north-wall.jpg · 3.9 MB"
- crop: ratio "1:1", width "1600 px"
- note: "The crop is 640 px wide, so it's uploaded at that size. Enlarging it would make it blurry."
- cancel "Choose another file"
- confirm "Upload image"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: in progress
**Trigger:** Upload image was pressed. The cropped, resized file is uploading. Closing the dialog cancels the upload.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Add an image**
- upload state: state "uploading" ("Uploading 180 of 420 KB")
- cancel "Cancel upload"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: rejected
**Trigger:** Checked in the browser, so nothing is sent.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Add an image**
- upload state: state "rejected"
- cancel "Cancel"
- confirm "Choose another file"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Upload: inserted
**Trigger:** 201: the image goes in at the cursor, and the article now has unsaved changes.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Toast (success, circle-check): **Image added** "Save to keep it in the article."
- Editor: status "draft", save "dirty", image true
- Mobile: leading arrow-left button, trailing ellipsis
### Publishing
**Trigger:** "Save and publish": the PATCH body, then the publish request.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "saving", pending "Saving and publishing…"
- Mobile: leading arrow-left button, trailing ellipsis
### Published
**Trigger:** 200: the badge flips, Unpublish is offered and a toast confirms.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Toast (success, circle-check): **Article published** ""How we price a bathroom renovation" is now online."
- Editor: status "online", save "saved"
- Mobile: leading arrow-left button, trailing ellipsis
### Unpublishing
**Trigger:** Unpublish doesn't save pending edits.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "online", save "saved", pending "Unpublishing…"
- Mobile: leading arrow-left button, trailing ellipsis
### Delete: confirm
**Trigger:** Delete… from the overflow menu. After a 204, it goes to /article with the "Article deleted" toast.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Delete this article?**
- text ""How we price a bathroom renovation" will be deleted. Its images stay in your library. This can't be undone."
- cancel "Cancel"
- confirm "Delete article" (danger)
- Editor: status "draft", save "saved"
- Mobile: leading arrow-left button, trailing ellipsis
### Leave with unsaved changes
**Trigger:** Back, a nav link or closing the tab.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Modal: **Leave without saving?**
- text "Your changes to "How we price a bathroom renovation" haven't been saved."
- cancel "Discard changes"
- confirm "Keep editing"
- Editor: status "draft", save "dirty"
- Mobile: leading arrow-left button, trailing ellipsis
### Offline
**Trigger:** The connection dropped. Writing continues, and Save and Publish wait.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "offline"
- offline: true
- Mobile: leading arrow-left button, trailing ellipsis
### Not found (404)
**Trigger:** Unknown id, or the article was deleted elsewhere.
- Breadcrumbs: Articles › How we price a bathroom renovation (mobile title "Edit article")
- Editor: status "draft", save "saved", notfound true
- Mobile: leading arrow-left button, trailing ellipsis
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Editor". 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.
### Fixed copy in the frame
- This article doesn't exist
- It may have been deleted, or the link is wrong.
- All articles
- Online
- Draft
- Retry
- Preview
- Save
- Delete
- Every bathroom is different, but the way we price them isn't. We start with a visit, measure everything, and
- write down what stays
- We also check the
- timber windows
- /articles/winter-checklist
- Edit
- Open
- Remove
- before any tiling starts.
- What goes into the price
- Stripping out and making good
- Plumbing moves, if any
- Tiles, fittings and a day for silicone
- /static/uploadedImages/3f9c…e1.jpg
- We don't add a margin on materials you choose yourself.
- Details
- Created
- 12 Mar 2026, 09:14
- Updated
- Today, 11:02
- ID
- Images
- Public API URL
- /v1/article/12
- Title
- Titles can't be changed after an article is created. To use a different title, create a new article and delete this one.
### Editor (group "Editor", 41 states)
Route: `/article/:id/edit`. API: GET /v1/article/{id} · PATCH /v1/article/{id} · PATCH …/publish|unpublish · POST …/image · DELETE.
On mobile, Save and Publish sit in a sticky bottom bar and the details panel opens as a slideover. A session expiry mid-edit keeps the draft in sessionStorage and goes to /login?redirect=/article/12/edit. After logging in, the editor restores the draft and shows "Unsaved changes".
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Loading | GET in flight. Skeletons for the title, content and details. | |
| 2 | Saved | Just opened or just saved. Save is disabled. | |
| 3 | Unsaved changes | Any edit. Publish becomes "Save and publish". Leaving asks for confirmation. | |
| 4 | Saving | Save, or Ctrl/⌘ S. | |
| 5 | Save failed | 500 or network failure. The changes are kept and Retry resends them. | |
| 6 | Very long article | No length limit. The count stays neutral and correct at 120,000 characters. Save and Publish stay enabled. | |
| 7 | Very long article: saving | Save with large content. The status shows the spinner and the page stays editable. | "Saving 120,000 characters. This can take a few seconds." |
| 8 | Very long article: saved | 200. Status reads Saved with the time. The count is unchanged. | |
| 9 | Very long article: save failed | 500, 413 or network failure. Nothing is lost; Retry resends the same content. | "Couldn't save. Your text is kept. Retry." |
| 10 | Preview | The Preview switch. Shows the title and body in the content scale, the way a public site might. | |
| 11 | Link: create from selection | Ctrl/⌘ K or the link button with text selected. Link text is prefilled from the selection; URL has focus. | "Link text" / "timber windows" / "URL" |
| 12 | Link: create with no selection | Nothing selected. Link text is empty and has focus. | "Link text" / "What the reader sees" / "URL" |
| 13 | Link: edit existing | Edit in the link popover, or Ctrl/⌘ K inside a link. Prefilled; "Remove link" is offered. | "Edit link" / "Save link" / "Link text" / "timber windows" / "URL" |
| 14 | Link: invalid URL | On submit or blur. Nothing is inserted. | "Link text" / "timber windows" / "URL" / "Enter a valid URL. Use http(s), mailto, a path or #anchor." |
| 15 | Link: empty text | On submit with empty link text. | "Link text" / "Enter the link text." / "What the reader sees" / "URL" |
| 16 | Link: long URL | The field truncates in the middle of the line; the full value is available by scrolling the field and in the title attribute. | "Edit link" / "Save link" / "Link text" / "planning guidance" / "URL" |
| 17 | Link button: default | Toolbar button, icon link, after the list buttons. Desktop 28 px, mobile 40 px. Text colour --ui-text-toned. The toolbar scrolls sideways on mobile (see "Toolbar overflow"). | |
| 18 | Link button: hover and tooltip | Pointer or keyboard focus after 400 ms. Tooltip "Insert link (Ctrl+K)"; on macOS it reads "Insert link (⌘K)". Touch has no tooltip. | |
| 19 | Link button: focus-visible | 2 px --ui-primary outline, 1 px offset inside the toolbar. Enter or Space opens the link dialog. | |
| 20 | Link button: active (cursor in a link) | The cursor or selection is inside a link: aria-pressed true, --rc-sand fill and --rc-on-sand icon. Pressing it opens the dialog in edit mode. | |
| 21 | Link button: disabled | An image is selected in the editor. The button is at 40% opacity, aria-disabled, no tooltip. Ctrl/⌘ K does nothing. | |
| 22 | Link popover and sheet | Click a link, or Enter on a focused link. Desktop: popover under the link with the URL and Edit, Open and Remove. Mobile (touch): bottom sheet with the link text, the URL and Edit link, Open link, Remove link at 48 px. Esc or a tap outside closes it. Remove asks for no confirmation; undo restores the link. | |
| 23 | Rendered link: default | Same as the published page: --ui-text-highlighted, 1 px underline, 3 px offset. | |
| 24 | Rendered link: hover | Underline thickens to 2 px. | |
| 25 | Rendered link: focus | Tab or arrow keys into the link: 2 px --ui-primary outline, 2 px offset. | |
| 26 | Rendered link: selected | Text selected across the link: --rc-sand fill, --rc-on-sand text. | |
| 27 | Toolbar overflow (390 px) | The full toolbar does not fit at 390 px. It scrolls sideways in one row (no wrap); a 24 or 32 px fade marks each hidden side. This frame is scrolled to the end, so the link, remove-formatting and Image buttons are visible. Desktop is unchanged. | |
| 28 | Upload: choose | The image button in the toolbar, or a file dropped on the editor. | "Add an image" / "Cancel" |
| 29 | Upload: crop and resize | A JPEG, PNG or WEBP passed the checks, and nothing is sent yet. The crop starts as the whole image and the width defaults to 1600 px. SVGs skip this step. | |
| 30 | Upload: crop to a ratio | 16:9 chosen. The frame keeps the ratio while it's dragged or resized. Arrow keys move it; Shift and arrow keys resize it. | |
| 31 | Upload: crop narrower than the width | The crop is smaller than the chosen width, so it keeps its own size. | |
| 32 | Upload: in progress | Upload image was pressed. The cropped, resized file is uploading. Closing the dialog cancels the upload. | "Add an image" / "Cancel upload" |
| 33 | Upload: rejected | Checked in the browser, so nothing is sent. | "Add an image" / "Cancel" / "Choose another file" |
| 34 | Upload: inserted | 201: the image goes in at the cursor, and the article now has unsaved changes. | "Image added" / "Save to keep it in the article." |
| 35 | Publishing | "Save and publish": the PATCH body, then the publish request. | "Saving and publishing…" |
| 36 | Published | 200: the badge flips, Unpublish is offered and a toast confirms. | "Article published" / ""How we price a bathroom renovation" is now online." |
| 37 | Unpublishing | Unpublish doesn't save pending edits. | "Unpublishing…" |
| 38 | Delete: confirm | Delete… from the overflow menu. After a 204, it goes to /article with the "Article deleted" toast. | "Delete this article?" / ""How we price a bathroom renovation" and its 3 images will be deleted. This can't be undone." / "Cancel" / "Delete article" |
| 39 | Leave with unsaved changes | Back, a nav link or closing the tab. | "Leave without saving?" / "Your changes to "How we price a bathroom renovation" haven't been saved." / "Discard changes" / "Keep editing" |
| 40 | Offline | The connection dropped. Writing continues, and Save and Publish wait. | |
| 41 | Not found (404) | Unknown id, or the article was deleted elsewhere. | |
docs/design/screens/forgot-password.md
+20 -56
View File
@@ -1,68 +1,32 @@
# Forgot password
- **Route:** `/register/reset/request`
- **API:** POST /v1/auth/password-reset
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Forgot password" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/register/reset/request`. API: POST /v1/auth/password-reset.
The sent state reads the same whether or not the email exists, so the page doesn't reveal which emails have accounts.
## States
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Forgot password". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** From "Forgot password?" on log in.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
- Heading: **Reset your password**
- Description: "Enter the email for your account and we'll send you a link to choose a new password."
- Field `Email`: placeholder "you@example.com"
- Submit button: "Send reset link"
- Below the card: [Back to log in]
### Base copy
- Reset your password
- Enter the email for your account and we'll send you a link to choose a new password.
- Send reset link
- Back to log in
### Validation error
### Forgot password (group "Forgot password", 6 states)
**Trigger:** Invalid email on submit. Nothing is sent.
Route: `/register/reset/request`. API: POST /v1/auth/password-reset.
- Heading: **Reset your password**
- Description: "Enter the email for your account and we'll send you a link to choose a new password."
- Field `Email`: placeholder "you@example.com"; value "marta@renew"; **error "Enter a full email address, like name@example.com."**
- Submit button: "Send reset link"
- Below the card: [Back to log in]
The sent state reads the same whether or not the email exists, so the page doesn't reveal which emails have accounts.
### Submitting
**Trigger:** Request in flight.
- Heading: **Reset your password**
- Description: "Enter the email for your account and we'll send you a link to choose a new password."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"
- Submit button: "Sending…", loading
- Below the card: [Back to log in]
### Sent
**Trigger:** Any 200, whether or not the account exists.
- ResultPanel (success, mail-check): **Check your email**; text "If an account exists for that email, a password reset link has been sent."; note "The link expires in 1 hour."; actions "Back to log in" (secondary)
### Too many attempts (429)
**Trigger:** Rate limit with Retry-After.
- Relied on an API marked pending in the design; that API now exists.
- Alert (info, timer): **Too many requests** "Wait a moment before asking for another link."
- Heading: **Reset your password**
- Description: "Enter the email for your account and we'll send you a link to choose a new password."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"
- Submit button: "Try again in 0:58", disabled
- Below the card: [Back to log in]
### Server error
**Trigger:** 500 or no response.
- Alert (error, circle-x): **Couldn't send the link** "Check your connection and try again."
- Heading: **Reset your password**
- Description: "Enter the email for your account and we'll send you a link to choose a new password."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"
- Submit button: "Send reset link"
- Below the card: [Back to log in]
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | From "Forgot password?" on log in. | |
| 2 | Validation error | Invalid email on submit. Nothing is sent. | "marta@renew" / "Enter a full email address, like name@example.com." |
| 3 | Submitting | Request in flight. | "marta@renew.example" / "Sending…" |
| 4 | Sent | Any 200, whether or not the account exists. | "Check your email" / "If an account exists for that email, a password reset link has been sent." / "The link expires in 1 hour." / "Back to log in" |
| 5 | Too many attempts (429) | Rate limit with Retry-After. | "Too many requests" / "Wait a moment before asking for another link." / "marta@renew.example" / "Try again in 0:58" |
| 6 | Server error | 500 or no response. | "Couldn't send the link" / "Check your connection and try again." / "marta@renew.example" |
docs/design/screens/global.md
+13 -28
View File
@@ -1,39 +1,24 @@
# Global states
- **Route:** `any route`
- **API:**
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Global" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `any route`. API: .
A 401 on any back-office call redirects to /login?redirect=<path>&reason=expired (see "Session expired" on the auth board). A 403 from an unverified account redirects to /register/pending. A 429 appears only on log in and password reset. Toasts sit bottom right on desktop and bottom center on mobile, at most 3 at once. Success and info last 5 s; errors stay until dismissed.
## States
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Global". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### 404 inside the shell
## Copy per state (generated from the board source, pass 2)
**Trigger:** An unknown route while logged in. Logged out, the same content appears inside AuthShell.
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.
- Breadcrumbs: Not found (mobile title "Not found")
- err: {"code":"404","title":"Page not found","text":"The link may be mistyped, or the page may have moved.","primary":"Go to Home","secondary":"All articles"}
### Global states (group "Global", 4 states)
### Generic error
Route: `any route`. API: none.
**Trigger:** An unexpected error while rendering a route.
A 401 on any back-office call redirects to /login?redirect=<path>&reason=expired (see "Session expired" on the auth board). A 403 from an unverified account redirects to /register/pending. A 429 appears only on log in and password reset. Toasts sit bottom right on desktop and bottom center on mobile, at most 3 at once. Success and info last 5 s; errors stay until dismissed.
- Breadcrumbs: Home (mobile title "Home")
- err: {"code":"Error","title":"Something went wrong","text":"This page couldn't load. Your saved work is safe. Try again, and if it keeps happening, restart the RenewCMS server.","primary":"Try again","secondary":"Go to Home"}
### Offline banner
**Trigger:** navigator.onLine is false. The banner is shown on every back-office page.
- Breadcrumbs: Articles (mobile title "Articles")
- offline: true
### Toast stack
**Trigger:** Three at most, newest at the bottom. A fourth pushes out the oldest non-error toast.
- Breadcrumbs: Articles (mobile title "Articles")
- Toast (success, circle-check): **Article published** ""Winter checklist for timber windows" is now online."
- Toast (info, info): **That article no longer exists** "It was deleted somewhere else, so we removed it from the list."
- Toast (error, circle-x): **Couldn't unpublish** "The server didn't respond. Nothing changed." with action "Retry"
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | 404 inside the shell | An unknown route while logged in. Logged out, the same content appears inside AuthShell. | "Not found" / "Page not found" / "The link may be mistyped, or the page may have moved." / "Go to Home" / "All articles" |
| 2 | Generic error | An unexpected error while rendering a route. | "Home" / "Error" / "Something went wrong" / "This page couldn't load. Your saved work is safe. Try again, and if it keeps happening, restart the RenewCMS server." / "Try again" / "Go to Home" |
| 3 | Offline banner | navigator.onLine is false. The banner is shown on every back-office page. | |
| 4 | Toast stack | Three at most, newest at the bottom. A fourth pushes out the oldest non-error toast. | "Article published" / ""Winter checklist for timber windows" is now online." / "That article no longer exists" / "It was deleted somewhere else, so we removed it from the list." / "Couldn't unpublish" / "The server didn't respond. Nothing changed." / "Retry" |
docs/design/screens/home.md
+38 -55
View File
@@ -1,66 +1,49 @@
# Home
- **Route:** `/home`
- **API:** GET /v1/article/
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Home" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/home`. API: GET /v1/article/ · GET /v1/activity?size=5.
The greeting reads "Good morning, {name}", where the name is the display name when the user has saved one and the username otherwise. The counts come from the list, so there's no separate endpoint. The five most recently updated articles link to the editor.
The counts come from the list, so there's no separate endpoint. The five most recently updated articles link to the editor. Below them, a Recent activity section shows the last 5 events (owner and admin) or the user's own (regular users), and links to Activity.
## States
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Home". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** The articles loaded.
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.
- Breadcrumbs: Home (mobile title "Home")
- Subtitle: "Here's where things stand on your site."
- Stats: 6 articles, 4 online, 2 drafts
- Recent: the 5 most recently updated articles, with status
### Fixed copy in the frame
- New article
- Couldn't load your articles
- Check your connection and try again.
- Try again
- Write your first article
- It starts as a draft, so nothing appears on your site until you publish it.
- Recently updated
- All articles
- Online
- Draft
- View all
- Couldn't load recent activity
- No activity yet
- Failed
- Connect your website
- Your site reads published articles from RenewCMS. Share this guide with whoever builds it.
- Open the guide
### Loading
### Home (group "Home", 10 states)
**Trigger:** The list request is in flight. Skeletons appear after 150 ms.
Route: `/home`. API: GET /v1/article/ · GET /v1/activity?size=5.
- Breadcrumbs: Home (mobile title "Home")
- Subtitle: "Here's where things stand on your site."
- Stats and recent list: skeletons
The counts come from the list, so there's no separate endpoint. The five most recently updated articles link to the editor. Below them, a Recent activity section shows the last 5 events (owner and admin) or the user's own (regular users), and links to Activity.
### Empty, first run
**Trigger:** Zero articles: a single call to action, and no stats.
- Breadcrumbs: Home (mobile title "Home")
- Subtitle: "Welcome to RenewCMS."
- First-run empty state instead of stats and recent list
### Error
**Trigger:** A 500 or network failure on the list request.
- Breadcrumbs: Home (mobile title "Home")
- Subtitle: "Here's where things stand on your site."
- Error state for the list request
### Update available (owner)
**Trigger:** The owner only. A quiet banner above the content, and an "Update" pill on the Settings sidebar item (a dot on the menu icon on mobile, read as "Update available"). Dismissing hides the banner until the next version; the pill stays. Admins see neither.
- Breadcrumbs: Home (mobile title "Home")
- Subtitle: "Here's where things stand on your site."
- Banner: `role="region"` labelled "Update available", info tone, `circle-arrow-up` icon, title "Version 2.3.0 is available", text "Update it from Settings. It takes about 2 minutes and the site stays online.", button "Go to Settings", and a dismiss button
### Update ready to install (owner)
**Trigger:** The download is checked. The same banner changes its copy, and a dismiss comes back on the next visit because the update is waiting.
- Banner: success tone, `circle-check` icon, title "Version 2.3.0 is ready to install", text "Restart from Settings to finish. The site is unavailable for about 10 seconds.", button "Go to Settings"
## Recent activity
**API:** GET /v1/activity?size=5. Visual reference: `source/RenewCMS Screens Back-office.dc.html`, group "Home" (states Default, Recent activity: loading, error and empty, Regular user), drawn by `source/AppFrame.dc.html`. This is the layout of record. The older Home card on the Activity board is superseded.
A section with the last five events, built like "Recently updated" above it: a 16 px semibold heading on the left ("Recent activity") and an underlined "View all" link on the right, then a bordered list. Header "Recent activity" (regular users: "Your recent activity") and a "View all" link with `arrow-right` to `/activity`. Each row: a 24 px avatar, the sentence clamped to two lines with the target in semibold, then "Marta Alves · 2 min ago" (own events: only the time). A failed event gets a "Failed" badge; a successful security event a small `shield`.
- Placement: full width, below the stats and the "Recently updated" list, on desktop and mobile. There is no side column. "View all" links to `/activity`.
- States: Owner or admin, Regular user, Loading (five skeleton rows after 150 ms), Error ("Couldn't load recent activity" with "Try again"), Empty ("No activity yet", "Actions on your site will appear here." / own: "Your actions will appear here.").
- The section never blocks the page: an error or empty card leaves the stats and the article list as they are.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | The articles loaded. | "Here's where things stand on your site." |
| 2 | Loading | The list request is in flight. Skeletons appear after 150 ms. | "Here's where things stand on your site." |
| 3 | Empty, first run | Zero articles: a single call to action, and no stats. | "Welcome to RenewCMS." |
| 4 | Error | A 500 or network failure on the list request. | "Here's where things stand on your site." |
| 5 | Update available (owner) | The owner only. A quiet banner above the content, and an "Update" pill on the Settings item (a dot on the menu icon on mobile, read as "Update available"). Dismissing hides the banner until the next version; the pill stays. Admins see neither. | "Here's where things stand on your site." / "Version 2.3.0 is available" / "Update it from Settings. It takes about 2 minutes and the site stays online." |
| 6 | Update ready to install (owner) | The download is checked. The same banner changes its copy, and a dismiss comes back on the next visit because the update is waiting. | "Here's where things stand on your site." / "Version 2.3.0 is ready to install" / "Restart from Settings to finish. The site is unavailable for about 10 seconds." |
| 7 | Recent activity: loading | The activity request is in flight. Five skeleton rows. | "Here's where things stand on your site." |
| 8 | Recent activity: error | A failed request shows an inline alert in the section only. The rest of Home is unaffected. | "Here's where things stand on your site." |
| 9 | Recent activity: empty | No events yet. | "Here's where things stand on your site." |
| 10 | Regular user | Own events only, titled "Your recent activity". The sidebar has no Users, Integration or Settings. | "Here's where things stand on your site." |
docs/design/screens/image-variants.md
+62 -307
View File
@@ -1,330 +1,85 @@
# Image variants
- **Routes:** `/settings/media/variants` and `/settings/media/cache` (admins and owners), plus additions to `/media` and `/article/:id/edit`
- **API (proposed by the design, to be fixed by the feature spec):** GET/POST /v1/image-variants · PUT/PATCH/DELETE /v1/image-variants/{name} · POST /v1/image-variants/{name}/purge · GET /v1/image-variants/cache · POST /v1/image-variants/cache/purge · GET /v1/media/{id}/variants · POST/DELETE /v1/media/{id}/variants/{name}
- **Public contract:** `<public image URL>?v=<name>`, see section 7
- **Visual reference:** `source/RenewCMS Screens Image variants.dc.html`, drawn by `source/VariantsFrame.dc.html` inside the `AppFrame.dc.html` back-office frame (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle). Every frame is numbered; the numbers below match.
Named variants of an original image. The original is never changed. An admin defines variants (a name, a width and/or height, a fit, a format, a quality). A request for an image with `?v=<name>` generates the variant on first use, caches it, and serves the cached file afterwards. Only variants that exist and are enabled are served: anything else is a 400. There is no arbitrary-size mode and no raw `width`, `height`, `format` or `quality` parameter.
Vocabulary: "variant", "generated", "purge". Delete removes a variant definition; purge removes only its generated files. Never "thumbnail preset", "version" or "rendition".
Variant fields: name (slug, 2 to 32 lowercase letters, numbers and dashes, unique, immutable after creation), width and height (1 to 8000 px, at least one required, images are never enlarged), fit (cover, contain, inside), format (original, JPEG, PNG, WebP; no AVIF), quality (1 to 100, hidden for PNG), generate on upload, enabled.
## 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)
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).
| State | Name | Trigger |
|---|---|---|
| 1a | Loaded | Six variants, one of them disabled (print). |
| 1b | Loading | Skeleton rows appear after 150 ms. |
| 1c | Empty | No variants. Two templates pre-fill the Add variant form. |
| 1d | Error loading | A 500 or network failure on the list request. |
| 1e | Forbidden | A signed-in user who is not an admin opens the URL. |
| 1f | Row menu | The ellipsis button on a row. |
| 1g | Row action in progress | Purge cache was confirmed on hero. The row is dimmed and its controls are disabled. |
| 1h | Purge confirm | Purge cache in the row menu. |
| 1i | Delete confirm | Delete in the row menu. |
| 1j | Delete in progress | Delete was confirmed. The button shows a spinner. |
| 1k | Request reference | Mobile scrolled to the reference card. On desktop it is visible below the table. |
| 1l | 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. |
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.
**Sidebar entry (1l).** For owner and admin, the Settings item has a chevron (right when closed, down when open) and expands to a group: a muted uppercase label "Media" (11 px, semibold, 0.04em tracking), then "Variants" (layers icon) and "Cache" (database icon). The group is indented 19 px with a 1 px left border; its items are 32 px high (44 px in the mobile drawer) with 14 px icons. The group is open on every `/settings` route. When a subpage is current, its item takes the sand fill and Settings keeps only the highlighted text and medium weight. On `/settings` itself Settings is the current item. Other roles see no chevron and no group. Cache stays inert until its screen exists.
## Copy per state (generated from the board source, pass 2)
### Copy: Variants list
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.
| State | Where | Copy |
|---|---|---|
| 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. |
### 1. Settings → Media → Variants (group "Variants list", 12 states)
## 2. Add / edit variant
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.
- **Route:** Slide-over on desktop · full page on mobile
- **API:** POST /v1/image-variants · PUT /v1/image-variants/{name}
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 | Name | Trigger |
|---|---|---|
| 2a | Create: pristine | Add variant just opened. Save is disabled. |
| 2b | Create: dirty | Valid values. The divider has keyboard focus. Mobile is scrolled to the preview. |
| 2c | Field errors | On blur and on submit. Name format, width above 8000, quality above 100. |
| 2d | No dimension | Width and height are both empty on submit. |
| 2e | Name already taken | POST returns 409. |
| 2f | Saving | Request in flight. Fields and buttons are disabled. |
| 2g | Save error | A 500 or network failure. Values are kept. |
| 2h | Edit: pristine | Opened from Edit. Name is locked. Save is disabled. |
| 2i | Edit: dirty | Quality changed from 82 to 70. |
| 2j | Unsaved changes | Close, Cancel or Escape while dirty. |
| 2k | PNG: no quality | Quality is hidden when the format is PNG. |
| # | 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" |
### Copy: Add / edit variant
### 5. Settings → Media → Cache (group "Cache panel", 10 states)
| State | Where | Copy |
|---|---|---|
| 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 |
## 3. Media library
- **Route:** /media
- **API:** GET /v1/media?variants=with|without&sort=total_size (proposed)
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.
| State | Name | Trigger |
|---|---|---|
| 3a | Grid with badges | Default view. Images with no cached variants have no badge. |
| 3b | Sort menu | The sort select is open. The new option is last. |
| 3c | Filter: With variants, sorted by total size | The meta line becomes total · original + variants. |
| 3d | Filter: Without variants | Images no variant has been generated for. |
| 3e | Filter: nothing to show | With variants, and the cache is empty. |
| 3f | Delete confirm | Delete on an image that has cached variants. |
### Copy: Media library additions
| State | Where | Copy |
|---|---|---|
| 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) |
## 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)
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.
| State | Name | Trigger |
|---|---|---|
| 4a | Partly generated | Four of five generated. Saving is shown against the original. |
| 4b | Nothing generated yet | No cached files for this image. |
| 4c | Generating | Generate all or Generate now was pressed. Rows show a spinner. |
| 4d | Generation failed | The row shows the cause and Retry. Both causes are shown together for reference. |
| 4e | No variants defined | There are no enabled variants. |
| 4f | Source is an SVG | Variants aren't generated for vector images. |
| 4g | Source is an animated GIF | Same rule as SVG. |
| 4h | Preview dialog | Preview on a generated row. Both at actual size. |
### Copy: Variants tab
| State | Where | Copy |
|---|---|---|
| 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. |
## 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)
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 | Name | Trigger |
|---|---|---|
| 5a | Loaded | Default view. |
| 5b | Loading | Tiles and lists show skeletons. |
| 5c | Empty cache | Nothing generated. Purge buttons are disabled. |
| 5d | Purging | Progress for a purge in progress. Content is dimmed. |
| 5e | Purge done | The cache is empty and a toast reports the result. |
| 5f | Purge failed | Part of the purge did not complete. |
| 5g | Error loading | A 500 or network failure. |
| 5h | Purge all: confirm | The word is not typed yet. The button is disabled. |
| 5i | Purge all: confirm, typed | The input matches "purge". |
| 5j | Purge unused: confirm | Variants of enabled variants not requested for 30 days. |
### Copy: Cache panel
| State | Where | Copy |
|---|---|---|
| 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 |
## 6. Editor image picker
- **Route:** /articles/{id}/edit
- **API:** Inserted URL: /media/{file}?v={name}
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.
| State | Name | Trigger |
|---|---|---|
| 6a | Variant select | An image is selected. The URL line shows what will be inserted. |
| 6b | Select open | Original plus five enabled variants. |
| 6c | No variants defined | Only Original is offered. |
| 6d | Variant deleted | The block keeps its URL. Pick another variant opens the select. |
| 6e | Variant disabled | Same block, different cause. Proposed copy. |
### Copy: Editor picker
| State | Where | Copy |
|---|---|---|
| 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 |
## 7. Public request contract
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.
| Request | Status | Body or result |
|---|---|---|
| /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" } |
## 8. Activity log entries
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.
| Event | Row copy | Detail line |
|---|---|---|
| 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) |
## States matrix
Frame: a numbered state above. Copy: covered by the copy tables, with no separate frame. Existing: unchanged behavior of the existing screen.
| Screen | Loaded | Empty | Loading | Error | Forbidden | In progress | Confirm | Validation | Success |
|---|---|---|---|---|---|---|---|---|---|
| 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 | – | – | – | – | – |
## Back-office API errors
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.
| Status | Title | Text | Where it shows |
| # | State | Trigger | Copy |
|---|---|---|---|
| 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 |
| 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" |
## Component inventory
### Settings navigation: parent and child selected (group "Settings navigation", 5 states)
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.
Route: `/settings · /settings/media/variants · /settings/media/cache`. API: none.
| Component | Status | Nuxt UI mapping | Notes |
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 |
|---|---|---|---|
| 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. |
## Vocabulary and accessibility
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.
## Implementation notes
The board predates two decisions. Where the board and these notes differ, these notes win for behaviour and the board stays the reference for layout and copy structure.
- The public URL is `/static/uploadedImages/<storedName>?v=<name>` (`image.PublicPathPrefix`), not `/media/<file>`. Every `/media/...?v=...` string in the copy tables above (URL field, Copy URL, URL line in the picker, request contract rows) shows that URL instead. `/media` stays the SPA library route.
- WebP output depends on a CGO-free lossy encoder. If none is viable, the Format select offers Original, JPEG and PNG only.
- The padding colour of `contain` is not drawn. The feature spec decides it.
| 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" |
docs/design/screens/integration-api-keys.md
+40 -30
View File
@@ -2,7 +2,7 @@
Route: `/integration/api-keys`. Component: `ApiKeysPage.dc.html`, mounted by `AppFrame`.
- **Visual reference:** `source/RenewCMS Screens API keys.dc.html`, group "API keys", drawn by `source/ApiKeysPage.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Visual reference: `RenewCMS Screens API keys.dc.html`.
## API
`POST /v1/api-key` · `GET /v1/api-key` · `DELETE /v1/api-key/{id}`. Access: Session only. An API key cannot manage keys; with a key these routes answer 403 "This action needs a real session."
@@ -16,7 +16,7 @@ Under Integration, as a sub-page linked from the Authentication section ("Manage
- Columns: Name, Key (prefix, mono), Status (active, expired, revoked), Created by (owners only), Created, Last used, Expires, Revoke. Owners see all keys; admins see their own.
- Create key modal: Name (required, up to 60, counter), Expiry date (optional, must be in the future). Errors: "Enter a name." / "Use 60 characters or fewer." / "Choose a date in the future."
- The Expiry field is a native date input. The displayed format follows the browser's locale, so there is no custom format. The board draws one example date only.
- One-time reveal: warning "You won't be able to see this key again.", monospace key, Copy / Copied, "Closing this window discards the key from the screen. Copy it first." Button "Done".
- One-time reveal: warning "You won't be able to see this key again.", the key in a CodeSnippet with one tab ("API key") and Copy / Copied, "Closing this window discards the key from the screen. Copy it first." Button "Done".
- Revoke: "Revoke this key?" / ""Nightly media import" (rcms_Mq7b…) will stop working right away. Requests that use it answer 401. This can't be undone." Buttons "Keep key", "Revoke key". Toast "Key revoked".
- Empty: "No API keys yet" / "Create a key to call the API from a script or service." Error: "Couldn't load your API keys" / "Check your connection and try again."
- Note: "Resetting a user's password revokes all of their keys."
@@ -25,34 +25,44 @@ Under Integration, as a sub-page linked from the Authentication section ("Manage
On mobile the "Create key" button is pinned to the bottom of the viewport (44 px high, full width, on a bar with a top border). It shows in Owner list, Admin own keys only, Loading, Empty, Error and Revoked, and is hidden behind every modal state. In Empty it replaces the inline button. The content has bottom padding so nothing sits under the bar, and the toast sits above it. Desktop keeps "Create key" in the page header (and in the Empty card).
## States
Names are matched exactly by the visual-check script.
### Owner: list
### Admin: own keys only
### Loading
the list request is in flight. Skeleton rows appear only after 150 ms.
### Empty
### Error
a 500 or network failure on the list request. If a key is created while this state is showing, the list reloads, the new key appears and the error alert is cleared.
### Create key
### Create key: validation
### Create key: name too long
### One-time reveal
### One-time reveal: copied
### Revoke: confirm
### Revoked
- Owner: list
- Admin: own keys only
- Loading: the list request is in flight. Skeleton rows appear only after 150 ms.
- Empty
- Error: a 500 or network failure on the list request. If a key is created while this state is showing, the list reloads, the new key appears and the error alert is cleared.
- Create key
- Create key: validation
- Create key: name too long
- One-time reveal
- One-time reveal: copied
- Revoke: confirm
- Revoked
## Component inventory (Nuxt UI v4)
`UTable`, `UBadge`, `UModal` with `UForm`/`UFormField`/`UInput` (type date), `UAlert` color warning, `UButton`, `useClipboard`.
`UTable`, `UBadge`, `UModal` (dialog on desktop, bottom sheet on mobile, footer secondary left and primary right) with `UForm`/`UFormField`/`UInput` (type date), `UAlert` color warning, `UButton`, CodeSnippet for the key.
## 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 API keys.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
### API keys (group "API keys", 12 states)
Route: `/integration/api-keys`. API: GET /v1/api-key · POST /v1/api-key · DELETE /v1/api-key/{id} (session only).
Recommendation: place it under Integration, as a sub-page linked from the Authentication section and from the sidebar item. Keys exist to call the API, so they belong next to the reference. Settings is owner-only today, but admins can also create keys. The screen is session only: an API key cannot manage keys. Key name: required, up to 60 characters. Expiry: optional, in the future. A key is shown in full once; afterwards only its prefix is visible.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Owner: list | Owners see every user's keys and a "Created by" column. Expired keys keep their Revoke action. | "Integration" / "API keys" |
| 2 | Admin: own keys only | Admins see only the keys they created, with no "Created by" column. | "Integration" / "API keys" |
| 3 | Loading | The list request is in flight. Skeleton rows appear after 150 ms. | "Integration" / "API keys" |
| 4 | Empty | No keys yet. | "Integration" / "API keys" |
| 5 | Error | A 500 or network failure on the list request. | "Integration" / "API keys" |
| 6 | Create key | "Create key" in the page header, or the bottom action on mobile. Name is required and limited to 60 characters; expiry is optional. | "Integration" / "API keys" |
| 7 | Create key: validation | On submit or blur. Nothing is sent. The name is empty and the expiry is in the past. | "Integration" / "API keys" |
| 8 | Create key: name too long | Over 60 characters. Checked as you type. | "Integration" / "API keys" |
| 9 | One-time reveal | 201: the full key is shown once. Closing the dialog discards it from the screen. | "Integration" / "API keys" |
| 10 | One-time reveal: copied | Copy was pressed. The button reads "Copied" for 2 s and this is announced. | "Integration" / "API keys" |
| 11 | Revoke: confirm | Revoke on an active or expired row. | "Integration" / "API keys" |
| 12 | Revoked | 204: the key stays in the list, greyed, with no Revoke action. A toast confirms. | "Integration" / "API keys" |
docs/design/screens/integration.md
+53 -25
View File
@@ -2,7 +2,7 @@
Route: `/integration`. Component: `IntegrationPage.dc.html`, mounted by `AppFrame`. The API keys sub-page is in `screens/integration-api-keys.md`.
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Integration", drawn by `source/IntegrationPage.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Visual reference: `RenewCMS Screens Back-office.dc.html`, group "Integration".
## Navigation decision
Sticky section index on the right (desktop), "Jump to" select (mobile). A reference is read in one scroll and searched with the browser, so tabs would hide content and break find-in-page and deep links; the index keeps one page with anchors and shows position.
@@ -10,9 +10,9 @@ Sticky section index on the right (desktop), "Jump to" select (mobile). A refere
## Page copy
- Header: breadcrumb "Integration", title "API reference", description "Everything a developer needs to build on RenewCMS."
- Intro: "RenewCMS is headless: it stores your content and your own code displays it. There are two ways in. Public read-only access lets a website read online articles. API keys let a script or service manage articles, media and users without the back-office."
- Base URL: label "Base URL", button "Copy" / "Copied" (2 s, announced).
- Base URL: label "Base URL", a CodeSnippet with one tab ("Base URL") and the button "Copy" / "Copied" (2 s, announced).
- Authentication, card "Public": "No key needed. Two read-only routes, and only online articles are returned." `GET /v1/article/`, `GET /v1/article/{id}`.
- Card "API key": "Send `Authorization: Bearer rcms_…`. Requests act as the user who created the key, with that user's role (owner or admin). A key never has more rights than its creator." CodeBlock tabs curl, fetch (GET /v1/auth/me). "Keys start with `rcms_` and are shown in full once, when you create them." Link "Manage API keys".
- Card "API key": "Send `Authorization: Bearer rcms_…`. Requests act as the user who created the key, with that user's role (owner or admin). A key never has more rights than its creator." CodeSnippet tabs curl, fetch (GET /v1/auth/me). "Keys start with `rcms_` and are shown in full once, when you create them." Link "Manage API keys".
- Note 1: "A key can't create, list or revoke API keys, log in, register, verify or reset a password, or call anything under `/v1/system`. Those routes answer 403 "This action needs a real session." An invalid, unknown, expired or revoked key answers 401, even on public routes, and so does a key whose user was deleted or unverified."
- Note 2: "Each key can make 120 requests per minute. Beyond that the API answers 429 with a `Retry-After` header."
- Groups: Articles (7), Media (6), Users and invites (6), Settings (1), Session only (12 routes, 3 sub-groups; every `/v1/system` route is in this group). Session-only banner: "These routes need a signed-in browser session. With an API key they answer 403 "This action needs a real session.""
@@ -21,33 +21,18 @@ Sticky section index on the right (desktop), "Jump to" select (mobile). A refere
## EndpointCard states
- Collapsed (44 px row): method badge, mono path, one-line description, chips, chevron. Desktop is one line; mobile is three (method and path, description, chips).
- Expanded: "Request body" table (Name, Type, Required, Rule; "No request body." when empty), tabs fetch / curl / Response with one CodeBlock and Copy, then "Errors": status chip plus one-line caption (also its `title` tooltip).
- Expanded: "Request body" table (Name, Type, Required, Rule; "No request body." when empty), tabs fetch / curl / Response in one CodeSnippet with Copy, then "Errors": status chip plus one-line caption (also its `title` tooltip).
- Session only: dashed border, muted fill, lock icon, "Session only" chip, no method colour, no expand.
- Chips: access "Public", "Verified user", "Owner only"; key "API key OK" (success soft) or "Session only" (dashed, muted).
- Method badges: GET `--ui-bg-inverted`, POST success soft, PATCH warning soft, DELETE error soft. Existing tokens only.
## States
Desktop 1440×900, mobile 390×844, light and dark. Names are matched exactly by the visual-check script.
### 1. Default
### 2. Group scrolled, one card expanded
### 3a. Copied: base URL
### 3b. Copied: CodeBlock
### 4. Authentication
### 5. Session only
### 6. Errors
### 7. Navigation
Desktop 1440×900, mobile 390×844, light and dark.
1 Default · 2 Media group, POST /v1/media/ expanded with curl tab · 3a Base URL copied · 3b CodeSnippet copied · 4 Authentication · 5 Session only · 6 Errors · 7 Navigation (index active item Media; mobile select open).
## Error messages
Plain text, one sentence. Used in the table and in the per-endpoint error captions.
- 400: "The request cannot be processed due to a mismatch in the format of the body." / "The expiry must be a date in the future."
- 400: "The request cannot be processed due to a mismatch in the format of the body." / "The expiry must be a date in the future." Image requests (`/media/photo.png?v=`) answer 400 with a JSON body (`status`, `error`, `message`, `detail`) in two cases: `{ "status": 400, "error": "unknown_variant", "message": "Unknown variant", "detail": "unknown" }` for an unknown or disabled variant, and `{ "status": 400, "error": "unsupported_parameter", "message": "Unsupported parameter", "detail": "width" }` for any other query parameter (`width`, `height`, `format`, `quality`). Both are rows of the "Responses" table in "Images and variants".
- 401: "You must be logged in to access this resource."
- 403: "This action needs a real session." (session-only routes called with a key) / "Only the owner can do this." / "You must verify your account to access this resource."
- 404: "Article not found" / "Image not found" / "Invite not found" / "API key not found"
@@ -57,8 +42,8 @@ Plain text, one sentence. Used in the table and in the per-endpoint error captio
- 413 and 415 on `POST /v1/media/` keep their earlier plain captions; no real message is known.
## Request bodies
- `POST /v1/article/`: `title` (string, required, 3 to 200 characters), `body` (string, required, max 10000).
- `PATCH /v1/article/{id}`: `body` (string, required, max 10000).
- `POST /v1/article/`: `title` (string, required, 3 to 200 characters), `body` (string, required, max 10000 today; the limit is being removed, see change-list.md item 3).
- `PATCH /v1/article/{id}`: `body` (string, required, max 10000 today; same).
- `PATCH /v1/media/{id}` (rename): `filename` (string, required).
- `POST /v1/media/merge`: `keep_id` (number, required, > 0), `merge_ids` (number[], required, at least 1, each > 0).
- `POST /v1/media/`: multipart/form-data, 1 file field (shown as "multipart/form-data, 1 file field").
@@ -67,7 +52,7 @@ Plain text, one sentence. Used in the table and in the per-endpoint error captio
- `POST /v1/system/update/restart`: optional body `{ "kind": "update" | "restart" }`.
## Component inventory and Nuxt UI v4
- EndpointCard (extended): `UCollapsible` (trigger is a button with aria-expanded), `UBadge` (method, chips, status), `UTable` (body fields), `UTabs` (fetch, curl, Response), CodeBlock.
- EndpointCard (extended): `UCollapsible` (trigger is a button with aria-expanded), `UBadge` (method, chips, status), `UTable` (body fields), CodeSnippet (fetch, curl, Response). CodeSnippet is the only code block in the product: Integration, Integration images, API keys (one-time key) all use it. Selected tab: 2 px `--ui-primary` underline. Syntax colouring was dropped so there is one rendering.
- SectionIndex (new): custom `<nav>` of anchor buttons with `aria-current`; sticky, scroll-spy. Mobile: `USelectMenu` labelled "Jump to".
- SessionOnlyGroup (new): `UAlert`-style info note plus list rows; no new colour.
- ErrorTable: `UTable`. Info notes: existing note style (or `UAlert` variant `naked`).
@@ -80,3 +65,46 @@ Plain text, one sentence. Used in the table and in the per-endpoint error captio
## Tokens
No new tokens. Foundations check: colours, radius (0) and spacing come from existing `--ui-*` and `--rc-*` values; every control has a 2 px primary focus ring; index, select and cards are keyboard operable. Open question: the board hard-codes a few pixel sizes, as the other screens do.
## 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.
### Integration: API reference (group "Integration", 8 states)
Route: `/integration`. API: none (static). Replaces "Connect your website"..
Navigation: a sticky section index on the right on desktop, and a "Jump to" select on mobile. A long reference is read in one scroll and searched with the browser, so tabs would hide content and break find-in-page; the index keeps every group on one page, links to anchors and shows where you are. Written for a developer. The base URL is window.location.origin. The API keys screen has its own board.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | 1. Default | Opened from the sidebar or the Home card. Every endpoint card is collapsed. Desktop shows the sticky index on the right; mobile shows the "Jump to" select above the content. | "Integration" |
| 2 | 2. Group scrolled, one card expanded | POST /v1/media/ opened in the Media group: multipart body with 1 file field, curl tab shown. Only one example block is visible per card. Other cards stay collapsed. | "Integration" |
| 3 | 3a. Copied: base URL | The base URL was copied. The button reads "Copied" for 2 s and this is announced. | "Integration" |
| 4 | 3b. Copied: CodeBlock | The Copy button in the API key example after a click. Back to "Copy" after 2 s. | "Integration" |
| 5 | 4. Authentication | The API key card with its example, the "Manage API keys" link (goes to the API keys board) and the two notes. | "Integration" |
| 6 | 5. Session only | Routes API keys cannot call. Dashed, muted and locked, so they read as unavailable and not as an error. | "Integration" |
| 7 | 6. Errors | Status table and the plain-text error response (status line plus a one-sentence body). Key-specific causes are in the 401, 403 and 429 rows. | "Integration" |
| 8 | 7. Navigation | Desktop: the sticky index with the active item (Media). Mobile: the "Jump to" select open. Keyboard: the index buttons and the select are in the tab order, Enter jumps, Escape closes the list. | "Integration" |
### Integration: images and ?v= (group "Integration: images", 9 states)
Route: `/integration#images`. API: GET /v1/image-variants (existing).
New section "Images and variants" on the Integration page, after Media and before Errors. It explains the ?v=<variant-name> parameter, shows one CodeSnippet with curl, HTML and JavaScript tabs, a table of enabled variants, a URL builder and the response codes. When there are no variants, admins see a link to /settings/media/variants and other users see plain information. A removed variant is not replaced by the original: the request returns 400 with the body shown in the builder.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Many variants | Twelve enabled variants. The table scrolls at 264 px. On mobile the table and snippet scroll horizontally. | |
| 2 | One variant | A single enabled variant. The snippets use its name. | |
| 3 | No variants, admin | Empty state with a link to /settings/media/variants. | |
| 4 | No variants, not an admin | Plain information, no link. | |
| 5 | Variant removed | The builder holds "hero", which was deleted. Warning with the exact 400 body. | |
| 6 | Loading | Skeleton blocks while variants load. Snippets are hidden until the list is known. | |
| 7 | Error loading | 500 or network failure. Snippets still render with the placeholder name. | |
| 8 | Snippet copied | Copy pressed on the snippet. The label reads Copied for 2 s and is announced politely. | |
| 9 | URL builder copied | Copy pressed on the built URL. | |
## Pass 2 notes
- The base URL field and the image URL builder output are CodeSnippets with a single tab.
- Page padding 24 px (16 px on mobile), page title 20/28, section headings 18/26, card titles 15/24, sub headings 14/22 (foundations.md).
docs/design/screens/log-in.md
+22 -95
View File
@@ -1,107 +1,34 @@
# Log in
- **Route:** `/login`
- **API:** GET /v1/auth/registration (pending) · POST /v1/auth/login
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Log in" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/login`. API: GET /v1/auth/registration (pending) · POST /v1/auth/login.
After logging in, you go back to the page you originally asked for (?redirect=), or to /home. An unverified account goes to /register/pending. "Create the owner account" appears only when registration is open.
## States
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Log in". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** Registration is closed, which is the usual case.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"
- Field `Password`: password with show/hide; link "Forgot password?"
- Submit button: "Log in"
### Base copy
- Log in
- Welcome back. Log in to manage your articles.
- Log in
### Fresh install
### Log in (group "Log in", 9 states)
**Trigger:** GET /v1/auth/registration returns { open: true }.
Route: `/login`. API: GET /v1/auth/registration (pending) · POST /v1/auth/login.
- Relied on an API marked pending in the design; that API now exists.
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"
- Field `Password`: password with show/hide; link "Forgot password?"
- Submit button: "Log in"
- Footer: First time here? [Create the owner account]
After logging in, you go back to the page you originally asked for (?redirect=), or to /home. An unverified account goes to /register/pending. "Create the owner account" appears only when registration is open.
### Validation errors
**Trigger:** Submit with a short username and an empty password. Nothing is sent.
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"; value "ma"; **error "Use at least 3 characters."**
- Field `Password`: password with show/hide; link "Forgot password?"; **error "Enter your password."**
- Submit button: "Log in"
### Submitting
**Trigger:** The request is in flight. Fields and button are disabled.
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"; value "marta"
- Field `Password`: value "limewash2026"; password with show/hide; link "Forgot password?"
- Submit button: "Logging in…", loading
### Wrong credentials (403)
**Trigger:** The API doesn't say which field is wrong, so neither does the message. The password is cleared and gets focus.
- Alert (error, circle-x): **That username and password don't match** "Check both and try again. Passwords are case-sensitive."
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"; value "marta"
- Field `Password`: password with show/hide; focused; link "Forgot password?"
- Submit button: "Log in"
### Too many attempts (429)
**Trigger:** Retry-After is counted down. The button re-enables at zero.
- Relied on an API marked pending in the design; that API now exists.
- Alert (info, timer): **Too many attempts** "For your security, wait a moment before trying again."
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"; value "marta"
- Field `Password`: value "limewash"; password with show/hide; link "Forgot password?"
- Submit button: "Try again in 0:42", disabled
### Session expired
**Trigger:** Redirected from a 401 with ?redirect=/article/12/edit&reason=expired. Unsaved edits are kept in the browser.
- Alert (info, clock): **Your session expired** "Log in again to pick up where you left off. Unsaved changes are kept on this device."
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"; value "marta"
- Field `Password`: password with show/hide; focused; link "Forgot password?"
- Submit button: "Log in"
### Password changed
**Trigger:** Arrived from a successful reset with ?reason=password-changed.
- Alert (success, circle-check): **Password changed** "Log in with your new password."
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"
- Field `Password`: password with show/hide; link "Forgot password?"
- Submit button: "Log in"
### Server or network error
**Trigger:** A 500 or no response. The fields keep their values.
- Alert (error, circle-x): **Couldn't reach RenewCMS** "Check your connection and try again."
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"; value "marta"
- Field `Password`: value "limewash2026"; password with show/hide; link "Forgot password?"
- Submit button: "Log in"
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | Registration is closed, which is the usual case. | |
| 2 | Fresh install | GET /v1/auth/registration returns { open: true }. | "First time here?" / "Create the owner account" |
| 3 | Validation errors | Submit with a short username and an empty password. Nothing is sent. | "Use at least 3 characters." / "Enter your password." |
| 4 | Submitting | The request is in flight. Fields and button are disabled. | "Logging in…" |
| 5 | Wrong credentials (403) | The API doesn't say which field is wrong, so neither does the message. The password is cleared and gets focus. | "That username and password don't match" / "Check both and try again. Passwords are case-sensitive." |
| 6 | Too many attempts (429) | Retry-After is counted down. The button re-enables at zero. | "Too many attempts" / "For your security, wait a moment before trying again." / "Try again in 0:42" |
| 7 | Session expired | Redirected from a 401 with ?redirect=/article/12/edit&reason=expired. Unsaved edits are kept in the browser. | "Your session expired" / "Log in again to pick up where you left off. Unsaved changes are kept on this device." |
| 8 | Password changed | Arrived from a successful reset with ?reason=password-changed. | "Log in with your new password." |
| 9 | Server or network error | A 500 or no response. The fields keep their values. | "Couldn't reach RenewCMS" / "Check your connection and try again." |
docs/design/screens/media-picker.md
+33 -42
View File
@@ -1,56 +1,47 @@
# Media picker (editor)
# Media picker
- **Route:** `/article/:id/edit` (inside the editor's existing "Add an image" dialog)
- **API:** GET /v1/media/?q=&limit=&cursor= · POST /v1/media/ (same as the Media page)
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Media picker", drawn by `source/MediaFrame.dc.html`.
Route: `/article/:id/edit`, `/articles/{id}/edit`. API: GET /v1/media/?q=&limit=&cursor= · POST /v1/media/ (same as the Media page) · Inserted URL: /media/{file}?v={name}.
The existing "Add an image" dialog gains two tabs, Upload and Library. The Upload tab is the current flow unchanged, so it still offers crop and resize, and a new image lands in the library and is inserted as before. The Library tab opens on the Library tab when the library has images and on Upload when it is empty. Images load 24 at a time with "Load more". Newest first, and images already in this article carry "In this article". Alt text is set here and lives only in the article. The dialog is 640 px wide on desktop and a bottom sheet on mobile.
This supersedes the upload-only "Add an image" dialog described in [editor](editor.md), and the "Remove this image?" confirmation from `features/editor_image_removal.feature`.
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Media picker", "Editor picker". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
## Dialog
## Copy per state (generated from the board source, pass 2)
Title "Add an image", `x` to close, 640 px wide on desktop (bottom sheet on mobile). Two tabs under the title: **Upload** (`upload` icon) and **Library** (`images` icon). The dialog opens on Library when the library has images and on Upload when it is empty; dropping a file onto the editor opens Upload with the file provided, as before. Footer: "Cancel", and on Library a primary "Insert image", disabled until an image is selected.
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.
**Upload tab.** The current flow unchanged (drop zone "Drop an image here, or choose a file", help "PNG, JPEG, WEBP, SVG · max 10 MB", crop and resize, rejected, uploading and failed states). Two changes: the new image lands in the library and is inserted as before, and a chosen file whose content matches an existing image sends nothing and shows an info-bordered card: thumbnail, "Already in your library", `north-wall.jpg matches an image uploaded on 12 Sep 2026 by Marta Alves.`, with "Use existing" (primary) and "Upload anyway". "Use existing" goes to the alt text step for the existing image; "Upload anyway" continues to crop and upload.
### Picker in the editor (group "Media picker", 13 states)
**Library tab.** Search field ("Search by filename"), the line "Newest first · 48 images", a grid of square tiles (4 columns on desktop, 3 on mobile; scrolls inside the dialog) with the filename under each, and "Load more" below (24 images per page). Tiles are buttons labelled with filename, size and use; Enter or Space selects (single selection). A tile of an image already in this article carries a sand "In this article" tag. The selected tile gets a primary outline and a check. Once one is selected, the grid shrinks and a panel appears below it: 56 px thumbnail, filename, `dimensions · size`, and a field "Alt text (optional)" with placeholder "e.g. North wall of the kitchen before plastering" and help "Describes the image for people who use a screen reader, and shows if it doesn't load. Leave it empty if the image is only decoration." Alt text lives only in the article, never on the image.
Route: `/article/:id/edit`. API: GET /v1/media/?q=&limit=&cursor= · POST /v1/media/ (same as the Media page).
| Library state | Copy |
|---|---|
| Empty | `images` icon, "Your library is empty" / "Images you upload appear here, ready to use in any article." / "Upload an image" (switches to Upload) |
| No results | `search` icon, `No images match "wall"` / "Check the spelling, or search for a shorter part of the filename." / "Clear search" |
| Failed | error alert "Couldn't load your library" / "Check your connection and try again." / "Try again" |
| Loading more | button reads "Loading…" with a loader, skeleton tiles at the end |
The existing "Add an image" dialog gains two tabs, Upload and Library. The Upload tab is the current flow unchanged, so it still offers crop and resize, and a new image lands in the library and is inserted as before. The Library tab opens on the Library tab when the library has images and on Upload when it is empty. Images load 24 at a time with "Load more". Newest first, and images already in this article carry "In this article". Alt text is set here and lives only in the article. The dialog is 640 px wide on desktop and a bottom sheet on mobile.
Insert (either tab): the image goes in at the cursor with the chosen alt text (empty alt means decorative), the draft becomes "Unsaved changes", and a toast appears: `circle-check`, "Image added" / "Save to keep it in the article." The dialog then closes.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Upload tab | The image button in the toolbar. Identical to the current "Add an image" content; only the tabs are new. Rejected, uploading and failed states are unchanged. | "Upload" |
| 2 | Upload tab: already in your library | A chosen file has the same content as an existing image. Nothing is sent. "Use existing" inserts the existing image (the alt text step follows); "Upload anyway" continues to crop and upload as usual. | "Upload" |
| 3 | Library: loading | The Library tab was opened, or a search changed. Skeleton tiles after 150 ms. | |
| 4 | Library: nothing selected | Newest first. Tiles are buttons labelled with filename, size and use, and Enter or Space selects. Images already in this article carry "In this article". "Insert image" is disabled. | |
| 5 | Library: selected | One image selected (single selection). Below the grid: thumbnail, filename, dimensions and size, and an optional alt text field. "Insert image" turns on. | |
| 6 | Library: alt text entered | Alt text is optional. Empty alt text is inserted as a decorative image. It is not saved on the image. | "A kitchen with new oak worktops and white tiles" |
| 7 | Library: loading more | "Load more" pressed. The button shows progress and new skeleton tiles appear at the end. Focus stays on the button until the new tiles arrive, then moves to the first new tile. | |
| 8 | Library: empty | Zero images. "Upload an image" switches to the Upload tab. | |
| 9 | Library: no results | Search matched nothing. "Clear search" resets it. | |
| 10 | Library: failed to load | A 500 or network failure. The error shows in the dialog and Try again repeats the request. A 429 uses the same countdown alert as the Media page, and a 401 is handled globally. | |
| 11 | Inserted | Insert image from either tab. The image goes in at the cursor with the chosen alt text, and the article now has unsaved changes. | "Image added" / "Save to keep it in the article." |
| 12 | Remove image: confirm | Remove image on an image in the article. It now only removes it from this article, and the copy says the file stays in the library. The confirm button is neutral, not red, because nothing is deleted. Title: "Remove this image from the article?" | |
| 13 | Removed | Confirmed. The image leaves the article body, which now has unsaved changes. | "Image removed" / "It's still in your library." |
## Removing an image from the article
### 6. Editor image picker (group "Editor picker", 5 states)
The "Remove image" button on a selected image in the editor (and Backspace or Delete on it) now opens a neutral (not red) confirm, because nothing is deleted:
Route: `/articles/{id}/edit`. API: Inserted URL: /media/{file}?v={name}.
- Title: "Remove this image from the article?"
- Description: "It's removed from this article only. The file stays in your library and in any other article that uses it."
- Body: thumbnail, filename, "Stays in the library · 3.9 MB"
- Buttons: "Cancel" / "Remove image"
- Done: the image leaves the body, the draft becomes "Unsaved changes", and a toast appears: `circle-check`, "Image removed" / "It's still in your library."
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.
No API call is made. Removing is a body edit only.
## States
| State | Trigger and behaviour |
|---|---|
| Upload tab | The image button in the toolbar. Identical to the current "Add an image" content; only the tabs are new. Rejected, uploading and failed states are unchanged. |
| Upload tab: already in your library | A chosen file has the same content as an existing image. Nothing is sent. "Use existing" inserts the existing image (the alt text step follows); "Upload anyway" continues to crop and upload as usual. |
| Library: loading | The Library tab was opened, or a search changed. Skeleton tiles after 150 ms. |
| Library: nothing selected | Newest first. Tiles are buttons labelled with filename, size and use, and Enter or Space selects. Images already in this article carry "In this article". "Insert image" is disabled. |
| Library: selected | One image selected (single selection). Below the grid: thumbnail, filename, dimensions and size, and an optional alt text field. "Insert image" turns on. |
| Library: alt text entered | Alt text is optional. Empty alt text is inserted as a decorative image. It is not saved on the image. |
| Library: loading more | "Load more" pressed. The button shows progress and new skeleton tiles appear at the end. Focus stays on the button until the new tiles arrive, then moves to the first new tile. |
| Library: empty | Zero images. "Upload an image" switches to the Upload tab. |
| Library: no results | Search matched nothing. "Clear search" resets it. |
| Library: failed to load | A 500 or network failure. The error shows in the dialog and Try again repeats the request. A 429 uses the same countdown alert as the Media page, and a 401 is handled globally. |
| Inserted | Insert image from either tab. The image goes in at the cursor with the chosen alt text, and the article now has unsaved changes. |
| Remove image: confirm | Remove image on an image in the article. It now only removes it from this article, and the copy says the file stays in the library. The confirm button is neutral, not red, because nothing is deleted. Title: "Remove this image from the article?" |
| Removed | Confirmed. The image leaves the article body, which now has unsaved changes. |
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Variant select | An image is selected. The URL line shows what will be inserted. | "Articles" / "How we price a bathroom renovation" / "Edit article" |
| 2 | Select open | Original plus five enabled variants. | "Articles" / "How we price a bathroom renovation" / "Edit article" |
| 3 | No variants defined | Only Original is offered. | "Articles" / "How we price a bathroom renovation" / "Edit article" |
| 4 | Variant deleted | The block keeps its URL. Pick another variant opens the select. | "Articles" / "How we price a bathroom renovation" / "Edit article" / "Variant 'hero' no longer exists." |
| 5 | Variant disabled | Same block, different cause. Proposed copy. | "Articles" / "How we price a bathroom renovation" / "Edit article" / "Variant 'hero' is disabled." |
docs/design/screens/media.md
+83 -141
View File
@@ -1,164 +1,106 @@
# Media
- **Route:** `/media` (verified users)
- **API:** GET /v1/media/purge-preview · POST /v1/media/purge · GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Media", drawn by `source/MediaFrame.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
The library of every uploaded image. It replaces "images belong to one article": an image belongs to the library and can be used in any number of articles. Deleting an article never deletes images. The sidebar gains **Media** (`images` icon) between Articles and Users, breadcrumb "Media".
Route: `/media`, `/media (detail panel)`, `/media?filter=duplicates`. API: GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage · GET /v1/media?variants=with|without&sort=total_size · GET /v1/media/{id}/variants · POST /v1/media/{id}/variants/{name} · DELETE /v1/media/{id}/variants/{name} · owner and admin only.
New route for verified users, in the sidebar between Articles and Users with the images icon. Images belong to the library, not to an article: one image can be used in many articles, and deleting an article never deletes images. Uploads from this page are not cropped or resized, and the file is stored as chosen. "Used in" is read from article bodies each time the list loads. Duplicates are images with identical content, whatever their filenames. Alt text is not stored on the image; it is set when inserting into an article. Search, filter, sort and view are stored in the query string. Keyboard: grid items are buttons in one tab stop each; Enter opens the detail panel, Space toggles selection, and Escape closes the panel or clears the selection. Selection changes are announced ("north-wall.jpg selected, 1 selected").
## Layout
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Media", "Media library", "Image detail", "Media duplicates entry". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
Header: title "Media", subtitle "Every image you've uploaded, ready to use in any article.", primary "Upload" button (`upload` icon) on the right. On mobile the button is a full-width 48 px button pinned to the bottom (it turns into "Try again in 0:42" while rate limited, and is replaced by the bulk bar while items are selected).
## Copy per state (generated from the board source, pass 2)
Toolbar: tabs **All**, **Unused** and **Duplicates** (count badge of duplicate groups, only while groups exist), then search ("Search by filename"), sort and the grid/list toggle. Sort options: Newest (default), Oldest, Name, Largest. On the Duplicates tab, owners and admins also get a secondary "Purge duplicates" button (`merge` icon) after the sort menu (full width, 44 px, in the stacked toolbar on mobile), hidden while there are no groups; it opens the PurgeDuplicatesDialog described in [settings](settings.md#media-cleanup-second-card). Below md the toolbar stacks: search, tabs, then sort and toggle.
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.
Grid (default): 5 columns on desktop, 2 on mobile, 16 px gap (10 px on mobile). Each card is one button: 4:3 thumbnail (checkerboard behind transparent PNG and SVG), filename (medium, ellipsis), `size · dimensions` (SVG dimensions read "Vector"), then badges. The accessible name reads "north-wall.jpg, 3.9 MB, used in 2 articles" or "…, unused". A "Select all" row with the image count sits above the grid.
### Media (group "Media", 43 states)
| Badge | Look |
|---|---|
| Unused | warning-soft fill, `unlink` icon |
| Duplicate | info-soft fill, `copy` icon |
| Used in N | outline, toned text |
Route: `/media`. API: GET /v1/media/ · POST /v1/media/ · PATCH /v1/media/{id} · DELETE /v1/media/{id} · POST /v1/media/merge · GET /v1/media/{id}/usage.
List view: table from md up, columns Filename (with 40 px thumbnail and Duplicate badge), Dimensions, Size, Type, Used in (underlined count, opens the detail panel), Uploaded by, Uploaded (sorted, `arrow-down`); 56 px rows, 36 px header, first column is the checkbox. Below md it is a card list with a 44 px checkbox column, a 56 px thumbnail, filename, `size · dimensions · type`, badges plus `uploader · date`, and a trailing `chevron-right`.
New route for verified users, in the sidebar between Articles and Users with the images icon. Images belong to the library, not to an article: one image can be used in many articles, and deleting an article never deletes images. Uploads from this page are not cropped or resized, and the file is stored as chosen. "Used in" is read from article bodies each time the list loads. Duplicates are images with identical content, whatever their filenames. Alt text is not stored on the image; it is set when inserting into an article. Search, filter, sort and view are stored in the query string. Keyboard: grid items are buttons in one tab stop each; Enter opens the detail panel, Space toggles selection, and Escape closes the panel or clears the selection. Selection changes are announced ("north-wall.jpg selected, 1 selected").
Selection: selected items take the sand fill (`--rc-sand`) with a primary outline. The checkbox shows on hover, on keyboard focus, on mobile, and whenever anything is selected. The bulk bar is sticky at the bottom (400 px wide on desktop, full width above the bottom edge on mobile): inverted fill, "3 selected", a danger "Delete" button (`trash-2`) and an inverted "Clear".
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Grid, many images | Default view. 12 images, newest first. Each item is a button labelled like "north-wall.jpg, 3.9 MB, used in 2 articles". Badges: "Unused" (warm), "Duplicate" (info), "Used in N" (outline). The Duplicates tab carries a count of groups only while duplicates exist. | |
| 2 | Grid, few images | Three images. Cards keep their size instead of stretching. Checkerboard shows behind the SVG. | |
| 3 | List view | The list icon in the toggle. A table from md up (Filename, Dimensions, Size, Type, Used in, Uploaded by, Uploaded) and a card list below md. The "Used in" count opens the article list in the detail panel. | |
| 4 | Loading | The first load, a retry, or a change of search or filter. Skeleton cards appear after 150 ms. | |
| 5 | Empty library, first run | Zero images. Toolbar and tabs are hidden; one call to action. Copy: "No images yet" / "Upload your first image. You can use it in any article." / "Upload an image". | |
| 6 | No results | Search or filter matched nothing. "Clear filters" resets the search and goes back to All. | |
| 7 | Hover, focus and keyboard | Hover (second item) darkens the border, adds the pop shadow and reveals the checkbox. Keyboard focus (third item) shows the 2 px primary ring with a 2 px offset and reveals the checkbox. Tab moves between items, Enter opens the detail panel, Space toggles selection, and arrow keys move focus across the grid. | "aria-label: kitchen-before.webp, 1.1 MB, used in 1 article" |
| 8 | Selection and bulk bar | Checkbox on any item, or Space. Selected items take the sand fill with a primary outline, and Select all shows a partial state. The bar is sticky at the bottom (above the bottom edge on mobile, replacing the Upload button). Announced: "3 selected". Escape or Clear empties it. | |
| 9 | Bulk delete: confirm | Delete in the bulk bar. The dialog says how many of the selection are in use and lists them. The confirm button carries the count. | |
| 10 | Bulk delete: in progress | Requests in flight. The dialog can't be dismissed. | |
| 11 | Bulk delete: partly failed | Some requests failed. Deleted images leave the grid, failed ones stay selected, and the toast stays until retried or dismissed. | "Couldn't delete 1 image" / "2 images were deleted. window-frame.jpg is still in your library. Try again." / "Retry" |
| 12 | Bulk delete: done | 204 for all. Focus moves to the next item. | "3 images deleted" / "They're gone from your library." |
| 13 | Detail panel: in use | Click or Enter on an item. Right-hand slideover on desktop, full screen on mobile with a back arrow. Actions: Copy URL, Rename, Delete. "Used in 2 articles" lists title, Online or Draft, and links to the editor. Focus returns to the item on close. | |
| 14 | Detail panel: unused | Used in nothing. The section reads "Not used in any article" and says the image is safe to delete. | |
| 15 | Detail panel: duplicate | The image has identical copies. An info alert links to the duplicates view. | |
| 16 | Copy URL | Copy URL. Clipboard write succeeded. Success toasts last 5 s. | "URL copied" / "Paste it wherever you need the image address." |
| 17 | Rename: dialog | Rename in the panel. The field holds the name without its extension, and the .jpg ending is fixed. The description says the URL stays the same. | |
| 18 | Rename: saving | PATCH in flight. Field and buttons disabled, dialog can't be dismissed. | |
| 19 | Rename: validation | Empty or only symbols, on submit or blur. Nothing is sent. | "Enter a filename." |
| 20 | Rename: failed | 500 or network failure. The error shows inside the dialog. | "Couldn't rename the image. Your text is still here. Try again in a moment." |
| 21 | Rename: done | 200: the panel title and list update in place. | "Image renamed" / "It's now "north-wall-01.jpg". The URL is the same." |
| 22 | Delete: unused image | Delete in the panel. Plain confirm. Says what happens and that it can't be undone. | |
| 23 | Delete: image in use | Stronger confirm. Lists the affected articles and states that they will show a broken image. | "delUsed" |
| 24 | Delete: in progress | DELETE in flight. The dialog can't be dismissed. | "delUsed" |
| 25 | Delete: failed | 500 or network failure. The error shows inside the dialog, as in the article delete. | "Couldn't delete the image, so it's still there. Try again in a moment." |
| 26 | Delete: done | 204: the panel closes, the item leaves the grid and focus moves to the next item. | "Image deleted" / ""window-frame.jpg" is gone from your library." |
| 27 | Image already gone (404) | Any action on an image that was deleted elsewhere. The panel closes and the item leaves the list. | "That image no longer exists" / "It was deleted somewhere else, so we removed it from the library." |
| 28 | Upload: drag over the page | Files dragged onto the page. A dashed drop area covers the content. Dropping starts the upload straight away; there is no crop step on this page. | |
| 29 | Upload: several files, mixed | Upload button or drop, several files. Each file has its own row and progress. Files upload two at a time. A row can end as added, "Already in your library", rejected in the browser, or failed. Rejected and failed rows stay until dismissed. | "2.2 MB" / "2.6 MB" / "1.1 of 2.6 MB" / "1.9 MB" |
| 30 | Upload: summary | All rows settled. The summary counts each outcome. "Use existing" selects the existing image and drops the row; "Upload anyway" stores a second copy, which then appears under Duplicates. "Try again" retries one file. Announced when it finishes. | "2.2 MB" / "2.6 MB" / "Upload finished" / "5 images" / "2 uploaded · 1 already in your library · 2 need attention" |
| 31 | Upload: rejected files (413, 400) | Type and size are checked in the browser first, so nothing is sent. A server 413 or 400 for a file that got through shows the same row with its own message. | "210 KB" / "notes.pdf isn't an image" / "Images can be up to 10 MB. Use a PNG, JPEG, WEBP or SVG image." / "3.0 MB" / "broken.png couldn't be read" / "The server couldn't read this image. Save it again as a PNG or JPEG, then try again." / "Nothing was uploaded" / "3 files were rejected" |
| 32 | Upload: too many requests (429) | Rate limited. Retry-After is counted down in the button. It re-enables at zero. Already-added files are kept. | |
| 33 | Duplicates: groups | The Duplicates tab. Groups of identical images side by side, each with its uploader, upload date and "Used in N articles". The suggested copy to keep is the most used, then the oldest. | |
| 34 | Purge duplicates: confirm | "Purge duplicates" in the toolbar, next to the sort menu (in the stacked toolbar on mobile). Opens the same dialog as Settings; every other state is on the Media cleanup board. | |
| 35 | Duplicates: no purge button (member) | Verified users who are not owner or admin. The "Purge duplicates" button is hidden. "Merge into this one" is unchanged. | |
| 36 | Duplicates: empty | No groups. The Duplicates tab loses its count badge. | |
| 37 | Merge: confirm | "Merge into this one" on floorboards.jpg. The dialog says articles using the other copies will switch to this image and the other copies will be deleted, with the article count. | |
| 38 | Merge: in progress | Request in flight. The dialog can't be dismissed. | |
| 39 | Merge: failed | 500 or network failure. Nothing is switched or deleted. | "Couldn't merge the copies. Nothing was changed. Try again in a moment." |
| 40 | Merge: conflict (409) | A copy was deleted, or a new copy appeared, since the page loaded. | "One of these images changed, so nothing was merged. The list is up to date now. Check it and try again." |
| 41 | Merge: done | 200: the group leaves the list. When it was the last one, "No duplicates" shows. | "Copies merged" / "2 copies merged. 5 articles updated." |
| 42 | List failed to load | A 500 or network failure on the list request. The alert replaces the images; Try again repeats the request. | |
| 43 | Offline | navigator.onLine is false. Loaded images stay browsable. Upload, Rename, Delete and Merge are disabled, and the banner says why. | |
Detail panel: right-hand slideover 460 px wide on desktop (`x` to close), full screen on mobile with an `arrow-left`. Title is the filename. Body: 16:10 preview (4:3 on mobile), actions Copy URL (`link`), Rename (`pencil`), Delete (`trash-2`, error text), an info alert for duplicates, a metadata list (Type, Size, Dimensions, Uploaded, Uploaded by, URL in mono), then the "Used in" section.
### 3. Media library (group "Media library", 6 states)
Detail panel copy:
Route: `/media`. API: GET /v1/media?variants=with|without&sort=total_size.
| Where | Copy |
|---|---|
| Duplicate alert | "Identical to 2 other images" / "floorboards-copy.jpg and IMG_2208.jpg have the same content." / action "Review duplicates" (`arrow-right`) |
| Used | "Used in 2 articles", then one row per article: title (underlined link to the editor), badge "Online" (`globe`, inverted) or "Draft" (`pencil-line`, outline), `arrow-up-right`. Footnote: "Counted from the text of your articles each time you open this page." |
| Not used | "Not used in any article" / "This image is safe to delete. No article shows it." |
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.
## Image variants
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Grid with badges | Default view. Images with no cached variants have no badge. | "New: badge" |
| 2 | Sort menu | The sort select is open. The new option is last. | "New: sort option" |
| 3 | Filter: With variants, sorted by total size | The meta line becomes total · original + variants. | "With variants" |
| 4 | Filter: Without variants | Images no variant has been generated for. | "Without" |
| 5 | Filter: nothing to show | With variants, and the cache is empty. | "With variants" |
| 6 | Delete confirm | Delete on an image that has cached variants. | "deleteImage" |
The Library gains a "N variants" badge, an All / With variants / Without filter, the sort option "Largest total size (original + variants)", a delete dialog that names the generated variants it removes, and a Variants tab in the detail panel. Those states are in [image-variants](image-variants.md), sections 3 and 4.
### 4. Image detail: Variants tab (group "Image detail", 8 states)
## Dialogs
Route: `/media (detail panel)`. API: GET /v1/media/{id}/variants · POST /v1/media/{id}/variants/{name} · DELETE /v1/media/{id}/variants/{name}.
All dialogs use the existing ConfirmDialog look (`UModal`, `sm:max-w-md`, bottom sheet on mobile, cancel first). While a request runs the confirm button shows a `loader-circle`, both buttons are disabled and the dialog cannot be dismissed. A failure shows an error alert at the top of the dialog body and the dialog stays open.
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.
| Dialog | Title | Description | Body | Cancel / Confirm (pending) |
|---|---|---|---|---|
| Rename | "Rename image" | "Only the filename changes. The URL stays the same, so articles that use this image keep working." | Field "Filename" with the extension fixed as a mono suffix (`.jpg`); help "Letters, numbers, dashes and underscores. The .jpg ending stays."; error "Enter a filename." on empty or only symbols | "Cancel" / "Rename" ("Renaming…") |
| Delete, unused | "Delete this image?" | ""window-frame.jpg" will be deleted from your library. No article uses it. This can't be undone." | none | "Cancel" / "Delete image" ("Deleting…"), danger |
| Delete, in use | "Delete an image that's in use?" | ""north-wall.jpg" is used in 2 articles. If you delete it, they will show a broken image. This can't be undone." | list of affected articles with Online or Draft badges | "Cancel" / "Delete image" ("Deleting…"), danger |
| Bulk delete | "Delete 3 images?" | "2 of them are used in 4 articles, which will show a broken image. The other one isn't used anywhere. This can't be undone." | one row per image: filename and "Used in N" or "Unused" | "Cancel" / "Delete 3 images" ("Deleting…"), danger |
| Merge | "Merge into floorboards.jpg?" | "Articles that use the other 2 copies will be switched to floorboards.jpg, and the other 2 copies will be deleted. 5 articles will be updated. This can't be undone." | the kept image: thumbnail, filename, "Kept · used in 4 articles now" | "Cancel" / "Merge 2 copies" ("Merging…"), danger |
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Partly generated | Four of five generated. Saving is shown against the original. | |
| 2 | Nothing generated yet | No cached files for this image. | |
| 3 | Generating | Generate all or Generate now was pressed. Rows show a spinner. | |
| 4 | Generation failed | The row shows the cause and Retry. Both causes are shown together for reference. | "Unsupported source format" / "Image too large" |
| 5 | No variants defined | There are no enabled variants. | |
| 6 | Source is an SVG | Variants aren't generated for vector images. | "SVG images are served as they are." |
| 7 | Source is an animated GIF | Same rule as SVG. | "Animated GIFs are served as they are." |
| 8 | Preview dialog | Preview on a generated row. Both at actual size. | |
Dialog errors: rename "Couldn't rename the image. Your text is still here. Try again in a moment."; delete "Couldn't delete the image, so it's still there. Try again in a moment."; merge (500) "Couldn't merge the copies. Nothing was changed. Try again in a moment."; merge (409) "One of these images changed, so nothing was merged. The list is up to date now. Check it and try again."
### Media: Duplicates tab entry point (group "Media duplicates entry", 2 states)
## Upload panel
Route: `/media?filter=duplicates`. API: owner and admin only.
A panel above the images while files are in flight and until dismissed. Header: "Uploading 6 images" with "2 of 6 done" and "Cancel all" (after it settles: "Upload finished" / "5 images" and "Dismiss"; if nothing was added: "Nothing was uploaded"). Files upload two at a time, one row each: 40 px thumbnail, filename, size, then per status:
A secondary "Purge duplicates" button (icon merge) in the toolbar next to the sort menu, and in the stacked toolbar on mobile. The dialog and the member state are listed with the Media states above. Per-group "Merge into this one" is unchanged.
| Status | Row |
|---|---|
| Waiting | "Waiting" |
| Uploading | "Uploading 1.1 of 2.6 MB" with a 4 px progress bar and a cancel `x` |
| Added | `circle-check` "Added to your library" |
| Duplicate | "Already in your library" / `Same as "floorboards.jpg", uploaded 14 Jun 2026 by Inès Duarte.` / "Use existing" and "Upload anyway" |
| Rejected | `file-x` title, then "Images can be up to 10 MB. Use a PNG, JPEG, WEBP or SVG image." Titles: `scan.tif is 14.2 MB` (too large), `notes.pdf isn't an image` (type), `broken.png couldn't be read` with "The server couldn't read this image. Save it again as a PNG or JPEG, then try again." (400) |
| Failed | `circle-x` "Upload failed" / "The server didn't accept the file. Nothing was added to your library." / "Try again" (`rotate-cw`) |
Summary line when settled: "2 uploaded · 1 already in your library · 2 need attention". Type and size are checked in the browser before anything is sent (PNG, JPEG, WEBP, SVG; 10 MB), by MIME type and by extension, exactly as the editor's uploader does. Dropping files onto the page shows a dashed primary-bordered area "Drop images to upload" / "PNG, JPEG, WEBP, SVG · max 10 MB each".
## Duplicates view
Groups stacked with 16 px gap. Each group is a bordered card: header "Group 1" and "3 identical images · 2.4 MB each · 3600 × 2400"; one column per copy (stacked on mobile) with thumbnail, filename, "Uploaded 14 Jun 2026 by Inès Duarte", underlined "Used in 4 articles", and a "Merge into this one" button (`merge` icon). The suggested copy has the sand fill, a primary outline, a "Suggested" tag and a primary button; the others are outline. Footer: "Suggested: the most used copy, then the oldest. Choosing another copy switches articles to it." Empty: `copy` icon, "No duplicates" / "Every image in your library is different." / "Back to all images".
## Other copy
| Where | Copy |
|---|---|
| Empty library | `images` icon, "No images yet" / "Upload your first image. You can use it in any article." / primary "Upload an image"; under it "PNG, JPEG, WEBP, SVG · max 10 MB each" |
| No results | `search` icon, `No images match "wall"` / "Nothing matches in Unused. Check the spelling, or clear the filters." / "Clear filters" |
| List error | error alert "Couldn't load your images" / "Check your connection and try again." / "Try again" |
| Rate limited | info alert `timer` "Too many uploads" / "For your security, wait a moment before uploading again."; the Upload button reads "Try again in 0:42" and is disabled |
| Offline banner | `wifi-off` "You're offline. You can look through the images that are loaded, but uploading, renaming and deleting need a connection." |
Toasts (success 5 s unless noted):
| Trigger | Icon, title, description |
|---|---|
| Copy URL | `circle-check` "URL copied" / "Paste it wherever you need the image address." |
| Rename | `circle-check` "Image renamed" / `It's now "north-wall-01.jpg". The URL is the same.` |
| Delete | `circle-check` "Image deleted" / `"window-frame.jpg" is gone from your library.` |
| Bulk delete | `circle-check` "3 images deleted" / "They're gone from your library." |
| Bulk delete, partial | error, stays until retried or dismissed: `circle-x` "Couldn't delete 1 image" / "2 images were deleted. window-frame.jpg is still in your library. Try again." / "Retry" |
| Merge | `circle-check` "Copies merged" / "2 copies merged. 5 articles updated." |
| 404 | info `info` "That image no longer exists" / "It was deleted somewhere else, so we removed it from the library." |
## Status to copy
| Status | Where | Copy |
|---|---|---|
| 200 / 201 | Upload, rename, merge | Upload: row reads "Added to your library". Rename and merge: toasts above. |
| 204 | Delete, bulk delete | Toasts above. |
| 400 | Upload row | "broken.png couldn't be read" / "The server couldn't read this image. Save it again as a PNG or JPEG, then try again." In a dialog: "Something in the form isn't valid. Check the highlighted fields." |
| 401 | any | Global: /login?redirect=/media&reason=expired. No local copy. |
| 403 | any, unverified | Global: /register/pending. |
| 404 | rename, delete, merge, panel | The info toast above; the panel or dialog closes. |
| 409 | merge | Dialog alert above. |
| 413 | upload row | "scan.tif is 14.2 MB" / "Images can be up to 10 MB. Use a PNG, JPEG, WEBP or SVG image." |
| 415 | upload row | "notes.pdf isn't an image" / same description. |
| 429 | upload | Rate-limited alert above, counting down Retry-After. |
| 500 / network | list, upload row, rename, delete, merge | The copy for each place above. |
| Offline | whole page | Banner above. |
## Keyboard and accessibility
Grid items are buttons, one tab stop each. Enter opens the detail panel, Space toggles selection, arrow keys move focus across the grid, Escape closes the panel or clears the selection. Focus returns to the item when the panel closes, and moves to the next item after a delete. Selection changes are announced ("north-wall.jpg selected, 1 selected"), as are upload completion and the merge result. Search, filter, sort and view live in the query string.
## States
| State | Trigger and behaviour |
|---|---|
| Grid, many images | Default view. 12 images, newest first. Each item is a button labelled like "north-wall.jpg, 3.9 MB, used in 2 articles". Badges: "Unused" (warm), "Duplicate" (info), "Used in N" (outline). The Duplicates tab carries a count of groups only while duplicates exist. |
| Grid, few images | Three images. Cards keep their size instead of stretching. Checkerboard shows behind the SVG. |
| List view | The list icon in the toggle. A table from md up (Filename, Dimensions, Size, Type, Used in, Uploaded by, Uploaded) and a card list below md. The "Used in" count opens the article list in the detail panel. |
| Loading | The first load, a retry, or a change of search or filter. Skeleton cards appear after 150 ms. |
| Empty library, first run | Zero images. Toolbar and tabs are hidden; one call to action. Copy: "No images yet" / "Upload your first image. You can use it in any article." / "Upload an image". |
| No results | Search or filter matched nothing. "Clear filters" resets the search and goes back to All. |
| Hover, focus and keyboard | Hover (second item) darkens the border, adds the pop shadow and reveals the checkbox. Keyboard focus (third item) shows the 2 px primary ring with a 2 px offset and reveals the checkbox. Tab moves between items, Enter opens the detail panel, Space toggles selection, and arrow keys move focus across the grid. |
| Selection and bulk bar | Checkbox on any item, or Space. Selected items take the sand fill with a primary outline, and Select all shows a partial state. The bar is sticky at the bottom (above the bottom edge on mobile, replacing the Upload button). Announced: "3 selected". Escape or Clear empties it. |
| Bulk delete: confirm | Delete in the bulk bar. The dialog says how many of the selection are in use and lists them. The confirm button carries the count. |
| Bulk delete: in progress | Requests in flight. The dialog can't be dismissed. |
| Bulk delete: partly failed | Some requests failed. Deleted images leave the grid, failed ones stay selected, and the toast stays until retried or dismissed. |
| Bulk delete: done | 204 for all. Focus moves to the next item. |
| Detail panel: in use | Click or Enter on an item. Right-hand slideover on desktop, full screen on mobile with a back arrow. Actions: Copy URL, Rename, Delete. "Used in 2 articles" lists title, Online or Draft, and links to the editor. Focus returns to the item on close. |
| Detail panel: unused | Used in nothing. The section reads "Not used in any article" and says the image is safe to delete. |
| Detail panel: duplicate | The image has identical copies. An info alert links to the duplicates view. |
| Copy URL | Copy URL. Clipboard write succeeded. Success toasts last 5 s. |
| Rename: dialog | Rename in the panel. The field holds the name without its extension, and the .jpg ending is fixed. The description says the URL stays the same. |
| Rename: saving | PATCH in flight. Field and buttons disabled, dialog can't be dismissed. |
| Rename: validation | Empty or only symbols, on submit or blur. Nothing is sent. |
| Rename: failed | 500 or network failure. The error shows inside the dialog. |
| Rename: done | 200: the panel title and list update in place. |
| Delete: unused image | Delete in the panel. Plain confirm. Says what happens and that it can't be undone. |
| Delete: image in use | Stronger confirm. Lists the affected articles and states that they will show a broken image. |
| Delete: in progress | DELETE in flight. The dialog can't be dismissed. |
| Delete: failed | 500 or network failure. The error shows inside the dialog, as in the article delete. |
| Delete: done | 204: the panel closes, the item leaves the grid and focus moves to the next item. |
| Image already gone (404) | Any action on an image that was deleted elsewhere. The panel closes and the item leaves the list. |
| Upload: drag over the page | Files dragged onto the page. A dashed drop area covers the content. Dropping starts the upload straight away; there is no crop step on this page. |
| Upload: several files, mixed | Upload button or drop, several files. Each file has its own row and progress. Files upload two at a time. A row can end as added, "Already in your library", rejected in the browser, or failed. Rejected and failed rows stay until dismissed. |
| Upload: summary | All rows settled. The summary counts each outcome. "Use existing" selects the existing image and drops the row; "Upload anyway" stores a second copy, which then appears under Duplicates. "Try again" retries one file. Announced when it finishes. |
| Upload: rejected files (413, 400) | Type and size are checked in the browser first, so nothing is sent. A server 413 or 400 for a file that got through shows the same row with its own message. |
| Upload: too many requests (429) | Rate limited. Retry-After is counted down in the button. It re-enables at zero. Already-added files are kept. |
| Duplicates: groups | The Duplicates tab. Groups of identical images side by side, each with its uploader, upload date and "Used in N articles". The suggested copy to keep is the most used, then the oldest. |
| Duplicates: purge all | Owner or admin, groups exist. "Purge duplicates" opens the purge dialog (preview, confirm, progress, results), the same one as Settings "Purge now". "Merge into this one" is unchanged. |
| Duplicates: empty | No groups. The Duplicates tab loses its count badge. |
| Merge: confirm | "Merge into this one" on floorboards.jpg. The dialog says articles using the other copies will switch to this image and the other copies will be deleted, with the article count. |
| Merge: in progress | Request in flight. The dialog can't be dismissed. |
| Merge: failed | 500 or network failure. Nothing is switched or deleted. |
| Merge: conflict (409) | A copy was deleted, or a new copy appeared, since the page loaded. |
| Merge: done | 200: the group leaves the list. When it was the last one, "No duplicates" shows. |
| List failed to load | A 500 or network failure on the list request. The alert replaces the images; Try again repeats the request. |
| Offline | navigator.onLine is false. Loaded images stay browsable. Upload, Rename, Delete and Merge are disabled, and the banner says why. |
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Duplicates tab with the button | Owner or admin. | |
| 2 | Duplicates tab: offline | The button is disabled with the existing banner. | |
docs/design/screens/new-article.md
+15 -61
View File
@@ -1,71 +1,25 @@
# New article
- **Route:** `modal from anywhere · /article/new`
- **API:** POST /v1/article/
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "New article" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `modal from anywhere · /article/new`. API: POST /v1/article/.
Recommendation: a modal. It needs two fields, and keeping the page underneath means cancelling costs nothing. /article/new opens the same modal over the article list, so it can be linked to and the back button closes it. A successful create always makes a draft and goes to the editor.
Recommendation: a modal. Title is the only field. The body is not asked for here; it is written in the editor, which opens straight after. Keeping the page underneath means cancelling costs nothing. /article/new opens the same modal over the article list, so it can be linked to and the back button closes it. A successful create always makes a draft and goes to the editor.
## States
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "New article". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** "New article" from Home, Articles or the empty state.
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.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **New article**
- text "It's saved as a draft. Titles can't be changed later, so check it now."
- field `Title`: placeholder "e.g. Choosing tiles for a small bathroom"; focused; counter "0 / 200"; help "3 to 200 characters."
- field `First paragraph`: placeholder "Start writing. You'll continue in the editor."; textarea; help "You can format it and add images in the editor."
- cancel "Cancel"
- confirm "Create draft"
### New article (group "New article", 5 states)
### Validation
Route: `modal from anywhere · /article/new`. API: POST /v1/article/.
**Trigger:** On submit or blur. Nothing is sent.
Recommendation: a modal. Title is the only field. The body is not asked for here; it is written in the editor, which opens straight after. Keeping the page underneath means cancelling costs nothing. /article/new opens the same modal over the article list, so it can be linked to and the back button closes it. A successful create always makes a draft and goes to the editor.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **New article**
- text "It's saved as a draft. Titles can't be changed later, so check it now."
- field `Title`: value "Ti"; counter "2 / 200" in error; **error "Use at least 3 characters."**
- field `First paragraph`: textarea; **error "Add a first paragraph. It can be a single sentence."**
- cancel "Cancel"
- confirm "Create draft"
### Submitting
**Trigger:** Request in flight. Fields are disabled and the dialog can't be dismissed.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **New article**
- text "It's saved as a draft. Titles can't be changed later, so check it now."
- field `Title`: value "Choosing tiles for a small bathroom"; counter "35 / 200"
- field `First paragraph`: value "Small rooms show every grout line, so we start with the floor."; textarea
- cancel "Cancel"
- confirm "Creating…", loading, not dismissible
### Title rejected (400)
**Trigger:** A server 400 that got past the browser checks. The raw error isn't shown.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **New article**
- text "It's saved as a draft. Titles can't be changed later, so check it now."
- field `Title`: value "Choosing tiles for a small bathroom"; counter "35 / 200"; **error "Check this title and try again."**
- field `First paragraph`: value "Small rooms show every grout line, so we start with the floor."; textarea
- Alert: "Something in the form isn't valid. Check the highlighted fields."
- cancel "Cancel"
- confirm "Create draft"
### Error
**Trigger:** 500 or network failure.
- Breadcrumbs: Articles (mobile title "Articles")
- Modal: **New article**
- text "It's saved as a draft. Titles can't be changed later, so check it now."
- field `Title`: value "Choosing tiles for a small bathroom"; counter "35 / 200"
- field `First paragraph`: value "Small rooms show every grout line, so we start with the floor."; textarea
- Alert: "Couldn't create the article. Your text is still here. Try again in a moment."
- cancel "Cancel"
- confirm "Create draft"
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | "New article" from Home, Articles or the empty state. | |
| 2 | Validation | On submit or blur. Nothing is sent. | "Use at least 3 characters." |
| 3 | Submitting | Request in flight. Fields are disabled and the dialog can't be dismissed. | "Creating…" / "Choosing tiles for a small bathroom" / "Small rooms show every grout line, so we start with the floor." |
| 4 | Title rejected (400) | A server 400 that got past the browser checks. The raw error isn't shown. | "Something in the form isn't valid. Check the highlighted fields." / "Choosing tiles for a small bathroom" / "Small rooms show every grout line, so we start with the floor." / "Check this title and try again." |
| 5 | Error | 500 or network failure. | "Couldn't create the article. Your text is still here. Try again in a moment." / "Choosing tiles for a small bathroom" / "Small rooms show every grout line, so we start with the floor." |
docs/design/screens/pending.md
+16 -51
View File
@@ -1,61 +1,26 @@
# Check your email
# Pending
- **Route:** `/register/pending`
- **API:** DELETE /v1/auth/register · POST /v1/auth/logout
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Pending" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/register/pending`. API: DELETE /v1/auth/register · POST /v1/auth/logout.
Any back-office route visited by an unverified account lands here. There's no way to resend the email because the API doesn't offer one, so the note explains the way out.
## States
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Pending". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** Straight after registering, when the email is known from the form.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to marta@renew.example. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
### Check your email (group "Pending", 6 states)
### Email unknown
Route: `/register/pending`. API: DELETE /v1/auth/register · POST /v1/auth/logout.
**Trigger:** Arrived after logging in as an unverified user.
Any back-office route visited by an unverified account lands here. There's no way to resend the email because the API doesn't offer one, so the note explains the way out.
- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to the email you registered with. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
### Confirm cancel
**Trigger:** "Cancel registration" opens the destructive ConfirmDialog.
- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to marta@renew.example. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
- ConfirmDialog: **Cancel your registration?**
- text "Your account will be deleted. You can register again with the same or a different email."
- cancel "Keep my account"
- confirm "Cancel registration"
### Cancelling
**Trigger:** DELETE in flight. The dialog can't be dismissed.
- ResultPanel (success, mail-check): **Check your email**; text "We sent a verification link to marta@renew.example. It expires in 2 hours."; note "Opened it on another device? That works too; you'll log in there first. Can't find it? Check your spam folder. If the link has expired, cancel your registration and start again."; actions "Log out" (secondary), "Cancel registration" (secondary)
- ConfirmDialog: **Cancel your registration?**
- text "Your account will be deleted. You can register again with the same or a different email."
- cancel "Keep my account"
- confirm "Cancelling…"
### Cancelled
**Trigger:** 200 → /register, with a toast.
- Heading: **Create the owner account**
- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
- Field `Username`: placeholder "e.g. marta"; counter "0 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Email`: placeholder "you@example.com"; help "We'll send a verification link here."
- Field `Password`: password with show/hide; checklist "At least 8 characters" (unmet)
- Submit button: "Create account"
- Footer: Already set up? [Log in]
- Toast (circle-check): **Registration cancelled** "You can create the owner account again."
### Already verified (403)
**Trigger:** Verified on another device. Goes to /home; shown here as the toast over the destination.
- ResultPanel (success, shield-check): **You're verified**; text "Taking you to your dashboard…"
- Toast (info): **Your account is already verified** "There's nothing to cancel."
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | Straight after registering, when the email is known from the form. | "marta@renew.example" |
| 2 | Email unknown | Arrived after logging in as an unverified user. | |
| 3 | Confirm cancel | "Cancel registration" opens the destructive ConfirmDialog. | "marta@renew.example" |
| 4 | Cancelling | DELETE in flight. The dialog can't be dismissed. | "marta@renew.example" |
| 5 | Cancelled | 200 → /register, with a toast. | "Registration cancelled" / "You can create the owner account again." |
| 6 | Already verified (403) | Verified on another device. Goes to /home; shown here as the toast over the destination. | "You're verified" / "Taking you to your dashboard…" / "Your account is already verified" / "There's nothing to cancel." |
docs/design/screens/profile.md
+37 -172
View File
@@ -1,183 +1,48 @@
# Profile
- **Route:** `/profile`
- **API:** GET /v1/auth/me · PATCH /v1/user/me (pending) · POST /v1/auth/password-reset
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Profile" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/profile`. API: GET /v1/auth/me · PATCH /v1/user/me (pending) · POST /v1/auth/password-reset.
Opened from the account menu at the bottom of the sidebar. Username, email and password are read-only. The display name is optional, trimmed, and up to 60 characters.
Opened from the account menu at the bottom of the sidebar. Username, email and password are read-only. The display name is optional, trimmed, and up to 60 characters. Once saved it replaces the username everywhere a person is named: the sidebar, the account menu, the Home greeting, the Users list (with the username beside it) and the emails RenewCMS sends, such as "Marta Alves invited you to RenewCMS". Saving it empty goes back to the username. The reset link uses the same flow as "Forgot password" and ends on the auth board's "Choose a new password" screen.
Once saved it replaces the username everywhere a person is named:
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Profile". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
- the sidebar chip and the account menu (name, and the avatar initials)
- the Home greeting ("Good morning, Marta Alves")
- the Display name column of the Users list
- the emails RenewCMS sends, such as "Marta Alves invited you to RenewCMS"
## Copy per state (generated from the board source, pass 2)
Saving it empty goes back to the username. Logging in still uses the username.
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.
The reset link uses the same flow as "Forgot password" and ends on the auth board's "Choose a new password" screen ([reset-password.md](reset-password.md)).
### Fixed copy in the frame
- Profile
- Your account on this RenewCMS workspace.
- Display name
- Shown instead of your username across the back-office and in the emails RenewCMS sends. Leave it empty to use your username.
- (optional)
- Account
- Set when your account was created. You log in with your username, even after adding a display name.
- Username
- marta
- Email
- marta@renew.example
- Password
- To change it, we'll email a reset link to marta@renew.example. The link works once, within 1 hour.
## The page
### Profile (group "Profile", 13 states)
Three cards under the title "Profile" and the subtitle "Your account on this RenewCMS workspace.", 720 px wide at most.
Route: `/profile`. API: GET /v1/auth/me · PATCH /v1/user/me (pending) · POST /v1/auth/password-reset.
| Card | Content |
|---|---|
| Display name | Title "Display name". Text "Shown instead of your username across the back-office and in the emails RenewCMS sends. Leave it empty to use your username." One input, label "Display name (optional)", placeholder "e.g. Marta Alves", with a live counter "n / 60" in mono on the right of the help row. A footer strip holds a status line on the left and the Save button on the right. |
| Account | Title "Account". Text "Set when your account was created. You log in with your username, even after adding a display name." Two disabled inputs with a lock icon: Username and Email (two columns on desktop, one on mobile). |
| Password | Title "Password". Text "To change it, we'll email a reset link to marta@renew.example. The link works once, within 1 hour." A disabled input showing "••••••••••••" beside the button "Send reset link" (mail icon). A note appears under them once a request has been made. |
Opened from the account menu at the bottom of the sidebar. Username, email and password are read-only. The display name is optional, trimmed, and up to 60 characters. Once saved it replaces the username everywhere a person is named: the sidebar, the account menu, the Home greeting, the Users list (with the username beside it) and the emails RenewCMS sends, such as "Marta Alves invited you to RenewCMS". Saving it empty goes back to the username. The reset link uses the same flow as "Forgot password" and ends on the auth board's "Choose a new password" screen.
**Footer status line** (12 px): "Unsaved changes" in the warning color while dirty and not saving. Otherwise "You appear as “Marta Alves”." when a display name is saved, or "You appear as “marta”, your username." when it isn't.
**Save button:** full opacity when the value changed and is valid, or while saving. 40 % opacity and inert otherwise. Enter in the field saves.
**Counting:** characters are counted as Unicode characters, not bytes or UTF-16 units. The counter turns red over 60.
**Leaving the page** with unsaved changes asks for confirmation.
**Mobile:** cards use 16 px padding, inputs are 44 px, the two account inputs stack, and the password input and its button stack.
## The account menu
Opened from the account chip at the bottom of the sidebar (chevrons-up-down icon; `aria-haspopup="menu"`, `aria-expanded`). The chip takes the sand fill with ink text while the menu is open, and while `/profile` is the current page.
Desktop: a 224 px popover above the chip, aligned to its left. Mobile: the account row in the navigation drawer opens it as a bottom sheet with a grab handle. Escape or a click outside closes both.
| Part | Content |
|---|---|
| Header | The name in semibold (display name, or the username), and the email in muted 12 px (14 px on mobile, with a 36 px initials avatar beside them) |
| Item | Profile (circle-user icon), highlighted while on `/profile` |
| Separator | |
| Label | "Theme": 11 px, weight 500, uppercase, letter-spacing .04em, muted |
| Items | System, Light, Dark: a radio-style group, the current choice carries a check icon at the right edge; choosing one applies the theme at once and keeps the menu open |
| Separator | |
| Label | "Language", styled like "Theme" |
| Items | English, Français (each in its own language, with `lang`): a radio-style group with a check on the current one; choosing one applies the language at once and keeps the menu open |
| Separator | |
| Item | Log out (log-out icon) |
Avatar initials come from the first letters of the first two words of the display name, uppercased ("Marta Alves" gives MA). Without a display name they come from the username.
The board's menu now carries System, Light and Dark, matching the shipped UserMenu. The theme choice stays in the account menu; the Profile page does not repeat it. Items are 32 px on desktop and 48 px in the mobile sheet.
## States
### Account menu
**Trigger:** The account chip at the bottom of the sidebar. On mobile, the account row in the navigation drawer opens it as a sheet. Escape or a click outside closes it.
- Breadcrumbs: Home (mobile title "Home")
- Page behind the menu: Home, default
- Menu open, as described above, with the Theme group (System, Light, Dark) and the Language group (English, Français) between Profile and Log out. The board shows Light and English checked
### Loading
**Trigger:** Opened directly by URL before /auth/me has returned. From the menu, the cached user renders straight away.
- Breadcrumbs: Profile (mobile title "Profile")
- Three skeleton cards (one input, two inputs, one input)
### Default, no display name
**Trigger:** The usual first visit. The username is used everywhere.
- Breadcrumbs: Profile (mobile title "Profile")
- Display name: empty, placeholder "e.g. Marta Alves", counter "0 / 60"
- Footer: "You appear as “marta”, your username."
- Save: 40 % opacity
### Editing
**Trigger:** Typing in the field. Save turns on, and leaving the page asks for confirmation.
- Breadcrumbs: Profile (mobile title "Profile")
- Display name: "Marta Alves"; focused; counter "11 / 60"
- Footer: "Unsaved changes" (warning)
- Save: enabled
### Too long
**Trigger:** Over 60 characters. Checked as you type, and Save stays off.
- Breadcrumbs: Profile (mobile title "Profile")
- Display name: "Marta Alves, Head of Renovations, Brussels and Wallonia office"; focused; counter red
- **Error "Use 60 characters or fewer."**
- Footer: "Unsaved changes" (warning)
- Save: 40 % opacity
### Saving
**Trigger:** Save, or Enter in the field. The field is disabled.
- Breadcrumbs: Profile (mobile title "Profile")
- Display name: "Marta Alves", disabled, dimmed
- Save: "Saving…" with a loader
### Saved
**Trigger:** 200: the sidebar and account menu switch to the display name at once, and a toast confirms.
- Breadcrumbs: Profile (mobile title "Profile")
- Sidebar chip: "Marta Alves", initials MA
- Display name: "Marta Alves"; counter "11 / 60"
- Footer: "You appear as “Marta Alves”."
- Toast (success, circle-check): **Display name saved** "You now appear as Marta Alves across RenewCMS and in emails."
### Save failed
**Trigger:** 500 or network failure. The typed value is kept.
- Breadcrumbs: Profile (mobile title "Profile")
- Alert (error) in the Display name card: "Couldn't save your display name. Your text is still here. Try again in a moment."
- Display name: "Marta Alves"
- Footer: "Unsaved changes" (warning)
- Save: enabled
### Reset: sending
**Trigger:** "Send reset link". No confirmation, since it only sends an email.
- Breadcrumbs: Profile (mobile title "Profile")
- Button: "Sending…" with a loader
- Sidebar chip shows the display name "Marta Alves"
### Reset: sent
**Trigger:** 200. The message stays until the page is left. "Send again" sends a new link and the old one stops working.
- Breadcrumbs: Profile (mobile title "Profile")
- Button: "Send again" (mail)
- Note (success, mail-check): **Reset link sent** "Check marta@renew.example. The link works once, within 1 hour."
### Reset: too many requests (429)
**Trigger:** Rate limited. The button is disabled for 5 minutes.
- Breadcrumbs: Profile (mobile title "Profile")
- Button: "Send reset link", 40 % opacity, disabled
- Note (warning, clock-alert): **Too many requests** "You've asked for several links recently. Wait a few minutes, then try again."
### Reset: failed
**Trigger:** 500 or network failure. The button can be pressed again.
- Breadcrumbs: Profile (mobile title "Profile")
- Button: "Send reset link"
- Note (error, circle-x): **Couldn't send the link** "Check your connection and try again."
### Display names in the Users list
**Trigger:** The Display name column of the Users list shows the name when one is set and a dash when not. Your own row follows your saved name. This state needs the Users page ([users.md](users.md)).
- Breadcrumbs: Users (mobile title "Users")
- Signed-in user's display name: "Marta Alves" (sidebar chip shows it too)
- Row `marta@renew.example` (you): display name "Marta Alves", role owner, Accepted
- Row `ines.duarte@renew.example`: display name "Inès Duarte", role admin, Accepted
- Row `jonas@renew.example`: display name "—" (muted), role admin, Accepted
## Notes for implementation
- `PATCH /v1/user/me` is marked pending by the design: it does not exist yet. `GET /v1/auth/me` has to start returning the display name.
- The Password card sends the reset email to the account's own address through the existing `POST /v1/auth/password-reset`. The link ends on the reset confirm screen, and a successful reset invalidates the current session like any other reset.
- "Disabled for 5 minutes" is the design's number. The real window comes from the `Retry-After` header, as on the login and reset screens.
- Resolved: the theme choice (System, Light, Dark) stays in the account menu, as the board now draws it. The board still draws Profile highlighted on Home; the app highlights it only on `/profile`.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Account menu | The account chip at the bottom of the sidebar. On mobile, the account row in the navigation drawer opens it as a sheet. Escape or a click outside closes it. | "Here's where things stand on your site." |
| 2 | Loading | Opened directly by URL before /auth/me has returned. From the menu, the cached user renders straight away. | |
| 3 | Default, no display name | The usual first visit. The username is used everywhere. | |
| 4 | Editing | Typing in the field. Save turns on, and leaving the page asks for confirmation. | |
| 5 | Too long | Over 60 characters. Checked as you type, and Save stays off. | "Marta Alves, Head of Renovations, Brussels and Wallonia office" / "Use 60 characters or fewer." |
| 6 | Saving | Save, or Enter in the field. The field is disabled. | |
| 7 | Saved | 200: the sidebar and account menu switch to the display name at once, and a toast confirms. | "Display name saved" / "You now appear as Marta Alves across RenewCMS and in emails." |
| 8 | Save failed | 500 or network failure. The typed value is kept. | "Couldn't save your display name. Your text is still here. Try again in a moment." |
| 9 | Reset: sending | "Send reset link". No confirmation, since it only sends an email. | |
| 10 | Reset: sent | 200. The message stays until the page is left. "Send again" sends a new link and the old one stops working. | |
| 11 | Reset: too many requests (429) | Rate limited. The button is disabled for 5 minutes. | |
| 12 | Reset: failed | 500 or network failure. The button can be pressed again. | |
| 13 | Display names in the Users list | The Display name column shows the name when one is set and a dash when not. Your own row follows your saved name. | |
docs/design/screens/register.md
+22 -65
View File
@@ -1,76 +1,33 @@
# Create the owner account
# Register
- **Route:** `/register`
- **API:** POST /v1/auth/register
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Register" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/register`. API: POST /v1/auth/register.
Seen once, on a fresh install. After registering, the new user is logged in but not yet verified, and goes to /register/pending.
## States
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Register". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** Registration is open.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
- Heading: **Create the owner account**
- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
- Field `Username`: placeholder "e.g. marta"; counter "0 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Email`: placeholder "you@example.com"; help "We'll send a verification link here."
- Field `Password`: password with show/hide; checklist "At least 8 characters" (unmet)
- Submit button: "Create account"
- Footer: Already set up? [Log in]
### Base copy
- Create the owner account
- This creates the single admin account for this site. Once it's verified, registration closes.
- Create account
- Already set up?
- Log in
### Validation errors
### Create the owner account (group "Register", 6 states)
**Trigger:** Checked on blur and on submit, using the same rules as the API.
Route: `/register`. API: POST /v1/auth/register.
- Heading: **Create the owner account**
- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
- Field `Username`: placeholder "e.g. marta"; value "ma"; counter "2 / 20" in error; **error "Use 3 to 20 characters."**
- Field `Email`: placeholder "you@example.com"; value "marta@renew"; **error "Enter a full email address, like name@example.com."**
- Field `Password`: value "lime"; password with show/hide; checklist "At least 8 characters" (err)
- Submit button: "Create account"
- Footer: Already set up? [Log in]
Seen once, on a fresh install. After registering, the new user is logged in but not yet verified, and goes to /register/pending.
### Filled, valid
**Trigger:** Every rule is met and the checklist item turns green.
- Heading: **Create the owner account**
- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
- Field `Username`: placeholder "e.g. marta"; value "marta"; counter "5 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; help "We'll send a verification link here."
- Field `Password`: value "limewash2026"; password with show/hide; password shown; checklist "At least 8 characters" (met)
- Submit button: "Create account"
- Footer: Already set up? [Log in]
### Submitting
**Trigger:** Fields and button are disabled.
- Heading: **Create the owner account**
- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
- Field `Username`: placeholder "e.g. marta"; value "marta"; counter "5 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; help "We'll send a verification link here."
- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Submit button: "Creating account…", loading
- Footer: Already set up? [Log in]
### Registration closed (403)
**Trigger:** Someone already verified an owner account. The form is replaced.
- ResultPanel (info, user-x): **This site already has an owner**; text "Log in instead."; actions "Go to log in" (primary)
### Server error
**Trigger:** A 500 or no response. The values are kept.
- Alert (error, circle-x): **Couldn't create the account** "Something went wrong on the server. Try again in a moment."
- Heading: **Create the owner account**
- Description: "This creates the single admin account for this site. Once it's verified, registration closes."
- Field `Username`: placeholder "e.g. marta"; value "marta"; counter "5 / 20"; help "Letters and numbers, 3 to 20 characters. You'll use it to log in."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; help "We'll send a verification link here."
- Field `Password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Submit button: "Create account"
- Footer: Already set up? [Log in]
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | Registration is open. | |
| 2 | Validation errors | Checked on blur and on submit, using the same rules as the API. | "Use 3 to 20 characters." / "marta@renew" / "Enter a full email address, like name@example.com." |
| 3 | Filled, valid | Every rule is met and the checklist item turns green. | "marta@renew.example" |
| 4 | Submitting | Fields and button are disabled. | "marta@renew.example" / "Creating account…" |
| 5 | Registration closed (403) | Someone already verified an owner account. The form is replaced. | "This site already has an owner" / "Log in instead." / "Go to log in" |
| 6 | Server error | A 500 or no response. The values are kept. | "Couldn't create the account" / "Something went wrong on the server. Try again in a moment." / "marta@renew.example" |
docs/design/screens/reset-password.md
+21 -65
View File
@@ -1,76 +1,32 @@
# Choose a new password
# Reset password
- **Route:** `/register/reset/validate?c=CODE&email=EMAIL`
- **API:** POST /v1/auth/password-reset/confirm
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Reset password" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/register/reset/validate?c=CODE&email=EMAIL`. API: POST /v1/auth/password-reset/confirm.
Opened from the reset email. The email comes from the URL and is read-only. The confirm field is checked only in the browser.
## States
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Reset password". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Default
## Copy per state (generated from the board source, pass 2)
**Trigger:** Both parameters are present.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
- Heading: **Choose a new password**
- Description: "Pick something you haven't used here before. You'll log in with it next."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
- Field `New password`: password with show/hide; checklist "At least 8 characters" (unmet)
- Field `Confirm new password`: password with show/hide; checklist "Passwords match" (unmet)
- Submit button: "Change password"
### Base copy
- Choose a new password
- Pick something you haven't used here before. You'll log in with it next.
- Change password
### Too short
### Choose a new password (group "Reset password", 7 states)
**Trigger:** On submit, with fewer than 8 characters.
Route: `/register/reset/validate?c=CODE&email=EMAIL`. API: POST /v1/auth/password-reset/confirm.
- Heading: **Choose a new password**
- Description: "Pick something you haven't used here before. You'll log in with it next."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
- Field `New password`: value "lime"; password with show/hide; checklist "At least 8 characters" (err)
- Field `Confirm new password`: value "lime"; password with show/hide; checklist "Passwords match" (met)
- Submit button: "Change password"
Opened from the reset email. The email comes from the URL and is read-only. The confirm field is checked only in the browser.
### Mismatch
**Trigger:** On blur of the confirm field, or on submit.
- Heading: **Choose a new password**
- Description: "Pick something you haven't used here before. You'll log in with it next."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
- Field `New password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Field `Confirm new password`: value "limewash2025"; password with show/hide; **error "The passwords don't match."**; checklist "Passwords match" (err)
- Submit button: "Change password"
### Submitting
**Trigger:** Request in flight.
- Heading: **Choose a new password**
- Description: "Pick something you haven't used here before. You'll log in with it next."
- Field `Email`: placeholder "you@example.com"; value "marta@renew.example"; read-only; help "From your reset link."
- Field `New password`: value "limewash2026"; password with show/hide; checklist "At least 8 characters" (met)
- Field `Confirm new password`: value "limewash2026"; password with show/hide; checklist "Passwords match" (met)
- Submit button: "Changing password…", loading
### Success
**Trigger:** 200 → /login?reason=password-changed.
- Alert (success, circle-check): **Password changed** "Log in with your new password."
- Heading: **Log in**
- Description: "Welcome back. Log in to manage your articles."
- Field `Username`: placeholder "Your username"
- Field `Password`: password with show/hide; link "Forgot password?"
- Submit button: "Log in"
### Invalid or expired (403)
**Trigger:** The code is wrong, used, or older than 1 hour.
- ResultPanel (error, link-2-off): **This reset link has expired**; text "Reset links work once, for 1 hour. Request a new one and use it within the hour."; actions "Request a new link" (primary), "Back to log in" (secondary)
### Missing parameters
**Trigger:** The link has no c or no email. No request is made.
- ResultPanel (error, link-2-off): **This link is incomplete**; text "Part of the reset link is missing. Open it from your email again, or request a new one."; actions "Request a new link" (primary)
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default | Both parameters are present. | |
| 2 | Too short | On submit, with fewer than 8 characters. | |
| 3 | Mismatch | On blur of the confirm field, or on submit. | "The passwords don't match." |
| 4 | Submitting | Request in flight. | "Changing password…" |
| 5 | Success | 200 → /login?reason=password-changed. | "Password changed" / "Log in with your new password." |
| 6 | Invalid or expired (403) | The code is wrong, used, or older than 1 hour. | |
| 7 | Missing parameters | The link has no c or no email. No request is made. | "This link is incomplete" / "Part of the reset link is missing. Open it from your email again, or request a new one." / "Request a new link" |
docs/design/screens/settings.md
+147 -148
View File
@@ -1,140 +1,14 @@
# Settings
# Settings: Media cleanup
- **Route:** `/settings`
- **API:** GET /v1/media/purge-settings · PATCH /v1/media/purge-settings · GET /v1/media/purge-preview · POST /v1/media/purge (see "Media cleanup (third card)" at the end) · GET /v1/settings (version) · GET /v1/system/update · POST /v1/system/update/check · POST /v1/system/update/download · POST /v1/system/update/restart
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Settings", drawn by `source/AppFrame.dc.html` (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Settings area: `/settings` (parent), `/settings/media/variants`, `/settings/media/cache` (children under the "Media" group). A "Media" card above this card links to both: "Manage image variants" ("Named sizes requested with ?v="), "Cache usage" ("Generated images and disk space"). Same sidebar on all three routes; see "Settings navigation" in the Back-office board.
Opened from the sidebar (Settings, settings icon, after Integration) and from the mobile drawer. Every verified user sees it. It holds two sections: Version (everyone) and Updates (the owner has the buttons, admins read the status).
The Updates card lets a non-technical owner update the site without a terminal. **Update** downloads the new version and checks it, and changes nothing. **Restart** installs it and restarts the site (about 10 seconds). "Restart later" is simply closing the dialog or leaving the page; the update waits. A plain **Restart** appears only when no update is waiting. The state lives on the server, so any owner on any device sees the same card, and the buttons are disabled while any step runs.
Out of scope: choosing versions, downgrades, automatic updates, update history.
## The page
One column of cards, top to bottom: Version, Updates, Media cleanup, Retention (owner only). Title "Settings" (20 px/28 px semibold), subtitle "Workspace information.", 720 px at most, 20 px between sections. Every card heading (Version, Updates, Media cleanup, Retention) is 15 px/24 px semibold in `--ui-text-highlighted`; a card heading is never larger than the page title and never smaller than a body line. The Back-office board draws this page scrolled to the card each state is about. Page padding 32 px on desktop and `20px 16px 88px` on mobile.
**Version card** (unchanged): label "Version" and the running build's version in IBM Plex Mono 14 px, shown exactly as the server reports it (for example `v2.2.0-beta`).
**Updates card**, under it: `--ui-bg`, 1 px `--ui-border`, 20 px padding (16 px on mobile), 16 px gap. A region labelled by its heading "Updates" (`id="updates-h"`, `tabindex="-1"`, focus ring `2px solid var(--ui-primary)` with 4 px offset when focus is moved there). Inside:
| Part | Content |
|---|---|
| Status block | A polite live region (`aria-live="polite"`): 14 px padding, 12 px gap, an 18 px icon, a semibold title, the text, and a muted `meta` line. Background and icon color follow the tone: neutral `--ui-bg-muted`, success, info, warning, error (`--rc-<tone>-soft` fill, `--ui-<tone>` icon). The title row is a flex row with an 8 px gap that wraps. In "Ready to install" it carries a **Pending tag** after the title and the block holds the **Restart** button (see below). |
| Pending tag | Only in "Ready to install", right after the title: 20 px high, 0 6 px padding, IBM Plex Mono 11 px medium, `--ui-bg` fill, `--ui-warning` text and 1 px `--ui-warning` border, square corners, text "Pending". |
| In-block button | Only in "Ready to install", "Restart: confirm" and "Restart: request failed": the primary Restart button sits inside the status block, under the `meta` line, after 8 px of extra top padding, left-aligned (content width, 14 px side padding, 32 px high, 44 px on mobile, not stretched). The buttons row under the block is not drawn in these states. The hint stays under the card. |
| Progress | A `progressbar` with a value (`aria-valuenow`) while downloading, labelled for example "Downloading version 2.3.0", with the text `42% · 11 of 26 MB`. Indeterminate while verifying (35 % wide moving bar), labelled "Checking the download", text "Almost there". Announced at 25 % steps and when the step changes, never on every tick. |
| Release notes | A button "What's new in 2.3.0" with `aria-expanded` and a chevron, collapsed by default. Open: "Released 24 Sep 2026" and a plain-text list. |
| Server command | Only in the "Not prepared" state: "For whoever manages the server", a one-line `code` block, a Copy button (reads "Copied" with a check for 2 s, announced), and the note "They run this once on the server. After that, Update and Restart appear here." The command shown is `renewcms enable-browser-updates` and is subject to the real one. |
| Buttons | 32 px high (44 px on mobile, stacked full width), 14 px side padding. One primary at most. Disabled buttons use 40 % opacity. |
| Hint | 12 px muted line under the buttons. |
| Link | Underlined, with an `external-link`: "How to update" or "Read the release notes". |
Buttons used: **Check for updates** (`refresh-cw`, secondary), **Update** (`download`, primary), **Restart** (`power`, primary and inside the status block when an update is ready, otherwise secondary in the buttons row), **Try again** (`rotate-cw`, primary), and the disabled "Checking…" and "Updating…" (`loader-circle`). Copy such as "Version 2.3.0" names the newer release. Decision for the spec: show the release tag without its leading `v` ("Version 2.3.0-beta" for tag `v2.3.0-beta`), while the Version card keeps the running build exactly as the server reports it.
## Copy
| Where | Copy |
|---|---|
| Up to date | `circle-check`, success: "You're up to date" / "You have the latest version of RenewCMS." / "Last checked today at 09:41"; buttons "Check for updates" and "Restart"; hint "Restart takes about 10 seconds. Your site is unavailable while it restarts." |
| Checking | `loader-circle`: "Checking for updates…" / "This usually takes a few seconds."; "Checking…" disabled |
| Check failed | `wifi-off`, warning: "Couldn't check for updates" / "RenewCMS couldn't reach the update server. Check your connection and try again. Your site isn't affected." / "Last checked yesterday at 18:12"; "Try again" (primary) and "Restart" |
| Available | `circle-arrow-up`, info: "Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart."; "Update"; hint "Takes about 2 minutes. Your site stays online." |
| Downloading | `download`, info: "Downloading version 2.3.0…" / "You can leave this page. The download continues and your site stays online."; "Updating…" disabled |
| Verifying | `shield-check`, info: "Checking the download…" / "Making sure the file is complete and safe to install. This takes a few seconds." |
| Ready | `clock`, warning, with the "Pending" tag after the title: "Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet."; "Restart" (primary, inside the block); hint "Not now? Leave this page. The update waits here, and the banner on Home reminds you." |
| Done | "You're on version 2.3.0" / "The update is installed and your site is running again." / "Updated today at 09:52"; link "Read the release notes"; toast `circle-check` "Update installed" / "RenewCMS is now on version 2.3.0." |
| Rolled back | `triangle-alert`, warning: "The update didn't install" / "RenewCMS put the previous version back, so your site is running as before. Nothing was lost." / "What to do next: try again in a few minutes. If it fails again, ask whoever manages your server to check the update."; "Try again"; toast (error, stays) `circle-x` "The update didn't install" / "Your site is back on v2.2.0-beta." |
| Download failed | `circle-x`, error: "The download didn't finish" / "The connection dropped before the file was complete. Nothing was changed and your site is running as before."; "Try again" |
| Not trusted | `triangle-alert`, warning: "We didn't use this update" / "The file didn't pass our safety check, so it was not installed. Nothing was changed. Try downloading it again. If this keeps happening, contact RenewCMS support." Technical detail goes to the server log. |
| Rate limited | `info`: "Too many tries" / "Wait a moment before trying again."; button "Try again in 0:42" counting down Retry-After |
| Not prepared | `info`: "Version 2.3.0 is available" / "This site can't update itself from the browser yet. Whoever manages your server can set it up once, or update RenewCMS for you." and a link "How to update". No buttons, not even Restart. |
| Admin | "Version 2.3.0 is available" / "You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site." No buttons. Up to date reads "You're up to date" and "Only the owner can update or restart the site." |
## Dialogs and overlays
Both dialogs use the ConfirmDialog behaviour: focus moves to the first button, Escape and the cancel button close it, and focus returns to the button that opened it. The confirm button is neutral, not red, because nothing is lost.
| Dialog | Title | Description | Cancel / Confirm |
|---|---|---|---|
| Install | "Restart to finish the update?" | "RenewCMS will install version 2.3.0 and restart. Your site will be unavailable for about 10 seconds. This page reloads on its own when the site is back. Save anything you're editing first." | "Restart later" / "Restart now" |
| Plain restart | "Restart the site?" | "Your site will be unavailable for about 10 seconds. This page reloads on its own when the site is back. Save anything you're editing first." | "Cancel" / "Restart site" |
Failure inside the install dialog: "Couldn't start the restart. Nothing was changed and your site is still running. Try again in a moment."
Restart overlay: a full-page `role="status"` live region (`--ui-bg-muted`, 440 px card) that survives the server going away, with a moving bar. Copy: "Installing version 2.3.0" / "Your site is restarting with the new version. This takes about 10 seconds. This page reloads on its own when the site is back." / "Started at 09:51". Announced once as "Installing version 2.3.0. Your site is restarting." After 60 seconds with no answer: "Still restarting" / "This is taking longer than usual. Keep this page open. It reloads on its own when the site is back, or you can reload it now." / "Started at 09:51 · 1 minute ago" and a "Reload page" button. Plain restart: "Restarting your site" / "This takes about 10 seconds. This page reloads on its own when the site is back." After the reload: focus lands on the "Updates" heading and a toast `circle-check` "Site restarted" / "Your site is running again."
## Elsewhere
For the owner only: an **Update** pill on the Settings sidebar item, and a dot on the menu icon on mobile (read as "Update available"). Admins see neither. The Home banner is described in [home](home.md).
## Status to copy
| Status | Where | Copy |
|---|---|---|
| 200 | Check, up to date | "You're up to date" and the last-checked line |
| 200 | Check, newer version | "Version 2.3.0 is available" and its text |
| 202 | Update, Restart | Accepted. The card switches to progress, announced as "Downloading version 2.3.0, 25 percent". |
| 200 | Update finished | "Version 2.3.0 is ready to install" |
| 200 | After restart | Toast "Update installed" or "Site restarted" |
| 400 | Update, nothing to install | Info toast "Nothing to update" / "You already have the latest version." The card refreshes. |
| 401 | any | Global: /login?redirect=/settings&reason=expired. No local copy. |
| 403 | any button, not the owner | Error toast "Only the owner can do this" / "Ask the owner of this site to update RenewCMS." The card reloads as the admin view. An unverified account is handled globally. |
| 409 | Update, Restart | Already running: info toast "An update is already running" / "Another owner started it. Progress shows here." Not prepared: the card shows the "Not prepared" state. |
| 422 | Update, file not trusted | The "Not trusted" card above |
| 429 | Check, Update | The rate-limited card above |
| 500 / network | Check | "Couldn't check for updates" with "Try again" |
| 500 / network | Update | "The download didn't finish" with "Try again" |
| 500 / network | Restart dialog | "Couldn't start the restart. Nothing was changed and your site is still running. Try again in a moment." |
| Site back, old version | after restart | The rolled-back card above |
| No answer, 60 s | restart overlay | "Still restarting" |
| Offline | whole page | Existing banner. Check, Update and Restart are disabled. During a restart the overlay keeps polling and ignores the offline state. |
## Behaviour notes
- The page asks for `GET /v1/system/update` on open and, when a step is running, polls it every second. The server holds the state (idle, downloading, verifying, ready, restarting, succeeded, failed), so another device or owner sees the same card.
- A check runs on the first open after 24 hours and when "Check for updates" is pressed.
- Update takes no confirmation because it changes nothing. Restart always asks.
## States
| State | Trigger and behaviour |
|---|---|
| Up to date | Opened with no newer version. Restart is available but not emphasised. |
| Checking | Check for updates pressed, or the first open after 24 hours. Announced as "Checking for updates". Buttons are disabled. |
| Check failed | Offline, or the update server didn't answer (500, network). The last known result is kept. |
| Update available | A newer version exists. Release notes are collapsed. Update is the one primary button. |
| Update available, notes open | "What's new in 2.3.0" expanded. It is a button with aria-expanded, and the list is plain text. |
| Downloading | Update pressed (202). Progress polls every second. Announced as "Downloading, 25 percent" and so on, never every tick. |
| Verifying | The download finished. No percentage, so the bar is indeterminate. Announced as "Checking the download". |
| Ready to install | The file passed its checks. The card turns warning (orange) with a "Pending" tag and a `clock` icon, and Restart, the primary action, sits inside it. "Restart later" is closing the dialog or leaving the page. |
| Restart: confirm | Restart pressed. The card behind the dialog keeps the Ready look. Same dialog behaviour as the delete confirm: focus moves to the first button, Escape and "Restart later" close it, and focus returns to Restart. The confirm button is neutral, not red, because nothing is lost. |
| Restart: request failed | 500 or network failure before the restart began. The site is still running. The card behind the dialog keeps the Ready look. |
| Restarting to install | Full-page overlay, so it survives the server going away. The page polls until the site answers, then reloads. It is a live region announced once as "Installing version 2.3.0. Your site is restarting." |
| Restarting, taking longer | No answer after 60 seconds. The copy changes and a manual reload appears. The overlay stays until the site is back. |
| Update done | The page reloaded on the new version. Focus lands on the "Updates" heading (ring shown), the toast is announced, and the version updates. |
| Update failed, rolled back | The site came back on v2.2.0-beta. The error toast stays until dismissed and the card keeps the explanation. |
| Download failed | A 500, or the connection dropped. Focus moves to the card heading. Try again restarts the download. |
| Verification failed | The downloaded file isn't trusted. The tone is a warning, and the file is thrown away. Technical detail goes to the server log, not the screen. |
| Too many requests (429) | Retry-After counted down in the button. It re-enables at zero. |
| Not prepared | The server can't update from the browser. No buttons, not even Restart. The command is for the person who runs the server and is a single line. The placeholder command is subject to the real one. |
| Not prepared: command copied | Copy pressed. The button reads "Copied" for 2 s and it is announced. |
| Plain restart: confirm | Restart with no update waiting. Nothing is installed. |
| Plain restart: restarting | Same overlay as the update restart with shorter copy. |
| Plain restart: done | The page reloaded. Focus lands on the "Updates" heading. |
| Admin view | Admins see the version and the note, with no buttons. Up to date: "You're up to date" and "Only the owner can update or restart the site." No Home banner or Settings pill. |
| Role changed (403) | An owner was changed to admin while the page was open and pressed a button. The card reloads in the admin view. |
| Update already running (409) | Another owner started it. The card switches to that run's progress. |
## Media cleanup (third card)
Route: `/settings`. Visual reference: `source/RenewCMS Screens Back-office.dc.html`, groups "Settings: Media cleanup", "Purge dialog", "Purge results" and "Media duplicates entry" (frames: `source/AppFrame.dc.html`, `source/MediaFrame.dc.html`).
Route: `/settings`. Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Settings: Media cleanup", "Purge dialog", "Purge results" (frames: `AppFrame.dc.html`, `MediaFrame.dc.html`).
API: `GET/PATCH /v1/media/purge-settings` (owner, admin), `GET /v1/media/purge-preview`, `POST /v1/media/purge`. 401 and 403 are global: no local copy.
Rule: a group is purged only if at least one copy is used in an article. All copies merge into the one used in the most articles (ties: oldest, then lowest id). Groups with no used copy are left alone. Automatic purge is off by default.
### Card
Third card, below Updates, 20 px gap, same card styling as the others. The board scrolls the page to this card for its states.
## Card
Second card below Version, 20 px gap, same card styling. Page max width 720 px.
- Title: "Media cleanup". Description: "Merge identical images so your library stays tidy. Articles that use a copy are switched to the most used one."
- "Automatic purge" / helper "Runs in the background. Off by default." / USwitch.
- When on: "Every" / helper "Between 1 and 365 days." / number input, suffix "days", default 30.
@@ -143,7 +17,7 @@ Third card, below Updates, 20 px gap, same card styling as the others. The board
- No Save button. Saves on toggle and on blur or Enter of the days field. "Saved" (check, success) sits in the card header and fades after 2 s; "Saving…" (loader-circle) while pending.
- Non-owner/admin: switch and input disabled, button and divider hidden, info alert "Only owners and admins can change this."
### States (names matched exactly)
## States (names matched exactly)
- Default: off, never run
- On: 30 days, last run
- Saving
@@ -154,7 +28,7 @@ Third card, below Updates, 20 px gap, same card styling as the others. The board
- Loading skeleton (after 150 ms)
- Offline: banner "You're offline. Changing automatic purge and purging duplicates need a connection." Switch, input and button disabled.
### Dialog
## Dialog
UModal, `sm:max-w-md`, bottom sheet on mobile, cancel first.
- Title "Purge duplicates?". Description "Articles that use a duplicate will be switched to the most used copy of that image, and the other copies will be deleted. This can't be undone."
- Summary: "4 groups · 9 copies will be deleted · 12 articles will be updated". Singular: "1 group · 1 copy will be deleted · 2 articles will be updated".
@@ -167,29 +41,154 @@ UModal, `sm:max-w-md`, bottom sheet on mobile, cancel first.
- Partial: "Some groups couldn't be merged. 3 of 4 groups were purged. Try again to finish." Buttons "Close", "Retry". Summary refreshes to the remaining groups.
- Conflict (409): "The library changed, so nothing was purged. Check the new summary and try again." Summary refreshes.
### Results
## Results
- Toast (5 s): circle-check, "Duplicates purged" / "9 copies merged. 12 articles updated."
- "Last purge" updates in place; "Next purge" moves forward by the interval.
- An unattended run shows no toast. The next visit shows the updated line.
### Media entry point
## Media entry point
Duplicates tab: secondary "Purge duplicates" button (merge) next to the sort menu; stacked toolbar on mobile. Opens the same dialog. Hidden for non-owner/admin and when there are no groups. "Merge into this one" is unchanged.
### Components (Nuxt UI v4)
## Components (Nuxt UI v4)
`UCard`, `USwitch`, `UInputNumber` (min 1, max 365, suffix), `UFormField`, `UAlert`, `UButton`, `UModal`, `USkeleton`, `useToast`.
## Activity retention
## Copy per state (generated from the board source, pass 2)
**API:** GET /v1/settings · PATCH /v1/settings (owner only). Visual reference: `source/RenewCMS Screens Back-office.dc.html`, group "Settings: Retention", drawn by `source/AppFrame.dc.html`.
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.
The last card on the page, below Media cleanup, owner only (hidden for admins and for the read-only Media cleanup view), same card styling and 720 px column as the others.
### Fixed copy in the frame
- Settings
- Workspace information.
- Version
- Updates
- Pending
- Read the full release notes
- For whoever manages the server
- Media
- Image sizes, cache and cleanup for your media library.
- Manage image variants
- Named sizes requested with ?v=
- Cache usage
- Generated images and disk space
- Media cleanup
- Merge identical images so your library stays tidy. Articles that use a copy are switched to the most used one.
- Saving…
- Saved
- Only owners and admins can change this.
- Automatic purge
- Runs in the background. Off by default.
- Every
- Between 1 and 365 days.
- days
- Purge now
- Merge every group of duplicates that has an image in use, right away.
- Purge duplicates
- Retention
- How long activity is kept, and how much log data to keep. Whichever limit is reached first removes the oldest events. Only owners can change it.
- Couldn't save the retention period
- Your previous setting is still in place.
- Try again
- Keep activity for
- or
- Keep at most
- Events older than 30 days will be removed
- This happens at the next cleanup on 7 Oct 2026, 03:00. It can't be undone.
- Apply 30 days
- Cancel
- Activity logs are append-only
- Events can't be edited or deleted from the app. Only the retention limits remove them.
- Header: "Retention" / "How long activity is kept, or how much of it. Whichever limit is reached first removes the oldest events." "Saved" (check, success) at the right after a save, fading after 2 s.
- "Keep activity for" `USelectMenu`: 30 days, 90 days, 365 days, Forever. Default 90 days. Helper: "Events older than this are removed." when a size limit is set, otherwise "Older events are removed automatically." For Forever: "Nothing is removed automatically. The log grows over time." without a size limit, "No age limit. Only the size limit applies." with one.
- An "or" divider, then "Keep at most" `USelectMenu` (160 px wide, full width on mobile): "No size limit" (default) and sizes in GB. Helper without a limit: "Optional. Logs can grow without a size cap." With one: "When logs pass 5 GB, the oldest events are removed. Currently 3.2 GB." The figure after "Currently" is the real size of the activity log. The size options are listed in the API note below.
- Info alert (`lock`): "Activity logs are append-only", "Events can't be edited or deleted from the app. Only the retention limits remove them."
- Divider, then read-only lines: "Last cleanup: 6 Oct 2026, 03:00 · 142 events removed" and "Next cleanup: 7 Oct 2026, 03:00". Forever with no size limit: "Never" and "Not scheduled". Forever with a size limit still shows a schedule, because the size check runs at every cleanup.
- Both selects save on change. Choosing a shorter age, or a smaller size limit than the current one, first shows a warning alert, "Events older than 30 days will be removed" (or "Events over 5 GB will be removed"), "This happens at the next cleanup on 7 Oct 2026, 03:00. It can't be undone.", buttons "Apply 30 days" (or "Apply 5 GB") and "Cancel"; nothing is sent until Apply. Lengthening, raising, choosing Forever or choosing "No size limit" saves at once.
- Save error alert: "Couldn't save the retention period", "Your previous setting is still in place.", "Try again". The control reverts.
- States: "Default, 90 days or 5 GB", "Age only (no size limit)", "Size only (forever)", "Shortening the period" (also with a 5 GB limit), "Forever" and "Save error". Loading and Offline follow the Media cleanup card.
- `GET /v1/settings` adds `activity_retention_days` (30, 90, 365 or 0 for forever), `activity_retention_max_gb` (0 for no size limit, otherwise one of the size options), `activity_log_size_bytes`, `activity_last_cleanup_at` (null before the first cleanup) and `activity_last_cleanup_removed`. `PATCH /v1/settings` takes `{ "activity_retention_days": 30 }`, `{ "activity_retention_max_gb": 5 }` or both; any other value answers 400 "The request cannot be processed due to a mismatch in the format of the body."; a non-owner gets 403 "Only the owner can do this.". The cleanup runs once a day at 03:00 server time, removes events older than the age limit, then removes the oldest events until the log is under the size limit, and never touches the last 24 hours.
### Settings: Updates (group "Settings", 25 states)
Route: `/settings`. API: GET /v1/system/update · POST …/check · POST …/download · POST …/update/restart (all pending).
The page is one column of cards, top to bottom: Version, Updates, Media cleanup, Retention (owner only). The screens below are scrolled to the card they show. New Updates card under Version, owner only. Update downloads and checks the new version and changes nothing. Restart installs it and restarts the site (about 10 seconds). "Restart later" is simply leaving the card or the dialog. A plain Restart shows only when no update is waiting. Admins see the version and a note. When the server isn't prepared, the card shows the notice and a "How to update" link with no buttons. Progress is a progressbar with a value, announced at 25% steps and when each step changes. The card is a polite live region. After the restart the page reloads, focus lands on the "Updates" heading, and a toast confirms. Buttons are disabled while any step runs, and any owner on any device sees the same state from the server. Cue elsewhere: see Home. Out of scope: choosing versions, downgrades, automatic updates, update history.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Up to date | Opened with no newer version. Restart is available but not emphasised. | "You're up to date" / "You have the latest version of RenewCMS." / "Check for updates" / "Restart" |
| 2 | Checking | Check for updates pressed, or the first open after 24 hours. Announced as "Checking for updates". Buttons are disabled. | "Checking for updates…" / "This usually takes a few seconds." / "Checking…" |
| 3 | Check failed | Offline, or the update server didn't answer (500, network). The last known result is kept. | "Couldn't check for updates" / "RenewCMS couldn't reach the update server. Check your connection and try again. Your site isn't affected." / "Last checked yesterday at 18:12" / "Try again" / "Restart" |
| 4 | Update available | A newer version exists. Release notes are collapsed. Update is the one primary button. | "Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart." / "Update" / "Takes about 2 minutes. Your site stays online." |
| 5 | Update available, notes open | "What's new in 2.3.0" expanded. It is a button with aria-expanded, and the list is plain text. | "Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart." / "Update" / "Takes about 2 minutes. Your site stays online." |
| 6 | Downloading | Update pressed (202). Progress polls every second. Announced as "Downloading, 25 percent" and so on, never every tick. | "Downloading version 2.3.0…" / "You can leave this page. The download continues and your site stays online." / "Downloading version 2.3.0" / "42% · 11 of 26 MB" / "Updating…" |
| 7 | Verifying | The download finished. No percentage, so the bar is indeterminate. Announced as "Checking the download". | "Checking the download…" / "Making sure the file is complete and safe to install. This takes a few seconds." / "Checking the download" / "Almost there" / "Updating…" |
| 8 | Ready to install | The file passed its checks. Restart becomes the primary action. "Restart later" is closing the dialog or leaving the page. | "Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet." / "Restart" / "Not now? Leave this page. The update waits here, and the banner on Home reminds you." |
| 9 | Restart: confirm | Restart pressed. Same dialog behaviour as the delete confirm: focus moves to the first button, Escape and "Restart later" close it, and focus returns to Restart. The confirm button is neutral, not red, because nothing is lost. | "Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet." / "Restart" |
| 10 | Restart: request failed | 500 or network failure before the restart began. The site is still running. | "Version 2.3.0 is ready to install" / "The download is checked. Restart to install it. Your site will be unavailable for about 10 seconds." / "Nothing has changed yet." / "Restart" / "Couldn't start the restart. Nothing was changed and your site is still running. Try again in a moment." |
| 11 | Restarting to install | Full-page overlay, so it survives the server going away. The page polls until the site answers, then reloads. It is a live region announced once as "Installing version 2.3.0. Your site is restarting." | "Version 2.3.0 is ready to install" / "Installing version 2.3.0" / "Your site is restarting with the new version. This takes about 10 seconds. This page reloads on its own when the site is back." / "Started at 09:51" |
| 12 | Restarting, taking longer | No answer after 60 seconds. The copy changes and a manual reload appears. The overlay stays until the site is back. | "Still restarting" / "This is taking longer than usual. Keep this page open. It reloads on its own when the site is back, or you can reload it now." / "Started at 09:51 · 1 minute ago" / "Reload page" |
| 13 | Update done | The page reloaded on the new version. Focus lands on the "Updates" heading (ring shown), the toast is announced, and the version updates. | "You're on version 2.3.0" / "The update is installed and your site is running again." / "Updated today at 09:52" / "Check for updates" / "Restart" / "Read the release notes" / "Update installed" / "RenewCMS is now on version 2.3.0." |
| 14 | Update failed, rolled back | The site came back on v2.2.0-beta. The error toast stays until dismissed and the card keeps the explanation. | "The update didn't install" / "RenewCMS put the previous version back, so your site is running as before. Nothing was lost." / "What to do next: try again in a few minutes. If it fails again, ask whoever manages your server to check the update." / "Try again" / "Your site is back on v2.2.0-beta." |
| 15 | Download failed | A 500, or the connection dropped. Focus moves to the card heading. Try again restarts the download. | "The download didn't finish" / "The connection dropped before the file was complete. Nothing was changed and your site is running as before." / "Try again" |
| 16 | Verification failed | The downloaded file isn't trusted. The tone is a warning, and the file is thrown away. Technical detail goes to the server log, not the screen. | "We didn't use this update" / "The file didn't pass our safety check, so it was not installed. Nothing was changed. Try downloading it again. If this keeps happening, contact RenewCMS support." / "Try again" |
| 17 | Too many requests (429) | Retry-After counted down in the button. It re-enables at zero. | "Too many tries" / "Wait a moment before trying again." / "Try again in 0:42" |
| 18 | Not prepared | The server can't update from the browser. No buttons, not even Restart. The command is for the person who runs the server and is a single line. The placeholder command is subject to the real one. | |
| 19 | Not prepared: command copied | Copy pressed. The button reads "Copied" for 2 s and it is announced. | |
| 20 | Plain restart: confirm | Restart with no update waiting. Nothing is installed. | "You're up to date" / "You have the latest version of RenewCMS." / "Check for updates" / "Restart" |
| 21 | Plain restart: restarting | Same overlay as the update restart with shorter copy. | "Restarting your site" / "This takes about 10 seconds. This page reloads on its own when the site is back." / "Started at 09:51" |
| 22 | Plain restart: done | The page reloaded. Focus lands on the "Updates" heading. | "Your site is back" / "Site restarted" / "Your site is running again." |
| 23 | Admin view | Admins see the version and the note, with no buttons. Up to date: "You're up to date" and "Only the owner can update or restart the site." No Home banner or Settings pill. | "Version 2.3.0 is available" / "You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site." |
| 24 | Role changed (403) | An owner was changed to admin while the page was open and pressed a button. The card reloads in the admin view. | "Version 2.3.0 is available" / "You have v2.2.0-beta. Only the owner can update RenewCMS. Ask the owner of this site." / "Only the owner can do this" / "Ask the owner of this site to update RenewCMS." |
| 25 | Update already running (409) | Another owner started it. The card switches to that run's progress. | "Version 2.3.0 is available" / "You have v2.2.0-beta. Update downloads the new version and checks it. Nothing changes until you restart." / "Update" / "An update is already running" / "Another owner started it. Progress shows here." |
### Settings: Media cleanup (group "Settings: Media cleanup", 9 states)
Route: `/settings`. API: GET /v1/media/purge-settings · PATCH /v1/media/purge-settings (owner, admin).
A card below Updates, same card styling and 20 px gap. Automatic purge is off by default. Settings save immediately on toggle and on blur or Enter of the days field; there is no Save button. 401 and 403 are global (login redirect, /register/pending) and have no local copy.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default: off, never run | Owner or admin. Automatic purge is off, so the "Every" row and "Next purge" are hidden. | |
| 2 | On: 30 days, last run | Switch on. "Every" appears with the default of 30 days. The last-run line and the next run are shown. | |
| 3 | Saving | Brief state after toggling or leaving the field. "Saving…" with loader-circle sits in the card header; controls stay usable. | |
| 4 | Saved | The save succeeded. A small "Saved" confirmation shows in the card header and fades after 2 s. It is announced politely. | |
| 5 | Save failed | A 500 or network failure. The error sits under the field and the control reverts to its previous value (30). | |
| 6 | Validation error | Empty, 0, above 365 or not a whole number, checked on blur or Enter. Nothing is sent. The field keeps what was typed until corrected. | |
| 7 | Read-only (non-admin) | Other verified users. Switch and input are disabled, "Purge now" is hidden, and an info alert explains why. | |
| 8 | Loading skeleton | The settings request is in flight. Skeleton shows only after 150 ms. | |
| 9 | Offline | navigator.onLine is false. The banner matches Media. Switch, input and button are disabled. | "You're offline. Changing automatic purge and purging duplicates need a connection." |
### Purge duplicates: dialog (group "Purge dialog", 8 states)
Route: `opens from "Purge now" (Settings) and "Purge duplicates" (Media, Duplicates tab)`. API: GET /v1/media/purge-preview · POST /v1/media/purge.
UModal, sm:max-w-md, bottom sheet on mobile. Cancel first, then the danger confirm. While the request runs, the confirm shows loader-circle and the dialog can't be dismissed. The preview is computed before confirming. A group is purged only if one of its copies is used in an article; the kept copy is the one used in the most articles (ties: oldest, then lowest id).
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | loading | Loading preview | "The preview request is in flight. Skeleton rows show after 150 ms and the confirm is disabled." |
| 2 | confirm | Confirm | ""Purge now" pressed. Summary, up to 5 groups, a link to the Duplicates tab." |
| 3 | confirm | Confirm: many groups | "More than 5 groups. The list stops at 5 and says how many more." |
| 4 | progress | In progress | "POST in flight. Confirm reads "Purging…" with loader-circle; Cancel is disabled and Esc, the overlay and swipe do nothing." |
| 5 | nothing | Nothing to purge | "The preview has no group with an image in use. No confirm; one Close button." |
| 6 | error | Error | "500 or network failure. The dialog stays open, nothing changed. Confirm retries." |
| 7 | partial | Partial failure | "Some groups failed. The summary refreshes to what is left. Buttons: Close, Retry." |
| 8 | conflict | Conflict (409) | "The library changed since the preview. Nothing was purged, the summary refreshes and the dialog stays open." |
### Purge: results and feedback (group "Purge results", 2 states)
Route: `/settings`. API: after POST /v1/media/purge.
An unattended run does not toast. The next visit to Settings shows the updated "Last purge" line.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Success | The dialog closes, a toast shows for 5 s, and the "Last purge" line updates in place. | "Duplicates purged" / "9 copies merged. 12 articles updated." |
| 2 | Success, automatic purge on | Same, with the next run moved forward by the interval. | "4 Nov 2026" / "Duplicates purged" / "9 copies merged. 12 articles updated." |
### Settings: Retention (owner only) (group "Settings: Retention", 6 states)
Route: `/settings`. API: GET /v1/settings · PATCH /v1/settings.
The last card on the page, same card styling as Version, Updates and Media cleanup. Saves on change.
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Default, 90 days or 5 GB | Saves on change. Whichever limit is reached first removes the oldest events. | |
| 2 | Age only (no size limit) | The size select reads "No size limit". Same as before this option. | |
| 3 | Size only (forever) | Age is set to Forever, so only the size limit removes events. | |
| 4 | Shortening the period | Confirms before older events are removed. | |
| 5 | Forever | No cleanup scheduled. | |
| 6 | Save error | The previous setting is still in place. | |
docs/design/screens/users.md
+40 -220
View File
@@ -1,232 +1,52 @@
# Users
- **Route:** `/users`
- **API:** GET /v1/user/ · POST /v1/user/invite · DELETE /v1/user/invite/:id (pending) · POST /v1/user/invite/:id/renew (pending)
- **Visual reference:** `source/RenewCMS Screens Back-office.dc.html`, group "Users" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/users`. API: GET /v1/user/ · POST /v1/user/invite · DELETE /v1/user/invite/:id (pending) · POST /v1/user/invite/:id/renew (pending).
One shared workspace: every user sees the same articles and this same list. The list shows email, display name, role, invite status and created date. A Pending invite can be cancelled and an Expired one renewed; accepted accounts have no row actions, so nobody can be removed or promoted from here. Only the owner can invite, cancel and renew (see "Roles").
One shared workspace: every user sees the same articles and this same list. Columns: email, display name, role (owner or admin), invite status and created date. A pending invite can be cancelled and an expired one renewed; accepted accounts have no row actions. An invite is Pending until its link is used, Expired after 3 days, and Accepted once the account is created.
An invite is **Pending** until its link is used, **Expired** after 3 days, and **Accepted** once the account is created. The list is sorted by created date, newest first.
Visual reference: `RenewCMS Screens Back-office.dc.html`, groups "Users". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
## Roles
## Copy per state (generated from the board source, pass 2)
There are two roles. They are shown as a badge and are not editable.
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.
| Role | Who | Can |
|---|---|---|
| owner | The account that registered first on the workspace. There is exactly one. | Everything an admin can, plus invite users, cancel invites and renew invites. |
| admin | Everyone who joined through an invite. Every invite creates an admin. | Read and write articles, see the Users list, edit their own profile, see Settings. |
### Fixed copy in the frame
- Users
- Everyone who can sign in and work on your articles.
- Invite user
- Couldn't load users
- Check your connection and try again.
- Try again
- Email
- Display name
- Role
- Invite status
- Created
- you
- Invite someone so they can sign in with their own account instead of sharing yours.
The owner is the only difference for now. The role cannot be changed, transferred or removed from the UI.
### Users (group "Users", 17 states)
**Not drawn by the board** (decide in the spec, cover by Vitest and Go tests only, like the 429 on invite):
Route: `/users`. API: GET /v1/user/ · POST /v1/user/invite · DELETE /v1/user/invite/:id (pending) · POST /v1/user/invite/:id/renew (pending).
- What a non-owner sees: the recommendation is to hide "Invite user" (desktop and mobile), hide the row actions, and hide the "Invite someone…" hint on the "Only you" state.
- The API answer when a non-owner calls an owner-only endpoint: the recommendation is 403 with a plain-text body, and no state change.
- The message if the owner's session sees a 403 anyway (role changed under it): the global 403 handling applies.
One shared workspace: every user sees the same articles and this same list. Columns: email, display name, role (owner or admin), invite status and created date. A pending invite can be cancelled and an expired one renewed; accepted accounts have no row actions. An invite is Pending until its link is used, Expired after 3 days, and Accepted once the account is created.
## The list
| Column | Content |
|---|---|
| Email | The account's or invite's email address, medium weight, highlighted. The current user's row carries a muted mono "you" tag after it. |
| Display name | The display name when set, highlighted; a muted dash `—` when not. An invite has none, so it shows the dash. Your own row follows your saved name. |
| Role | A mono 11 px badge, 20 px high: `owner` (filled, `--ui-primary` with `--ui-bg` text) or `admin` (transparent, toned text, `--ui-border-accented` border). An invite shows the role it will create, `admin`. |
| Invite status | A badge: Accepted (circle-check, success), Pending (mail, warning), Expired (clock-alert, outline, muted). Shown by icon and word as well as color. |
| Created | The date as `27 Sep 2026`, or "Today" for the current day. For an invite it is the day the invite was sent (or last renewed), for a user the day the account was created. |
| (actions) | Right-aligned, no header text. Pending row: "Cancel invite". Expired row: "Renew invite". Accepted row: empty. |
The username is no longer shown in this list.
Desktop is a table: 36 px header, 48 px rows, columns `minmax(0,1.3fr) minmax(0,1fr) 84px 120px 110px 150px` with a 12 px gap. Below md it becomes a card list (68 px minimum row height): the email line (with "you"), the display name below it when there is one, then the role badge, the status badge and "Created {date}" on one line, then the row action, if any, as a 44 px button with 14 px side padding.
The page header is a title "Users" with the subtitle "Everyone who can sign in and work on your articles." and a primary "Invite user" button (user-plus icon) on its right. On mobile the button becomes a full-width 48 px button pinned to the bottom of the screen.
The owner is always listed, so the list is never empty.
### Row actions
| Action | Shown on | Icon | Look |
| # | State | Trigger | Copy |
|---|---|---|---|
| Cancel invite | Pending | user-x | Outline button, text in `--ui-error` |
| Renew invite | Expired | refresh-cw | Outline button, text `--ui-text-highlighted` |
Desktop buttons are 28 px high, 12 px medium text, a 13 px icon, 9 px side padding, `--ui-border-accented` border, `--ui-bg` fill. Mobile buttons are 44 px high and 14 px side padding with a 14 px icon.
- **Cancel invite** asks first with a danger confirmation dialog, since it cannot be undone from here (the address can be invited again).
- **Renew invite** asks nothing, since it only sends an email. While the request runs, that row's button reads "Renewing…" with a loader-circle icon at 50 % opacity and is disabled. Only that row is busy.
## States
### Default
**Trigger:** The list loaded, newest first.
- Breadcrumbs: Users (mobile title "Users")
- Rows:
- `sam.oliveira@renew.example`, no display name, admin, Pending, 27 Sep 2026, "Cancel invite"
- `p.huber@gmail.com`, display name "Paul Huber", admin, Expired, 3 Aug 2026, "Renew invite"
- `ines.duarte@renew.example`, "Inès Duarte", admin, Accepted, 18 Jun 2026
- `jonas@renew.example`, no display name, admin, Accepted, 2 Apr 2026
- `marta@renew.example` (you), no display name, owner, Accepted, 12 Mar 2026
The board gives the Expired invite a display name. A real invite has none, so the SPA renders whatever `display_name` the item carries and the dash when it is empty.
### Loading
**Trigger:** The first load, or a retry. Skeletons appear after 150 ms.
- Breadcrumbs: Users (mobile title "Users")
- Five skeleton rows, one bar per column, plus a role-badge and a status-badge placeholder
### Only you
**Trigger:** Nobody has been invited yet. The owner is always listed.
- Breadcrumbs: Users (mobile title "Users")
- One row: `marta@renew.example` (you), owner, Accepted
- Hint under the list: "Invite someone so they can sign in with their own account instead of sharing yours."
### Error
**Trigger:** A 500 or network failure on the list request.
- Breadcrumbs: Users (mobile title "Users")
- Alert (error): **Couldn't load users** "Check your connection and try again."
- Action "Try again" (rotate-cw)
- No table or cards
### Invite: default
**Trigger:** "Invite user" in the page header, or the bottom button on mobile.
- Breadcrumbs: Users (mobile title "Users")
- Modal: **Invite a user**
- text "We'll email them a link to choose a username and password. The link expires after 3 days."
- field `Email`: placeholder "name@example.com"; focused
- close button
- cancel "Cancel"
- confirm "Send invite"
### Invite: validation
**Trigger:** On submit or blur. Nothing is sent.
- Breadcrumbs: Users (mobile title "Users")
- Modal: **Invite a user** (same text)
- field `Email`: value "sam.oliveira@renew"; **error "Enter a full email address, like name@example.com."**
- cancel "Cancel"
- confirm "Send invite"
### Invite: sending
**Trigger:** Request in flight. The field is disabled and the dialog can't be dismissed.
- Breadcrumbs: Users (mobile title "Users")
- Modal: **Invite a user** (same text)
- field `Email`: value "lea.martin@renew.example"; disabled
- cancel "Cancel"
- confirm "Sending…", loading, not dismissible
### Invite: already a user (409)
**Trigger:** The email belongs to an existing user. For a live pending invite the message reads "There's already a pending invite for this address." An expired invite can be sent again.
- Breadcrumbs: Users (mobile title "Users")
- Modal: **Invite a user** (same text)
- field `Email`: value "jonas@renew.example"; **error "This address already has an account."**
- cancel "Cancel"
- confirm "Send invite"
### Invite: failed
**Trigger:** 500, network failure, or the email couldn't be sent. The address stays in the field.
- Breadcrumbs: Users (mobile title "Users")
- Modal: **Invite a user** (same text)
- field `Email`: value "lea.martin@renew.example"
- Alert: "Couldn't send the invite. Try again in a moment."
- cancel "Cancel"
- confirm "Send invite"
### Invite sent
**Trigger:** 201: the dialog closes, the new invite appears at the top as Pending (highlighted row), and a toast confirms.
- Breadcrumbs: Users (mobile title "Users")
- New first row: `lea.martin@renew.example`, no display name, admin, Pending, created "Today", row background `--ui-bg-elevated`, with "Cancel invite"
- Toast (success, circle-check): **Invite sent** "lea.martin@renew.example has 3 days to accept."
The "Today" label makes this state clock-sensitive, so `task visual:check` skips it.
### Cancel invite: confirm
**Trigger:** "Cancel invite" on a Pending row.
- Breadcrumbs: Users (mobile title "Users")
- Modal (danger): **Cancel this invite?**
- text "The link sent to sam.oliveira@renew.example will stop working. You can invite the address again later."
- cancel "Keep invite"
- confirm "Cancel invite"
### Cancel invite: sending
**Trigger:** Request in flight. Both buttons are disabled and the dialog can't be dismissed.
- Breadcrumbs: Users (mobile title "Users")
- Modal (danger): **Cancel this invite?** (same text)
- cancel "Keep invite", disabled
- confirm "Cancelling…", loading
### Cancel invite: failed
**Trigger:** 500 or network failure. The dialog stays open.
- Breadcrumbs: Users (mobile title "Users")
- Modal (danger): **Cancel this invite?** (same text)
- notice "Couldn't cancel the invite. Try again in a moment."
- cancel "Keep invite"
- confirm "Cancel invite"
### Cancel invite: done
**Trigger:** 204: the row disappears and a toast confirms.
- Breadcrumbs: Users (mobile title "Users")
- The Pending row `sam.oliveira@renew.example` is gone; the other four remain
- Toast (success, circle-check): **Invite cancelled** "sam.oliveira@renew.example can no longer use the link."
### Renew invite: sending
**Trigger:** "Renew invite" on an Expired row. No confirmation, since it only sends an email. The button shows progress and is disabled.
- Breadcrumbs: Users (mobile title "Users")
- The Expired row's button reads "Renewing…" with a loader-circle icon, 50 % opacity, disabled
### Renew invite: done
**Trigger:** 200: the row becomes Pending with today's date, moves to the top, and the old link stops working.
- Breadcrumbs: Users (mobile title "Users")
- First row: `p.huber@gmail.com` Pending, created "Today", row background `--ui-bg-elevated`, now with "Cancel invite"
- Toast (success, circle-check): **Invite renewed** "p.huber@gmail.com has 3 days to accept the new link."
The "Today" label makes this state clock-sensitive, so `task visual:check` skips it.
### Renew invite: failed
**Trigger:** 500 or network failure. The row stays Expired and the button can be pressed again.
- Breadcrumbs: Users (mobile title "Users")
- Toast (error, circle-x): **Couldn't renew the invite** "Try again in a moment."
## Notes for implementation
- Accepted users are now listed by email, display name and role. This reverses the earlier rule that a user is never listed with an email.
- How display names look in this list is the state "Display names in the Users list" of [profile.md](profile.md). The board draws it in the Profile group, and `task visual:check` finds states by group.
- The board's API line marks both new endpoints "(pending)", meaning "not built yet". Cancel applies to a Pending invite. Renew is drawn on an Expired one; the recommendation is that the API also accepts a Pending one (it resets the 3 days and replaces the link) and refuses an Accepted one with 409. The SPA only offers Renew on Expired rows.
- Renewing replaces the code and expiry, resets the created date to now, and sends the invitation email again. The old link stops working. The email is specified in [emails.md](../emails.md).
- A 404 on cancel or renew (the invite was already used or cancelled elsewhere) is not drawn. Decide it in the spec; the recommendation is to drop the row and toast the outcome.
- 429 on the invite request is not drawn. Decide it in the spec before coding.
- The email the invite sends is specified in [emails.md](../emails.md). The screen the link opens is in [accept-invite.md](accept-invite.md).
- The role rules and what is not drawn are in "Roles" above.
| 1 | Default | The list loaded, newest first. | |
| 2 | Loading | The first load, or a retry. Skeletons appear after 150 ms. | |
| 3 | Only you | Nobody has been invited yet. The admin who registered is always listed. | |
| 4 | Error | A 500 or network failure on the list request. | |
| 5 | Invite: default | "Invite user" in the page header, or the bottom button on mobile. | |
| 6 | Invite: validation | On submit or blur. Nothing is sent. | "sam.oliveira@renew" / "Enter a full email address, like name@example.com." |
| 7 | Invite: sending | Request in flight. The field is disabled and the dialog can't be dismissed. | "Sending…" / "lea.martin@renew.example" |
| 8 | Invite: already a user (409) | The email belongs to an existing user. For a live pending invite the message reads "There's already a pending invite for this address." An expired invite can be sent again. | "jonas@renew.example" / "This address already has an account." |
| 9 | Invite: failed | 500, network failure, or the email couldn't be sent. The address stays in the field. | "Couldn't send the invite. Try again in a moment." / "lea.martin@renew.example" |
| 10 | Cancel invite: confirm | "Cancel invite" on a Pending row. | "Cancel this invite?" / "The link sent to sam.oliveira@renew.example will stop working. You can invite the address again later." / "Keep invite" / "Cancel invite" |
| 11 | Cancel invite: sending | Request in flight. Both buttons are disabled. | "Cancel this invite?" / "The link sent to sam.oliveira@renew.example will stop working. You can invite the address again later." / "Keep invite" / "Cancelling…" |
| 12 | Cancel invite: failed | 500 or network failure. The dialog stays open. | "Cancel this invite?" / "The link sent to sam.oliveira@renew.example will stop working. You can invite the address again later." / "Keep invite" / "Cancel invite" / "Couldn't cancel the invite. Try again in a moment." |
| 13 | Cancel invite: done | 204: the row disappears and a toast confirms. | "Invite cancelled" / "sam.oliveira@renew.example can no longer use the link." |
| 14 | Renew invite: sending | "Renew invite" on an Expired row. No confirmation, since it only sends an email. The button shows progress and is disabled. | "Renewing…" |
| 15 | Renew invite: done | 200: the row becomes Pending with today's date, moves to the top, and the old link stops working. | "Today" / "Invite renewed" / "p.huber@gmail.com has 3 days to accept the new link." |
| 16 | Renew invite: failed | 500 or network failure. The row stays Expired and the button can be pressed again. | "Couldn't renew the invite" / "Try again in a moment." |
| 17 | Invite sent | 201: the dialog closes, the new invite appears at the top as Pending, and a toast confirms. | "lea.martin@renew.example" / "Today" / "lea.martin@renew.example has 3 days to accept." |
docs/design/screens/verify.md
+16 -40
View File
@@ -1,50 +1,26 @@
# Verify account
# Verify
- **Route:** `/register/validate?c=CODE`
- **API:** POST /v1/auth/verify
- **Visual reference:** `source/RenewCMS Screens Auth.dc.html`, group "Verify" (open it in a browser; each state is drawn at desktop and mobile, with a light/dark toggle).
Route: `/register/validate?c=CODE`. API: POST /v1/auth/verify.
Opened from the verification email, and submits automatically on load. This is the only full-card spinner in the product.
## States
Visual reference: `RenewCMS Screens Auth.dc.html`, groups "Verify". Frames: `AppFrame.dc.html` (shell, sidebar, topbar, drawer) plus the screen frame where listed in components.md.
### Verifying
## Copy per state (generated from the board source, pass 2)
**Trigger:** On load, with a code in the URL.
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 Auth.dc.html`. Copy is exact; where a cell is empty the state reuses the fixed copy.
- Full-card spinner: "Verifying your account…"
### Verify account (group "Verify", 6 states)
### Success
Route: `/register/validate?c=CODE`. API: POST /v1/auth/verify.
**Trigger:** 200 → /home after 800 ms, with a toast.
Opened from the verification email, and submits automatically on load. This is the only full-card spinner in the product.
- ResultPanel (success, shield-check): **Your account is verified**; text "Taking you to your dashboard…"
- Toast (circle-check): **Your account is verified** "Welcome to RenewCMS."
### Invalid or expired (403)
**Trigger:** The code is wrong, used, or older than 2 hours.
- ResultPanel (error, link-2-off): **This verification link doesn't work**; text "It may have expired (links last 2 hours) or already been used."; note "Cancel your registration and start over to get a new link."; actions "Cancel registration and start over" (primary), "Log out" (secondary)
### No session (401)
**Trigger:** Opened in another browser or device. Log in inline, then verification retries automatically with the same code.
- Heading: **Log in to finish verifying**
- Description: "You opened this link somewhere you're not logged in. Log in here and we'll verify your account right after."
- Field `Username`: placeholder "Your username"
- Field `Password`: password with show/hide
- Submit button: "Log in and verify"
### No session, retrying
**Trigger:** Logged in inline. Now verifying.
- Full-card spinner: "Verifying your account…"
### Missing code
**Trigger:** The link has no ?c= parameter. No request is made.
- ResultPanel (error, link-2-off): **This link is incomplete**; text "The verification code is missing. Open the link from your email again, or copy the full address into your browser."; actions "Go to log in" (secondary)
| # | State | Trigger | Copy |
|---|---|---|---|
| 1 | Verifying | On load, with a code in the URL. | "Verifying your account…" |
| 2 | Success | 200 → /home after 800 ms, with a toast. | "Your account is verified" / "Taking you to your dashboard…" / "Welcome to RenewCMS." |
| 3 | Invalid or expired (403) | The code is wrong, used, or older than 2 hours. | "This verification link doesn't work" / "It may have expired (links last 2 hours) or already been used." / "Cancel your registration and start over to get a new link." / "Cancel registration and start over" / "Log out" |
| 4 | No session (401) | Opened in another browser or device. Log in inline, then verification retries automatically with the same code. | "Log in to finish verifying" / "You opened this link somewhere you're not logged in. Log in here and we'll verify your account right after." / "Log in and verify" |
| 5 | No session, retrying | Logged in inline. Now verifying. | "Verifying your account…" |
| 6 | Missing code | The link has no ?c= parameter. No request is made. | "This link is incomplete" / "The verification code is missing. Open the link from your email again, or copy the full address into your browser." / "Go to log in" |