namespace Lattice.Core.DragDrop.Abstractions;

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

    /// <summary>
    /// Вызывается, когда перетаскиваемый объект перемещается над целью.
    /// </summary>
    /// <param name="dropInfo">Информация о текущем положении перетаскивания.</param>
    /// <param name="cancellationToken">Токен отмены операции.</param>
    /// <returns>Задача, представляющая асинхронную операцию.</returns>
    /// <remarks>
    /// <para>
    /// Этот метод вызывается постоянно, пока пользователь перемещает объект над целью.
    /// Реализация может:
    /// </para>
    /// <list type="bullet">
    /// <item>Обновить визуальную обратную связь (подсветка, изменение курсора)</item>
    /// <item>Вычислить точную позицию сброса (например, между элементами списка)</item>
    /// <item>Уточнить предлагаемые эффекты на основе текущей позиции</item>
    /// <item>Прокрутить содержимое, если цель поддерживает прокрутку</item>
    /// </list>
    /// <para>
    /// Метод должен быть оптимизирован для частого вызова. Длительные операции
    /// должны выполняться асинхронно без блокировки потока.
    /// </para>
    /// </remarks>
    Task OnDragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается, когда пользователь сбрасывает данные на цель.
    /// </summary>
    /// <param name="dropInfo">Информация о сбросе, включая данные и позицию.</param>
    /// <param name="cancellationToken">Токен отмены операции.</param>
    /// <returns>Задача, представляющая асинхронную операцию.</returns>
    /// <remarks>
    /// <para>
    /// Этот метод вызывается, когда пользователь отпускает кнопку мыши над целью.
    /// Реализация должна обработать принятие данных и выполнить соответствующее действие:
    /// </para>
    /// <list type="bullet">
    /// <item>Добавить данные в коллекцию (для копирования)</item>
    /// <item>Переместить данные (при поддержке перемещения)</item>
    /// <item>Создать ссылку на данные</item>
    /// <item>Выполнить пользовательскую логику обработки</item>
    /// </list>
    /// <para>
    /// После успешной обработки данных следует вызвать <see cref="Models.DropInfo.MarkAsHandled()"/>,
    /// чтобы указать системе, что операция обработана и дополнительная обработка не требуется.
    /// </para>
    /// <para>
    /// Если операция завершилась успешно, система уведомит источник через
    /// <see cref="IDragSource.OnDragCompletedAsync"/> с соответствующими эффектами.
    /// </para>
    /// </remarks>
    Task OnDropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается, когда перетаскиваемый объект покидает область цели.
    /// </summary>
    /// <param name="cancellationToken">Токен отмены операции.</param>
    /// <returns>Задача, представляющая асинхронную операцию.</returns>
    /// <remarks>
    /// <para>
    /// Этот метод вызывается, когда пользователь перемещает объект за пределы цели.
    /// Реализация должна:
    /// </para>
    /// <list type="bullet">
    /// <item>Очистить любую визуальную обратную связь, установленную ранее</item>
    /// <item>Сбросить временное состояние, связанное с операцией</item>
    /// <item>Освободить ресурсы, выделенные для предварительного просмотра</item>
    /// </list>
    /// <para>
    /// Метод гарантированно вызывается после любого успешного или неуспешного
    /// вызова <see cref="OnDragOverAsync"/>, если курсор покидает область цели.
    /// </para>
    /// </remarks>
    Task OnDragLeaveAsync(CancellationToken cancellationToken = default);
}