namespace Lattice.UI.Docking.Abstractions;

/// <summary>
/// Предоставляет абстракцию для платформенно-зависимых UI-операций.
/// Инкапсулирует вызовы к системным диалогам, управление окнами и
/// синхронизацию с UI-потоком.
/// </summary>
/// <remarks>
/// Этот интерфейс позволяет отделить бизнес-логику док-системы от конкретной
/// UI-платформы (WinUI, WPF, Avalonia и т.д.), обеспечивая возможность
/// кроссплатформенной разработки.
/// </remarks>
public interface IDockUIService
{
    /// <summary>
    /// Создает главное окно приложения для размещения док-хоста.
    /// </summary>
    /// <param name="host">
    /// Экземпляр <see cref="IDockHost"/>, который будет содержаться в окне.
    /// </param>
    /// <returns>
    /// Платформенно-зависимый объект окна, который можно отобразить.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="host"/> равен null.
    /// </exception>
    /// <remarks>
    /// Реализация должна создавать окно с соответствующими стилями и поведением
    /// для целевой платформы, настроенное для работы с док-системой.
    /// </remarks>
    object CreateMainWindow(IDockHost host);

    /// <summary>
    /// Отображает модальное диалоговое окно с указанным содержимым.
    /// </summary>
    /// <param name="title">Заголовок диалогового окна.</param>
    /// <param name="content">Содержимое диалогового окна.</param>
    /// <returns>
    /// Nullable boolean значение, указывающее результат диалога:
    /// true - пользователь подтвердил действие,
    /// false - пользователь отменил действие,
    /// null - диалог был закрыт без выбора.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="title"/> или <paramref name="content"/> равны null.
    /// </exception>
    /// <remarks>
    /// Реализация должна блокировать взаимодействие с родительским окном
    /// до закрытия диалога.
    /// </remarks>
    bool? ShowDialog(string title, object content);

    /// <summary>
    /// Отображает информационное сообщение с кнопкой OK.
    /// </summary>
    /// <param name="message">Текст сообщения.</param>
    /// <param name="caption">Заголовок окна сообщения.</param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="message"/> или <paramref name="caption"/> равны null.
    /// </exception>
    /// <remarks>
    /// Реализация должна использовать стандартные диалоги платформы
    /// или создавать кастомные окна сообщений.
    /// </remarks>
    void ShowMessage(string message, string caption);

    /// <summary>
    /// Отображает диалог подтверждения с кнопками Yes/No.
    /// </summary>
    /// <param name="message">Текст вопроса.</param>
    /// <param name="caption">Заголовок окна подтверждения.</param>
    /// <returns>
    /// true, если пользователь выбрал "Yes"; false, если пользователь выбрал "No".
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="message"/> или <paramref name="caption"/> равны null.
    /// </exception>
    /// <remarks>
    /// Используется для получения подтверждения от пользователя перед выполнением
    /// критических операций (закрытие вкладок, сброс настроек и т.д.).
    /// </remarks>
    bool Confirm(string message, string caption);

    /// <summary>
    /// Отображает диалог ввода текста.
    /// </summary>
    /// <param name="prompt">Текст подсказки для пользователя.</param>
    /// <param name="defaultValue">Значение по умолчанию для поля ввода.</param>
    /// <returns>
    /// Введенный пользователем текст или null, если диалог был отменен.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="prompt"/> равен null.
    /// </exception>
    /// <remarks>
    /// Реализация должна предоставлять однострочное поле ввода текста
    /// с возможностью отмены операции.
    /// </remarks>
    string? Prompt(string prompt, string? defaultValue = null);

    /// <summary>
    /// Выполняет указанное действие в UI-потоке.
    /// </summary>
    /// <param name="action">Действие для выполнения.</param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="action"/> равен null.
    /// </exception>
    /// <remarks>
    /// Этот метод гарантирует, что действие будет выполнено в потоке,
    /// связанном с пользовательским интерфейсом, что необходимо для
    /// безопасного обновления UI-элементов.
    /// </remarks>
    void InvokeOnUIThread(Action action);
}