Skip to content

Align pane headers and standardise list spacing - #324

Open
singkia wants to merge 10 commits into
Homebrew:mainfrom
singkia:ui/pane-header-alignment
Open

singkia wants to merge 10 commits into
Homebrew:mainfrom
singkia:ui/pane-header-alignment

Conversation

@singkia

@singkia singkia commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Repeated subtitles and uneven alignment made the same information harder to find across tabs. This change gives all six tabs a consistent layout while keeping native macOS window titles and controls.

  • Prefer a 1,080-point opening width, fit smaller displays and retain the original 820-point minimum. Align the sidebar, list headers and detail panes with shared 20-point content insets.
  • On narrow panes, wrap the heading first, then stack the buttons beside it. The vertical pair matches the wider button's native width. Move the controls below the heading only when neither side-by-side layout fits.
  • Put counts, status and actions in the pane headers. Keep command cards and diagnostic guidance visible, with more space between commands and list filters.
  • Draw the top boundary once. Preserve native list separators and pinned headings, remove dark section bands and give the amber selection background the same inset across five lists.

Validation

  • Apple M2, macOS 27.0.1, Xcode 27.2 and Swift 6.4.2.

  • Passed locally: pre-commit, scripts/test, SwiftFormat, SwiftLint, BrewUILint and localisation verification.

  • Focused local UI: the section separator gutters and narrow-window Spanish and Swedish layouts passed. The broader local run reproduced two failures on the unchanged baseline: loss of app focus while clearing search and a window restoration test that reopened at its default size. #294 addresses the restoration test separately.

  • Passed in GitHub Actions on 2a9e500: deterministic UI suite, build and unit/integration tests, Swift quality checks and live Homebrew E2E canaries.

  • The full UI suite and live Homebrew E2E were not rerun locally on this revision. Reviewed light and dark screenshots. Manual keyboard and VoiceOver checks were not run locally on this revision.

  • I followed the conventions and workflow, checked for duplicate PRs and kept this change focused.

  • I added regression coverage for bug fixes or explained why automated coverage is impractical, and reported the relevant validation above.

Screenshots

The same fixtures are shown at the old and new default widths (1,000 and 1,080 points).

Before After
Installed before Installed after
Upgrades before Upgrades after
Discover before Discover after
Services before Services after
Doctor before Doctor after
Configuration before Configuration after

English detail comparisons

The crops below come from the same English screenshots above. They retain the nearby controls and panes for context.

Window alignment, controls and separators (9 before/after crops)
Change Before After
Window and first row: remove repeated subtitles, add one top boundary and align the three columns Before After
Installed: move the dependency switch beside the count Before After
Upgrades: align bulk actions with Available and separate the command card from the filter Before After
List selection: give the amber background 10 points of clearance on both sides Before After
Discover: put the 30-day explanation beside Trending and preserve the Popular sections Before After
Services: put Refresh beside the count and keep the command card distinct from the filter Before After
Doctor: align status, actions and detail badge; keep the guidance above the warning group Before After
Configuration: put the title and actions above the report and align the guidance with the cards Before After
Detail pane: use the package icon as the alignment anchor without changing the title or description layout. Remove the extra colour overlay from section dividers Before After
Upgrades: up-to-date state (before and after)

The header retains Available and the command card. The completion message and success badge stay together in the list pane.

Before After
Upgrades up to date before Upgrades up to date after

English state and appearance checks

These post-change captures are not before/after pairs.

Doctor: all five states (full windows)

All five English captures show the full 1,080 × 732-point window.

Initial check

Doctor: Initial check, full window

No problems found

Doctor: No problems found, full window

Warnings found

Doctor: Warnings found, full window

Re-checking

Doctor: Re-checking, full window

Check failed

Doctor: Check failed, full window

Light and dark: list sections and split junction
Detail Light Dark
Doctor: inset warning separator and no dark header band Light appearance Dark appearance
Discover: same inset for Popular Formulae and Popular Casks Light appearance Dark appearance
Top junction: the split does not darken the horizontal divider Light appearance Dark appearance

Localisation stress cases

Spanish Doctor (1,080 points). The status wraps to three lines while both buttons stay aligned with its first line.

