namespace Lattice.Core.DragDrop.Abstractions;

/// <summary>
/// Определяет контракт для объектов, которые могут быть источником данных
/// в операции перетаскивания.
/// </summary>
/// <remarks>
/// Объекты, реализующие этот интерфейс, могут инициировать операции перетаскивания
/// и предоставлять данные для передачи другим элементам через механизм drag-and-drop.
/// </remarks>
public interface IDragSource
{
    /// <summary>
    /// Определяет, может ли объект начать операцию перетаскивания.
    /// </summary>
    /// <returns>
    /// Кортеж, содержащий флаг возможности начала перетаскивания и информацию о перетаскивании.
    /// </returns>
    /// <remarks>
    /// Этот метод вызывается системой перетаскивания для проверки возможности
    /// начала операции. Если метод возвращает true, он должен заполнить
    /// DragInfo необходимыми данными.
    /// </remarks>
    Task<(bool CanStart, Models.DragInfo? DragInfo)> CanStartDragAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Начинает операцию перетаскивания.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании.</param>
    /// <returns>
    /// true, если операция перетаскивания успешно начата; в противном случае — false.
    /// </returns>
    /// <remarks>
    /// Этот метод вызывается, когда пользователь начинает перетаскивание элемента.
    /// Реализация должна подготовить данные для перетаскивания и, возможно,
    /// создать визуальное представление перетаскиваемого объекта.
    /// </remarks>
    Task<bool> StartDragAsync(Models.DragInfo dragInfo, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается при завершении операции перетаскивания.
    /// </summary>
    /// <param name="dragInfo">Исходная информация о перетаскивании.</param>
    /// <param name="effects">Эффекты, которые были применены при сбросе.</param>
    /// <remarks>
    /// Этот метод вызывается после завершения операции перетаскивания
    /// (успешного или неуспешного). Реализация может выполнить очистку
    /// или обновить состояние на основе результата операции.
    /// </remarks>
    Task DragCompletedAsync(Models.DragInfo dragInfo, Enums.DragDropEffects effects, CancellationToken cancellationToken = default);

    /// <summary>
    /// Вызывается при отмене операции перетаскивания.
    /// </summary>
    /// <param name="dragInfo">Исходная информация о перетаскивании.</param>
    /// <remarks>
    /// Этот метод вызывается, когда операция перетаскивания была отменена
    /// пользователем (например, нажатием клавиши Escape).
    /// </remarks>
    Task DragCancelledAsync(Models.DragInfo dragInfo, CancellationToken cancellationToken = default);
}