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>
    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>
    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>
    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>
    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>
    string? Prompt(string prompt, string? defaultValue = null);

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