[Proposal]: Allow Extended tool captions to customize control buttons

[TachiKuma]

Problem statement

中文：
我希望 MewDock 的 Extended tool caption 能支持宿主应用控制右侧 caption control buttons 的呈现方式。

当前 Extended tool pane caption 固定显示三个右侧控制按钮：options menu、auto-hide/dock、close。这对通用 dock UI 是合理默认值，但有些宿主应用会把部分 tool panes 当作固定工作区面板使用，例如 Elements、Layers、Properties、Preview 等。这类面板通常不希望暴露 close、auto-hide 或 popout-related controls，因为这些操作会让主要工作区布局变得不可预测。

同时，某些 tool pane 可能需要一个与 document tabset 相同语义的 maximize/restore 控制。例如 Preview pane 仍然应该保持在主 dock layout 内，但用户需要临时放大查看内容；这更像 document tabset 的 maximize，而不是把 pane pop out 到独立窗口。

English:
I would like MewDock Extended tool captions to let host applications control how the right-side caption control buttons are rendered.

Currently an Extended tool pane caption always shows three right-side controls: options menu, auto-hide/dock, and close. That is a reasonable default for a general docking UI, but some host applications treat certain tool panes as fixed workspace panels, such as Elements, Layers, Properties, or Preview. Those panes often should not expose close, auto-hide, or popout-related controls because those actions can make the main workspace layout unpredictable.

At the same time, some tool panes may need a maximize/restore control with the same semantics as a document tabset. For example, a Preview pane should remain inside the main dock layout, but the user may still need to temporarily enlarge it. That is closer to document tabset maximize than to popping the pane out into a separate window.

Why the current approach is insufficient

中文：
目前宿主应用可以选择接受默认 tool caption chrome，或者避免使用 Extended tool caption 的默认行为。但对已经使用 Extended dock layout 的应用来说，没有一个小范围、声明式的方式控制单个 tool pane caption 的按钮区域。

应用层可以自己实现独立弹窗或自定义外层 UI，但这会绕过 dock layout 已经存在的 maximize/restore 行为，也容易产生两套并行窗口/布局逻辑。对于“只想隐藏某些 tool pane 的 caption buttons”或“只想让某个 tool pane 使用现有 maximize toggle”的场景，应用层实现会比需求本身更重。

English:
Today a host application can either accept the default tool caption chrome or avoid relying on the default Extended tool caption behavior. For applications already using the Extended dock layout, there is no small, declarative way to control the button area of a specific tool pane caption.

The application could implement a separate popout window or custom surrounding UI, but that bypasses the maximize/restore behavior that already exists in the dock layout and can lead to parallel window/layout logic. For cases that only need to hide caption buttons for some tool panes, or expose the existing maximize toggle for one tool pane, an app-level implementation is heavier than the problem itself.

Type of change

Behavior change

Expected impact

中文：
预期影响应保持非常小：

• 默认行为不变。未配置的 Extended tool captions 仍然显示 options menu、auto-hide/dock 和 close。
• 只有宿主应用显式设置 per-tab config 时，caption controls 才改变。
• 现有应用如果不使用新配置，不应看到任何行为差异。
• 使用该能力的宿主可以让固定 tool panes 隐藏右侧控制按钮，或者让特定 tool pane 显示 maximize/restore 按钮。
• 该能力主要影响 Extended MewDock 的 tool caption rendering，不改变 docking model 的默认 reducer 行为。

English:
The expected impact should be very small:

• Default behavior remains unchanged. Extended tool captions without configuration still show the options menu, auto-hide/dock, and close controls.
• Caption controls only change when a host explicitly sets per-tab config.
• Existing applications that do not use the new config should not observe any behavior change.
• Hosts that opt in can hide right-side controls for fixed tool panes, or show a maximize/restore button for a specific tool pane.
• The feature mainly affects Extended MewDock tool caption rendering and does not change the default docking model reducer behavior.

Alternatives or tradeoffs

中文：
我考虑过以下替代方案：

