namespace DodoSSH.Client.Session;

/// <summary>
/// How the phone's terminal keys are arranged on this device.
/// </summary>
/// <remarks>
/// <para>
/// <b>Ids, not keys.</b> Every list here names keys and groups by the stable ids in the shell's key catalog
/// (<c>TerminalKeyCatalog</c>) rather than storing what a key sends, so a fix to a predefined key's bytes
/// reaches people who customised their bar before the fix. An id this build does not know — one written by
/// a newer build, or one for a custom key since deleted — is skipped on the way in rather than refused.
/// </para>
/// <para>
/// <b>In <see cref="ClientSettings"/>, so on this device and in plain text.</b> The arrangement suits one
/// screen and one pair of thumbs, which is the same argument the font size makes for not following
/// somebody onto a desktop. Custom keys are keystrokes such as <c>:wq</c>, and the customise screen says
/// outright that this file is not a place for a password.
/// </para>
/// <para>
/// Null lists mean "as shipped" rather than "empty". An empty <see cref="Bar"/> is a choice somebody made,
/// and has to survive a launch as one.
/// </para>
/// </remarks>
/// <param name="Bar">The keys on the bar above the software keyboard, in order.</param>
/// <param name="GroupOrder">The order of the groups on the quick-access keyboard's KEYS tab.</param>
/// <param name="HiddenGroups">Groups turned off on the KEYS tab.</param>
/// <param name="CustomKeys">Keys somebody added for themselves.</param>
/// <param name="QuickAccessTab">The quick-access keyboard's tab last used, which it reopens to.</param>
/// <param name="SidePanelOpen">Whether a wide screen shows the quick-access keyboard beside the terminal.</param>
/// <param name="CursorGestures">Whether long-press-and-drag on the terminal moves the cursor.</param>
public sealed record TerminalKeyboardSettings(
    string[]? Bar = null,
    string[]? GroupOrder = null,
    string[]? HiddenGroups = null,
    CustomTerminalKey[]? CustomKeys = null,
    string? QuickAccessTab = null,
    bool SidePanelOpen = true,
    bool CursorGestures = true);

/// <summary>A key somebody added: what it says on it, and what it types.</summary>
/// <param name="Id">Stable, so the bar can refer to it. Always starts <c>custom:</c>.</param>
/// <param name="Label">What the key shows.</param>
/// <param name="Sequence">
/// What it sends, in the notation the customise screen accepts — <c>\e</c>, <c>\r</c>, <c>^C</c> and so on —
/// rather than as bytes, so the file stays readable and the parser stays the one place escapes are decided.
/// </param>
public sealed record CustomTerminalKey(string Id, string Label, string Sequence);