rzen
7f1adf47c5
The settle rule 3f4125e introduced — at release the shadow swaps for the
dropped card(s) drawn in place immediately — is withdrawn on review. The
board returns to the presentation the committed-overlay hold has always
had: the shadows keep standing at their landing slot and the originals
keep their lift until the echo reload lands, whatever the operation was,
and the real faces arrive with the snapshot that carries the write.
Gone with it: the DropLanding/DroppedItem seam and the three landing
accessors, the hold's landing/operation payload and the removesOriginals
and keepsIdentity halves it decided, the pickup-captured titles a
cross-board arrival's face needed, LaneSlot.dropped with DroppedFace and
DroppedCardFace, the strip's dropped-lane run, and the trash column's
settled tombstone rows — the same presentation at the delete gesture's
end, which goes for the same reason while the drop-to-delete write and
its shadow row stay exactly as they were.
Kept: the hold itself, which predates the commit, along with the 1500 ms
failed-write timeout, its injectable duration and its extracted expire,
and the guard that keeps a settled release past retargeting. The tests
pinning those stay; the ones asserting what the landing slot drew are
gone, and the suite now pins the hold's own claim — the arrangement does
not move at the release.
The pause between the release and the echo is therefore an open design
question again, filed on the Redesign board.
Claude-Session: https://claude.ai/code/session_01CqjXB7ASoWtbyoGod68k97
674 lines
33 KiB
Swift
674 lines
33 KiB
Swift
import AppKit
|
|
import Foundation
|
|
import Observation
|
|
import SwiftUI
|
|
|
|
// MARK: - Where a drag would land
|
|
|
|
/// The drop proposal: which board, which container, which slot.
|
|
///
|
|
/// One value for every layout, because they differ only in what the container is, and `boardRoot` is
|
|
/// what makes a proposal cross-board-aware: only the board whose root it names renders the shadows,
|
|
/// and only that board's delegate may commit it.
|
|
struct DropTarget: Equatable, Sendable {
|
|
|
|
/// The three surfaces a drop can name, spelled as a sum so the impossible combinations cannot be
|
|
/// written down at all.
|
|
///
|
|
/// The trash is a case rather than an id because **it has no id**: the quasi-lane is not in the
|
|
/// snapshot — it is `TrashModel.entries` derived from it — so there is nothing to put in a
|
|
/// `lane`, and its index is not a position the pointer chose either (see `TrashDrop`).
|
|
enum Container: Equatable, Sendable {
|
|
/// The **lane strip**: the index counts live lanes with the dragged run removed.
|
|
case strip
|
|
/// That lane's **masonry**: the index is a position in its logical card order
|
|
/// (DRAG-REORDER.md § The card masonry).
|
|
case lane(ItemID)
|
|
/// The **trash quasi-lane**, which a live card drag proposes into to delete it
|
|
/// (04-interactions.md ▸ The trash, settled 2026-07-28). The index is always the topmost row.
|
|
case trash
|
|
}
|
|
|
|
var boardRoot: URL
|
|
var container: Container
|
|
var index: Int
|
|
|
|
/// The lane this proposal names, or `nil` for the strip and the trash — the shape the container
|
|
/// wore before there were three of them, kept because most readers only ask this one question.
|
|
var laneID: ItemID? {
|
|
if case let .lane(id) = container { return id }
|
|
return nil
|
|
}
|
|
|
|
/// Whether this proposal names the trash column, and therefore means *delete*.
|
|
var isTrash: Bool { container == .trash }
|
|
}
|
|
|
|
// MARK: - Dropping on the trash
|
|
|
|
/// **Drop-on-trash deletes** (04-interactions.md ▸ The trash, settled 2026-07-28: "the drag becomes
|
|
/// the pointer's delete gesture — release tombstones the dragged card(s), exactly the ⌫ tombstone"),
|
|
/// as the two pure facts the gesture is made of (`TrashDropTests`).
|
|
///
|
|
/// Kept out of the drop context so the ruling is checkable without a window, and stated once so the
|
|
/// **hover** and the **release** cannot disagree about what the trash takes — the hazard being a
|
|
/// modifier pressed *after* the proposal stood, which no `dropUpdated` need ever report.
|
|
enum TrashDrop {
|
|
|
|
/// The row the shadow takes, always: **the topmost**.
|
|
///
|
|
/// Not arbitrary, and the sort is what makes it honest: the trash orders by `deleted`
|
|
/// newest-first (03-board-ui.md § Trash), so a fresh tombstone genuinely lands on top. The drop
|
|
/// therefore still lands exactly where the shadow shows — the one positional promise every other
|
|
/// drop in this app makes — while being the only proposal on the board the *pointer* does not
|
|
/// choose.
|
|
static let landingIndex = 0
|
|
|
|
/// Whether the shown trash takes this session — the whole of the gate, and every clause is a
|
|
/// refusal 04 states in its own words:
|
|
///
|
|
/// - **Lanes are not deliverable this way** — "a lane drag proposes only lane slots". (The strip's
|
|
/// slot list has never contained the quasi-lane, so this is belt over braces; it is written down
|
|
/// because a guard that is only true by construction is one refactor from being false.)
|
|
/// - **A trash row is already there.** A `.trashed` session's vocabulary is restore and copy-out;
|
|
/// dropping it back where it came from writes nothing.
|
|
/// - **Cross-board is refused.** "No move or paste ever targets the trash": a foreign card
|
|
/// delivered *into* this board's trash would be a transfer-and-delete compound, an operation the
|
|
/// design gives no name and no undo story. The card stays where it is.
|
|
/// - **⌥ is refused.** Copying into the trash is not a thing — the copy grammar promises the
|
|
/// original stays exactly where it was, and there is nothing to tombstone but the original.
|
|
/// - **Hidden, the trash is invisible to every gesture.** True by construction too (the column is
|
|
/// not rendered, so it has no drop region), and stated here so the claim is testable.
|
|
/// - **The mutating-gesture rule**, like every other write the pointer can start.
|
|
static func accepts(
|
|
kind: DragKind?,
|
|
side: Liveness,
|
|
isWithinBoard: Bool,
|
|
operation: TransferOperation,
|
|
isTrashShown: Bool,
|
|
acceptsMutations: Bool
|
|
) -> Bool {
|
|
guard isTrashShown, acceptsMutations else { return false }
|
|
guard kind == .cards, side == .live, isWithinBoard else { return false }
|
|
return operation == .move
|
|
}
|
|
}
|
|
|
|
// MARK: - Where an external file drag would land
|
|
|
|
/// Where an external **Finder file** session would land (04-interactions.md ▸ Drag and drop, "Files
|
|
/// from Finder").
|
|
///
|
|
/// A separate type from `DropTarget` because a file session is a separate *mode*: nothing of ours is
|
|
/// in flight, so there is no dragged run to lift out of the resting layout, no operation to resolve
|
|
/// against modifiers, and no source board to compare roots with — only a destination and what the
|
|
/// files would become there.
|
|
struct FileDropTarget: Equatable, Sendable {
|
|
|
|
/// The two landings 04 gives a file drop, and the whole of its behavioural split.
|
|
enum Landing: Equatable, Sendable {
|
|
/// **Onto a card**: the files copy into that card's `attachments/`. A card under the cursor
|
|
/// always wins over the lane behind it — attach beats create, anywhere on the card's bounds.
|
|
/// This is the one file landing that **highlights**, and only because it has no shadow to
|
|
/// show instead (04-interactions.md ▸ Drag and drop, settled 2026-07-28).
|
|
case attach(cardID: ItemID)
|
|
/// **Onto the lane's card grid**: one card per file, landing at this position in the lane's
|
|
/// logical card order.
|
|
///
|
|
/// **Positional, everywhere the grid reaches** (04-interactions.md ▸ Drag and drop, settled
|
|
/// 2026-07-28): "created cards land at the drop position — resolved through the same
|
|
/// card-grid zones an ordinary card drag uses, shadow included", and a release on the lane
|
|
/// **header** resolves to index 0, the topmost position. Append-at-bottom is the creation
|
|
/// trio's rule (⌘N, Return, a double click), never the drop's. `FileDropZones.landing` is
|
|
/// where the index comes from.
|
|
case create(laneID: ItemID, index: Int)
|
|
}
|
|
|
|
/// The board under the cursor — only that board's delegates may commit, and only its lanes draw
|
|
/// the shadows, exactly as `DropTarget.boardRoot` works for our own sessions.
|
|
var boardRoot: URL
|
|
|
|
var landing: Landing
|
|
|
|
/// How many files ride along — **one nominal-height shadow per incoming file** on the create path
|
|
/// (04-interactions.md ▸ Drag and drop, settled 2026-07-28: the multi-drag precedent), one shadow
|
|
/// per card that will land. Read off the session's item providers at hover time
|
|
/// (`FinderDrop.shadowCount`), **floored at one** for the drag whose count macOS withholds — the
|
|
/// commit is unaffected either way, since the write counts resolved URLs, not providers.
|
|
///
|
|
/// **Folders are not counted** (same bullet: "a mixed drag proposes for its files only"):
|
|
/// `FinderDrop.importableCount` reads the providers' declared types, so a mixed drag draws
|
|
/// shadows for its files alone and a folders-only drag never proposes at all.
|
|
var fileCount: Int
|
|
}
|
|
|
|
// MARK: - The committed-overlay hold
|
|
|
|
/// The hand-off condition for **the committed-overlay hold** (DRAG-REORDER.md § The
|
|
/// committed-overlay hold), as a value so the state machine is testable without a filesystem.
|
|
///
|
|
/// At release the write goes to disk and the *snapshot does not change* — the one-way flow means the
|
|
/// board only shows the new order once the watcher's reload lands (02-architecture.md). Dropping the
|
|
/// drag state at release would snap every sibling back to the pre-drop layout for a frame. So the
|
|
/// session flips from *proposing* to *committed*, keeps rendering the arrangement it was showing,
|
|
/// and stands until the destination store applies its next snapshot — **any** snapshot: the
|
|
/// app-mediated echo is normally next, and a foreign one that lands first re-grounds everything
|
|
/// anyway.
|
|
///
|
|
/// The `timeout` is the same guarantee the drag session's watchdog gives the drag itself: a write
|
|
/// that was refused outright (a read-only board) produces no reload at all, and an overlay with no
|
|
/// hand-off coming must still dissolve and let the snapshot be the authority again.
|
|
struct CommittedHold: Equatable, Sendable {
|
|
|
|
/// The board whose next applied snapshot retires this hold.
|
|
var boardRoot: URL
|
|
|
|
/// That board's `snapshotGeneration` at the moment of the commit.
|
|
var generation: Int
|
|
|
|
/// How long the hold may stand with no snapshot arriving. Comfortably longer than a write plus
|
|
/// a watcher round trip, short enough that a refused write does not leave the board drawing an
|
|
/// arrangement it never got.
|
|
static let timeout: Duration = .milliseconds(1500)
|
|
|
|
/// Whether a snapshot applied on `root` at `generation` retires this hold. A snapshot on another
|
|
/// board says nothing about this one, and the *same* generation is the one already on screen at
|
|
/// the commit.
|
|
func isRetired(byRoot root: URL, generation: Int) -> Bool {
|
|
DragLocality.isSameBoard(root, boardRoot) && generation > self.generation
|
|
}
|
|
}
|
|
|
|
// MARK: - Locality
|
|
|
|
/// **Locality picks the default — the Finder volume model** (04-interactions.md ▸ Drag and drop,
|
|
/// settled), as pure functions (`DragLocalityTests`).
|
|
///
|
|
/// Within a board a drag is a **move**: rearranging. Between boards it is a **copy**: transferring,
|
|
/// with the system copy badge showing over the foreign board. **⌥ always forces copy** and **⌘
|
|
/// always forces move** — Finder's exact modifier grammar — and each is a no-op where its behavior
|
|
/// is already the default. The operation is therefore a function of (source board, board under the
|
|
/// cursor, modifiers) sampled every frame, not a decision taken at pickup, which is what lets the
|
|
/// badge track live as the cursor crosses a boundary.
|
|
enum DragLocality {
|
|
|
|
/// Whether two roots name the same board. Symlinks are resolved first — a board reached through
|
|
/// a pinned symlink is the same board as the one reached directly (01-storage-format.md's
|
|
/// symlink pins) — and the standardized path is the comparison key.
|
|
static func isSameBoard(_ lhs: URL, _ rhs: URL) -> Bool {
|
|
lhs.resolvingSymlinksInPath().standardizedFileURL.path
|
|
== rhs.resolvingSymlinksInPath().standardizedFileURL.path
|
|
}
|
|
|
|
/// The effective operation, live.
|
|
///
|
|
/// Two carve-outs, both 04-interactions.md's:
|
|
///
|
|
/// - **Lane drags never copy within their board.** ⌥ is simply ignored there: the drag stays a
|
|
/// clean reorder and the badge never shows copy. The within-board lane duplicate exists, but
|
|
/// its home is the clipboard (▸ Clipboard, Lane paste).
|
|
/// - **A trash row's drag is copy-out grammar** (▸ The trash). Within its own board it is the
|
|
/// restore — a move, no badge; across boards the default is the live copy that leaves the
|
|
/// tombstoned original in place, exactly as ⌘C out of the trash behaves. ⌘ forces the true
|
|
/// restore-move either way, and ⌥ forces the live copy either way ("⌘C, ⌥-drag, and the
|
|
/// cross-board drag default always yield *live* copies").
|
|
static func operation(
|
|
kind: DragKind,
|
|
side: Liveness,
|
|
isWithinBoard: Bool,
|
|
modifiers: NSEvent.ModifierFlags
|
|
) -> TransferOperation {
|
|
let forcesCopy = modifiers.contains(.option)
|
|
let forcesMove = modifiers.contains(.command)
|
|
|
|
// The lane carve-out comes first, because it is an outright refusal of the modifier rather
|
|
// than a different default: a within-board lane drag is a reorder and nothing else.
|
|
if kind == .lanes, isWithinBoard { return .move }
|
|
|
|
if forcesMove { return .move }
|
|
if forcesCopy { return .copy }
|
|
_ = side // the side changes which commit runs, never which operation the badge shows
|
|
return isWithinBoard ? .move : .copy
|
|
}
|
|
}
|
|
|
|
// MARK: - DragSession
|
|
|
|
/// The app's one drag session — what is in flight, where it would land, and what a release means
|
|
/// (DRAG-REORDER.md; 04-interactions.md ▸ Drag and drop).
|
|
///
|
|
/// **App-wide, because a drag crosses windows.** The identities are UUIDs and the folders are paths,
|
|
/// so the source board hides the dragged items while *any* open board's drop delegates propose a
|
|
/// landing spot for them. It is owned by `AppModel` and reached through the environment; the system
|
|
/// `NSItemProvider` payload is the formal drop data (`DragPayload`), and this is what every hover
|
|
/// actually reads — decoding a provider is asynchronous, and `dropUpdated` must answer synchronously
|
|
/// to drive the reflow.
|
|
///
|
|
/// ### What is frozen and what is not
|
|
///
|
|
/// 03-board-ui.md § Motion's animation-proof rule, made structural: the **only** inputs frozen at
|
|
/// drag start are the *dragged items'* own sizes — card heights and lane unit counts, which the
|
|
/// pickup transition corrupts the instant it starts. Everything else (the resting zones, the
|
|
/// destination's standard width, which lanes are live) is recomputed from the current snapshot on
|
|
/// every sample, which is rule 1 of the mid-drag re-grounding trio: a foreign reload just moves the
|
|
/// zones.
|
|
///
|
|
/// ### Termination is structural
|
|
///
|
|
/// `begin` arms a watchdog that polls the physical mouse-button state and clears the session shortly
|
|
/// after the button is released, no matter where the drop landed — on a delegate (whose
|
|
/// `performDrop` already cleaned up, making the watchdog a no-op), on empty window space, in another
|
|
/// window, outside every window, or on a cancelled drag. This is the pathfinder's hard-won lifecycle
|
|
/// pair: cleanup on session-phase events must be gated on the button being physically up (a finished
|
|
/// session's events can arrive *after* the next drag has started), and the watchdog is the
|
|
/// guaranteed path for the sessions SwiftUI never reports at all.
|
|
@MainActor
|
|
@Observable
|
|
final class DragSession {
|
|
|
|
// MARK: What is in flight
|
|
|
|
/// Which level is being dragged; `nil` when no session is in flight — which is what "no drag"
|
|
/// means here rather than a separate flag.
|
|
private(set) var kind: DragKind?
|
|
|
|
/// The side the drag started on. A trash row's drag is a `.cards` session on the `.trashed`
|
|
/// side, and that is the whole of what makes it one (04-interactions.md ▸ The trash).
|
|
private(set) var side: Liveness = .live
|
|
|
|
/// The dragged items in **flatten order** — the order they will land in.
|
|
private(set) var members: [ItemID] = []
|
|
|
|
/// Fast identity test for hiding the originals wherever they render.
|
|
private(set) var memberSet: Set<ItemID> = []
|
|
|
|
/// The dragged items' folders, aligned 1:1 with `members` — what the cross-board commits take.
|
|
@ObservationIgnored private(set) var folders: [URL] = []
|
|
|
|
/// The board the drag started in. Root and store are kept separately because the store may go
|
|
/// away with its window mid-drag while the root — the left-hand side of the locality
|
|
/// comparison — stays perfectly usable.
|
|
private(set) var sourceRoot: URL?
|
|
|
|
@ObservationIgnored private(set) weak var sourceStore: BoardStore?
|
|
|
|
/// The dragged cards' heights, **frozen at drag start**. `DropSlotMath.cardSlot` caps the
|
|
/// vertical trigger region at the first one (the shadow the cursor is over), and the shadows are
|
|
/// drawn at all of them.
|
|
@ObservationIgnored private(set) var cardHeights: [CGFloat] = []
|
|
|
|
/// The dragged lanes' width units, frozen at drag start — the run's span, measured against
|
|
/// whichever board's standard width it is being proposed into.
|
|
@ObservationIgnored private(set) var laneUnits: [Int] = []
|
|
|
|
// MARK: Where it would land
|
|
|
|
/// The current proposal, or `nil` when the drag has none — a fresh session before the first
|
|
/// sample, or one whose target lane was tombstoned in a reload (rule 2 of the re-grounding
|
|
/// trio). **Release with no valid proposal cancels.**
|
|
private(set) var proposal: DropTarget?
|
|
|
|
/// The effective operation, re-resolved on every `dropUpdated` so the system badge tracks live.
|
|
private(set) var operation: TransferOperation = .move
|
|
|
|
/// The committed-overlay hold, or `nil` while the session is still proposing. See
|
|
/// `CommittedHold`.
|
|
private(set) var hold: CommittedHold?
|
|
|
|
// MARK: The external file mode
|
|
|
|
/// Where an external Finder file drag would land, or `nil` when there is none in flight or it is
|
|
/// over nothing that accepts it (`FileDropTarget`).
|
|
///
|
|
/// **A distinct mode, deliberately kept out of everything above.** A file session arms none of
|
|
/// this object's own state — `kind` stays `nil`, so `isActive` stays false, no member is hidden
|
|
/// from any resting layout, and the marquee and card/lane machinery carry on as if no drag
|
|
/// existed. It lives here rather than in a drop delegate for the reason the rest does: the
|
|
/// highlight and the shadows render off it, so it has to be observable and it has to be one
|
|
/// value the whole window agrees on.
|
|
private(set) var fileTarget: FileDropTarget?
|
|
|
|
@ObservationIgnored private var watchdog: Task<Void, Never>?
|
|
@ObservationIgnored private var fileWatchdog: Task<Void, Never>?
|
|
@ObservationIgnored private var holdTimeoutTask: Task<Void, Never>?
|
|
|
|
/// How long this session's holds may stand with no snapshot arriving — `CommittedHold.timeout`,
|
|
/// and a `var` for one reason only: the discard path is a `Task` sleeping on the main actor, and
|
|
/// a test that had to wait the real figure out would be a 1.5 s wall clock in the suite
|
|
/// (`DragSessionTests`). Nothing in the app writes it.
|
|
@ObservationIgnored var holdTimeout: Duration = CommittedHold.timeout
|
|
|
|
init() {}
|
|
|
|
// MARK: Queries
|
|
|
|
var isActive: Bool { kind != nil }
|
|
var isDraggingCards: Bool { kind == .cards }
|
|
var isDraggingLanes: Bool { kind == .lanes }
|
|
|
|
/// Whether the release has **settled**: the write is issued and the arrangement the session was
|
|
/// showing is being held as overlay state until the echo reload lands (`CommittedHold`).
|
|
var isSettled: Bool { hold != nil }
|
|
|
|
/// N — the number of contiguous shadows the proposal draws.
|
|
var shadowCount: Int { members.count }
|
|
|
|
/// Whether `id` is one of the dragged items.
|
|
func isDragging(_ id: ItemID) -> Bool { memberSet.contains(id) }
|
|
|
|
/// The items to **leave out of the resting layout** on the board rooted at `root`.
|
|
///
|
|
/// Only the source board hides anything, and only for a live-side session: a trash row's drag
|
|
/// carries items that render in the quasi-lane, not in any lane's masonry, so no lane loses a
|
|
/// card to it.
|
|
///
|
|
/// **The dragged run is lifted out whatever the effective operation is** (DRAG-REORDER.md §
|
|
/// Resting-layout zones): ⌥ can be pressed and released mid-drag, and a layout that re-admitted
|
|
/// the originals on every modifier flip would flap the whole board under the cursor. The copy's
|
|
/// originals reappear when the write lands — the hold keeps them lifted for that round trip, so
|
|
/// the arrangement on screen is the one the release proposed and stays still until the echo.
|
|
func hiddenMembers(onBoardRooted root: URL) -> Set<ItemID> {
|
|
guard isActive, side == .live, let sourceRoot,
|
|
DragLocality.isSameBoard(root, sourceRoot)
|
|
else { return [] }
|
|
return memberSet
|
|
}
|
|
|
|
/// The proposal's index when it names this board's strip, else `nil` — the lane strip's shadow
|
|
/// run position.
|
|
func stripProposal(onBoardRooted root: URL) -> Int? {
|
|
guard kind == .lanes, let proposal, proposal.container == .strip,
|
|
DragLocality.isSameBoard(proposal.boardRoot, root)
|
|
else { return nil }
|
|
return proposal.index
|
|
}
|
|
|
|
/// The proposal's index when it names `laneID` on this board, else `nil` — the masonry's shadow
|
|
/// run position, in the lane's logical card order.
|
|
func laneProposal(onBoardRooted root: URL, laneID: ItemID) -> Int? {
|
|
guard kind == .cards, let proposal, proposal.container == .lane(laneID),
|
|
DragLocality.isSameBoard(proposal.boardRoot, root)
|
|
else { return nil }
|
|
return proposal.index
|
|
}
|
|
|
|
/// The proposal's index when it names this board's **trash column**, else `nil` — the delete
|
|
/// gesture's shadow row (04-interactions.md ▸ The trash).
|
|
///
|
|
/// Always `TrashDrop.landingIndex`, and read through this accessor anyway so the column asks the
|
|
/// same "is it me?" question every other container asks, and gets the position from the same
|
|
/// place.
|
|
func trashProposal(onBoardRooted root: URL) -> Int? {
|
|
guard kind == .cards, let proposal, proposal.container == .trash,
|
|
DragLocality.isSameBoard(proposal.boardRoot, root)
|
|
else { return nil }
|
|
return proposal.index
|
|
}
|
|
|
|
/// The members that are still there — **rule 3 of the re-grounding trio**: drag membership is a
|
|
/// UUID set that vanished items leave silently (`TransientBoardState.dragMembers`), and when the
|
|
/// last one goes the drag has emptied itself. Partial vanishing drops the survivors, matching
|
|
/// the pending-cut precedent.
|
|
///
|
|
/// The source store answers because it is the one re-grounding the set against each reload; with
|
|
/// its window gone there is nothing left to invalidate the set, and the folders on disk are as
|
|
/// good as they were.
|
|
var survivors: [Int] {
|
|
guard let store = sourceStore else { return Array(members.indices) }
|
|
let live = store.transient.dragMembers.ids
|
|
return members.indices.filter { live.contains(members[$0]) }
|
|
}
|
|
|
|
// MARK: The file mode's queries and lifecycle
|
|
|
|
/// The card an external file drag is hovering **on this board**, or `nil` — the attach
|
|
/// highlight's one input (`CardFaceView`).
|
|
func fileAttachTarget(onBoardRooted root: URL) -> ItemID? {
|
|
guard let fileTarget,
|
|
DragLocality.isSameBoard(fileTarget.boardRoot, root),
|
|
case let .attach(cardID) = fileTarget.landing
|
|
else { return nil }
|
|
return cardID
|
|
}
|
|
|
|
/// The shadow run a file drop would open in `laneID` on this board — where the created cards
|
|
/// land and how many there are — or `nil` when the proposal is elsewhere.
|
|
///
|
|
/// **This run is the create path's whole feedback** (04-interactions.md ▸ Drag and drop, settled
|
|
/// 2026-07-28): there is no lane-level highlight to go with it, deliberately — each target gets
|
|
/// one clear signal, and `fileAttachTarget` above is the highlight precisely because a card
|
|
/// target has no shadow.
|
|
///
|
|
/// The floor restates `FinderDrop.shadowCount`'s, at the render end rather than in place of it: a
|
|
/// proposal that somehow carried a zero would otherwise open a run of no shadows at all, which is
|
|
/// a landing spot the user cannot see.
|
|
func fileLaneProposal(onBoardRooted root: URL, laneID: ItemID) -> (index: Int, count: Int)? {
|
|
guard let fileTarget,
|
|
DragLocality.isSameBoard(fileTarget.boardRoot, root),
|
|
case let .create(lane, index) = fileTarget.landing,
|
|
lane == laneID
|
|
else { return nil }
|
|
return (index: index, count: max(1, fileTarget.fileCount))
|
|
}
|
|
|
|
/// Records where the files would land. `nil` withdraws the proposal — over a gap, the outer
|
|
/// margin, the trash column, or a board that refuses the drop outright.
|
|
///
|
|
/// **No hysteresis, unlike our own sessions.** A card or lane proposal deliberately *holds* while
|
|
/// the cursor crosses ambiguous territory, because the drop must land where the shadows show even
|
|
/// if the cursor drifted off a live zone. A file drop has no such contract: it is a plain "what is
|
|
/// under the cursor right now", so leaving every target simply clears the highlight and the drop
|
|
/// is refused (the pathfinder's `retargetFile` precedent).
|
|
func proposeFile(_ target: FileDropTarget?) {
|
|
guard fileTarget != target else { return }
|
|
let wasHovering = fileTarget != nil
|
|
fileTarget = target
|
|
if target == nil {
|
|
fileWatchdog?.cancel()
|
|
fileWatchdog = nil
|
|
} else if !wasHovering {
|
|
armFileWatchdog()
|
|
}
|
|
}
|
|
|
|
// MARK: Lifecycle
|
|
|
|
/// Begins a card session — live faces or trash rows.
|
|
///
|
|
/// - Parameters:
|
|
/// - members: the dragged cards in flatten order (`SelectionGrammar.liveCards`, or the trash's
|
|
/// own sorted order for a trash-row drag).
|
|
/// - heights: their measured heights, captured **before** the pickup transition starts.
|
|
func beginCards(
|
|
_ members: [ItemID],
|
|
folders: [URL],
|
|
heights: [CGFloat],
|
|
side: Liveness,
|
|
source: BoardStore
|
|
) {
|
|
begin(kind: .cards, members: members, folders: folders, side: side, source: source)
|
|
cardHeights = heights
|
|
laneUnits = []
|
|
}
|
|
|
|
/// Begins a lane session.
|
|
func beginLanes(_ members: [ItemID], folders: [URL], units: [Int], source: BoardStore) {
|
|
begin(kind: .lanes, members: members, folders: folders, side: .live, source: source)
|
|
laneUnits = units
|
|
cardHeights = []
|
|
}
|
|
|
|
private func begin(
|
|
kind: DragKind,
|
|
members: [ItemID],
|
|
folders: [URL],
|
|
side: Liveness,
|
|
source: BoardStore
|
|
) {
|
|
endHold()
|
|
self.kind = kind
|
|
self.members = members
|
|
self.memberSet = Set(members)
|
|
self.folders = folders
|
|
self.side = side
|
|
self.sourceStore = source
|
|
self.sourceRoot = source.rootURL
|
|
self.proposal = nil
|
|
self.operation = .move
|
|
// The reload-resolved drag set: vanished members leave it silently, which is what
|
|
// `survivors` reads and what "an emptied drag cancels itself" is stated in terms of.
|
|
source.transient.dragMembers = ItemReferenceSet(ids: memberSet, liveness: side)
|
|
armWatchdog()
|
|
}
|
|
|
|
/// Records a new proposal. `nil` withdraws it — rule 2's "the shadow withdraws".
|
|
///
|
|
/// **A settled release is past retargeting**: the write naming that slot is already on its way,
|
|
/// so a late callback arriving after the commit — a stray `dropUpdated`, a revalidation — must
|
|
/// not move or withdraw the arrangement the hold is drawing.
|
|
func propose(_ target: DropTarget?) {
|
|
guard isActive, hold == nil, proposal != target else { return }
|
|
proposal = target
|
|
}
|
|
|
|
/// Re-resolves the effective operation against the board under the cursor and the modifiers
|
|
/// **right now**, and hands it back for the `DropProposal` the badge tracks.
|
|
@discardableResult
|
|
func resolveOperation(destinationRoot: URL) -> TransferOperation {
|
|
guard let kind, let sourceRoot else { return operation }
|
|
let resolved = DragLocality.operation(
|
|
kind: kind,
|
|
side: side,
|
|
isWithinBoard: DragLocality.isSameBoard(sourceRoot, destinationRoot),
|
|
modifiers: NSEvent.modifierFlags
|
|
)
|
|
if resolved != operation { operation = resolved }
|
|
return resolved
|
|
}
|
|
|
|
/// Ends the session outright — a cancel, a release with no valid proposal, or the watchdog.
|
|
func end() {
|
|
sourceStore?.transient.dragMembers = .empty
|
|
kind = nil
|
|
members = []
|
|
memberSet = []
|
|
folders = []
|
|
cardHeights = []
|
|
laneUnits = []
|
|
proposal = nil
|
|
operation = .move
|
|
sourceStore = nil
|
|
sourceRoot = nil
|
|
watchdog?.cancel()
|
|
watchdog = nil
|
|
endHold()
|
|
}
|
|
|
|
/// Enters the committed phase: the arrangement the session was showing stays on screen until
|
|
/// `store` applies its next snapshot (`CommittedHold`).
|
|
///
|
|
/// Everything that drives the rendering — the members, the proposal, the source root — is kept
|
|
/// exactly as it was, so "keeps rendering the arrangement it was showing" needs no second
|
|
/// mechanism: the shadows stay at the landing slots and the originals stay lifted out until the
|
|
/// snapshot carrying the write arrives and the real faces take their place.
|
|
func commit(into store: BoardStore) {
|
|
guard isActive else { return }
|
|
sourceStore?.transient.dragMembers = .empty
|
|
watchdog?.cancel()
|
|
watchdog = nil
|
|
let hold = CommittedHold(boardRoot: store.rootURL, generation: store.snapshotGeneration)
|
|
self.hold = hold
|
|
let timeout = holdTimeout
|
|
holdTimeoutTask?.cancel()
|
|
holdTimeoutTask = Task { @MainActor [weak self] in
|
|
try? await Task.sleep(for: timeout)
|
|
guard !Task.isCancelled, let self else { return }
|
|
self.expire(hold)
|
|
}
|
|
}
|
|
|
|
/// **The failed write's path**: no echo is coming, so the hold discards and the board animates
|
|
/// back to snapshot order (03-board-ui.md § Motion — "the width-drag rollback posture: the
|
|
/// action visibly doesn't happen"). The one path in the settle that *is* motion, and the reason
|
|
/// it wears `Motion.dragReflow`: what moves is the arrangement un-happening.
|
|
///
|
|
/// The timeout's own body, spelled as a method rather than inlined in the `Task`, so the discard
|
|
/// can be pinned directly as well as through the clock (`DragSessionTests`). A hold that has
|
|
/// already been handed off — or replaced by a second drag's — is not this one's to end.
|
|
func expire(_ hold: CommittedHold) {
|
|
guard self.hold == hold else { return }
|
|
withAnimation(Motion.dragReflow(reduced: Motion.prefersReducedMotion)) { end() }
|
|
}
|
|
|
|
/// The hand-off: a snapshot landed on `root`, so an overlay standing in for it dissolves.
|
|
///
|
|
/// Called from every board window's own snapshot-generation watch, which is why the hold names
|
|
/// the board it belongs to — a reload on some other board says nothing about this one.
|
|
func handOff(root: URL, generation: Int) {
|
|
guard let hold, hold.isRetired(byRoot: root, generation: generation) else { return }
|
|
end()
|
|
}
|
|
|
|
private func endHold() {
|
|
hold = nil
|
|
holdTimeoutTask?.cancel()
|
|
holdTimeoutTask = nil
|
|
}
|
|
|
|
/// Cleanup for a session-phase event SwiftUI reports.
|
|
///
|
|
/// **Gated on the physical button being up**, because a finished session's `.ended` /
|
|
/// `.dataTransferCompleted` events can be delivered *after the user has already started the next
|
|
/// drag*, and a naive handler wipes the new session's state — no shadow, drop dead. The watchdog
|
|
/// covers every genuinely-ended session anyway, so refusing here costs nothing.
|
|
func endIfButtonReleased() {
|
|
guard NSEvent.pressedMouseButtons == 0 else { return }
|
|
guard isActive, hold == nil else { return }
|
|
withAnimation(Motion.dragReflow(reduced: Motion.prefersReducedMotion)) { end() }
|
|
}
|
|
|
|
// MARK: The watchdog — the single guaranteed termination path
|
|
|
|
/// Polls the physical mouse-button state while a drag is in flight. When the button is released
|
|
/// and, after a short grace period (long enough for a landing `performDrop` to run first), a
|
|
/// session still lingers, it is cleared here. Backstops every path a drop delegate cannot see.
|
|
private func armWatchdog() {
|
|
watchdog?.cancel()
|
|
watchdog = Task { @MainActor [weak self] in
|
|
while !Task.isCancelled {
|
|
try? await Task.sleep(for: .milliseconds(120))
|
|
guard let self, self.isActive, self.hold == nil else { return }
|
|
guard NSEvent.pressedMouseButtons == 0 else { continue }
|
|
try? await Task.sleep(for: .milliseconds(250))
|
|
guard !Task.isCancelled, self.isActive, self.hold == nil else { return }
|
|
withAnimation(Motion.dragReflow(reduced: Motion.prefersReducedMotion)) { self.end() }
|
|
return
|
|
}
|
|
}
|
|
}
|
|
|
|
/// The file mode's own watchdog, and its only guaranteed termination path.
|
|
///
|
|
/// An external session is not ours to end: no `performDrop` runs when the user drops the files
|
|
/// somewhere else entirely, and `onDragSessionUpdated` reports only sessions this app started. A
|
|
/// drag is a button held down, so the same poll the internal watchdog uses answers here — when
|
|
/// the button has been up for a grace period and a target is still standing, the highlight is
|
|
/// stale and goes.
|
|
private func armFileWatchdog() {
|
|
fileWatchdog?.cancel()
|
|
fileWatchdog = Task { @MainActor [weak self] in
|
|
while !Task.isCancelled {
|
|
try? await Task.sleep(for: .milliseconds(120))
|
|
guard let self, self.fileTarget != nil else { return }
|
|
guard NSEvent.pressedMouseButtons == 0 else { continue }
|
|
try? await Task.sleep(for: .milliseconds(250))
|
|
guard !Task.isCancelled, self.fileTarget != nil else { return }
|
|
withAnimation(Motion.dragReflow(reduced: Motion.prefersReducedMotion)) {
|
|
self.proposeFile(nil)
|
|
}
|
|
return
|
|
}
|
|
}
|
|
}
|
|
}
|