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

namespace Lattice.UI.DragDrop.Abstractions;

/// <summary>
/// Визуальный элемент, показывающий обратную связь при наведении на цель сброса.
/// </summary>
/// <remarks>
/// <para>
/// Интерфейс предоставляет абстракцию для визуальных индикаторов, которые
/// показывают пользователю возможность сброса данных на целевом элементе.
/// </para>
/// <para>
/// Реализации могут предоставлять различные типы визуальной обратной связи:
/// подсветку элемента, отображение индикатора позиции, изменение курсора и т.д.
/// </para>
/// </remarks>
public interface IDropVisualAdorner
{
    /// <summary>
    /// Показывает визуальную обратную связь для цели сброса.
    /// </summary>
    /// <param name="dropInfo">Информация о потенциальном сбросе, включая данные и позицию.</param>
    /// <param name="targetBounds">Границы целевого элемента в экранных координатах.</param>
    /// <remarks>
    /// <para>
    /// Метод должен отобразить визуальную обратную связь, соответствующую типу данных
    /// и контексту сброса. Обратная связь должна явно указывать на возможность
    /// сброса и ожидаемый эффект (копирование, перемещение и т.д.).
    /// </para>
    /// <para>
    /// Обратная связь должна учитывать свойства <see cref="DropInfo.ShowVisualFeedback"/>
    /// и <see cref="DropInfo.VisualFeedbackData"/> для кастомизации отображения.
    /// </para>
    /// </remarks>
    void Show(DropInfo dropInfo, Rect targetBounds);

    /// <summary>
    /// Обновляет позицию и состояние визуальной обратной связи.
    /// </summary>
    /// <param name="dropInfo">Текущая информация о сбросе, включая обновленную позицию и состояние.</param>
    /// <remarks>
    /// Метод вызывается при каждом перемещении курсора над целью и должен
    /// обновлять визуальную обратную связь в соответствии с новой позицией
    /// и состоянием операции.
    /// </remarks>
    void Update(DropInfo dropInfo);

    /// <summary>
    /// Скрывает визуальную обратную связь.
    /// </summary>
    /// <remarks>
    /// Метод должен скрыть и очистить все визуальные элементы обратной связи.
    /// После вызова этого метода ресурсы могут быть освобождены или переиспользованы
    /// для следующих операций.
    /// </remarks>
    void Hide();
}