Behavior of window title bar and Toolbar seem to conflict, not clear what's "right" to do

[driftwoodstudio]

Description

Mac window title bar and toolbar have some very strange interactions that make replicating a standard mac UI appearance very difficult.

See below for example code, noting two relevant blocks that can be commented in or out to reproduce the appearance shown in these screenshots.

Issue 1: without doing MacosWindowUtilsConfig() from macos_window_utils package, canvas background is black, even in Light mode. This is effectively a hard-requirement for using macos_ui successfully, but isn't documented well -- and has some odd effects when included.

Without it: completely black canvas with black text and black toolbar icon, but at least the title bar is handled right.

With it, the canvas now appears right but the toolbar gets overlaid with the title bar:

In addition to appearance issues, this now means that quickly double-tapping a toolbar icon gets interpreted as double clicking on the "title bar" causing window to resize to full screen (undesired and unexpected).

To fix the toolbar underlaying the title bar, dev can add a TitleBar parameter to MacosApp:

MacosWindow(
  titleBar: TitleBar(title: Text('TitleBar Widget')),

That now makes the appearance somewhat problematic:

From here, it's not clear how the dev should proceed to turn this into something usable.

Things I've found that sort-of work are:

1. Either the app title or the TitleBar title widget has to be made hidden or blank, so they don't both appear.
2. The TitleBar widget has to have a larger height set to overwrite default heigh, to keep horizontal divider line from drawing through window control buttons.
3. Hacks have to be made to macos_ui's Toolbar class to keep it from adding the leading space that indents the 'leading' icon/widget. (Seems intended to indent 'leading' item past the title bar window controls, but odd/wrong here where toolbar is under the title bar)

Documentation is desperately needed for how to turn this jumble of contradictory behaviors into one of two standard macOS 15.x window appearances:

1. Window with window control buttons and toolbar, as in Calendar, Clock, Dictionary...
2. Window with thin title bar and toolbar below, as in BBEdit, OmniOutliner, iTerm, Github Desktop...

Steps To Reproduce

Run the below example code, commenting in or out the indicated blocks marked BLOCK 1 and BLOCK 2.

Code sample

import 'package:macos_ui/macos_ui.dart';
import 'package:flutter/cupertino.dart';
void main() async {
  // BLOCK 1
  // Without this, window canvas color is black in Light mode. 
  // Seems to be a hard-requirement, but adding it changes how toolbar/title bar interact
    const config = MacosWindowUtilsConfig(
      hideTitle: false,
    );
    await config.apply();
  // END
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) {
    return MacosApp(
      title: 'Test',  // THIS APPEARS TO HAVE NO EFFECT AT ALL
      debugShowCheckedModeBanner: false,
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});
  @override
  State<MyHomePage> createState() => _MyHomePageState();
}
class _MyHomePageState extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    return MacosWindow(
      // BLOCK 2
      // without this, Toolbar overlays title bar area
        titleBar: TitleBar(title: Text('TitleBar Widget')),
      // END
      sidebar: null,
      child: 
        MacosScaffold(
          toolBar: 
            ToolBar(
              leading: 
                SizedBox(width: 60, height: 50, child:
                  MacosIcon( 
                    CupertinoIcons.sidebar_left,
                  ),
                ),
              actions: [
                ToolBarIconButton(
                    label: 'abc', showLabel: false,
                    icon: MacosIcon(CupertinoIcons.add),
                    onPressed: () => {}
                  )                
              ]
            ),  
          children: [
            ContentArea( 
              builder: (context, scrollController) {
                return Center(child: Text('Hello World'));
              }
            ),
          ],
        ) 
    );
  }
}

Something resembling some sort of standard mac app window appearance.

Screenshots

Logs

Logs

"Run your application with flutter run --verbose and attach all the
log output below between the lines with the backticks."

Why does your template even ask for this? If the reporter does this, the log output is too long and github won't let them submit the issue. My log output is 1055 lines long. There are no exceptions or errors that I can see.

bill@Bills-MacBook-Air macos_ui_tester % flutter analyze
Analyzing macos_ui_tester...                                            
No issues found! (ran in 2.5s)
bill@Bills-MacBook-Air macos_ui_tester % 

bill@Bills-MacBook-Air macos_ui_tester % flutter doctor
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.29.1, on macOS 15.3.1 24D70 darwin-arm64, locale en-US)
[!] Android toolchain - develop for Android devices (Android SDK version 33.0.1)
    ✗ cmdline-tools component is missing
      Run `path/to/sdkmanager --install "cmdline-tools;latest"`
      See https://developer.android.com/studio/command-line for more details.
    ✗ Android license status unknown.
      Run `flutter doctor --android-licenses` to accept the SDK licenses.
      See https://flutter.dev/to/macos-android-setup for more details.
[!] Xcode - develop for iOS and macOS (Xcode 16.1)
    ! iOS 18.1 Simulator not installed; this may be necessary for iOS and macOS development.
      To download and install the platform, open Xcode, select Xcode > Settings > Components,
      and click the GET button for the required platform.
      For more information, please visit:
        https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes
[✓] Chrome - develop for the web
[✓] Android Studio (version 2021.3)
[✓] VS Code (version 1.98.0)
[✓] Connected device (4 available)
[✓] Network resources

! Doctor found issues in 2 categories.
bill@Bills-MacBook-Air macos_ui_tester %