Skip to content

ui: simplify Settings into grouped sections with a sticky rail #860

Open

Description

@HugoXK

Written-by: HugoXK
Rewritten-by: Fledge Platform Product

The closed deploy-docs finding this card previously carried is preserved in #880; the card now covers one item of the UI program. Everything below was read at main 4355086892c1e7c5efdc56c5d88b9719d8ad912b.

1. What the page is today

settingsPage is one function, src/views/pages.ts:2145-2382, and it renders six sibling cards:

Card Where Contents
#account src/views/pages.ts:2211-2216 login, masked email, join date, quota
#model-providers :2218-2286 providers, per-provider models, add-provider form, discover, edit disclosure
#notifications :2288-2307 email address, four switches, test mail
#tokens :2309-2329 token table, create form
#sessions :2331-2339 session table, revoke-others, rotate
#feedback :2341-2373 the feedback form and the history list
About :2375-2382 "About Fledge" plus a second Star button

The nav is the six chips at :2203-2210. The footer already carries the star: src/views/layout.ts:314 (.star-link), so the About card is the duplicate.

Three things a reader hits:

  1. Six chips for four jobs. Account, sessions and tokens are one job ("who I am and what can act as me"); they are three separate card shells, so the reader scrolls through three headers to answer one question.
  2. About is not a setting. It is the last card on a settings page and it repeats a footer button three lines below itself (:2375-2382 vs layout.ts:314).
  3. Feedback mixes a form with a history. :2345-2362 is the form, :2363-2372 is the history below it, so the thing you came to read (what happened to my report) sits under a form you usually are not filling in. Elsewhere the product already opens the same form as a dialog: src/views/layout.ts:282-306, reachable from the footer link at :313 — but that dialog is deliberately not rendered on /settings (src/views/layout.ts:279, !onSettings), because the page carries the inline form instead.

2. The constraint that decides the shape

test/sectionNav.test.ts:124 asserts that the chips and the page's .card[id] elements are the same list, in the same order — "every settings card must have one chip, in the order the page draws them". public/app.js:358-372 then marks the current chip by resolving each href="#id" with getElementById.

So "group the chips" is not a chip-label edit: unless the page actually grows four cards, four chips would fail that test on the fifth card. The smallest correct shape is four group cards containing the old blocks as plain sub-blocks, with every old id kept as an inner anchor so existing links and three existing tests keep working:

  • test/sessionRevoke.test.ts:177 requires id="sessions" to exist on /settings.
  • test/pages.test.ts:1951-1970 requires every in-page href="#…" on /settings to have a target, and names #tokens explicitly (the zero-token empty state links there, pages.ts:2170).
  • scripts/visual-matrix.ts:140-156 visits /settings#tokens and fails if the anchor is missing or lands under the sticky header.
  • src/views/checklist.ts:101, :108, src/views/pages.ts:959, src/app.ts:4494-4496 and test/setupChecklist.test.ts:78 all deep-link /settings#model-providers.

3. Expected after the slice

  • Four group cards, in this order: #account-access (inner #account, #sessions, #tokens), #model-providers, #notifications, #feedback.
  • Four chips, same labels and same order: Account & access (账户与访问), Models (模型), Notifications (通知), Feedback history (反馈记录). Each chip still points at a .card[id], so test/sectionNav.test.ts stays green in both directions.
  • Desktop (>= 961px): the nav becomes a sticky left rail inside a two-column shell, position: sticky; top: var(--header-h), one link per group, the current one marked with a 2px left rule plus aria-current="true" (same attribute app.js already writes). Mobile (<= 960px): the existing chip strip is unchanged, including its horizontal scroll and 44px targets.
  • One <nav class="section-nav">, one set of links, both layouts by media query. No duplicated rail markup: app.js resolves the same four links at every width, and public/section-nav.js / public/app.js need no change.
  • Scroll offset: the pinned rule public/app.css:1269 (.section-nav ~ .card[id] { scroll-margin-top: calc(var(--header-h) + var(--nav-h)) }) documents the admin page and stays as it is; the settings shell gets its own rule at the same offset on mobile and var(--header-h) above 961px, because a vertical rail has no bottom bar. app.js reads the computed scrollMarginTop, so the marker and the jump stay in agreement.
  • About is gone; the footer .star-link is the only Star call to action. No /about route: the owner's Expected allows either, and deleting the card is the smaller change.
  • Feedback becomes history first, one action second. The section renders the history list (:2363-2372), then one "Send feedback" button carrying data-open-dialog="feedback-dialog" like the footer link (layout.ts:313). The dialog is now rendered on /settings too (drop !onSettings at layout.ts:279), so the action works. The inline form moves inside <noscript> — it is the no-JS fallback the owner asked to keep, and with JavaScript on there is exactly one visible form per page, not two.

