namespace Lattice.Core.DragDrop.Abstractions;

/// <summary>
/// Определяет контракт для объектов, которые могут принимать сбрасываемые данные
/// в операции перетаскивания.
/// </summary>
/// <remarks>
/// Объекты, реализующие этот интерфейс, могут обрабатывать данные, сброшенные
/// пользователем, и предоставлять визуальную обратную связь во время перетаскивания.
/// </remarks>
public interface IDropTarget
{
    /// <summary>
    /// Определяет, может ли объект принять сбрасываемые данные.
    /// </summary>
    /// <param name="dropInfo">Информация о потенциальном сбросе.</param>
    /// <returns>
    /// true, если объект может принять данные; в противном случае — false.
    /// </returns>
    /// <remarks>
    /// Этот метод вызывается, когда перетаскиваемый объект находится над целью.
    /// Реализация должна проверить, совместимы ли данные с целью, и установить
    /// предлагаемые эффекты в <paramref name="dropInfo"/>.
    /// </remarks>
    Task<bool> CanAcceptDropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается, когда перетаскиваемый объект находится над целью.
    /// </summary>
    /// <param name="dropInfo">Информация о текущем положении перетаскивания.</param>
    /// <remarks>
    /// Этот метод вызывается постоянно, пока пользователь перемещает объект над целью.
    /// Реализация может обновить визуальную обратную связь или изменить предлагаемые эффекты.
    /// </remarks>
    Task DragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается, когда пользователь сбрасывает данные на цель.
    /// </summary>
    /// <param name="dropInfo">Информация о сбросе.</param>
    /// <remarks>
    /// Этот метод вызывается, когда пользователь отпускает кнопку мыши над целью.
    /// Реализация должна обработать принятие данных и выполнить соответствующее действие.
    /// </remarks>
    Task DropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается, когда перетаскиваемый объект покидает область цели.
    /// </summary>
    /// <remarks>
    /// Этот метод вызывается, когда пользователь перемещает объект за пределы цели.
    /// Реализация должна очистить любую визуальную обратную связь, установленную ранее.
    /// </remarks>
    Task DragLeaveAsync(CancellationToken cancellationToken = default);
}