using Lattice.Core.DragDrop.Models;
using Lattice.Core.Geometry;

namespace Lattice.UI.DragDrop.Abstractions;

/// <summary>
/// Поставщик визуального представления для перетаскиваемого элемента.
/// </summary>
/// <remarks>
/// <para>
/// Интерфейс предоставляет абстракцию для создания и управления визуальными
/// представлениями элементов при операции перетаскивания.
/// </para>
/// <para>
/// Реализации могут предоставлять различные стили визуального представления:
/// от простого клонирования оригинального элемента до сложных анимированных представлений.
/// </para>
/// </remarks>
public interface IDragVisualProvider
{
    /// <summary>
    /// Создает визуальное представление для перетаскивания на основе информации о перетаскивании.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании, содержащая данные и метаданные операции.</param>
    /// <param name="initialPosition">Начальная позиция в экранных координатах.</param>
    /// <returns>Объект, представляющий визуальное отображение для перетаскивания.</returns>
    /// <remarks>
    /// <para>
    /// Созданный визуальный элемент должен:
    /// 1. Отображать репрезентативное представление перетаскиваемых данных
    /// 2. Иметь прозрачный фон или альфа-канал для плавного отображения
    /// 3. Быть легковесным для обеспечения плавной анимации
    /// 4. Поддерживать возможность изменения позиции через <see cref="UpdateDragVisualPosition"/>
    /// </para>
    /// <para>
    /// Метод может возвращать null, если визуальное представление не требуется.
    /// </para>
    /// </remarks>
    object? CreateDragVisual(DragInfo dragInfo, Point initialPosition);

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

    /// <summary>
    /// Освобождает ресурсы визуального представления.
    /// </summary>
    /// <param name="dragVisual">Визуальное представление для освобождения.</param>
    /// <remarks>
    /// <para>
    /// Метод должен освободить все ресурсы, связанные с визуальным представлением,
    /// включая графические ресурсы, подписки на события и временные данные.
    /// </para>
    /// <para>
    /// Этот метод гарантированно вызывается после завершения операции перетаскивания,
    /// независимо от её успешности.
    /// </para>
    /// </remarks>
    void ReleaseDragVisual(object dragVisual);
}