Full Doctor window in Spanish

Upgrades. At 1,024 points the buttons remain horizontal. At 820 points the buttons stack on the right at matching widths, with the first button beside the heading.

Language 1,024 points 820 points
Spanish Full Spanish Upgrades window at 1,024 points Full Spanish Upgrades window at 820 points
Swedish Full Swedish Upgrades window at 1,024 points Full Swedish Upgrades window at 820 points

AI assistance

  • AI was used to generate or assist with generating this PR.

OpenAI Codex assisted with implementation, regression tests and the local checks reported above.

Reuse the existing typography and colours to align pane headings, filters
and native window titles. Keep the blue guidance and expanded command cards
and move Doctor's help into the native toolbar.

Add deterministic screenshot coverage for English, Traditional Chinese,
narrow windows and dark appearance.
Align headers across all six tabs by the centre of the text. Retain the
existing typography tokens and the relationship between icons and text in
detail panes. Do not repeat the bulk action's package count in the Upgrades
heading.

Package tests, layout tests, Swift quality checks and localisation checks
passed. Native UI automation timed out during startup, so full-window
screenshots still needed review.
Measure the top anchor using the existing heading font. Move the detail
pane as a unit to preserve its internal icon and text alignment. Bring the
app to the foreground before capturing screenshots to avoid occluded or
partially rendered windows.

Package tests, Swift quality checks and localisation checks passed. Ten
header UI tests and the English screenshot rerun passed.
Set shared content insets and row selection styling. Keep native dividers and pinned list headings while removing the extra toolbar boundary and dark section bands.

Cover pane geometry, window sizing and light and dark dividers with regression tests.
Prefer the 1080-point opening width without preventing narrower windows. Let pane headings wrap independently and keep actions beside them when they need to stack. Cover compact translations and native separator rendering at both pixel scales.
Use the wider native button width only for a vertical pair. Retain intrinsic widths in horizontal layouts and keep the Doctor refresh indicator outside the button pair.
Render the native divider and the former 40% opacity with SwiftUI under the same conditions. Require the render to distinguish the two before checking the production divider. Avoid a fixed contrast threshold for a system colour.
@SMillerDev

Copy link
Copy Markdown
Member

Please reword the commits in English. Otherwise it'll be difficult for other contributors to find out what changed.

@singkia
singkia force-pushed the ui/pane-header-alignment branch from 4cc0b88 to d70efe6 Compare November 19, 2026 05:41
@singkia

singkia commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for pointing that out. All commit messages are now in English.

Restore the original divider between the console toolbar and output. Remove the pixel test and package dependency for the withdrawn styling change. Leave the split boundary, drag handle and unrelated tests unchanged.
Capture the actual window instead of forcing it to the visible display height. Retain exact compact widths and require a complete screenshot. Use stable accessibility identifiers for guidance and upgrade completion, and wait for console hittability after resizing.
Measure section separators against pixels above and below them in the same column so sidebar shadows do not skew the measured gutters.

Resize from the right edge and keep the compact upgrade check focused on upgrade actions. This avoids depending on console controls that the Dock can cover.
@singkia
singkia marked this pull request as ready for review November 19, 2026 10:27
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Explain Change →

Summary

Summary by CodeRabbit

  • New Features
    • Pane headers now adapt to narrow windows, keeping titles and actions readable across screens and languages.
    • Detail views, lists and section headings use more consistent alignment and spacing; system-drawn separators are retained.
    • The default window is wider, while its initial size adapts to the display.
    • Upgrade screens show an “Available” status and a clearer up-to-date state.
    • Service screens display the brew services info --all command.
  • Bug Fixes
    • Improved layout consistency for pane content and sidebar alignment.

The pull request adds shared pane layout and header components, then applies them across the application screens. It also updates upgrade status copy, list separator styling, window placement, accessibility identifiers, and UI test support.

Changes: Pane layout and shared components

