feat(frontend): let users switch to a branch from its details page

Merged
BI
3mo ago
+158-1

Why

Opening /branches/<name> told you everything about a branch except the one thing you needed to act on it: whether you were working in that branch. Viewing one branch while your session targeted another was silent and completely normal, so edits could land somewhere you weren't looking. The only switch in the product lives in the top-bar selector, which meant leaving the page you were reading to use it.

Goal: make the branch page state which branch your session targets, and let you switch from there.

Non-goals: the branch list still can't say which branch you're on — a list row has no room for a sentence, and the notice only exists on the branch page. Deliberately left for a follow-up.

Closes #10050 — "set a branch as the active branch from the branch details view". The issue describes the inspect → work on it flow: browse the list, open a branch to check its status and diff, then decide to continue in it, which today means abandoning that context and re-finding the same name in the top-bar dropdown.

One deliberate divergence from the issue: it suggests the action would "fit naturally alongside" the existing merge / rebase / delete buttons. It doesn't, for two reasons. Every control in that row mutates the branch, whereas switching only changes what your session targets — filing them together teaches that switching is a branch operation. And that whole row is gated on !branch.is_default, so putting the switch there would make it impossible to switch back to main from main's own page. The notice sits above the header instead, where it can also explain why the switch is being offered.

What changed

When you are on a different branch:
image

When it is the same branch:
image

Behavioral changes:

  • The branch details page now opens with a notice saying "You're working on this branch." when the page matches your session.
  • When it doesn't match, the notice instead warns that you're viewing one branch while working on another, and offers Switch to this branch.
  • Switching is immediate: the notice flips from amber to blue in place, which is the confirmation.
  • The top-bar selector, sidebar menu and branch actions all follow the switch — it changes the session, not just the banner.

Implementation notes:

  • setCurrentBranch on the branch context was unsafe to call. It exposed the raw atom setter, but the ?branch= query string is the source of truth and the atom is derived from it — writing the atom alone strands BranchesProvider on its loading guard until the branches query refetches, then silently reverts the session to main. The provider owns both pieces of state, so it now owns the pairing and keeps exposing it under the same name. No call site changed; the reconciling effect keeps an atom-only setter so it doesn't steer the value it reacts to.
  • "Working branch" is kept distinct from BranchStatus. Status is the branch's own state and already spends green (Open), yellow (rebase), red (Deleting) and purple (Merged). The session signal takes blue — the one hue the status palette never uses — and is never labelled "active", which would read as a status value.
  • Amber is reserved for the mismatch, where the caution is real. The matching case is blue: informational, not a success. Nothing was achieved by arriving on a page.
  • Both states render through one wrapper with a shared min-height, so switching doesn't shift the page below. Measured: the two states were 49px and 41px (an 8px jump); they are now both 40px, verified by a regression test asserting the content below doesn't move.
  • No toast. An earlier revision confirmed the switch with an undo toast. It was dropped: the notice changing colour one line below the cursor is already the confirmation, switching isn't destructive, and the mismatch notice returns on its own. That also removed a stale-capture bug in the undo handler.

What stayed the same: no backend changes, no schema or GraphQL changes, no new dependencies. Nothing outside the branch page and the selector is touched.

How to review

Read the commits in order — the second and third are follow-ups that delete more than they add.

Start with branch-working-notice.tsx (56 lines) — it's the whole feature, both states in one component. Then the setCurrentBranch change in branches-provider.tsx, and the one-line insertion in pages/branches/details.tsx.

The branch-selector.tsx change is mechanical: it drops its hand-rolled copy of the switch now that the provider owns it. No behaviour change.

Unrelated latent bug found along the way, not addressed here: ToastContainer in router.tsx passes no theme, so react-toastify emits Toastify__toast-theme--undefined, no theme rule matches, and .Toastify__toast falls back to its base color: #fff. Every existing toast renders through Alert, which sets its own colour, so nothing has hit it — but any toast content relying on inherited colour renders white-on-white. The fix is theme="light" on the container; worth a separate one-liner.

Known limitation: below roughly 630px of card width (about a 990px window with the sidebar open) the mismatch sentence wraps to two lines and a 9px shift returns. Removing it entirely means either a permanently 9px-taller banner at every width, or truncating the branch names. Both trade something real, so neither was taken. Long branch names do not trigger it at normal widths — a 58-character name at 1080px still measures 0px.

How to test

cd frontend/app
pnpm test                                          # 1143 passed
pnpm exec biome ci . && pnpm knip && pnpm exec betterer ci
pnpm build

# e2e needs a backend; run against the dev server, not :8000 (that serves a prebuilt bundle)
pnpm dev                                           # separate shell, serves :8080
pnpm exec playwright test tests/e2e/branches/branch-details.spec.ts tests/e2e/branches/branch-selector.spec.ts   # 15 passed

Manual check: open a non-default branch's page while on main, confirm the amber notice, click Switch to this branch, and confirm the top-bar selector follows, the sidebar schema menu repopulates, and the notice turns blue.

Impact & rollout

  • Backward compatibility: no breaking changes. Additive UI, plus a behaviour-preserving change to how BranchesProvider exposes setCurrentBranch (same name, same signature, same call sites).
  • Performance: none — the notice reads state that's already in context.
  • Config/env changes: none.
  • Deployment notes: safe to deploy.

Checklist

  • Tests added/updated — 4 component tests (including a layout-shift regression) and 2 e2e assertions
  • Changelog entry added
  • External docs updated — not needed, no documented behaviour changes
  • Internal .md docs reviewed — nothing documented branch switching as selector-only, so no update needed
  • I have reviewed AI generated content