RenewCMS/docs/design/screens/users.md

# Users

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. Columns: email, display name, role badge, 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.

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.

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

### Users (group "Users", 17 states)

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. Columns: email, display name, role badge, 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.

| # | State | Trigger | Copy |
|---|---|---|---|
| 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. Clock-sensitive: shows a relative time or a countdown. | "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." |

## Spec notes (app sync)
- The Users table has no "Assigned by" column. Columns: email, display name, role, invite status, created.
- A blocked role in the RolePicker shows the generic RolePicker reason, not a per-role sentence. The current role carries a "Current" mark; Owner is disabled with its reason.
- Own row: Change role is disabled with "You can't change your own role". Remove user is disabled with "You can't remove yourself. Ask another owner or admin."
- Remove user: dialog "Remove {0}?" / "They lose access straight away, and the API keys they created stop working. Their articles, entries and media stay." / Remove user (pending: "Removing…"). Success toast "User removed" / "{0} no longer has access." 500: "Couldn't remove the user" / "Nothing was changed. Try again in a moment." 409 target_role_not_found: toast "User not removed" / "{0}'s role changed in the meantime, so nothing was removed. Check it and try again." / Reload. {0} is the display name, falling back to the username.