namespace Lattice.Core.DragDrop.Abstractions;

/// <summary>
/// Определяет контракт для объектов, которые могут быть источником данных
/// в операции перетаскивания.
/// </summary>
/// <remarks>
/// <para>
/// Объекты, реализующие этот интерфейс, могут инициировать операции перетаскивания
/// и предоставлять данные для передачи другим элементам через механизм drag-and-drop.
/// </para>
/// <para>
/// Интерфейс полностью асинхронный и поддерживает отмену операций через CancellationToken.
/// Все методы должны быть потокобезопасными и поддерживать вызов из любого потока.
/// </para>
/// </remarks>
public interface IDragSource
{
    /// <summary>
    /// Пытается начать операцию перетаскивания из указанной позиции.
    /// </summary>
    /// <param name="startPosition">Начальная позиция операции в координатах экрана.</param>
    /// <param name="cancellationToken">Токен отмены операции.</param>
    /// <returns>
    /// Информация о перетаскивании, если операция может быть начата; в противном случае — null.
    /// Возвращаемый объект <see cref="Models.DragInfo"/> должен быть полностью инициализирован,
    /// включая данные, разрешенные эффекты и ссылку на источник.
    /// </returns>
    /// <remarks>
    /// <para>
    /// Этот метод вызывается сервисом перетаскивания при попытке начать операцию
    /// (обычно при нажатии и перемещении мыши). Метод должен проверить, может ли
    /// источник начать перетаскивание в текущем контексте.
    /// </para>
    /// <para>
    /// Реализация должна быть быстрой и не выполнять длительных операций.
    /// Если подготовка данных требует времени, ее следует выполнить асинхронно
    /// после подтверждения возможности начала.
    /// </para>
    /// </remarks>
    Task<Models.DragInfo?> TryStartDragAsync(Geometry.Point startPosition, CancellationToken cancellationToken = default);

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

    /// <summary>
    /// Уведомляет источник об отмене операции перетаскивания.
    /// </summary>
    /// <param name="dragInfo">Информация о перетаскивании, полученная при начале операции.</param>
    /// <param name="cancellationToken">Токен отмены операции.</param>
    /// <returns>Задача, представляющая асинхронную операцию.</returns>
    /// <remarks>
    /// <para>
    /// Этот метод вызывается, когда операция перетаскивания была отменена
    /// пользователем (например, нажатием клавиши Escape) или системой.
    /// </para>
    /// <para>
    /// Реализация должна выполнить очистку и восстановить исходное состояние.
    /// Обычно это включает освобождение ресурсов и сброс визуальных индикаторов.
    /// </para>
    /// </remarks>
    Task OnDragCancelledAsync(Models.DragInfo dragInfo, CancellationToken cancellationToken = default);
}