namespace AcDream.App.UI;

/// <summary>
/// Visual result of a drag-over query. Retail handlers can consume a drag-over
/// message without setting either accept or reject art; shortcut aliases over a
/// physical item list use that neutral path.
/// </summary>
public enum ItemDragAcceptance
{
    None,
    Accept,
    Reject,
}

/// <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 neutral/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>Returns the advisory target-cell overlay state.</summary>
    ItemDragAcceptance 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);
}