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/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. | |