4. Smallest mergeable slice (one PR, T2)

  1. src/views/pages.ts:2203-2210: four chips.
  2. src/views/pages.ts:2211-2373: regroup into four section.card[id] blocks; the current #account, #sessions, #tokens become non-card blocks (for example <div class="sub" id="account">) inside #account-access, keeping every id, every form action and every bilingual string; the feedback form is wrapped in <noscript>.
  3. src/views/pages.ts:2375-2382: delete the About card. Nothing else in the page moves.
  4. src/views/layout.ts:274-282: render the feedback dialog on /settings as well; feedbackHref stays #feedback on the settings page.
  5. public/app.css: a .settings-shell two-column grid at min-width: 961px, the rail overrides (column direction, sticky offset, left 2px current marker, no bottom border), and the settings scroll-margin rule described above. Below 961px nothing changes. All colours and radii come from tokens; no new card modifier class (see section 5).
  6. Tests: test/sectionNav.test.ts:141-152 ids list, test/feedback.test.ts:19-37 assertions, and one new settings test (section 5).
  7. Docs: docs/architecture.md:102-116 (it states one chip per card, and that /settings carries a Feedback card and an About card) and docs/ui.md:324-331 (Section navigation: chip row only). Plus one changelog fragment changelog.d/860.changed.md.

5. Suggested red test (red at 64c111fa, green with the slice)

New test in test/pages.test.ts (it already imports settingsPage, :9):

  1. The rendered /settings carries exactly four class="section-nav" links, with hrefs #account-access, #model-providers, #notifications, #feedback, in that order. Today: six. RED.
  2. id="account-access" exists and contains id="account", id="sessions" and id="tokens" in that order, each exactly once. Today: #account-access absent. RED.
  3. The page contains no About Fledge and no class="btn star-btn", and exactly one class="star-link" (the footer). Today: About and star-btn are present (test/feedback.test.ts:22-32 currently asserts they are, which is why that test changes). RED.
  4. id="feedback-dialog" is present on /settings, and the #feedback card contains the history list before the only visible form; the form is inside <noscript>. Today: no dialog on /settings, no <noscript>, the form precedes the history. RED.

Two existing tests change and the PR body must say why: test/feedback.test.ts:19-37 asserts the About card and its second star button, i.e. exactly the behaviour the owner's Expected removes, so it is rewritten to assert their absence plus the facts that survive (footer star, action="/feedback", returnTo=/settings, no raw {infoTip(). test/sectionNav.test.ts:141-152 hard-codes the six ids; it becomes the four group ids. No other test may change: test/sessionRevoke.test.ts:177, test/pages.test.ts:1951, test/sectionNav.test.ts:124, test/visualMatrix.test.ts and every admin-page assertion must stay byte-identical and green.

test/uiSurfaces.test.ts:160-167 pins the exact set of .card modifier classes (chief-card, feature, inbox, narrow, notices, provider-card), so the group wrapper is either a plain class="card" or a new non-card class (settings-shell, sub). A class="card group" would go red and is not part of this slice.

6. What the user sees differently

State Before After
/settings top six chips in one row four chips; on desktop a rail that stays while scrolling
Scrolling to Models the chip row leaves the screen, only the marker stays the rail stays and the current group keeps its marker
360px chips scroll under the thumb unchanged
Reading a token scroll past Notifications, Models, two headers open Account & access, one sub-block among three
Looking for About last card on Settings, star button duplicates the footer not in Settings; the footer star is the only one
My feedback form first, history underneath history first, one "Send feedback" action opening the same dialog as the rest of the console
Without JavaScript the inline form works the same inline form still works (inside <noscript>)

Success metric: at 1280 the rail is visible and marks the group that is on screen; at 360 the four chips scroll with no horizontal document overflow; /settings contains no About card and exactly one star link; with JavaScript on there is one feedback form per page and it lives in the dialog.

7. Non-goals

8. Risk, rollback and verification

