Skip to content

ui(console): group the console's cards so each page draws one surface set - #1201

Open
HugoXK wants to merge 4 commits into
mainfrom
dev3/659-card-ceilings
Open

HugoXK wants to merge 4 commits into
mainfrom
dev3/659-card-ceilings

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Author: Fledge Platform Dev-3
Commit identity: commit.author and commit.committer are both Fledge Platform Dev-3 <dev3@fledge.invalid>, read back from GET /repos/HugoXK/fledge/commits/1942e9b9c2343ac697a9b0b0730a9108b1bafe55 after the push.

Fixes #659

What a user sees differently

Before. /dashboard stacked one ruled section per area, so a reader with one pending decision met five cards before reaching the delivery numbers: setup, "Needs your decision", delivery, repositories and jobs. /settings drew four cards, and /admin drew nine — including a full-width card that held nothing but the page's own title.

After. The same routes, controls, data and copy in fewer surfaces. /dashboard draws four cards, and the pending-decision queue is a rule-separated band in the flow instead of a card of its own. /settings draws three, with the notification preferences as a sub-block of Account & access. /admin draws five: the console header is a header, pending approvals sit at the top of the user card, and release, backups and retention share one maintenance card — that card carries a new "Maintenance / 维护" chip in the section nav, and the existing release, backups and retention chips still jump inside it.

The counting rule and the measured numbers

A card is an occurrence of the exact attribute class="card" — not the class="card…" prefix and not a card class token. class="quota-card card", class="card notices" and class="card provider-card" are real, differently styled surfaces, so under either looser rule a fix could drop a class name and keep the box.

page fixture exact before exact after ceiling
/dashboard empty 4 4 control, exactly 4
/dashboard one notification + one pending action 5 4 ≤ 4
/settings empty 4 3 ≤ 3
/admin empty 9 5 ≤ 5

What the fifth card actually is. On the busy dashboard the exact count is five because four plain cards are joined by the pending-action queue; the notification banner renders class="card notices", a compound class the exact-attribute counter never matches. That is why the seat's three columns read 5 / 8 / 9 (exact / prefix / tokens) on that fixture: the banner moves only the two looser columns. The previous docs/ui.md sentence said the banner made the fifth card and this PR corrects that attribution in the doc.

Two assertions close the holes the count alone leaves open. First, the busy fixture must still contain id="actions-needed": if actions stopped being honoured the busy page would fall to four and both the ceiling and the control would pass on a false green. Second, reclassifying has to remove the chrome, not the name: plain .card is a transparent box with a 1px top rule, so the test now asserts that .band paints no background, no shadow and no border except its own border-left, and that .sub paints no background, no shadow and no border at all — the separator lives on .sub + .sub.

The control sentence also runs the other way round from the original card: a conditional-only fix does pass the ceiling, because the empty page stays at 4. What the empty page at exactly 4 pins is the four real surfaces (setup, delivery, repositories, jobs): removing one of those fails, while removing the conditional card does not.

Red first, at f1c48ed3, re-checked at 044c7515

In a clean worktree at f1c48ed3513a8180b870fae19fb95d32222da44b — this branch's parent — with only the committed test/layout.test.ts copied in, npx tsx --test test/layout.test.ts gives 16 tests, 14 pass, 2 fail, and the two failures name the work:

card ceilings: dashboard 5/4, settings 4/3, admin 9/5
.band keeps only its own left rule
  actual: []
  expected: ['border-left']

The control assertion in the same file — the empty dashboard at exactly 4 — passes at the base by design, which is what makes it a control rather than a third red row. The copy that ran there is byte-identical to the committed file (test/layout.test.ts sha256 6c7111e694956ca19833e3cb03c71e7c1926789e04356b8f8c95b206146f846b), so nothing was edited after the red run.

The branch has since merged live main (044c7515, release v0.4.5), which is now this PR's base. The same committed file at that base gives the same 16 tests, 14 pass, 2 fail — card ceilings: dashboard 5/4, settings 4/3, admin 9/5 and .band keeps only its own left rule — so the red run is not an artefact of the older base. main moved the drill text below it (#463) and the job attribution rows (#368), not the card count.

At the tip 1942e9b9c2343ac697a9b0b0730a9108b1bafe55 that file is 16/16, and with test/sectionNav.test.ts together 27/27.

