acdream/src/AcDream.UI.Abstractions/Panels/Settings/ChatOpacityLink.cs

namespace AcDream.UI.Abstractions.Panels.Settings;

/// <summary>
/// Retail's linked default/active window-opacity invariant: active &gt;= default,
/// ALWAYS — enforced by dragging the OTHER value, never by clamping the one being
/// set. Verbatim port of <c>ChatInterface::SetDefaultOpacity @0x004F3BC0</c> /
/// <c>SetActiveOpacity @0x004F3C40</c> (docs/research/2026-08-09-chat-retail-window-shell.md
/// §3): raising the default ABOVE the current active value drags active UP to match;
/// lowering the active value BELOW the current default drags default DOWN to match.
/// Retail's options-page sliders share a <c>DualHash</c> link
/// (<c>gmChatOptionsUI::InitOptions @0x0049FC60</c>) — this is why they visibly track
/// each other while dragging.
///
/// <para>
/// Consumed directly by <c>RetailWindowOpacityController</c> (AcDream.App — the
/// live per-window mechanism, mutating its own two float fields). The retail
/// Options panel's Chat tab (<c>ChatOptionsPageController</c>, Campaign OP slice
/// OP5) drives that SAME controller rather than calling these methods a second
/// time, so the panel's two sliders and every retained window's live fade always
/// apply the identical link math through one path. (The OP9-retired
/// <c>SettingsPanel</c>'s own Chat tab used to call these methods directly as a
/// second consumer, mutating a draft <see cref="ChatSettings"/> record — that
/// draft mechanism is gone, not the link math.) Pure functions — no
/// window/render/state dependency — so any future caller can use them without
/// violating the App→Abstractions dependency direction.
/// </para>
/// </summary>
public static class ChatOpacityLink
{
    /// <summary>
    /// Port of <c>ChatInterface::SetDefaultOpacity @0x004F3BC0</c>: set the default
    /// (unfocused) opacity to <paramref name="newDefault"/>, dragging
    /// <paramref name="currentActive"/> UP if it would otherwise fall below the new
    /// default. Never returns an (default, active) pair with active &lt; default.
    /// </summary>
    public static (float DefaultOpacity, float ActiveOpacity) SetDefault(
        float currentActive, float newDefault)
    {
        newDefault = System.Math.Clamp(newDefault, 0f, 1f);
        float active = currentActive < newDefault ? newDefault : currentActive;
        return (newDefault, active);
    }

    /// <summary>
    /// Port of <c>ChatInterface::SetActiveOpacity @0x004F3C40</c>: set the active
    /// (focused) opacity to <paramref name="newActive"/>, dragging
    /// <paramref name="currentDefault"/> DOWN if it would otherwise exceed the new
    /// active value. Never returns an (default, active) pair with active &lt; default.
    /// </summary>
    public static (float DefaultOpacity, float ActiveOpacity) SetActive(
        float currentDefault, float newActive)
    {
        newActive = System.Math.Clamp(newActive, 0f, 1f);
        float def = currentDefault > newActive ? newActive : currentDefault;
        return (def, newActive);
    }
}