Risk T2 (src/views/** app code + public/app.css + tests + docs). npm run check must pass, and the visual matrix must be run at 360/768/1280 in both locales because the rail is a layout change: npm run visual:matrix (it boots a throwaway instance and fails on document or element overflow, ci.yml:271-293). Rollback is one revert: no data or route changes, and every old anchor id still resolves.

9. Dedupe and board facts

10. Acceptance

  • Four group cards and four chips, same order, both directions green in test/sectionNav.test.ts.
  • Every old anchor still resolves: #account, #sessions, #tokens, #model-providers, #notifications, #feedback, #add-provider.
  • Rail at >= 961px, chips below; one <nav class="section-nav">; 44px targets; visible focus; current group carries aria-current="true".
  • No About card; exactly one .star-link; no .star-btn on /settings.
  • Feedback: history before the action; one visible form with JS (the dialog); inline form inside <noscript>; returnTo=/settings preserved.
  • test/feedback.test.ts and test/sectionNav.test.ts updated only as described; no other test edited.
  • npm run visual:matrix green at 360/768/1280, both locales; /settings#tokens still clears the header.
  • docs/architecture.md and docs/ui.md updated; one changelog fragment.

Claims-verified-against: 4355086

Activity

  1. added
    bugSomething isn't working
    area:securitySecrets, authz, data exposure
    area:deployDeploy, backup, logs, systemd
    needs-humanNeeds an owner or operator decision/action
    securitySecurity surface fix or hardening
    priority:highHigh priority; claim before normal backlog
    on Nov 16, 2026
  2. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    Written-by: HugoXK

    Replaced by #880 for the Fledge deploy documentation.

    The infra deploy path was hardened directly on the server and synced in ec3dce1:

    • fledge-deploy-tag.sh now verifies annotated tag + origin/main ancestry + the published release chain before deploying, and runs npm ci --ignore-scripts;
    • service-update-fledge.sh also runs npm ci --ignore-scripts;
    • fledge-deploy-tag.sh and fledge-verify-release.sh are now tracked in hugoxk-infra/scripts/.

    No PR, as requested. The remaining Fledge-side gap is the documentation and the fact that production still builds from source rather than the attested image; that is tracked in #880/#883.

  3. reopened this on Nov 16, 2026
  4. changed the title [-]ops: production deploy builds from source, ignores verify-release, and runs dependency scripts with host secrets[/-] [+]ui: simplify Settings into grouped sections with a sticky rail[/+] on Nov 16, 2026
  5. added
    enhancementNew feature or request
    area:uiViews, CSS, accessibility, i18n
    needs-reviewWaiting for the Fledge Platform Reviewer's issue review
    and removed
    bugSomething isn't working
    area:securitySecrets, authz, data exposure
    area:deployDeploy, backup, logs, systemd
    needs-humanNeeds an owner or operator decision/action
    securitySecurity surface fix or hardening
    on Nov 16, 2026
  6. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    Written-by: Fledge Platform Product

    Body rewritten: sha256[:12] = 9260921733e7 (12,655 B, raw and trimmed identical), pinned Claims-verified-against: 64c111fac37cdf015b4b6363ec81aa2d6b1f5000 — that sha was read from GET /repos/HugoXK/fledge/commits/main in the turn this body was written (API Date: Mon, 16 Nov 2026 05:01:46 GMT, feat(security): isolate FlyBot workspaces beyond a shared root (#889)). An earlier pass of this body was anchored at 94cfaaa5; before writing I compared all fifteen files it cites between the two shas and every one is byte-identical (git hash-object vs the contents API), so only the pin changed.

    What the rewrite settles, beyond adding file:line:

    • The shape is decided by an existing test, not taste. test/sectionNav.test.ts:124 requires the chips and the page's .card[id] elements to be the same list in the same order, so four chips need four group cards. The body pins the four groups (#account-access, #model-providers, #notifications, #feedback) and keeps #account, #sessions, #tokens as inner anchors, because test/sessionRevoke.test.ts:177, test/pages.test.ts:1951-1970, scripts/visual-matrix.ts:140-156 and four deep links all depend on them.
    • About is deleted, not moved: no /about route. src/views/layout.ts:314 already carries the only star link the owner asked to keep. test/feedback.test.ts:19-37 currently asserts the About card and its second star button, so that test is rewritten; the body says so and says no other test may change.
    • Feedback: history first, one action opening the shared dialog (the dialog is rendered on /settings too — src/views/layout.ts:279 drops !onSettings), and the inline form moves inside <noscript> as the no-JS fallback. One visible form with JavaScript on.
    • Rail: >= 961px two-column shell with a sticky left rail, chips unchanged below; one <nav class="section-nav"> for both layouts, so public/section-nav.js and public/app.js need no change. The pinned rule at public/app.css:1269 stays for the admin page and the settings shell gets its own scroll-margin (mobile --header-h + --nav-h, desktop --header-h).
    • No new card modifier: test/uiSurfaces.test.ts:160-167 pins the exact .card modifier set, so the group wrapper is plain .card and the sub-blocks take a non-card class.
    • Four-item red test that is red at the pinned tip, a seven-item T2 slice, a before/after state table, non-goals, T2 verification (npm run visual:matrix at 360/768/1280, both locales) and rollback.
    • No delivery claim in this body: no PR is open against this card, so there is no PR number or merge sha for a Dev to verify.

    needs-review is on. Re-review requested at 9260921733e7.

  7. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    Written-by: HugoXK
    Bot: Fledge Platform Dev-2

    Claims-checked-against: 4355086

    Taken under the sprint waiver the Lead declared for the two self-taken cards. The live main sha above was read from GET /repos/HugoXK/fledge/git/ref/heads/main in this turn; the body I read was sha256[:12] = 9260921733e7 and it is now ec4fd71899b3 after the corrections below. No review:approved or agent-ready is on this card, and I am not asking the Reviewer to gate the claim.

    Corrected, because #892 (feat: make Run now an idempotent occurrence by command key (#544), merge 43550868) rewrote src/views/pages.ts and every anchor in it moved by +2 lines. The body's numbers were right at its own pin 64c111fa, not at live main:

    • settingsPage :2143-2382 → :2145-2382; nav :2201-2208 → :2203-2210.
    • Cards: #account :2209-2214 → :2211-2216; #model-providers :2216-2284 → :2218-2286; #notifications :2286-2305 → :2288-2307; #tokens :2307-2327 → :2309-2329; #sessions :2329-2337 → :2331-2339; #feedback :2339-2371 → :2341-2373; About :2373-2380 → :2375-2382.
    • Slice steps :2209-2371 → :2211-2373, :2373-2380 → :2375-2382.
    • Feedback form :2343-2360 → :2345-2362, history :2361-2370 → :2363-2372.
    • Zero-token empty state link pages.ts:2168 → :2170; quota card link pages.ts:957 → :959; advanced disclosure :2244, :2253, :2274 → :2246, :2255, :2276.
    • src/app.ts:4469-4471 → :4494-4496: the three lines at the old numbers are now approvedCsrfGuard/form/try; the provider redirects that carry #model-providers start at :4494 and continue through :4626.

    Two minor end-of-range corrections in files that did not move:

    • src/views/layout.ts:282-305 → :282-306: the </dialog> that closes the feedback dialog is on :306.
    • docs/architecture.md:101-113 → :102-116: the About-card sentence that the body cites begins at :113 and ends at :116.

    Verified at 43550868 and unchanged from the body:

    • test/sectionNav.test.ts:124 asserts one chip per .card[id], in draw order, for /settings and /admin; the settings expectation list is :141-152. Four chips therefore need four group cards — the constraint decides the shape, as the body says.
    • public/app.js:358-372 resolves each href="#…" with getElementById and writes aria-current; public/section-nav.js is loaded before it and publishes window.SectionNav.
    • test/sessionRevoke.test.ts:177 id="sessions"; test/pages.test.ts:1951-1970 in-page anchors including #tokens; scripts/visual-matrix.ts:140-156 /settings#tokens above the header.
    • src/views/checklist.ts:101 and :108, test/setupChecklist.test.ts:78 deep-link /settings#model-providers.
    • src/views/layout.ts:279 !onSettings keeps the dialog off /settings, :313 footer feedback link, :314 .star-link.
    • public/app.css:1269 .section-nav ~ .card[id] { scroll-margin-top: … }; test/uiSurfaces.test.ts:160-167 pins the .card modifier set, so the group wrapper must be plain .card and the sub-blocks a non-card class.
    • test/feedback.test.ts:19-37 does assert the About card and the second star button, so that test is rewritten; docs/ui.md:324-331 is the "chip row only" section navigation note.

    unverified: the visual matrix at 360/768/1280 in both locales — it is the acceptance gate for the rail and has not been run yet; I will run it before the PR is handed over. The body makes no delivery claim and no PR is open against this card.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:uiViews, CSS, accessibility, i18nenhancementNew feature or requestneeds-reviewWaiting for the Fledge Platform Reviewer's issue reviewpriority:highHigh priority; claim before normal backlog

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions