RenewCMS/features/users_screen.qa.md

# QA: Users screen and InviteUserModal

## Implementation note for coder (informational, not a QA assertion)

The invitations API is already built and covered by features/invitations.qa.md: this slice has no
Go change in this slice; the API shape was extended by user_roles.feature, so it has no HTTP-level Go section.

The shell specs were amended to five destinations (Home, Articles, Users, Integration, Settings):
nuxt_ui_shell_foundation.feature / .qa.md (case 14) and dashboard_shell_branding.feature. Their
Vitest tests must be updated in the same change.

The Invite sent toast uses `useToast().add({ id: 'invite-sent-{id}', color: 'success', icon:
'i-lucide-circle-check', title: 'Invite sent', description: '{email} has 3 days to accept.' })`.
The list items are keyed by `kind` and `id`.

## Automated (Vitest + Vue Test Utils, `task test:web`)

Mock `useApi`'s `request` for `GET /v1/user/` and `POST /v1/user/invite` per case; no real backend.
Mount UsersPage inside DashboardShell with a resolved verified session (id 1, username "marta",
role "owner") and a test router at /users; cases 6 to 17 use that owner session. The Default
fixture is the Background's 5 items; the invite fixture is
id 3, email "lea.martin@renew.example". No test freezes the system date. The specs only assert on
the fixture's absolute dates; the sent row's "Today" label is not asserted anywhere (see the Visual
part). Run each layout case at a desktop and a below-md width (mock `matchMedia`).

1. **Default** — assert breadcrumb "Users", title, subtitle, "Invite user", the table header
   labels (Email, Display name, Role, Invite status, Created), rows in fixture order, per row the
   email, the display name or "—", the RoleBadge word and class (owner filled, admin outlined),
   the badge word and the absolute date, "Paul Huber" on the invite row, the "you" tag only on
   "marta@renew.example", no username text in any row, and the below-md cards (display name line
   only when set).
2. **Navigation** — assert the sidebar and the drawer list Home, Articles, Users, Integration,
   Settings in that order, and "Users" carries aria-current="page" on /users.
3. **Loading** — unresolved `GET`; with fake timers assert nothing is drawn at 149 ms; at 150 ms
   assert 5 skeleton rows and `aria-busy="true"`, and at desktop that each row has a RoleBadge
   and a status badge placeholder (below md the cards keep the two-bar shape); resolve and
   assert the Default rows.
4. **Only you** — a single "marta" item (email, role "owner"); assert the row, the hint text and
   "Invite user".
5. **Error, Examples-driven** — reject with `ApiError(500)`, then `NetworkError`; assert the alert
   copy, the "Try again" action, no close button and no rows; click "Try again"; assert `request`
   is called again, then resolve the Default fixture and assert its rows.
6. **Invite: default** — click "Invite user"; assert title, text, an empty focused Email with its
   placeholder, "Cancel", "Send invite"; below md assert the pinned button is hidden while open.
7. **Invite: validation, Examples-driven** — "sam.oliveira@renew" then blur; "not-an-email" then
   submit; empty then submit; assert the field error, no `request` call, and focus on the field.
   Assert that fixing the value clears the error.
8. **Invite: sending** — valid address, submit; assert one `POST /v1/user/invite` with body
   `{"email":"lea.martin@renew.example"}`, the field and "Cancel" disabled, "Sending…", and
   Escape and backdrop click not closing the modal.
9. **Invite sent** — resolve 201 with the invite fixture; assert the modal closes, `GET /v1/user/`
   was not called a second time, the list has 6 rows with the new Pending row first and the
   others unchanged, the first row has the `--ui-bg-elevated` background class, and the toast
   was raised with id "invite-sent-3", color success, icon "i-lucide-circle-check", title
   "Invite sent" and description "lea.martin@renew.example has 3 days to accept." Assert the new
   first row shows "—" and "admin", and nothing about the "Today" label.
10. **Replacement of an expired invite** — invite "p.huber@gmail.com", resolve 201; assert exactly
    one row for that address, first and Pending.
11. **Invite sent into Only you** — assert the new row above "marta" and the hint gone.
12. **409, Examples-driven** — reject with `ApiError(409)` carrying each of the two texts; assert
    the matching field error, the address kept, no alert. Also assert an unknown 409 body falls
    back to "This address already has an account.".
13. **400 got through** — reject with `ApiError(400)`; assert the alert and the field error.
14. **Rate limited (429)** — reject with `ApiError(429)` carrying `apperr.TooManyRequestsErrorMessage`
    as body; assert the alert "Too many invites. Wait a moment, then try again." above the buttons
    (the raw body is not shown), the address kept, the form re-enabled, no field error and the
    list unchanged; submit again, resolve 201, and assert the closed modal, the row and the toast.
15. **Failed, Examples-driven** — `ApiError(500)`, `ApiError(500)` with the API's own text as body,
    `NetworkError`; assert the alert "Couldn't send the invite. Try again in a moment." (shown
    once, not the raw body), the address kept, no field error, the list unchanged.
16. **Retry after failure** — from 15, submit again; assert `request` is called a second time with
    the same body; resolve 201 and assert the closed modal, the row and the toast.
17. **Cancel discards** — type, click "Cancel"; assert immediate close, no `request`, an empty
    field on reopening, and focus back on the opening button.