Layer / File(s) Summary
Shared pane layout and header primitives
Sources/BrewUIComponents/Theme/BrewSpacing.swift, Sources/BrewUIComponents/Views/PaneHeader.swift, Sources/BrewUIComponents/Views/PaneContentWidth.swift, Sources/BrewUIComponents/Views/PaneFirstRowAlignment.swift, Sources/BrewUIComponents/Views/DetailPaneContent.swift, Sources/BrewUIComponents/Views/LastUpdatedLabel.swift, Tests/BrewUIComponentsTests/*
Adds shared pane dimensions, responsive headers, row styling, alignment modifiers, and configurable label styles. Component tests check layout and alignment.
Native list separators and section headers
AGENTS.md, ARCHITECTURE.md, Sources/BrewUIComponents/Views/PlainListSectionHeader.swift, Sources/BrewUIComponents/Views/PackageDetailSubviews.swift, Sources/BrewFeatureDiscover/Views/DiscoverSectionHeader.swift, Tests/BrewUIComponentsTests/PackageDetailSectionDividerTests.swift
Documents system-drawn separators and custom split chrome. Adds a plain pinned section-header style and tests that the package detail divider matches a native divider.
Window presentation and UI test setup
Homebrew/BrewApp.swift, Homebrew/Features/MainWindow/Views/MainWindowView.swift, Homebrew/Localizable.xcstrings, Homebrew/UITesting/BrewApp+UITesting.swift, Sources/BrewUITestContract/BrewUITestingFixturePayload.swift, BrewUITests/Harness/*, BrewUITests/Fixtures/ScenarioFixtures.swift, Homebrew/Views/MainSidebarView.swift
Sets window dimensions from the display’s visible size, adds a main-content divider, removes navigation subtitles, and extends test launch arguments, fixtures, resize gestures, and dark-appearance setup.
Installed, upgrades, and Discover screens
Sources/BrewFeatureInstalled/Views/*, Sources/BrewFeatureInstalled/ViewModels/UpgradesViewModel.swift, Sources/BrewFeatureInstalled/Resources/Localizable.xcstrings, Sources/BrewFeatureDiscover/Views/*, Sources/BrewFeatureDiscover/ViewModels/DiscoverViewModel.swift, Tests/BrewFeatureInstalledTests/*, Tests/BrewFeatureDiscoverTests/DiscoverViewModelTests.swift
Applies shared pane headers and row styling. Upgrade subtitles now use “Available” for inventory states, while filtered results retain no-match copy. Discover places analytics in the header when appropriate.
Configuration, Doctor, and Services screens
Sources/BrewFeatureConfig/Views/ConfigView.swift, Sources/BrewFeatureConfig/Resources/Localizable.xcstrings, Sources/BrewFeatureDoctor/Views/DoctorView.swift, Sources/BrewFeatureServices/Views/ServicesView.swift, Sources/BrewAccessibilityID/AXID.swift, Tests/BrewAccessibilityIDTests/AXIDTests.swift
Applies shared headers and pane styling. Adds accessibility identifiers for pane headers and screen guidance. The Services command display omits --json.
Detail-pane content alignment
Sources/BrewFeatureInstalled/Views/InstalledPackageDetailView.swift, Sources/BrewFeatureDiscover/Views/DiscoverPackageDetailView.swift, Sources/BrewFeatureDoctor/Views/DoctorIssueDetailView.swift, Sources/BrewFeatureServices/Views/ServiceDetailView.swift
Applies shared detail-pane padding and top alignment anchors to detail content and placeholders.
Cross-screen UI validation
BrewUITests/Tests/HeaderLayoutUITests.swift
Adds UI tests for headers, action placement, separator gutters, split intersections, and screen content across appearances, widths, and languages.
Merge Risk: Low · up to 2a9e5

Layout and spacing are now consistent across the six tabs. In narrow windows the Configuration and Services headers may move their buttons below the heading earlier than intended. The light-appearance UI tests may also run in dark mode on dark-mode machines. These are minor and unlikely to affect users significantly.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title, 'Align pane headers and standardise list spacing', matches the main changeset. The diff adds PaneHeader and PaneHeaderActions, moves pane headers across the six tabs, and adds shared list-r…
Description check Passed The description explains the goals (consistent six-tab layout, a 1,080-point default width, shared 20-point content insets, header wrapping, and removed dark section bands). It also gives validation d…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title, 'Align pane headers and standardise list spacing', matches the main changeset. The diff adds PaneHeader and PaneHeaderActions, moves pane headers across the six tabs, and adds shared list-row insets and selection styling. It is specific enough for a teammate scanning history.

Full details: Description check

Explanation

The description explains the goals (consistent six-tab layout, a 1,080-point default width, shared 20-point content insets, header wrapping, and removed dark section bands). It also gives validation details and screenshots. These all relate directly to the changeset.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 3

Review info

Run configuration

  • Source mode: Auto
  • Repository: Homebrew/BrewUI
  • Branch: main
  • File: .coderabbit.config.ts
  • Commit: a956154
  • Layers: Repository TS config (base), Organization UI (inherited)
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e9f53cd2-03a2-48a9-b97e-d944356610ab
Commits

Reviewing files that changed from the base of the PR and between a956154 and 2a9e500.

Files selected for processing: 50

  • AGENTS.md
  • ARCHITECTURE.md
  • BrewUITests/Fixtures/ScenarioFixtures.swift
  • BrewUITests/Harness/BrewApp.swift
  • BrewUITests/Harness/BrewUITestCase.swift
  • BrewUITests/Harness/BrewUITestScenario.swift
  • BrewUITests/Harness/WindowGestures.swift
  • BrewUITests/Tests/HeaderLayoutUITests.swift
  • Homebrew/BrewApp.swift
  • Homebrew/Features/MainWindow/Views/MainWindowView.swift
  • Homebrew/Localizable.xcstrings
  • Homebrew/UITesting/BrewApp+UITesting.swift
  • Homebrew/Views/MainSidebarView.swift
  • Sources/BrewAccessibilityID/AXID.swift
  • Sources/BrewFeatureConfig/Resources/Localizable.xcstrings
  • Sources/BrewFeatureConfig/Views/ConfigView.swift
  • Sources/BrewFeatureDiscover/ViewModels/DiscoverViewModel.swift
  • Sources/BrewFeatureDiscover/Views/DiscoverPackageDetailView.swift
  • Sources/BrewFeatureDiscover/Views/DiscoverPackagesView.swift
  • Sources/BrewFeatureDiscover/Views/DiscoverSectionHeader.swift
  • Sources/BrewFeatureDoctor/Resources/Localizable.xcstrings
  • Sources/BrewFeatureDoctor/Views/DoctorIssueDetailView.swift
  • Sources/BrewFeatureDoctor/Views/DoctorView.swift
  • Sources/BrewFeatureInstalled/Resources/Localizable.xcstrings
  • Sources/BrewFeatureInstalled/ViewModels/UpgradesViewModel.swift
  • Sources/BrewFeatureInstalled/Views/InstalledPackageDetailSubviewSections.swift
  • Sources/BrewFeatureInstalled/Views/InstalledPackageDetailView.swift
  • Sources/BrewFeatureInstalled/Views/InstalledPackagesView.swift
  • Sources/BrewFeatureInstalled/Views/UpgradesHeaderView.swift
  • Sources/BrewFeatureInstalled/Views/UpgradesPackagesView.swift
  • Sources/BrewFeatureServices/Views/ServiceDetailView.swift
  • Sources/BrewFeatureServices/Views/ServicesView.swift
  • Sources/BrewUIComponents/Theme/BrewSpacing.swift
  • Sources/BrewUIComponents/Views/DetailPaneContent.swift
  • Sources/BrewUIComponents/Views/LastUpdatedLabel.swift
  • Sources/BrewUIComponents/Views/PackageDetailSubviews.swift
  • Sources/BrewUIComponents/Views/PaneContentWidth.swift
  • Sources/BrewUIComponents/Views/PaneFirstRowAlignment.swift
  • Sources/BrewUIComponents/Views/PaneHeader.swift
  • Sources/BrewUIComponents/Views/PlainListSectionHeader.swift
  • Sources/BrewUITestContract/BrewUITestingFixturePayload.swift
  • Tests/BrewAccessibilityIDTests/AXIDTests.swift
  • Tests/BrewFeatureDiscoverTests/DiscoverViewModelTests.swift
  • Tests/BrewFeatureInstalledTests/UpgradesUpToDateCopyTests.swift
  • Tests/BrewFeatureInstalledTests/UpgradesViewModelCheckFailureTests.swift
  • Tests/BrewFeatureInstalledTests/UpgradesViewModelScopeTests.swift
  • Tests/BrewFeatureInstalledTests/UpgradesViewModelTests.swift
  • Tests/BrewUIComponentsTests/DetailPaneContentTests.swift
  • Tests/BrewUIComponentsTests/PackageDetailSectionDividerTests.swift
  • Tests/BrewUIComponentsTests/PaneHeaderAlignmentTests.swift
Files with no reviewable changes: 1

  • Tests/BrewFeatureDiscoverTests/DiscoverViewModelTests.swift

Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 7 remain after this review.


private func windowEnvironment(dark: Bool) -> [String: String] {
var environment = freshWindow
if dark {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

Select light appearance explicitly for the light iteration.

On a Mac using Dark Mode, dark: false leaves the app appearance unset. AppKit then uses the system appearance, so both iterations of the separator and boundary tests run in dark appearance. The tests can pass without checking light appearance. (developer.apple.com)

Pass an explicit light-appearance request for false and handle it in the test-only startup code. Keep the default system appearance for launches that do not request an override.

.disabled(!viewModel.canCopyReport)
Button(String(localized: "Refresh", bundle: #bundle, comment: "Configuration header: re-run brew config"), systemImage: "arrow.clockwise") {
Task { await viewModel.refresh() }
PaneHeader {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

Allow the Configuration heading to wrap beside its actions.

ConfigView uses the default PaneHeader initialiser, where wrapsSummary is false. On that path, the heading keeps its single-line width. When the heading and actions do not fit on one line, the actions move below the heading. The heading does not wrap. A long localised heading at a narrow width can therefore stack the actions when wrapping would fit. The pull request states that headings wrap before buttons stack, so this layout differs from the intended narrow-pane behaviour.

Pass wrapsSummary: true at this call site, as UpgradesHeaderView already does. The wrapping path keeps the inline layout where it fits and wraps the heading before it stacks the actions.

Suggested fix

--- "a/Sources/BrewFeatureConfig/Views/ConfigView.swift"
+++ "b/Sources/BrewFeatureConfig/Views/ConfigView.swift"
@@ -32,7 +32,7 @@
     }
 
     private var header: some View {
-        PaneHeader {
+        PaneHeader(wrapsSummary: true) {
             Text("Homebrew environment & diagnostics", bundle: #bundle, comment: "Configuration content heading: Homebrew environment and diagnostic information")
                 .font(.brewTitle2)
                 .foregroundStyle(Color.brewTextPrimary)
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
PaneHeader {
PaneHeader(wrapsSummary: true) {

.font(.brewTitle2)
.foregroundStyle(Color.brewTextPrimary)
VStack(alignment: .leading, spacing: 0) {
PaneHeader {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Minor · Functional Correctness · Quick win

Wrap the Services count before stacking Refresh.

PaneHeader stacks its actions below the summary when wrapsSummary is false. The Services header uses the default, so the adaptive layout runs. In a column that is too narrow for the one-line count beside Refresh, but wide enough for a wrapped count beside Refresh, Refresh can move below the count. The PR states that headings wrap before buttons stack. UpgradesHeaderView already passes wrapsSummary: true for this layout.

Suggested fix

--- "a/Sources/BrewFeatureServices/Views/ServicesView.swift"
+++ "b/Sources/BrewFeatureServices/Views/ServicesView.swift"
@@ -81,7 +81,7 @@
 
     private var header: some View {
         VStack(alignment: .leading, spacing: 0) {
-            PaneHeader {
+            PaneHeader(wrapsSummary: true) {
                 if let subtitle = viewModel.runningServiceSubtitle {
                     Text(subtitle).font(.brewTitle2).foregroundStyle(Color.brewTextPrimary)
                 }
Committable suggestion

IMPORTANT
Review the replacement and indentation, then test before committing.

Suggested change
PaneHeader {
PaneHeader(wrapsSummary: true) {

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants