feat: integration page (PART 3/3)

features/integration.qa.md

@@ -1,66 +1,98 @@
-# QA: Integration screen
+# QA: Integration screen (API reference)
 
 ## Automated (Vitest + Vue Test Utils, `task test:web`)
 
 Mount IntegrationPage inside DashboardShell with a resolved verified session and a test router at
-/integration. Stub `window.location.origin` (or the equivalent composable/helper the coder uses to
-read it) to a fixed value for the test, and stub `navigator.clipboard.writeText` per case. No
-`/v1` mocks are needed; the screen makes no calls.
+/integration. Stub `window.location.origin` to `https://cms.renew.example` (the board's sample) and
+`navigator.clipboard.writeText` per case. No `/v1` mocks are needed. A spec fails if any `/v1` call
+is made.
 
-1. **Default** — mount at /integration with origin stubbed to a fixed value (e.g.
-   `https://cms.renew.example`, matching the design board's sample so the assertions read the same
-   as the visual reference); assert breadcrumb "Integration"; assert the PageHeader title
-   "Connect your website" and description "A guide for the developer who builds your public
-   site."; assert the intro paragraph text; assert the Base URL row shows exactly the stubbed
-   origin; assert the Base URL "Copy" button reads "Copy"; assert both EndpointCards render in
-   order (GET /v1/article/, GET /v1/article/{id}) with their descriptions and their fetch examples
-   containing the stubbed origin; assert the fetch tab is active by default on both cards; assert
-   the three info notes render in order.
-2. **Copied** — from Default, use fake timers; click the Base URL row's "Copy" button; assert
-   `navigator.clipboard.writeText` was called with the stubbed origin; assert the button's icon is
-   check and its text is "Copied"; assert the change is exposed to assistive technology (e.g. an
-   aria-live region or a status role holds "Copied"); advance the fake timer by 2 s; assert the
-   button reverts to icon copy and text "Copy".
-3. **EndpointCard's own Copy button is independent** — from Default, click the "/v1/article/"
-   card's "JavaScript" CodeBlock's "Copy" button; assert `navigator.clipboard.writeText` was called
-   with that card's exact code string; assert only that button reads "Copied"; assert the Base URL
-   button still reads "Copy" and the other card's Copy button still reads "Copy". This behavior is
-   Vitest-only; it has no visual-check state of its own (see Visual below).
-4. **curl and Response tabs render, unchecked visually** — from Default, switch the "/v1/article/"
-   card to its curl tab; assert its content is a plain curl command built from the stubbed origin
-   (e.g. "curl https://cms.renew.example/v1/article/"); switch to its Response tab; assert its
-   content is a JSON sample built from the real domain Article fields. Neither tab's content is
-   asserted pixel-for-pixel anywhere, since the design board only ever shows the fetch tab active.
+Catalogue spec (pure data, no mount, imports web/src/data/apiCatalogue.ts):
+1. The catalogue holds exactly the 20 expected key-callable routes from an explicit hand-maintained
+   list in the spec (Articles 7, Media 6, Users and invites 6, Settings 1), each once, with no other
+   expandable route. Session only has the 13 rows and Public auth flow the 6 rows listed in the
+   feature, from the same kind of explicit list.
+2. Every catalogue route has a non-empty `description`. An empty or missing one fails the spec and
+   names the route.
+3. Every route has method, path, access chip, key chip, a query-parameter list and a body-field list
+   (possibly empty), and fetch, curl and Response examples.
+4. The Response sample of each route parses as JSON and uses only keys from a fixture of the real
+   fields:
+   - article: id, title, body, body_format, is_online, created_at, updated_at;
+   - media item: id, filename, url, size, content_type, width, height, sha256, uploaded_by,
+     created_at, used_in, duplicate;
+   - media list: items, next_cursor, counts (all, unused, duplicates);
+   - merge: articles_updated, merged;
+   - usage: id, title, published;
+   - user list item: id, kind, username, display_name, email, role, status, created_at;
+   - invite: id, kind, email, status, created_at, expires_at;
+   - settings: version.
+   Any other key fails the spec. "images" and "status" are explicitly rejected on articles.
+5. Request-body tables equal the validate tags (title 3-200, body max 10000, filename, keep_id,
+   merge_ids, display_name, email). The multipart field is "file". Query tables: `format` on every
+   article route, and q, hash, cursor, filter, sort, limit on GET /v1/media/.
+6. The three invite routes carry "Owner only", a 403 "Only the owner can do this." caption and the
+   rate-limit sentence. No /v1/system route is in an expandable group. Login, Log out, Register and
+   Reset password rows carry no 403 claim. Verify, DELETE /auth/register, /api-key/* and
+   /system/* are the only rows that claim 403.
+7. Error captions equal fixtures copied from api/pkg/apperr/messages.go and the image domain
+   errors (413, 415, 400 on upload).
+
+Component specs, one per design state:
+1. **Default**: breadcrumb, title "API reference", description, intro, Base URL equals the stubbed
+   origin, all cards collapsed (aria-expanded "false"), section index entries present, the three
+   invite rows show "Owner only".
+2. **Group scrolled, one card expanded**: click the POST /v1/article/ row. Assert the Query
+   parameters table above the Request body table, the body rows, tabs fetch/curl/Response with fetch
+   active, the "JavaScript" CodeBlock, and the Errors list with 400 and 401.
+3. **Copied: base URL**: fake timers; click Copy. Clipboard gets the origin; check icon and "Copied";
+   announced; reverts after 2 s.
+4. **Copied: CodeBlock**: expand a card; click "Copy JavaScript example". Clipboard gets that code,
+   only that button reads "Copied", and it reverts after 2 s.
+5. **Authentication**: both cards, curl/fetch tabs for GET /v1/auth/me, the "Manage API keys" link
+   href /integration/api-keys, Note 1, Note 2.
+6. **Session only**: the corrected banner; lock icon and "Session only" chip only on rows that
+   answer 403; the caption on the login family; no expand control; the "Public auth flow" rows with
+   the "Public" chip.
+7. **Errors**: table rows 400, 401, 403, 404, 409, 429, 500 with the real strings and the 403
+   sample block.
+8. **Navigation**: clicking an index item sets aria-current and scrolls to its anchor; the mobile
+   "Jump to" lists the same sections.
+9. **Tabs**: curl and Response render for a card. curl contains the stubbed origin and the
+   Authorization header only on non-public routes. Not visually checked.
+10. **Notes**: format note, image-prefix note, CORS note.
 
 ## Visual (`task visual:check -- integration`, desktop and mobile, light and dark)
 
-Reference: `docs/design/screens/integration.md` and
-`docs/design/source/RenewCMS Screens Back-office.dc.html`, group "Integration"; layout detail from
-`docs/design/source/AppFrame.dc.html`'s `isInteg` block.
+Reference: docs/design/screens/integration.md; board "Integration" drawn by
+docs/design/source/IntegrationPage.dc.html. Serve the SPA under `https://cms.renew.example`. Mocks
+reuse the board's script data: BASE, KEY, group and endpoint descriptions, the request bodies
+(for example the "Choosing tiles for a small bathroom" article). Response samples are not compared;
+the Response tab is never active in a board frame.
 
-The visual-check setup for this screen serves the SPA under `https://cms.renew.example` via
-Playwright request routing, so the real `window.location.origin` the running app reads matches the
-board's sample text exactly; no production test hook or origin stub is needed in app code.
+Pre-approved exceptions: the user pre-approved visual exceptions for Session only, Group scrolled
+one card expanded, Errors and Default. For each of these four states the coder measures the real
+diff, sets the smallest `maxPercent` that is sufficient, writes the reason, and records
+`approvedBy` "Florian Sylvain". The other states must still pass 10 %.
 
-- [ ] Default state: PageHeader ("Connect your website" / description), intro paragraph, Base URL
-      row with monospace text and a "Copy" button (icon copy), two EndpointCards in order with
-      their GET badge, path, description, fetch/curl/Response tabs (fetch active), JavaScript
-      CodeBlock and its own "Copy" button, and the three info notes below — matches the board
-      exactly at desktop and mobile, light and dark. Sample data for the mocked run: origin
-      `https://cms.renew.example`, served as above.
-- [ ] Copied state: the Base URL button shows the check icon and "Copied" text, in the success
-      color, matching the board's `copied: true` frame. This state is timer-driven, not
-      date-driven, so it is not clock-sensitive and gets a real visual check, not a skip.
-- [ ] Keyboard/focus (manual, not a screenshot check): Tab order reaches the Base URL "Copy"
-      button, then each EndpointCard's tab strip (fetch/curl/Response, reachable and operable with
-      arrow keys per UTabs), then that card's own CodeBlock "Copy" button, then the pre's
-      `tabindex="0"` for scrolling; Enter/Space activates each Copy button.
-- [ ] Hover (manual): ghost Copy buttons show a hover state consistent with other ghost buttons
-      elsewhere in the app (UserMenu, ArticleTable row menu).
+- [ ] Default (exception: owner-only chips and rate-limit line)
+- [ ] Group scrolled, one card expanded (exception: Query parameters table)
+- [ ] Copied: base URL (must pass 10 %)
+- [ ] Copied: CodeBlock (must pass 10 %)
+- [ ] Authentication (must pass 10 %; Note 1 text changed)
+- [ ] Session only (exception: banner, 13th row, captions, Public auth flow block)
+- [ ] Errors (exception: 409 row)
+- [ ] Navigation (must pass 10 %)
 
-## Manual verification
+None of these states is clock-sensitive, so none is skipped.
 
-- Confirm the real running app's `window.location.origin` (e.g. `https://your-domain.example` in
-  production, or `http://localhost:8080` under `task dev`) renders correctly in the Base URL row
-  and in both fetch examples, since Vitest only ever exercises a stubbed origin, and
-  `visual:check` only ever exercises the routed `https://cms.renew.example` origin.
+## Manual
+- Keyboard and focus order: index, Base URL Copy, each row (Enter/Space), tab strip (arrow keys),
+  CodeBlock Copy, the pre (tabindex 0), Jump to on mobile.
+- Hover and motion on ghost Copy buttons and rows.
+- Find-in-page and a deep link to an `#ep-...` anchor.
+- Real origin in a production build and under `task dev`.
+- Run each documented example against a running server with a real `rcms_` key, including the
+  403 on a session-only route and the owner-only 403 for an admin key on the invite routes. This
+  needs a real server and is not automated.
+- docs/api.md matches the catalogue (hand check).