using Lattice.Core.Geometry;

namespace Lattice.UI.DragDrop.Abstractions;

/// <summary>
/// Хост для отображения визуальных элементов перетаскивания.
/// </summary>
/// <remarks>
/// <para>
/// Интерфейс предоставляет абстракцию для управления визуальными элементами
/// перетаскивания в различных UI-фреймворках (WPF, Avalonia, MAUI и т.д.).
/// </para>
/// <para>
/// Реализация должна обеспечивать корректное отображение визуальных элементов
/// поверх других элементов UI и их своевременное удаление при завершении операций.
/// </para>
/// </remarks>
public interface IDragDropHost
{
    /// <summary>
    /// Показывает визуальное представление перетаскиваемого элемента.
    /// </summary>
    /// <param name="dragVisual">Визуальное представление элемента для перетаскивания.</param>
    /// <param name="position">Начальная позиция визуального элемента в экранных координатах.</param>
    /// <remarks>
    /// <para>
    /// Метод должен отобразить переданный визуальный элемент в указанной позиции.
    /// Визуальный элемент должен следовать за курсором мыши при обновлении через <see cref="UpdateDragVisualPosition"/>.
    /// </para>
    /// <para>
    /// Визуальный элемент должен отображаться поверх всех других элементов интерфейса.
    /// </para>
    /// </remarks>
    void ShowDragVisual(object dragVisual, Point position);

    /// <summary>
    /// Обновляет позицию визуального представления перетаскивания.
    /// </summary>
    /// <param name="dragVisual">Визуальное представление, позиция которого должна быть обновлена.</param>
    /// <param name="position">Новая позиция в экранных координатах.</param>
    /// <remarks>
    /// Метод должен обновлять позицию уже отображаемого визуального элемента
    /// с минимальной задержкой для плавного перемещения.
    /// </remarks>
    void UpdateDragVisualPosition(object dragVisual, Point position);

    /// <summary>
    /// Скрывает визуальное представление перетаскивания.
    /// </summary>
    /// <param name="dragVisual">Визуальное представление для скрытия.</param>
    /// <remarks>
    /// После вызова этого метода визуальный элемент должен быть полностью
    /// удален из визуального дерева и его ресурсы освобождены.
    /// </remarks>
    void HideDragVisual(object dragVisual);

    /// <summary>
    /// Показывает визуальную обратную связь для цели сброса.
    /// </summary>
    /// <param name="adorner">Элемент обратной связи для отображения.</param>
    /// <remarks>
    /// <para>
    /// Метод должен отобразить элемент обратной связи (например, подсветку, рамку или индикатор позиции)
    /// для визуального указания возможности сброса на целевой элемент.
    /// </para>
    /// <para>
    /// Элемент обратной связи должен отображаться поверх целевого элемента, но под перетаскиваемым визуальным элементом.
    /// </para>
    /// </remarks>
    void ShowDropAdorner(IDropVisualAdorner adorner);

    /// <summary>
    /// Скрывает визуальную обратную связь для цели сброса.
    /// </summary>
    /// <param name="adorner">Элемент обратной связи для скрытия.</param>
    /// <remarks>
    /// После вызова этого метода элемент обратной связи должен быть
    /// удален из визуального дерева и его ресурсы освобождены.
    /// </remarks>
    void HideDropAdorner(IDropVisualAdorner adorner);
}