1. 应用层实现独立预览窗口

   • 优点：不需要修改 MewDock。
   • 缺点：会绕过 dock layout 的 maximize/restore 语义，引入独立窗口生命周期、焦点、owner、关闭、状态同步等额外逻辑。对于只需要放大 dock 内 pane 的场景过重。

2. 应用层自定义整个 pane body，并在 body 内放置按钮

   • 优点：不需要修改 MewDock caption。
   • 缺点：按钮不在 caption chrome 中，视觉和交互上不像 dock-level control；也不能自然替代 caption 右上角的 close/auto-hide/menu controls。

3. 全局关闭所有 tool caption controls

   • 优点：实现简单。
   • 缺点：粒度太粗。某些 tool panes 仍然需要默认 menu/auto-hide/close 行为，不能按 pane 区分。

4. 新增公开 enum / public API

   • 优点：类型更明确。
   • 缺点：会扩大公共 API surface。对于当前需求，复用已有 per-tab Config 可能更小、更符合“按需 opt-in”的约束。

建议方向：
使用 per-tab config，例如 config.captionControls，让宿主按 pane 声明 caption controls 模式。建议保持默认兼容，并只支持少量明确值：

• absent / unknown: default behavior
• none: no right-side caption controls
• maximize: show a maximize/restore button that calls the existing tabset maximize action

English:
I considered these alternatives:

1. Implement a separate preview window in the application

   • Pros: no MewDock change.
   • Cons: bypasses the dock layout maximize/restore semantics and introduces extra lifecycle, focus, owner, close, and state synchronization logic. This is too heavy for a pane that only needs to be enlarged inside the dock layout.

2. Put custom buttons inside the application pane body

   • Pros: no MewDock caption change.
   • Cons: the controls are not part of the caption chrome, so visually and interactively they do not behave like dock-level controls. They also cannot naturally replace the caption's right-side close/auto-hide/menu controls.

3. Globally disable all tool caption controls

   • Pros: simpler implementation.
   • Cons: too coarse-grained. Some tool panes may still need the default menu/auto-hide/close behavior, so this needs to be selectable per pane.

4. Add a new public enum / public API

   • Pros: more explicit typing.
   • Cons: expands the public API surface. For this use case, reusing the existing per-tab Config may be smaller and more consistent with opt-in behavior.

Suggested direction:
Use per-tab config, for example config.captionControls, so hosts can declare the caption control mode per pane. The default should remain backward-compatible, with only a few explicit values:

• absent / unknown: default behavior
• none: no right-side caption controls
• maximize: show a maximize/restore button that calls the existing tabset maximize action

Additional context

中文：
我最初提交过一个实现 PR，但它没有先开 proposal issue，也没有使用 PR 模板，因此维护者按贡献指南关闭了它：
https://github.com/aprillz/MewUI/pull/230

该 PR 的实现思路是：

• 在 DockCaption 中读取 selected TabNode.Config
• 识别 captionControls
• 默认保持现有按钮
• none 不创建右侧按钮
• maximize 创建 WindowMaximize / WindowRestore 按钮，并调用 DockAction.MaximizeToggle
• Refresh() 同步 maximize/restore glyph 和 tooltip

如果维护者认可这个方向，我可以基于讨论结果重新提交一个符合 PR 模板的更小范围实现。

English:
I originally opened an implementation PR, but it did not start with a proposal issue and did not use the PR template, so it was closed according to the contribution guidelines:
https://github.com/aprillz/MewUI/pull/230

The implementation idea in that PR was:

• Read the selected TabNode.Config in DockCaption
• Recognize captionControls
• Preserve existing controls by default
• Do not create right-side controls for none
• Create a WindowMaximize / WindowRestore button for maximize, invoking DockAction.MaximizeToggle
• Keep the maximize/restore glyph and tooltip synchronized from Refresh()

If the direction is acceptable, I can submit a smaller implementation PR based on the agreed design and using the repository PR template.

Before submitting

• I searched for existing issues and discussions first.
• I described why this belongs in MewUI core rather than only in app-level code.