namespace Lattice.Core.Docking.Abstractions;

/// <summary>
/// Базовый интерфейс для любого элемента, являющегося частью дерева компоновки.
/// Определяет общие свойства и методы для всех элементов док-системы.
/// </summary>
/// <remarks>
/// Элементы док-системы образуют древовидную структуру, где каждый элемент может иметь
/// родителя и дочерние элементы. Эта иерархия используется для организации пространства
/// главного окна и плавающих окон в IDE-подобных приложениях.
/// </remarks>
public interface IDockElement
{
    /// <summary>
    /// Получает уникальный идентификатор элемента.
    /// Используется для поиска элементов, сериализации состояния и отслеживания изменений.
    /// </summary>
    /// <value>
    /// Строковый идентификатор, гарантированно уникальный в пределах дерева компоновки.
    /// Обычно представляет собой GUID в строковом формате.
    /// </value>
    string Id { get; }

    /// <summary>
    /// Получает или задает родительский элемент в иерархии дерева компоновки.
    /// </summary>
    /// <value>
    /// Родительский элемент или null, если элемент является корневым.
    /// Это свойство управляется системой компоновки при добавлении или удалении элементов.
    /// </value>
    /// <remarks>
    /// Изменение этого свойства вручную может привести к нарушению целостности дерева.
    /// Для манипуляции структурой дерева следует использовать методы <see cref="DockOperations"/>.
    /// </remarks>
    IDockElement? Parent { get; set; }

    /// <summary>
    /// Получает или задает желаемую ширину элемента.
    /// </summary>
    /// <value>
    /// Ширина элемента в пикселях или относительных единицах.
    /// Может быть выражена как абсолютное значение (в пикселях) или как пропорция
    /// (например, 0.5 для 50% доступного пространства).
    /// </value>
    /// <remarks>
    /// Фактическая ширина элемента определяется родительским контейнером с учетом
    /// минимальных размеров и соотношений разделения.
    /// </remarks>
    double Width { get; set; }

    /// <summary>
    /// Получает или задает желаемую высоту элемента.
    /// </summary>
    /// <value>
    /// Высота элемента в пикселях или относительных единицах.
    /// Может быть выражена как абсолютное значение (в пикселях) или как пропорция.
    /// </value>
    /// <remarks>
    /// Фактическая высота элемента определяется родительским контейнером с учетом
    /// минимальных размеров и соотношений разделения.
    /// </remarks>
    double Height { get; set; }

    /// <summary>
    /// Получает минимально допустимую ширину элемента.
    /// </summary>
    /// <value>
    /// Минимальная ширина элемента в пикселях, при которой элемент сохраняет
    /// базовую функциональность и читаемость содержимого.
    /// </value>
    /// <remarks>
    /// Система компоновки не позволит уменьшить элемент ниже этого значения.
    /// Для групп разделения минимальная ширина вычисляется рекурсивно на основе
    /// минимальных размеров дочерних элементов.
    /// </remarks>
    double MinWidth { get; }

    /// <summary>
    /// Получает минимально допустимую высоту элемента.
    /// </summary>
    /// <value>
    /// Минимальная высота элемента в пикселях, при которой элемент сохраняет
    /// базовую функциональность и читаемость содержимого.
    /// </value>
    /// <remarks>
    /// Система компоновки не позволит уменьшить элемент ниже этого значения.
    /// Для групп разделения минимальная высота вычисляется рекурсивно на основе
    /// минимальных размеров дочерних элементов.
    /// </remarks>
    double MinHeight { get; }
}