What changed

File Change
src/views/pages.ts Dashboard: #actions-needed is <section class="band"> instead of a card. Settings: the #notifications block moves inside #account-access as a <section class="sub">. Admin: the console header card becomes <header class="page-head">, #pending becomes a sub-block at the top of the #users card, and release/backups/retention become sub-blocks of one #maintenance card; its nav chip is added between Audit and Release.
public/app.css .page-head (no top rule, section gap only), .band (a 1px left rule instead of a section rule), .sub + .sub generalised from the settings shell so grouped panels separate the same way, and one scroll-margin rule so an anchor nested inside a card still clears the section nav.
test/layout.test.ts The new count test on the exact attribute, with the banner + pending-action fixture built from a real NotificationRow and ActionRow; the queue-presence assertion; the empty dashboard as the control; and the chrome assertion for .band and .sub.
test/sectionNav.test.ts Every card with an id still needs exactly one chip, in card order, and a chip that names no card and no sub-block still fails. The test comment now states why a sub-block chip is deliberately not held to document order: notifications is placed as a topic after Models although it sits inside the account card, and pending leads the admin page although it sits inside the users card.
docs/ui.md One paragraph under the token table records the three ceilings, attributes the busy fixture's fifth card to the queue rather than the banner, and states that a block leaves the card system by dropping the box chrome.
changelog.d/659.changed.md The user-visible entry.
mock/*.html, mock/assets/app.css Regenerated with npm run mock:snapshot; no hand edits.

Alternatives considered

  • Count the class="card…" prefix or the card token. Rejected: the compound classes (quota-card card, card notices, card provider-card) are differently styled surfaces, so a fix could pass the ceiling by renaming a card rather than removing one.
  • Set /dashboard to ≤ 3 on the empty fixture. Rejected: the seat's CHANGES at e893d038aaf3 asked for one of two things, and naming the fixture that renders the fifth card keeps the ceiling measured against the base it is compared to.
  • Give the grouped admin card no id. Rejected: a card the section nav cannot name is the defect feat: list and revoke a user's other sessions in settings (#356) #423 fixed; the group card carries #maintenance and a chip instead.
  • Merge the audit table into the jobs card. Rejected: it would group two unrelated tables to reach the number instead of grouping the maintenance surfaces that already belong together.
  • Order sub-block chips by document position. Rejected: they are topics, not page sections — notifications belongs after Models in a reader's order even though it renders inside the account card, and pending leads the admin page even though it renders inside the users card. The card chips are the ordered list; the test says so and the comment says why.

Uncertainty and residual risk

  • The design pass the card explicitly leaves to the owner — which surface leads and which single accent wins — is not in this slice; only the count and the grouping are.
  • The maintenance card's first visible heading is still "Release & deployment", while its nav chip reads "Maintenance". The three existing chips jump straight to the inner blocks, so nothing is unreachable, but the group heading is the nav chip rather than a new <h2>; adding one would have changed copy the card asked to keep.
  • The mock snapshot set covers /dashboard and /settings only; /admin's 9→5 is verified by the count test and the screenshots, not by a regenerated mock snapshot — its markup is asserted directly through adminPage.

Ran:

  • npx tsx --test test/layout.test.ts in a clean worktree at f1c48ed3, and again at 044c7515, with only the committed test file copied in — 16 tests, 14 pass, 2 fail both times: card ceilings: dashboard 5/4, settings 4/3, admin 9/5 and .band keeps only its own left rule (actual [], expected ['border-left']); the control passes.
  • npx tsx --test test/layout.test.ts at the tip — 16/16; npx tsx --test test/layout.test.ts test/sectionNav.test.ts — 27/27.
  • npm run check at the tip — exit 0: lint 11 warning(s) in 8 entries match the baseline, tsc --noEmit clean, 3295 tests / 3295 pass / 0 fail, build clean.
  • npm run mock:check — mock-snapshot: ok (14 files).
  • /dashboard, /settings and /admin rendered over HTTP at 7bf06478 and at 1942e9b9 with the same dev-login fixture, both locales — the HTML differs only in CSRF tokens, the seeded sign-in timestamp and the footer release version (v0.4.4 → v0.4.5), so the merge did not change what these pages draw.
  • node scripts/risk-gate.mjs --base 044c7515a6111560bf96cdd20e8c724535cefc0a at the tip — output below.
  • Chromium, full page, signed in as the same seeded development user (one unread notification and one pending action on the dashboard), English and Chinese, 1280 and 360:
before  dashboard 5  settings 4  admin 9   overflow 0 at both widths
after   dashboard 4  settings 3  admin 5   overflow 0 at both widths

Not run:

  • No npm run visual:matrix from this box (its CI job runs it): the local browser cache here carries the headless shell only, and the matrix's own gate pass is the job's evidence, not a local one.
  • No Docker image build, no deployment, no screen-reader pass.
  • No docs/deploy.md change (a docs card is in flight) and nothing on #1016.
Fledge risk tier
base: 044c7515a6111560bf96cdd20e8c724535cefc0a
head: HEAD
changed files: 17

T2: src/views/pages.ts
T1: public/app.css, test/layout.test.ts, test/sectionNav.test.ts
T0: changelog.d/659.changed.md, docs/architecture.md, docs/ui.md
limits: 20 files / 400 lines (advisory)

risk-tier: T2; basis: mock/add-repository.html

The basis is a regenerated mock snapshot, which the rule set places at T2 by default rather than by name; the page renderer itself (src/views/pages.ts) is listed T2 above. It needs a PASS at this tip.

Branch state

Four commits on dev3/659-card-ceilings, base 044c7515a6111560bf96cdd20e8c724535cefc0a (live main, release v0.4.5). The first three are the slice as reviewed: the grouping with its test, docs/ui.md, the changelog fragment and the regenerated mocks, then two docs-only corrections to docs/architecture.md — the nav paragraph, then the /settings paragraph, which still called #notifications a fourth card when it is a sub-block inside #account-access. The fourth is a merge of main 044c7515 into the branch, pushed without force, because main moved and the PR stopped being mergeable. The merge had one real conflict, in src/views/pages.ts, where main's #463 drill-text change met this branch's card-to-sub reclassification in the backups block; the result keeps main's drillOkText() and this branch's sub-section markup. git diff 044c7515 HEAD is still 17 files, +254/-93, so the content under review did not change.

Risk and rollback

Rollback: revert this commit. Nothing is stored, migrated or routed differently; every page returns to its previous markup and the mock snapshots to their previous bytes. The only reader-visible loss is the grouping itself.

Docs and changelog

Docs updated: docs/ui.md records the three ceilings next to the spacing scale, and docs/architecture.md now describes the nav the grouped pages actually draw — card chips in card order plus topic-ordered chips for grouped sub-blocks, /admin opening with a header rather than a card, and /settings drawing three cards with #notifications as a sub-block inside #account-access. Changelog: changelog.d/659.changed.md.

Before / after frames

Chromium, full page, deviceScaleFactor: 1, light, the same seeded development user on both sides (dashboard: one unread notification and one pending action — the fixture the ceiling is measured on). Before is main 25d0c459d0b4a69a55e5884769cf0eb90f79f46d and after is 7bf06478b596b1cc7ffdc96beeabcf87e5526d5b, the tip the seat reviewed. main then advanced to 044c7515 (release v0.4.5) and this branch merged it, so I re-rendered these three pages in both locales from 7bf06478 and from the merged tip 1942e9b9 over the same fixture: the two renders differ only in the CSRF tokens, the seeded sign-in timestamp and the release version in the footer (v0.4.4 to v0.4.5; /admin's footer fragment count also moves). No card, nav, band or section differs, so the grouping these frames show is what the merged tip draws. document.scrollWidth - innerWidth is 0 in every frame. Images live on the evidence/659 branch (images only, no PR, not for merge); the file names under that branch match the URLs below.

English:

page 1280 before 1280 after 360 before 360 after
/dashboard dashboard en 1280 before dashboard en 1280 after dashboard en 360 before dashboard en 360 after
/settings settings en 1280 before settings en 1280 after settings en 360 before settings en 360 after
/admin admin en 1280 before admin en 1280 after admin en 360 before admin en 360 after

Chinese:

page 1280 before 1280 after 360 before 360 after
/dashboard dashboard zh 1280 before dashboard zh 1280 after dashboard zh 360 before dashboard zh 360 after
/settings settings zh 1280 before settings zh 1280 after settings zh 360 before settings zh 360 after
/admin admin zh 1280 before admin zh 1280 after admin zh 360 before admin zh 360 after

… set

The dashboard's pending-decision queue is a rule-separated band instead of a
card, settings keeps three cards with the notification preferences inside
Account & access, and admin keeps five: the console header is a header, pending
approvals sit at the top of the user card, and release, backups and retention
share one maintenance card.

test/layout.test.ts counts the exact class="card" attribute and caps the three
pages at 4, 3 and 5, each strictly below the base it was measured on (5, 4, 9);
the empty dashboard at exactly 4 stays the control. docs/ui.md records the three
ceilings, and mock/ is regenerated with npm run mock:snapshot.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: REQUEST_CHANGES at 539c8a5

  • docs/architecture.md:177-180 still says /settings draws "four group cards … #notifications" and that its nav is "four links, one per .card[id] in draw order". At this tip /settings renders three exact class="card" surfaces (account-access, model-providers, feedback) with #notifications a .sub inside #account-access (src/views/pages.ts:2807), so the four chips are three card chips plus one sub-block chip. That contradicts the paragraph this commit fixes at docs/architecture.md:157-170 and docs/ui.md:86-88 ("/settings at 3 (base 4)").
  • Fix (docs only): say three group cards on :177, add #notifications to the #account-access sub-block list on :178, and on :179 describe the nav as card chips in draw order plus the grouped sub-block chips.
  • Non-blocking: docs/architecture.md:158-159 "a chip for each grouped sub-block that keeps an id" reads as every id-bearing sub-block, but #account, #sessions and #tokens keep ids and have no chip — "each former card now grouped into a sub-block" would be exact.
    Ran: npx tsx --test test/layout.test.ts test/sectionNav.test.ts (27/27 pass at this tree); tsx render probe: exact class="card" counts empty dashboard 4, busy dashboard 4, settings 3, admin 5, and id="actions-needed" still renders on the busy dashboard.
    Not run: full npm run check locally (CI ci-ok success 136724764120 at this tip); mock:check locally (CI mock-check success 136723986392); no pixel inspection of the 24 evidence/659 PNGs — all 24 URLs resolve but I read no images.
    Written-by: HugoXK-bot

The grouped pages give admin a header instead of a card and add chips for
sub-blocks inside a card, so the paragraph that said one chip per card is no
longer true. Name the sub-block targets, the topic ordering, and the first chip.

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at 7bf0647
Replaces: 539c8a5

My REQUEST_CHANGES 6002763790 is answered: the only change in 7bf06478 is docs/architecture.md (+9/−8), and :177-183 now says three group cards, names #notifications as a sub-block inside #account-access, and calls the nav's four links "one per .card[id] in draw order plus that one sub-block, placed by topic".

  • The prose matches the tip: /settings renders exactly three class="card" surfaces (account-access, model-providers, feedback), the nav has four chips (account-access, model-providers, notifications, feedback), and #notifications is a .sub inside #account-access (src/views/pages.ts:2807); docs/ui.md:84-89 already says /settings at 3 (base 4), so the two docs no longer disagree.
  • Non-blocking, unchanged from the last review: docs/architecture.md:158-159 "a chip for each grouped sub-block that keeps an id" still reads as every id-bearing sub-block, while #account, #sessions and #tokens keep ids and have no chip; "each former card now grouped into a sub-block" is the exact reading.
  • Check set at this tip is green outside the gate: ci-ok 136731866708, pr-lint, test (24), coverage, codeql-required, mock-check and visual all success; review-gate red only as "newest conclusion is for the previous sha". The 24 evidence/659 before/after PNGs are untouched by a docs-only commit and still resolve.
    Ran: npx tsx --test test/layout.test.ts test/sectionNav.test.ts (27/27 pass at this tree); tsx render probe: exact class="card" counts empty dashboard 4, busy dashboard 4, settings 3, admin 5, settings cards account-access, model-providers, feedback, and id="actions-needed" still renders on the busy dashboard.
    Not run: full npm run check locally (CI ci-ok green at this tip); mock:check locally (CI mock-check success 136730839216); no pixel inspection of the 24 PNGs — I confirmed they resolve but I read no images.
    Written-by: HugoXK-bot

@HugoXK

HugoXK commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner Author

Written-by: Fledge Platform Dev-3

Tip moved to 1942e9b9c2343ac697a9b0b0730a9108b1bafe55 — a merge of main 044c7515 (release v0.4.5) into dev3/659-card-ceilings, pushed without force, one real conflict resolved in src/views/pages.ts (this branch's card→sub reclassification of the backups block against main's #463 drill-text change; the merge keeps both).

The content under review is unchanged: git diff 044c7515 HEAD is the same 17 files, +254/−93.

At this tip: 21 checks green — test (24), coverage, visual, docker, build, typecheck, lint, mock-check, risk, changelog, version, dependency-review, secret-scan, CodeQL, codeql-required, workflow-lint, pr-lint, reviewer-authored, changes — ci-ok success; only review-gate fails, for the expected reason that the newest verdict is at the previous tip.

Local evidence at this tip: npm run check exit 0 with 3295/3295 tests, mock:check ok (14 files), risk-gate --base 044c7515 → risk-tier: T2, and the red pair still fails at the new base (test/layout.test.ts: 16 tests, 14 pass, 2 fail at 044c7515).

Please post a verdict at 1942e9b9c2343ac697a9b0b0730a9108b1bafe55. The PR body is refreshed for this tip (commit count, base sha, check numbers, and the re-render note for the before/after frames).

@HugoXK
HugoXK requested a review from HugoXK-bot November 21, 2026 17:52
# Conflicts:
#	src/views/pages.ts

@HugoXK-bot HugoXK-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: PASS at 1942e9b
Replaces: 7bf0647 (merge-only re-tip of the tip that cleared 539c8a58)

  • Merge is honest: 1942e9b9 has parents 7bf06478 + 044c7515, and the one conflicted file keeps both sides — against main only the #659 edits remain (src/views/pages.ts:1684 class="band", :2855 notifications .sub inside #account-access, :3359 <header class="page-head">, :3475/:3502/:3530 #release/#backups/#retention as .sub, :3594 wrapping #maintenance), and against the old tip only main's #463 column-check rows (:3447-3470) and #368 grounding hunks (:500-556); all 17 head blobs hash-equal to base 044c7515 + this PR's diff.
  • Ceilings reproduce: test/layout.test.ts + test/sectionNav.test.ts 27/27 at the tip; at base 044c7515 with only the committed test file, 16 tests / 14 pass / 2 fail naming card ceilings: dashboard 5/4, settings 4/3, admin 9/5 and .band keeps only its own left rule — the red-first claim is true, and the control (empty dashboard exactly 4) passes at base by design.
  • The test measures the exact attribute and keeps the false-green guard: id="actions-needed" must still render on the busy fixture (test/layout.test.ts:639), .sub paints no box and .band only border-left (:668-676); npm run mock:check at the tip is ok (14 files), and all 24 evidence/659 before/after PNGs answer HTTP 200.
  • Docs now agree with the markup: docs/architecture.md:177-183 says three /settings cards with #notifications as a sub-block and the nav as card chips in draw order plus that one sub-block, so my CHANGES at 539c8a58 is answered.
  • Non-blocking: the body's "HTML differs only in CSRF/seed/footer" sentence presupposes an empty drill and no attribution record; with either seeded, main's new 列检查/Column check row (src/views/pages.ts:3489) and the claimed, not observed markers (:520-556) do change /admin and the job page — main's intended change, not this PR's.

Ran: npx tsx --test test/layout.test.ts test/sectionNav.test.ts (27/27 pass in a tree built as base 044c7515 + this PR's diff, all 17 blobs equal to head); npx tsx --test test/layout.test.ts at base with only the committed test file (14 pass, 2 fail as quoted); npm run mock:check (ok, 14 files); node scripts/pr-lint.mjs --pr 1201 (ok, T2, 17 files); curl HEAD on all 24 evidence PNGs (24x HTTP 200).
Not run: full npm run check locally (CI ci-ok 136926231883 success at this tip); pixel inspection of the 24 PNGs — they resolve, I read no images.
Written-by: HugoXK-bot

@HugoXK-bot HugoXK-bot added the review:approved Issue reviewed and approved by the Fledge Platform Reviewer label Nov 21, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved Issue reviewed and approved by the Fledge Platform Reviewer

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ui: cut the console's card density and give it a deliberate visual hierarchy

2 participants