Переработаны методы.

Lattice.Core.DragDrop/Abstractions/IDropTarget.cs

@@ -5,8 +5,15 @@
 /// в операции перетаскивания.
 /// </summary>
 /// <remarks>
+/// <para>
 /// Объекты, реализующие этот интерфейс, могут обрабатывать данные, сброшенные
 /// пользователем, и предоставлять визуальную обратную связь во время перетаскивания.
+/// </para>
+/// <para>
+/// Интерфейс поддерживает асинхронные операции и отмену через CancellationToken.
+/// Все методы должны быть потокобезопасными и идемпотентными (многократный вызов
+/// с одинаковыми параметрами должен давать одинаковый результат).
+/// </para>
 /// </remarks>
 public interface IDropTarget
 {
@@ -14,42 +21,98 @@ public interface IDropTarget
     /// Определяет, может ли объект принять сбрасываемые данные.
     /// </summary>
     /// <param name="dropInfo">Информация о потенциальном сбросе.</param>
+    /// <param name="cancellationToken">Токен отмены операции.</param>
     /// <returns>
     /// true, если объект может принять данные; в противном случае — false.
     /// </returns>
     /// <remarks>
+    /// <para>
     /// Этот метод вызывается, когда перетаскиваемый объект находится над целью.
     /// Реализация должна проверить, совместимы ли данные с целью, и установить
-    /// предлагаемые эффекты в <paramref name="dropInfo"/>.
+    /// предлагаемые эффекты в свойстве <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 DragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
+    Task OnDragOverAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Вызывается, когда пользователь сбрасывает данные на цель.
     /// </summary>
-    /// <param name="dropInfo">Информация о сбросе.</param>
+    /// <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 DropAsync(Models.DropInfo dropInfo, CancellationToken cancellationToken = default);
+    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 DragLeaveAsync(CancellationToken cancellationToken = default);
+    Task OnDragLeaveAsync(CancellationToken cancellationToken = default);
 }