18. **Display names in the Users list** — the Default fixture with user 1 named "Marta Alves"
    (session `/v1/auth/me` too); assert the "marta@renew.example" row shows "Marta Alves", "owner"
    and Accepted, the "ines.duarte@renew.example" row "Inès Duarte" and "admin", the
    "jonas@renew.example" row "—" and "admin", and the sidebar chip "Marta Alves".
19. **Non-owners, Examples-driven** — session role "admin", at desktop and below md; assert no
    "Invite user" button (header or pinned), the list still renders, no reserved space for the
    pinned button, and the hint absent for a list of only "marta" and "jonas". Also a session with
    no role (no button) and an owner control (button present in both layouts).

## Visual (task visual:check -- users, desktop and mobile, light and dark)

Reference: `docs/design/screens/users.md`, board group "Users" in `docs/design/source/RenewCMS
Screens Back-office.dc.html`, exact values in `docs/design/source/AppFrame.dc.html`. Add each
state's mock to `web/visual/states.ts` with the board's own sample data. The gate is hard: every
capture of every non-skipped state must be within 10 %, for both viewports and both themes.

- [ ] Fixtures: `usersFixture` in `web/visual/states.ts` follows the board data: invite 2
      `sam.oliveira@renew.example` pending, no name; invite 1 `p.huber@gmail.com` with
      `display_name: 'Paul Huber'` expired; user 3 `ines.duarte@renew.example` "Inès Duarte" admin;
      user 2 `jonas@renew.example` admin, empty name; user 1 `marta@renew.example` owner, empty
      name. `verifiedSession` carries `role: 'owner'`. `profileSession` and `usersWithDisplayNames`
      are updated so "Display names in the Users list" shows "Marta Alves", owner.
- [ ] Default: the 5 board rows by email with display names, roles and status badges, dates
      27 Sep 2026, 3 Aug 2026, 18 Jun 2026, 2 Apr 2026, 12 Mar 2026; session user `marta`. The
      Cancel/Renew buttons in the sixth column are specified in features/users_row_actions.feature.
- [ ] Loading: 5 skeleton rows, with role and status placeholders on desktop and the board's
      two-bar cards on mobile; the setup must give skeletons time to show (150 ms) before the
      capture.
- [ ] Only you: the single `marta@renew.example` row (owner) plus the hint.
- [ ] Profile "Display names in the Users list" (`task visual:check -- profile "Display names in
      the Users list"`): Marta Alves / Inès Duarte / dash.
- [ ] Not drawn, no visual state: non-owner rendering (no "Invite user", no hint). Covered by
      Vitest only (case 19); do not add it to `web/visual/states.ts`.
- [ ] Error: the alert and "Try again", no table or cards; the header button is still drawn.
- [ ] Invite: default: modal over the Default list, empty focused Email; the mobile pinned button hidden.
- [ ] Invite: validation: value `sam.oliveira@renew`, error copy.
- [ ] Invite: sending: value `lea.martin@renew.example`, disabled field, "Sending…".
- [ ] Invite: already a user (409): value `jonas@renew.example`, error "This address already has an account.".
- [ ] Invite: failed: value `lea.martin@renew.example`, alert "Couldn't send the invite. Try again in a moment.".
- [ ] skip: clock-sensitive. Invite sent: `skip: 'clock-sensitive'` in `web/visual/states.ts`
      ("Today"). It prints SKIP, and is never investigated or date-frozen. Its Vitest coverage is case 9.
- [ ] Not drawn, no visual state: the pending-invite 409 variant and the 429 alert. They are
      covered by Vitest only (cases 12 and 14); do not add them to `web/visual/states.ts`.
- [ ] Layout, taken from the board frame (`AppFrame.dc.html`), not `components.md`: desktop header
      row is title block left and the 32 px "Invite user" button right, aligned to the bottom of
      the row; on mobile the button is 16 px from left, right and bottom, 48 px high, 18 px icon.
- [ ] Layout, from `AppFrame.dc.html`: 36 px table header, 48 px rows, sixth 150 px track empty;
      RoleBadge 20 px high, 7 px side padding, IBM Plex Mono 11 px medium; cards show the email
      line, then the display name, then the badges line.
- [ ] Not covered by screenshots: keyboard and focus order (Tab reaches "Invite user", the modal
      focus starts on Email, then Cancel, then "Send invite", focus is trapped, Esc closes it in
      every dismissible state and is blocked while Sending, focus returns to the opening button);
      hover and active on the buttons; motion (240 ms modal, skeleton pulse 1.6 s, both stopped
      under reduced motion).

## Manual verification

- **Real round trips against `task dev`** — Vitest only mocks `useApi`. Invite a real address and
  confirm: the 201 row, the 409 texts for an existing account and a live pending invite, the
  replacement of an expired invite, the 429 after exceeding `AUTH_RATE_LIMIT_MAX_ATTEMPTS` within
  `AUTH_RATE_LIMIT_WINDOW_SECONDS`, and the list order after a reload.
- **Real invitation email** — needs real or sandboxed SMTP (`SMTP_HOST` and the related env
  vars): the mail arrives and its link `{PUBLIC_URL}/invite/accept?c=...` carries the code. The
  link will not resolve in the SPA, because the accept screen is out of scope.
- **Admin session** — sign in once as an admin against `task dev` and confirm there is no
  "Invite user" button and no "Only you" hint.
- **Toast placement and stacking on a live app** — bottom right on desktop and above the pinned
  button on mobile.
- **"Today" and the elevated row on a live app** — confirm the new row and the "Today" label
  against the real clock, since visual:check skips this state.