using Lattice.Core.Docking.Abstractions;
using Lattice.Core.Docking.Engine;
using System.ComponentModel;

namespace Lattice.UI.Docking.Abstractions;

/// <summary>
/// Определяет базовый контракт для всех UI-контролов, участвующих в системе докинга.
/// Этот интерфейс предоставляет общие свойства и методы, необходимые для интеграции
/// с менеджером макета и UI-сервисами.
/// </summary>
/// <remarks>
/// Реализации этого интерфейса должны отображать элементы док-системы (DockGroup, DockLeaf)
/// и обеспечивать взаимодействие пользователя с ними через жесты мыши, клавиатуру и сенсорный ввод.
/// Интерфейс обеспечивает двухстороннюю связь между визуальными элементами и их моделями данных.
/// </remarks>
public interface IDockControl : INotifyPropertyChanged
{
    /// <summary>
    /// Получает или задает модель данных, связанную с этим контролом.
    /// </summary>
    /// <value>
    /// Экземпляр класса, реализующего <see cref="IDockElement"/>, который представляет
    /// состояние и структуру отображаемого элемента док-системы.
    /// </value>
    /// <remarks>
    /// Изменение модели должно приводить к обновлению визуального представления.
    /// Свойство используется для привязки данных между UI-слоем и слоем бизнес-логики.
    /// </remarks>
    IDockElement? Model { get; set; }

    /// <summary>
    /// Получает или задает менеджер макета, к которому принадлежит этот контрол.
    /// </summary>
    /// <value>
    /// Экземпляр <see cref="LayoutManager"/>, управляющий структурой док-системы.
    /// </value>
    /// <remarks>
    /// Менеджер макета предоставляет доступ к дереву компоновки, плавающим окнам
    /// и автоскрываемым панелям, а также методы для манипуляции структурой.
    /// </remarks>
    LayoutManager? LayoutManager { get; set; }

    /// <summary>
    /// Получает или задает контекстный менеджер для этого контрола.
    /// </summary>
    /// <value>
    /// Экземпляр <see cref="IDockContextManager"/>, управляющий контекстными меню и действиями.
    /// </value>
    /// <remarks>
    /// Контекстный менеджер используется для отображения контекстно-зависимых команд
    /// при щелчке правой кнопкой мыши или других пользовательских действиях.
    /// </remarks>
    IDockContextManager? ContextManager { get; set; }

    /// <summary>
    /// Получает или задает признак того, что контрол выбран.
    /// </summary>
    /// <value>
    /// true, если контрол выбран; в противном случае false.
    /// </value>
    /// <remarks>
    /// Выделение контрола обычно визуально выделяет его границы или фон,
    /// чтобы указать пользователю на активный элемент. В каждый момент времени
    /// может быть выбран только один контрол в пределах контейнера.
    /// </remarks>
    bool IsSelected { get; set; }

    /// <summary>
    /// Получает или задает признак того, что контрол активен.
    /// </summary>
    /// <value>
    /// true, если контрол активен; в противном случае false.
    /// </value>
    /// <remarks>
    /// Активный контрол получает фокус ввода и может обрабатывать команды клавиатуры.
    /// Обычно соответствует активной вкладке в контейнере или активному окну.
    /// </remarks>
    bool IsActive { get; set; }

    /// <summary>
    /// Обновляет внешний вид контрола в соответствии с текущим состоянием модели.
    /// </summary>
    /// <remarks>
    /// Этот метод должен вызываться при изменении свойств модели или при необходимости
    /// принудительного обновления UI (например, после изменения темы или масштаба).
    /// Реализация должна обеспечить синхронизацию всех визуальных аспектов контрола
    /// с текущими значениями свойств модели.
    /// </remarks>
    void Refresh();

    /// <summary>
    /// Применяет указанную тему к контролу.
    /// </summary>
    /// <param name="theme">Тема для применения.</param>
    /// <exception cref="ArgumentNullException">
    /// Выбрасывается, если <paramref name="theme"/> равен null.
    /// </exception>
    /// <remarks>
    /// Метод должен обновить все стили, цвета и параметры отображения контрола
    /// в соответствии с переданной темой. Изменения должны применяться немедленно.
    /// </remarks>
    void ApplyTheme(IDockTheme theme);

    /// <summary>
    /// Вызывается при изменении состояния модели для обновления UI.
    /// </summary>
    /// <param name="propertyName">Имя изменившегося свойства модели.</param>
    /// <remarks>
    /// Этот метод предназначен для уведомления UI о конкретных изменениях в модели,
    /// что позволяет выполнять точечные обновления вместо полного перестроения.
    /// Должен вызываться из обработчиков событий изменения свойств модели.
    /// </remarks>
    void OnModelPropertyChanged(string propertyName);
}