@lovett/ui 0.0.11 → 0.2.0

package/src/sortable.tsx

@@ -9,15 +9,24 @@
  * - <DragHandle> is a Lucide-grip handle pre-wired to the listeners
  */
 
+import { useEffect, useRef, useState } from 'react'
 import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
 import {
   DndContext,
+  DragOverlay,
+  MeasuringStrategy,
   closestCenter,
+  closestCorners,
+  pointerWithin,
+  useDroppable,
   KeyboardSensor,
   PointerSensor,
   useSensor,
   useSensors,
+  type CollisionDetection,
   type DragEndEvent,
+  type DragOverEvent,
+  type DragStartEvent,
 } from '@dnd-kit/core'
 import {
   arrayMove,
@@ -86,13 +95,51 @@ export function SortableItem({
 }: {
   id: string
   children: (props: {
+    /** attributes + listeners merged — the single-node case, where the whole
+     *  node IS the handle (a `<DragHandle>`, a settings row's grip). */
     dragHandleProps: HTMLAttributes<HTMLElement>
+    /**
+     * The ACTIVATORS — `onPointerDown` from the PointerSensor, `onKeyDown` from
+     * the KeyboardSensor. Whatever element receives these is what starts a drag.
+     *
+     * Split from `dragAttributes` so a card can be a drop target and a
+     * transform target (`setNodeRef` + `style`) WITHOUT being a drag handle.
+     * Spread these onto the card root and a pointer-down anywhere on it starts
+     * a drag, which is the bug this split exists to prevent: the card's own
+     * buttons, links and text selection all stop working as themselves.
+     */
+    dragListeners: HTMLAttributes<HTMLElement>
+    /**
+     * `role="button"`, `tabIndex`, `aria-roledescription`, `aria-describedby`.
+     *
+     * These belong on the SAME element as `dragListeners` — they describe the
+     * handle to assistive tech, and dnd-kit's instruction text is reached
+     * through the `aria-describedby` here. Putting them on a card that holds
+     * its own buttons makes it an interactive element wrapping interactive
+     * elements, and `role="button"`'s presentational children erase the
+     * buttons inside it.
+     */
+    dragAttributes: HTMLAttributes<HTMLElement>
+    /** The draggable NODE — measured, transformed, and used as the drop rect. */
     setNodeRef: (node: HTMLElement | null) => void
+    /**
+     * The HANDLE node. dnd-kit restores focus here when a keyboard drag ends;
+     * without it focus lands on the card and the next arrow key does nothing.
+     */
+    setActivatorNodeRef: (node: HTMLElement | null) => void
     style: CSSProperties
     isDragging: boolean
   }) => ReactNode
 }) {
-  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    setActivatorNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({
     id,
   })
 
@@ -108,7 +155,14 @@ export function SortableItem({
     <>
       {children({
         dragHandleProps: { ...attributes, ...listeners } as HTMLAttributes<HTMLElement>,
+        dragListeners: { ...listeners } as HTMLAttributes<HTMLElement>,
+        // Attributes ONLY. This was `{ ...attributes, ...listeners }` — byte
+        // identical to `dragHandleProps` — so the "split" was not a split, and
+        // every consumer that took `dragAttributes` for the aria wiring got the
+        // pointer activators with it.
+        dragAttributes: { ...attributes } as HTMLAttributes<HTMLElement>,
         setNodeRef,
+        setActivatorNodeRef,
         style,
         isDragging,
       })}
@@ -135,3 +189,468 @@ export function DragHandle({
     </button>
   )
 }
+
+/* ============================================================================
+ * Multi-container drag — ADR-146 slice A.
+ *
+ * <SortableList> above is single-container: one list, reorder within it. A
+ * kanban needs a card to LEAVE its column, which dnd-kit models as a droppable
+ * per container plus a DragOverlay that follows the pointer while the source
+ * item stays in place.
+ *
+ * Kept from the single-container wrapper on purpose:
+ *   - the KeyboardSensor, so a card can cross columns without a pointer
+ *     (interface-standards §6 — non-negotiable, not polish)
+ *   - the 4px pointer activation constraint, so a click on a card still reads
+ *     as a click and not a 1px drag
+ *
+ * Added:
+ *   - pointer-first collision (`pointerFirstCollision` below), which resolves
+ *     the drop target from the CURSOR and falls back to `closestCorners` when
+ *     there is no cursor. That fallback is not a nicety: it is the keyboard
+ *     drag's only path.
+ *   - `MeasuringStrategy.Always`, because a container's height changes as
+ *     cards enter and leave it and a cached rect drops the item in the wrong
+ *     lane.
+ *   - screen-reader announcements naming the destination container, not its id.
+ * ========================================================================== */
+
+/**
+ * Pointer first, `closestCorners` second — dnd-kit's documented shape for a
+ * multi-container board (the pointer, then a rect-based fallback; which rect
+ * strategy is the choice made at the bottom of this note), and the answer to
+ * two defects rather than one.
+ *
+ * The history is a ladder, and each rung is still true:
+ *
+ *   `closestCenter` measured the dragged card's CENTRE against each droppable
+ *   and mis-resolved whenever the card was taller than the row it was over,
+ *   which is the normal case on a board with variable-height cards.
+ *
+ *   `closestCorners` measured the card's four CORNERS instead. Better, and
+ *   still wrong in the same family: it measures the CARD. A tall card's
+ *   corners stay nearer its source lane until most of its body has crossed the
+ *   boundary, so the user has to drag the whole card into the destination
+ *   rather than point at it. Reported as "I have to literally drag the full
+ *   entire card over the lane so it catches it".
+ *
+ *   `pointerWithin` measures the POINTER, so a card is caught by the lane the
+ *   cursor is over regardless of how tall the card is. Card height stops being
+ *   an input at all, which is why this does not reintroduce the defect
+ *   `closestCorners` was adopted to fix — it retires the whole measurement.
+ *
+ * `pointerWithin` returns EVERY droppable containing the pointer, ordered by
+ * the pointer's mean distance to that rect's four corners — so the tightest
+ * box around the cursor wins. A pointer inside a card yields [card, column]
+ * and `over` resolves to the card, which is what gives a cross-column drop its
+ * insertion INDEX. A pointer in the column's empty space below the last card
+ * yields just the column, and the item appends. Both are wanted.
+ *
+ * It returns nothing at all when `pointerCoordinates` is null, and dnd-kit
+ * derives those from the activator event's `clientX`/`clientY`. A KeyboardEvent
+ * has neither, so EVERY keyboard drag takes the fallback — a pointer-only
+ * strategy would leave `over` permanently null and break cross-column keyboard
+ * movement silently, gates all green. The fallback is therefore `closestCorners`
+ * and not `rectIntersection`: keyboard drags keep the exact resolution they
+ * have been tested against, and the pointer-outside-every-droppable case (the
+ * board's margins and gutters) keeps resolving to the nearest lane rather than
+ * to nothing. `rectIntersection` would answer that case by area of overlap —
+ * "most of the card", the defect above, back in the gutters.
+ */
+export const pointerFirstCollision: CollisionDetection = (args) => {
+  const byPointer = pointerWithin(args)
+  return byPointer.length > 0 ? byPointer : closestCorners(args)
+}
+
+/** containerId -> the ids it holds, in order. */
+export type SortableContainers = Readonly<Record<string, readonly string[]>>
+
+export interface MultiSortableMove {
+  itemId: string
+  fromContainerId: string
+  toContainerId: string
+  /** Destination index within `toContainerId`, after the move. */
+  toIndex: number
+}
+
+export interface MultiSortableListProps {
+  containers: SortableContainers
+  /** Container ids in board order. Also the set treated as drop targets. */
+  containerOrder: readonly string[]
+  /**
+   * Commit the move. Called from the drop handler with the arrangement the
+   * board is already showing, so the consumer's job is to make `containers`
+   * agree — it is not being asked to produce a frame.
+   *
+   * It used to say "called synchronously ... so a `setState` here batches with
+   * the primitive's own reset". True, and it described the wrong consumer. A
+   * consumer that patches its cache synchronously never saw the ghost; one
+   * that patches from a mutation's `onMutate` — a microtask at best, an
+   * `await cancelQueries` at worst — is not in that batch, and got a frame of
+   * the pre-drag arrangement. See the preview note below for what replaced it.
+   */
+  onMove: (move: MultiSortableMove, next: SortableContainers) => void
+  /**
+   * Override the drop-target strategy. Defaults to `pointerFirstCollision`,
+   * whose reasoning is in its own docblock.
+   *
+   * A prop because this component has now changed collision strategy twice
+   * (`closestCenter` → `closestCorners` → pointer-first) and both times a
+   * consumer had to wait for a release of this package to get the fix. The
+   * escape hatch costs one optional prop; a third such wait costs a release.
+   * Overriding it is opting out of the reasoning above, including the keyboard
+   * fallback — a bare `pointerWithin` here disables keyboard dragging.
+   */
+  collisionDetection?: CollisionDetection | undefined
+  /**
+   * What follows the pointer. Without this the card appears to vanish.
+   *
+   * Receives the item's container in the LIVE arrangement, which during a
+   * cross-column drag is the DESTINATION, not the origin. Without it the
+   * overlay renders in the origin's colour while the placeholder underneath
+   * already shows the destination's — one card, on screen twice, in two
+   * different hues.
+   */
+  renderOverlay?: ((itemId: string, containerId: string | null) => ReactNode) | undefined
+  /** Human name for an id, for both the overlay's a11y text and announcements. */
+  labelForItem?: ((itemId: string) => string) | undefined
+  labelForContainer?: ((containerId: string) => string) | undefined
+  /**
+   * Receives the live arrangement, which differs from `containers` mid-drag,
+   * and the container the drag is currently resolved INTO.
+   *
+   * The second argument exists because `useDroppable().isOver` cannot answer
+   * it on a board: every collision strategy here resolves `over` to a sortable
+   * ITEM whenever a column holds one — `closestCorners` by distance, and
+   * `pointerWithin` because a pointer inside a card is inside its column too
+   * and the card's centre is nearer — so the column's own droppable never wins
+   * and its `isOver` measured `false` on every column during real pointer AND
+   * keyboard drags. The container has to be derived from the resolved `over`
+   * id — the same `containerOf` the announcements already use.
+   */
+  children: (
+    arrangement: SortableContainers,
+    overContainerId: string | null,
+  ) => ReactNode
+}
+
+/**
+ * The arrangement the board renders INSTEAD of `containers`, and the thing
+ * `containers` has to catch up to.
+ *
+ * Defect: dropping a card in another lane showed it snap back to its origin
+ * and then forward again — "like an invisible or ghost presence". The old
+ * `handleDragEnd` cleared the preview and then called `onMove`. Clearing means
+ * rendering from `containers`, and `containers` is the consumer's cache, which
+ * at that instant still holds the PRE-DRAG arrangement. One frame in the old
+ * lane, then the consumer's patch lands and moves it again. That frame is the
+ * ghost.
+ *
+ * Reordering the two lines does not fix it. Both are in one discrete event
+ * handler, React flushes that as one batch, and an asynchronous consumer patch
+ * is not in the batch either way — the render it produces still has the
+ * preview cleared and `containers` stale. The fix is not to clear the preview
+ * at the drop at all: hold it, and let the next `containers` supersede it.
+ *
+ * So the preview is held against the exact `containers` value it was committed
+ * over. Any new one means the consumer has spoken — a patch, a rollback, a
+ * refetch, all of them authoritative — and the preview is dropped in the same
+ * render, not a frame later.
+ *
+ * WHEN THE CONSUMER NEVER PATCHES. A held preview is a claim that a move
+ * landed. A consumer that rejects the move, fails its write without rolling
+ * back, or simply ignores `onMove` never produces a new `containers`, and an
+ * unbounded hold would leave the board asserting a move that did not happen —
+ * silently, until something unrelated invalidated the query. So the hold is
+ * bounded: after `PREVIEW_SETTLE_MS` the preview expires and `containers`
+ * wins, which renders as the card returning to its lane. That is the correct
+ * picture of a rejected move, and the only picture available, because the
+ * primitive has no other way to be told.
+ *
+ * The cost is paid by a consumer that commits WITHOUT an optimistic patch and
+ * waits for a server round trip: past the deadline the card returns and then
+ * moves again when the response lands. That is the ghost, delayed — and it is
+ * honest, because a board that does not yet know the move landed should not be
+ * drawing it. The fix for that consumer is an optimistic patch, which is the
+ * pattern this component is shaped around.
+ */
+interface DragPreview {
+  arrangement: SortableContainers
+  /** The `containers` identity this was committed over. A new one supersedes. */
+  basis: SortableContainers
+  /** False while the drag is in flight — a live preview is never superseded. */
+  settled: boolean
+}
+
+/**
+ * How long a settled preview outlives the drop before `containers` wins.
+ *
+ * Floor: dnd-kit's drop animation is 250ms, and the preview has to still be
+ * under the overlay when it lands or the overlay animates onto an empty slot.
+ * Ceiling: a rejected move has to read as rejected rather than as accepted,
+ * and half a second is about where a snap-back stops looking like a response.
+ * The healthy path never reaches either — an optimistic patch supersedes this
+ * in a frame or two, and the timer is cleared.
+ */
+export const PREVIEW_SETTLE_MS = 500
+
+function moveBetween(
+  arrangement: SortableContainers,
+  itemId: string,
+  from: string,
+  to: string,
+  index: number,
+): SortableContainers {
+  const next: Record<string, readonly string[]> = { ...arrangement }
+  const fromItems = (next[from] ?? []).filter((id) => id !== itemId)
+  const toItems = from === to ? [...fromItems] : [...(next[to] ?? [])]
+  const clamped = Math.max(0, Math.min(index, toItems.length))
+  toItems.splice(clamped, 0, itemId)
+  next[from] = fromItems
+  next[to] = toItems
+  return next
+}
+
+export function MultiSortableList({
+  containers,
+  containerOrder,
+  onMove,
+  collisionDetection = pointerFirstCollision,
+  renderOverlay,
+  labelForItem,
+  labelForContainer,
+  children,
+}: MultiSortableListProps) {
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 4 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  )
+
+  const [activeId, setActiveId] = useState<string | null>(null)
+  const [overContainerId, setOverContainerId] = useState<string | null>(null)
+  const [preview, setPreview] = useState<DragPreview | null>(null)
+  // The arrangement the drag started from, so a cancel restores it exactly.
+  const originRef = useRef<SortableContainers | null>(null)
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (settleTimer.current !== null) clearTimeout(settleTimer.current)
+    },
+    [],
+  )
+
+  const stopSettleTimer = () => {
+    if (settleTimer.current !== null) {
+      clearTimeout(settleTimer.current)
+      settleTimer.current = null
+    }
+  }
+
+  // Derived, not stored: on the render where `containers` finally carries the
+  // move, the board is already right — no second commit, no frame in between.
+  const superseded = preview !== null && preview.settled && preview.basis !== containers
+  const arrangement = preview !== null && !superseded ? preview.arrangement : containers
+
+  // And a supersede is FINAL. `containers` can return to the exact object the
+  // preview was held against — a rolled-back optimistic write restores the
+  // previous reference, not a copy of it — and a preview still sitting in state
+  // would then stop looking superseded and draw the move a second time, after
+  // the consumer had undone it. Dropping it here rather than in an effect keeps
+  // that to zero frames: React re-runs this render with the state already gone.
+  // The pending timer is left to fire into a null preview, where it is a no-op.
+  if (superseded) setPreview(null)
+
+  /**
+   * Show `next` until `containers` says otherwise. Called at every exit from a
+   * drag — committed, no-op, dropped outside, cancelled — so there is exactly
+   * one place where the board stops previewing.
+   *
+   * `next === containers` covers the ordinary cancel: the board is already
+   * rendering the truth, so there is nothing to hold and no timer to run.
+   */
+  const holdPreview = (next: SortableContainers) => {
+    stopSettleTimer()
+    if (next === containers) {
+      setPreview(null)
+      return
+    }
+    setPreview({ arrangement: next, basis: containers, settled: true })
+    settleTimer.current = setTimeout(() => {
+      settleTimer.current = null
+      setPreview(null)
+    }, PREVIEW_SETTLE_MS)
+  }
+
+  const containerOf = (id: string): string | null => {
+    if (containerOrder.includes(id)) return id
+    for (const containerId of containerOrder) {
+      if ((arrangement[containerId] ?? []).includes(id)) return containerId
+    }
+    return null
+  }
+
+  const nameItem = (id: string) => labelForItem?.(id) ?? id
+  const nameContainer = (id: string) => labelForContainer?.(id) ?? id
+
+  const handleDragStart = (event: DragStartEvent) => {
+    const id = String(event.active.id)
+    setActiveId(id)
+    stopSettleTimer()
+    // `arrangement`, not `containers`. A previous drop may still be held while
+    // its consumer patch is in flight, and rebasing on `containers` here would
+    // yank that card back to its old lane the moment the user picks up the
+    // next one — the ghost again, one drag later. The drag starts from what is
+    // on screen, which is also what the user is dragging.
+    originRef.current = arrangement
+    setPreview({ arrangement, basis: containers, settled: false })
+    // The card starts over its own column, so the drop target is lit from the
+    // first frame rather than only once the pointer crosses a boundary.
+    setOverContainerId(containerOf(id))
+  }
+
+  const handleDragOver = (event: DragOverEvent) => {
+    const { active, over } = event
+    if (!over) {
+      setOverContainerId(null)
+      return
+    }
+    const itemId = String(active.id)
+    const overId = String(over.id)
+    const from = containerOf(itemId)
+    const to = containerOf(overId)
+    // Set BEFORE the same-container early return: a reorder inside one column
+    // still has a drop target, and it is that column.
+    setOverContainerId(to)
+    if (!from || !to || from === to) return
+
+    const overItems = arrangement[to] ?? []
+    const overIndex = overItems.indexOf(overId)
+    const index = overIndex === -1 ? overItems.length : overIndex
+    setPreview({
+      arrangement: moveBetween(arrangement, itemId, from, to, index),
+      basis: containers,
+      settled: false,
+    })
+  }
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event
+    const itemId = String(active.id)
+    const origin = originRef.current ?? containers
+    const from = Object.keys(origin).find((key) =>
+      (origin[key] ?? []).includes(itemId),
+    )
+    setActiveId(null)
+    setOverContainerId(null)
+    originRef.current = null
+
+    // Dropped outside every column, or an id the origin does not hold. Nothing
+    // is committed, so nothing will patch: the board goes back to what it was
+    // showing when the drag began.
+    if (!over || !from) {
+      holdPreview(origin)
+      return
+    }
+
+    const overId = String(over.id)
+    const to = containerOf(overId) ?? from
+    const overItems = (arrangement[to] ?? []).filter((id) => id !== itemId)
+    const overIndex = overItems.indexOf(overId)
+    const index = overIndex === -1 ? overItems.length : overIndex
+    const next = moveBetween(origin, itemId, from, to, index)
+
+    // Same lane, same slot. No `onMove`, therefore no patch to wait for.
+    if (from === to && (origin[from] ?? []).indexOf(itemId) === index) {
+      holdPreview(origin)
+      return
+    }
+
+    // Hold BEFORE handing over. The primitive's own state is then complete and
+    // consistent whatever `onMove` does, including throw.
+    holdPreview(next)
+    onMove({ itemId, fromContainerId: from, toContainerId: to, toIndex: index }, next)
+  }
+
+  const handleDragCancel = () => {
+    setActiveId(null)
+    setOverContainerId(null)
+    const origin = originRef.current ?? containers
+    originRef.current = null
+    // Not `setPreview(null)`: clearing renders `containers`, which is only the
+    // right answer when the drag started from it. If a previous drop is still
+    // held, cancelling this one must return to THAT, not undo both.
+    holdPreview(origin)
+  }
+
+  return (
+    <DndContext
+      sensors={sensors}
+      collisionDetection={collisionDetection}
+      measuring={{ droppable: { strategy: MeasuringStrategy.Always } }}
+      onDragStart={handleDragStart}
+      onDragOver={handleDragOver}
+      onDragEnd={handleDragEnd}
+      onDragCancel={handleDragCancel}
+      accessibility={{
+        announcements: {
+          onDragStart: ({ active }) => `Picked up ${nameItem(String(active.id))}.`,
+          onDragOver: ({ active, over }) =>
+            over
+              ? `${nameItem(String(active.id))} is over ${nameContainer(
+                  containerOf(String(over.id)) ?? String(over.id),
+                )}.`
+              : `${nameItem(String(active.id))} is no longer over a column.`,
+          onDragEnd: ({ active, over }) =>
+            over
+              ? `Moved ${nameItem(String(active.id))} to ${nameContainer(
+                  containerOf(String(over.id)) ?? String(over.id),
+                )}.`
+              : `${nameItem(String(active.id))} was dropped outside a column and returned.`,
+          onDragCancel: ({ active }) =>
+            `Cancelled. ${nameItem(String(active.id))} returned to where it started.`,
+        },
+      }}
+    >
+      {children(arrangement, overContainerId)}
+      <DragOverlay>
+        {activeId && renderOverlay ? renderOverlay(activeId, containerOf(activeId)) : null}
+      </DragOverlay>
+    </DndContext>
+  )
+}
+
+/**
+ * One droppable container inside a <MultiSortableList>.
+ *
+ * Renders through a prop so the consumer owns the container's chrome — the
+ * board column's drag-over state steps its BORDER rather than tinting with the
+ * accent (design brief §4), and only the consumer knows what its border is.
+ *
+ * `isOver` here is `useDroppable`'s raw answer and is NOT the board's drag-over
+ * signal: `over` resolves to a sortable item whenever the column holds one, so
+ * this reads `false` for the column the card is actually over. It is kept
+ * because the droppable registration is what makes an EMPTY column a drop
+ * target at all — and, under pointer-first collision, what makes the column's
+ * empty space below the last card a target for an append. The state a consumer
+ * should paint comes from `MultiSortableList`'s `overContainerId`.
+ */
+export function SortableDropZone({
+  id,
+  items,
+  children,
+}: {
+  id: string
+  items: readonly string[]
+  children: (props: {
+    setNodeRef: (node: HTMLElement | null) => void
+    isOver: boolean
+  }) => ReactNode
+}) {
+  const { setNodeRef, isOver } = useDroppable({ id })
+  return (
+    <SortableContext items={[...items]} strategy={verticalListSortingStrategy}>
+      {children({ setNodeRef, isOver })}
+    </SortableContext>
+  )
+}