namespace AcDream.App.UI;

/// <summary>
/// A panel controller implements this and registers itself on each of its
/// <see cref="UiItemList"/>s. Port of retail's <c>m_dragHandler</c> vtable
/// (<c>RegisterItemListDragHandler</c>, decomp 230461; confirmed acclient
/// 0x004a539e + the gmToolbarUI block 0x004bdd89).
/// <para><see cref="OnDragOver"/> decides the accept/reject OVERLAY only (advisory).
/// <see cref="HandleDropRelease"/> is authoritative — it performs the action, or
/// no-ops to reject.</para>
/// </summary>
public interface IItemListDragHandler
{
    /// <summary>The drag STARTED from a cell in this list — retail's RecvNotice_ItemListBeginDrag
    /// → RemoveShortcut (decomp 0x004bd930/0x004bd450): the handler removes the lifted item from its
    /// model + wire so the source slot empties immediately. The item is "in hand" until
    /// HandleDropRelease (place) or the drag ends off-target (stays removed). No restore on cancel.</summary>
    void OnDragLift(UiItemList sourceList, UiItemSlot sourceCell, ItemDragPayload payload);

    /// <summary>True ⇒ the target cell shows the accept (green) frame; false ⇒ reject (red).</summary>
    bool OnDragOver(UiItemList targetList, UiItemSlot targetCell, ItemDragPayload payload);

    /// <summary>Perform the drop (issue the per-panel wire action), or no-op to reject.</summary>
    void HandleDropRelease(UiItemList targetList, UiItemSlot targetCell, ItemDragPayload payload);
}