macOS Traffic Light and Tab Header Vertical Alignment (Browser Theme)

[wieslawsoltes]

PR Summary: macOS Traffic Light and Tab Header Vertical Alignment (Browser Theme)

Branch

• fix/macos-hostwindow-trafficlights-alignment

Problem Statement

The Browser theme sample on macOS showed two related layout issues:

1. Host/floating windows had traffic lights positioned too high in the titlebar area.
2. Document tab header text looked vertically off-center in Browser tabs.

While attempting to move traffic lights down by increasing titlebar height hints, the document tabs in floating host windows shifted downward, causing a secondary regression.

Root Cause Analysis

Host window regression source

HostWindow templates apply WindowDecorationMargin directly to content containers. On macOS, WindowDecorationMargin.Top is affected by titlebar/chrome hints.

When ExtendClientAreaTitleBarHeightHint is raised for host windows, the top decoration margin increases, and content (including tab strip) is pushed down. This created the observed “tabs moved down” issue in floating host windows.

Relevant paths:

• src/Dock.Avalonia.Themes.Browser/Styles/Controls/HostWindow.axaml
  • Template uses Margin="{TemplateBinding WindowDecorationMargin}"
  • Content template uses Margin="{Binding $parent[HostWindow].WindowDecorationMargin}"

Document tab text misalignment source

The tab template set VerticalContentAlignment="Center" on DocumentTabStripItem, but the template itself did not consume it for the tab-content root. Browser sample header template also used fixed Padding="2" instead of theme tokenized padding that can be platform-tuned.

What Changed

Commit 1

fluent: honor vertical content alignment in document tab item template

File:

• src/Dock.Avalonia.Themes.Fluent/Controls/DocumentTabStripItem.axaml

Changes:

• Bound tab-content root alignment:
  • DockableControl.VerticalAlignment="{TemplateBinding VerticalContentAlignment}"

Outcome:

• Tab content can now honor DocumentTabStripItem.VerticalContentAlignment.

Commit 4

fluent: keep single root vertical alignment binding for document tabs

File:

• src/Dock.Avalonia.Themes.Fluent/Controls/DocumentTabStripItem.axaml

Changes:

• Removed redundant nested VerticalAlignment bindings from inner StackPanel/ContentPresenter nodes.
• Kept the single effective binding at the tab-content root (DockableControl).

Outcome:

• Same behavior with simpler, easier-to-maintain template.

Commit 2

browser-theme: add macOS host chrome hints and platform header padding

Files:

• src/Dock.Avalonia.Themes.Browser/Styles/BrowserTabAccents.axaml
• src/Dock.Avalonia.Themes.Browser/Styles/Controls/HostWindow.axaml

Changes:

• Added DockHostWindowChromeHints token:
  • Default/Windows: PreferSystemChrome
  • macOS: Default, PreferSystemChrome, OSXThickTitleBar
• Wired HostWindow.ExtendClientAreaChromeHints to the token.
• Kept ExtendClientAreaTitleBarHeightHint at 0 for host windows (prevents margin-driven content shift).
• Converted DockHeaderContentPadding into OnPlatform token:
  • Default/Windows: 2
  • macOS: 2,1,2,0

Outcome:

• macOS traffic lights are aligned better for host windows via chrome hints.
• Host tab strip/content is no longer displaced by titlebar height changes.
• Header padding can be tuned by platform without hard-coded sample values.

Commit 3

browser-sample: align header padding and macOS titlebar chrome settings

Files:

• samples/BrowserTabTheme/App.axaml
• samples/BrowserTabTheme/MainWindow.axaml

Changes:

• Sample document header text now uses theme tokenized padding:
  • Padding="{DynamicResource DockHeaderContentPadding}"
• Sample main window macOS chrome updated for native-like titlebar behavior:
  • ExtendClientAreaTitleBarHeightHint="32"
  • ExtendClientAreaChromeHints="Default, PreferSystemChrome, OSXThickTitleBar"

Outcome:

• Sample reflects and exercises the new theme tokenization/chrome behavior expected on macOS.

Why This Is the Correct Fix

• It avoids using host titlebar height hints as a positioning workaround, which directly caused content displacement due to WindowDecorationMargin coupling.
• It applies a host-specific chrome hint strategy for macOS while preserving content geometry.
• It improves tab text alignment through one effective template binding plus platform-aware header padding, rather than one-off pixel offsets.

Validation

Build

• dotnet build src/Dock.Avalonia.Themes.Browser/Dock.Avalonia.Themes.Browser.csproj passed.
• dotnet build samples/BrowserTabTheme/BrowserTabTheme.csproj passed.

Tests

• dotnet test tests/Dock.Avalonia.Themes.UnitTests/Dock.Avalonia.Themes.UnitTests.csproj --filter "ThemeManager|ThemeDensity|DocumentTabStripItem" passed.
• Result: 34 passed, 0 failed, 0 skipped.

Note:

• One parallel run initially produced a transient MSBuild artifact conflict when build+test were started concurrently; rerunning tests alone passed cleanly.

Risk / Compatibility Notes

• OSXThickTitleBar is only applied via OnPlatform for macOS host windows.
• Windows/default behavior remains PreferSystemChrome.
• Host window titlebar height hint remains unchanged (0) to avoid regressions in content positioning.

Manual QA Checklist (macOS)

1. Open BrowserTabTheme sample main window.
2. Verify main window traffic lights are vertically centered in titlebar.
3. Float a document to create a host/floating window.
4. Verify floating host traffic lights are vertically centered.
5. Verify floating host tab strip is not pushed downward.
6. Verify document tab title text appears vertically centered relative to icon and close button.