@lovett/ui 0.0.10 → 0.1.0

package/src/sortable.tsx

@@ -9,15 +9,22 @@
  * - <DragHandle> is a Lucide-grip handle pre-wired to the listeners
  */
 
+import { useRef, useState } from 'react'
 import type { CSSProperties, HTMLAttributes, ReactNode } from 'react'
 import {
   DndContext,
+  DragOverlay,
+  MeasuringStrategy,
   closestCenter,
+  closestCorners,
+  useDroppable,
   KeyboardSensor,
   PointerSensor,
   useSensor,
   useSensors,
   type DragEndEvent,
+  type DragOverEvent,
+  type DragStartEvent,
 } from '@dnd-kit/core'
 import {
   arrayMove,
@@ -86,13 +93,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 +153,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 +187,265 @@ 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:
+ *   - `closestCorners` rather than `closestCenter`. Center-based collision
+ *     mis-resolves when the dragged card is taller than the row it is over,
+ *     which is the normal case on a board with variable-height cards.
+ *   - `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.
+ * ========================================================================== */
+
+/** 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 synchronously from the drop handler, so a
+   * `setState` here batches with the primitive's own reset and the board does
+   * not flash the pre-drag arrangement for a frame.
+   */
+  onMove: (move: MultiSortableMove, next: SortableContainers) => void
+  /**
+   * 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: `closestCorners` resolves `over` to a sortable ITEM
+   * whenever a column holds one, 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
+}
+
+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,
+  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<SortableContainers | null>(null)
+  // The arrangement the drag started from, so a cancel restores it exactly.
+  const originRef = useRef<SortableContainers | null>(null)
+
+  const arrangement = preview ?? containers
+
+  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)
+    originRef.current = containers
+    setPreview(containers)
+    // 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(moveBetween(arrangement, itemId, from, to, index))
+  }
+
+  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
+
+    if (!over || !from) {
+      setPreview(null)
+      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)
+
+    setPreview(null)
+    if (from === to && (origin[from] ?? []).indexOf(itemId) === index) return
+    onMove({ itemId, fromContainerId: from, toContainerId: to, toIndex: index }, next)
+  }
+
+  const handleDragCancel = () => {
+    setActiveId(null)
+    setOverContainerId(null)
+    originRef.current = null
+    setPreview(null)
+  }
+
+  return (
+    <DndContext
+      sensors={sensors}
+      collisionDetection={closestCorners}
+      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: with `closestCorners`, `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. 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>
+  )
+}