@coreui/data-grid 0.1.0-rc.0 → 0.3.0-rc.0

package/src/util/drag.ts

@@ -0,0 +1,832 @@
+/**
+ * --------------------------------------------------------------------------
+ * CoreUI PRO data-grid util/drag.ts
+ * License (https://coreui.io/pro/license/)
+ * --------------------------------------------------------------------------
+ */
+
+// The one drag implementation behind every reorder in the grid: column drag
+// (axis 'x', over the header) and row drag (axis 'y', over the body). It is
+// headless in the sense that matters — it never reads the table, only what the
+// consumer resolves for it — and pointer-based rather than HTML5 drag events,
+// which cannot render a drop indicator, cannot auto-scroll, and behave
+// differently on touch.
+//
+// The invariant that keeps it cheap: pointermove writes to the DOM directly.
+// Nothing here goes through component state, change detection or a signal, so
+// a drag costs no re-renders in any of the four editions.
+
+const CLASS_NAME_GHOST = 'data-grid-drag-ghost'
+const CLASS_NAME_INDICATOR = 'data-grid-drop-indicator'
+const CLASS_NAME_DRAGGING = 'data-grid-dragging'
+const CLASS_NAME_DRAG_ACTIVE = 'data-grid-drag-active'
+const CLASS_NAME_PREVIEW = 'data-grid-drag-preview'
+const CLASS_NAME_GHOST_SETTLE = 'data-grid-drag-ghost-settle'
+
+// A press has to travel this far before it becomes a drag — otherwise a click
+// on a sortable header would never sort.
+const DRAG_THRESHOLD = 4
+// How far past a zone boundary the pointer must travel before the slot flips.
+// Swaps fire on ENTRY into a neighbour's zone, and without this band a hand
+// tremor exactly on the boundary would re-animate back and forth.
+const DRAG_HYSTERESIS = 3
+// How close to the scroll element's edge the pointer starts auto-scrolling,
+// and the fastest it scrolls when pinned to that edge.
+const EDGE_SIZE = 48
+const EDGE_MAX_SPEED = 18
+// The ghost trails the pointer by this much, in px.
+const GHOST_OFFSET = 12
+// Removal fallback for the settling ghost — a context where the transition
+// never runs (reduced motion, a hidden tab) must not leak the element.
+const GHOST_SETTLE_FALLBACK_MS = 400
+
+export type DragAxis = 'x' | 'y'
+
+export interface DragHit {
+  id: string
+  element: HTMLElement
+}
+
+export interface DragDrop {
+  id: string
+  // The source lands after the target rather than before it — which side of
+  // the target's midpoint the pointer was released on.
+  after: boolean
+}
+
+export interface DragControllerOptions {
+  axis: DragAxis
+  root: HTMLElement
+  // Delegation selector for the element a drag may start from.
+  handle: string
+  // Called with the handle and the element actually pressed. Returning null
+  // vetoes the drag: a press on a resize handle, a column the author marked
+  // immovable, a grid whose reordering is off.
+  resolveSource: (handle: HTMLElement, target: HTMLElement) => DragHit | null
+  items: DragItems
+  // Vetoes a slot: the source itself, or an item the reorder may not cross
+  // (a column in another pinned region).
+  canDrop: (sourceId: string, targetId: string) => boolean
+  getScrollElement: () => HTMLElement | null
+  // The ghost's caption. Defaults to the source's collapsed text, which is the
+  // label for a header cell but every cell run together for a row.
+  ghostLabel?: (source: DragHit) => string
+  // The live preview: the items between the source and the drop slot slide
+  // aside and the source slides into the gap, so the grid shows the layout the
+  // drop will produce instead of only pointing at it. Transforms only, so
+  // nothing reflows and the real order still changes once, on drop. Replaces
+  // the drop-indicator line, which only renders when this is off.
+  preview?: boolean
+  onDrop: (sourceId: string, drop: DragDrop) => void
+}
+
+// The reorderable items, in display order along the drag's axis. This is both
+// what the pointer is hit-tested against and what the live preview slides.
+export interface DragItems {
+  getOrderedIds: () => string[]
+  // Every element that travels with that id: a column's header and body cells,
+  // or simply the row.
+  getElements: (id: string) => HTMLElement[]
+}
+
+export interface DragController {
+  dispose: () => void
+}
+
+const collapse = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
+// Which slot the source lands in, expressed in the CURRENT order — the same
+// arithmetic the drop itself does, so the preview cannot disagree with it.
+const destinationIndex = (from: number, target: number, after: boolean): number =>
+  (target > from ? (after ? target : target - 1) : (after ? target + 1 : target))
+
+const swallowClick = (event: Event) => {
+  event.preventDefault()
+  event.stopPropagation()
+}
+
+const disarmSwallowClick = () => {
+  document.removeEventListener('click', swallowClick, { capture: true })
+}
+
+// Server-side rendering reaches here through Angular, whose ngAfterViewInit and
+// ngOnDestroy both run during prerender. There is no pointer to track without a
+// document, so hand back an inert controller instead of touching one.
+const INERT_CONTROLLER: DragController = { dispose() {} }
+
+export const createDragController = (options: DragControllerOptions): DragController => {
+  if (typeof document === 'undefined') {
+    return INERT_CONTROLLER
+  }
+
+  const { axis, root } = options
+  const horizontal = axis === 'x'
+
+  let sourceHit: DragHit | null = null
+  let dragging = false
+  // +1 while the axis runs the way the coordinates do, -1 under RTL, where the
+  // logical column order runs against increasing x. Negating the axis keeps
+  // every comparison below — the zone tiling, the hysteresis band, both edge
+  // clamps, `index > fromIndex` — written once, for one direction. Only the
+  // three places that touch pixels again convert back: the indicator's side,
+  // the preview transform and the settling ghost.
+  //
+  // Read from the grid's own computed direction rather than the document's: a
+  // grid can sit in an RTL subtree of an LTR page, which is exactly the case
+  // the vendored isRTL() cannot see.
+  let axisSign = 1
+  let origin = { x: 0, y: 0 }
+  let pointer = { x: 0, y: 0 }
+  let drop: DragDrop | null = null
+  let ghost: HTMLElement | null = null
+  let indicator: HTMLElement | null = null
+  let scrollFrame = 0
+  let pointerId = -1
+  let previewKey = ''
+  // The zone that produced the current drop, padded by the hysteresis band.
+  let sticky: { lo: number; hi: number } | null = null
+  // The transform currently applied to each item — the preview diffs against
+  // it, and a layout captured mid-preview (a row revealed by auto-scroll) is
+  // corrected back through it.
+  const previewDeltas = new Map<string, number>()
+  // Every id that still carries the transition class. Mid-drag un-shifts keep
+  // the class so the slide BACK animates too; it only comes off at the end.
+  const previewClassed = new Set<string>()
+  // Each item's start in the scroll container's CONTENT coordinates — a space
+  // no transform and no scroll can move. Captured at drag start, when nothing
+  // is transformed yet, so the values are exact.
+  const contentStarts = new Map<string, number>()
+  const contentSizes = new Map<string, number>()
+
+  // A rect's logical start: its leading edge along the axis, in the negated
+  // space when the axis is negated, so the span stays [start, start + size].
+  const logicalStart = (rect: DOMRect): number => {
+    if (!horizontal) {
+      return rect.top
+    }
+
+    return axisSign === 1 ? rect.left : -rect.right
+  }
+
+  const logicalPointer = (): number => (horizontal ? pointer.x * axisSign : pointer.y)
+
+  const stopAutoScroll = () => {
+    if (scrollFrame) {
+      cancelAnimationFrame(scrollFrame)
+      scrollFrame = 0
+    }
+  }
+
+  const autoScroll = () => {
+    scrollFrame = 0
+    const scrollElement = options.getScrollElement()
+    if (!scrollElement || !dragging) {
+      return
+    }
+
+    const rect = scrollElement.getBoundingClientRect()
+    const position = horizontal ? pointer.x : pointer.y
+    const start = horizontal ? rect.left : rect.top
+    const end = horizontal ? rect.right : rect.bottom
+
+    // Speed ramps with how far into the edge zone the pointer sits, so the
+    // list creeps at the boundary and races when pinned to the edge.
+    let delta = 0
+    if (position < start + EDGE_SIZE) {
+      delta = -EDGE_MAX_SPEED * Math.min(1, (start + EDGE_SIZE - position) / EDGE_SIZE)
+    } else if (position > end - EDGE_SIZE) {
+      delta = EDGE_MAX_SPEED * Math.min(1, (position - (end - EDGE_SIZE)) / EDGE_SIZE)
+    }
+
+    if (delta !== 0) {
+      if (horizontal) {
+        scrollElement.scrollLeft += delta
+      } else {
+        scrollElement.scrollTop += delta
+      }
+
+      // Scrolling moved the content under a stationary pointer, and no
+      // pointermove will fire to say so.
+      updateTarget()
+      scrollFrame = requestAnimationFrame(autoScroll)
+    }
+  }
+
+  // The ghost trails the pointer instead of sitting under it, so the cell the
+  // hit test resolves stays visible.
+  const moveGhost = () => {
+    if (ghost) {
+      ghost.style.transform = `translate(${pointer.x + GHOST_OFFSET}px, ${pointer.y + GHOST_OFFSET}px)`
+    }
+  }
+
+  const hideIndicator = () => {
+    if (indicator) {
+      indicator.hidden = true
+    }
+  }
+
+  const showIndicator = (target: HTMLElement, after: boolean) => {
+    if (!indicator) {
+      return
+    }
+
+    const rect = target.getBoundingClientRect()
+    const rootRect = root.getBoundingClientRect()
+    indicator.hidden = false
+    if (horizontal) {
+      // `after` is logical; which pixel edge that is flips with the axis.
+      const trailing = after === (axisSign === 1)
+      indicator.style.left = `${trailing ? rect.right : rect.left}px`
+      indicator.style.top = `${rootRect.top}px`
+      indicator.style.height = `${rootRect.height}px`
+    } else {
+      indicator.style.left = `${rootRect.left}px`
+      indicator.style.top = `${after ? rect.bottom : rect.top}px`
+      indicator.style.width = `${rootRect.width}px`
+    }
+  }
+
+  const startDrag = () => {
+    dragging = true
+    axisSign = horizontal && getComputedStyle(root).direction === 'rtl' ? -1 : 1
+    // Chrome focuses a button on mousedown (a press on a header lands on the
+    // sort button), and tearing a FOCUSED element out of the DOM — which the
+    // drop's header re-append does — makes the browser reset the scroller it
+    // lived in: releasing a drag with the viewport scrolled right snapped it
+    // back to the left. A drag has no use for focus; drop it the moment the
+    // press becomes one. Sub-threshold presses never get here, so click-to-
+    // sort keeps its focus behavior.
+    const active = document.activeElement
+    if (active instanceof HTMLElement && root.contains(active)) {
+      active.blur()
+    }
+
+    root.classList.add(CLASS_NAME_DRAG_ACTIVE)
+    sourceHit!.element.classList.add(CLASS_NAME_DRAGGING)
+
+    const rect = sourceHit!.element.getBoundingClientRect()
+    ghost = document.createElement('div')
+    ghost.className = CLASS_NAME_GHOST
+    ghost.setAttribute('aria-hidden', 'true')
+    ghost.style.width = `${rect.width}px`
+    ghost.style.height = `${rect.height}px`
+    ghost.textContent = options.ghostLabel ?
+      options.ghostLabel(sourceHit!) :
+      collapse(sourceHit!.element.textContent ?? '')
+
+    // With the live preview on, the sliding items ARE the drop indicator; a
+    // line has no stable place to stand, because it would be measured against
+    // cells that are themselves mid-transition. The line only exists for
+    // consumers that turned the preview off.
+    if (!options.preview) {
+      indicator = document.createElement('div')
+      indicator.className = `${CLASS_NAME_INDICATOR} ${CLASS_NAME_INDICATOR}-${axis}`
+      indicator.setAttribute('aria-hidden', 'true')
+      indicator.hidden = true
+      root.append(indicator)
+    }
+
+    root.append(ghost)
+    moveGhost()
+    captureLayout()
+  }
+
+  // Where the container's content coordinate 0 currently sits on screen. The
+  // one live measurement the hit test needs — everything else is arithmetic on
+  // the snapshot, so mid-transition rects can never feed back into the slot.
+  //
+  // This is the whole reason the hit test is neither document.elementFromPoint
+  // nor rect-minus-delta reconstruction: the preview MOVES the cells under the
+  // pointer, and a rect measured mid-transition contains only part of its
+  // delta, so both models handed back zones shifted by the unfinished
+  // remainder of the animation. Dragging with the direction of travel, that
+  // shifted zone swallowed the next item's first half and the slot flipped
+  // back and forth until the transition settled.
+  const contentOrigin = (): number => {
+    const scrollElement = options.getScrollElement()
+    if (!scrollElement) {
+      return 0
+    }
+
+    const rect = scrollElement.getBoundingClientRect()
+    // scrollLeft stays a physical axis in every engine (RTL just runs it
+    // negative), so it enters the negated space through the sign.
+    return horizontal ?
+      logicalStart(rect) - (axisSign * scrollElement.scrollLeft) :
+      rect.top - scrollElement.scrollTop
+  }
+
+  const captureItem = (id: string, origin: number): boolean => {
+    const element = options.items.getElements(id)[0]
+    if (!element) {
+      return false
+    }
+
+    const rect = element.getBoundingClientRect()
+    // Corrected by the applied delta for items first seen mid-preview (a row
+    // revealed by auto-scroll); at drag start every delta is zero.
+    const start = logicalStart(rect) - (previewDeltas.get(id) ?? 0)
+    contentStarts.set(id, start - origin)
+    contentSizes.set(id, horizontal ? rect.width : rect.height)
+    return true
+  }
+
+  const captureLayout = () => {
+    contentStarts.clear()
+    contentSizes.clear()
+    const origin = contentOrigin()
+    for (const id of options.items.getOrderedIds()) {
+      captureItem(id, origin)
+    }
+  }
+
+  const updateTarget = () => {
+    const position = logicalPointer()
+    const origin = contentOrigin()
+
+    const zones: Array<{ id: string; start: number; size: number }> = []
+    for (const id of options.items.getOrderedIds()) {
+      if (!contentStarts.has(id) && !captureItem(id, origin)) {
+        continue
+      }
+
+      zones.push({ id, start: origin + contentStarts.get(id)!, size: contentSizes.get(id)! })
+    }
+
+    let hit: { id: string; after: boolean } | null = null
+    const lastZone = zones[zones.length - 1]
+    const fromIndex = zones.findIndex(zone => zone.id === sourceHit!.id)
+
+    if (lastZone && position > lastZone.start + lastZone.size) {
+      // Past the end there is no zone to be inside, but the intent could not
+      // be clearer: after the last item the source may land on. Same at the
+      // start edge below.
+      sticky = null
+      for (let index = zones.length - 1; index >= 0; index--) {
+        if (options.canDrop(sourceHit!.id, zones[index].id)) {
+          hit = { id: zones[index].id, after: true }
+          break
+        }
+      }
+    } else if (lastZone && position < zones[0].start) {
+      sticky = null
+      for (const zone of zones) {
+        if (options.canDrop(sourceHit!.id, zone.id)) {
+          hit = { id: zone.id, after: false }
+          break
+        }
+      }
+    } else if (drop && sticky && position >= sticky.lo - DRAG_HYSTERESIS && position <= sticky.hi + DRAG_HYSTERESIS) {
+      // Still inside (or barely past) the zone that produced the current
+      // drop — keep it, so boundary jitter cannot re-animate.
+      hit = drop
+    } else {
+      for (let index = 0; index < zones.length; index++) {
+        const zone = zones[index]
+        const previous = zones[index - 1]
+        const following = zones[index + 1]
+        // Zones TILE the axis: real tables have collapsed borders between the
+        // cells, and those few pixels belong to no rect. A pointer crossing
+        // such a gap used to hit nothing, which cleared the preview and
+        // re-applied it on the far side — replaying the slide right at the
+        // boundary. Each gap is split down its middle instead.
+        const lo = previous ? (previous.start + previous.size + zone.start) / 2 : zone.start
+        const hi = following ? (zone.start + zone.size + following.start) / 2 : zone.start + zone.size
+        if (position < lo || position > hi) {
+          continue
+        }
+
+        if (options.canDrop(sourceHit!.id, zone.id)) {
+          // Entering a neighbour's zone displaces it AT ONCE — the swap fires
+          // at the boundary, not at the neighbour's midpoint, which is the
+          // feel MUI and AG have and what a drag reads as: "I am past it, so
+          // it moves". The release then just commits whatever the preview
+          // shows.
+          hit = {
+            id: zone.id,
+            after: fromIndex === -1 ? position > zone.start + (zone.size / 2) : index > fromIndex
+          }
+          sticky = { lo, hi }
+        }
+
+        break
+      }
+    }
+
+    if (!hit) {
+      drop = null
+      sticky = null
+      hideIndicator()
+      applyPreview()
+      return
+    }
+
+    drop = hit
+    showIndicator(options.items.getElements(hit.id)[0], hit.after)
+    applyPreview()
+  }
+
+  const clearPreview = () => {
+    for (const id of previewClassed) {
+      for (const element of options.items.getElements(id)) {
+        element.style.transform = ''
+        element.classList.remove(CLASS_NAME_PREVIEW)
+      }
+    }
+
+    previewKey = ''
+    previewDeltas.clear()
+    previewClassed.clear()
+  }
+
+  const clearLayout = () => {
+    contentStarts.clear()
+    contentSizes.clear()
+  }
+
+  const applyPreview = () => {
+    if (!options.preview || !sourceHit) {
+      return
+    }
+
+    const ids = options.items.getOrderedIds()
+    const from = ids.indexOf(sourceHit.id)
+    const target = drop ? ids.indexOf(drop.id) : -1
+    const to = from === -1 || target === -1 ? from : destinationIndex(from, target, drop!.after)
+
+    // Keyed on the DESTINATION SLOT, not on the hit: two hits that resolve to
+    // the same slot (the clamp past the end vs the last zone, jitter inside
+    // the hysteresis band) must not rewrite anything. A clear-and-reapply of
+    // identical transforms next to a forced layout read restarts the running
+    // transition from zero — the mid-drag replay this file has already paid
+    // for once.
+    const key = String(to)
+    if (key === previewKey) {
+      return
+    }
+
+    previewKey = key
+
+    const next = new Map<string, number>()
+    if (from !== -1 && to !== from) {
+      // Sizes come from the drag-start snapshot: no DOM reads may happen in
+      // here, or they would flush layout between the transform writes below.
+      const sizeOf = (index: number): number => contentSizes.get(ids[index]) ?? 0
+      const forward = to > from
+      const first = forward ? from + 1 : to
+      const last = forward ? to : from - 1
+      const sourceSize = sizeOf(from)
+      let travelled = 0
+
+      for (let index = first; index <= last; index++) {
+        travelled += sizeOf(index)
+        next.set(ids[index], forward ? -sourceSize : sourceSize)
+      }
+
+      // The source moves by the combined size of everything it passed, so no
+      // gap opens anywhere and the axis keeps its total extent.
+      next.set(ids[from], forward ? travelled : -travelled)
+    }
+
+    // Only elements whose delta actually changed are touched; everything else
+    // keeps its running transition undisturbed. An un-shift keeps the
+    // transition class, so sliding back home animates exactly like sliding
+    // aside did — the class only comes off when the drag ends.
+    for (const id of previewDeltas.keys()) {
+      if (!next.has(id)) {
+        for (const element of options.items.getElements(id)) {
+          element.style.transform = ''
+        }
+      }
+    }
+
+    for (const [id, delta] of next) {
+      if (previewDeltas.get(id) === delta) {
+        continue
+      }
+
+      for (const element of options.items.getElements(id)) {
+        element.style.transform = horizontal ?
+          `translateX(${axisSign * delta}px)` :
+          `translateY(${delta}px)`
+        element.classList.add(CLASS_NAME_PREVIEW)
+      }
+
+      previewClassed.add(id)
+    }
+
+    previewDeltas.clear()
+    for (const [id, delta] of next) {
+      previewDeltas.set(id, delta)
+    }
+  }
+
+  // The gesture's closing beat: instead of vanishing at the pointer, the
+  // ghost flies to where the item landed (or back home on cancel) and fades
+  // out there. Purely cosmetic — the commit below never waits for it.
+  const settleGhost = (x: number, y: number) => {
+    if (!ghost) {
+      return
+    }
+
+    const element = ghost
+    // Taken out of cleanup's hands; it removes itself when the flight ends.
+    ghost = null
+    element.classList.add(CLASS_NAME_GHOST_SETTLE)
+    element.style.transform = `translate(${x}px, ${y}px)`
+    element.style.opacity = '0'
+
+    let settled = false
+    const finish = () => {
+      if (!settled) {
+        settled = true
+        element.remove()
+      }
+    }
+
+    element.addEventListener('transitionend', finish)
+    setTimeout(finish, GHOST_SETTLE_FALLBACK_MS)
+  }
+
+  // Where the ghost should land: the source's current visual position for a
+  // commit (the preview already put it in its slot), its untransformed home
+  // for a cancel (the preview is about to slide everything back there).
+  const settleTarget = (committed: boolean): { x: number; y: number } | null => {
+    if (!sourceHit) {
+      return null
+    }
+
+    const rect = sourceHit.element.getBoundingClientRect()
+    if (committed) {
+      return { x: rect.left, y: rect.top }
+    }
+
+    const delta = previewDeltas.get(sourceHit.id) ?? 0
+    return horizontal ?
+      { x: rect.left - (axisSign * delta), y: rect.top } :
+      { x: rect.left, y: rect.top - delta }
+  }
+
+  const cleanup = () => {
+    clearPreview()
+    clearLayout()
+    stopAutoScroll()
+    root.classList.remove(CLASS_NAME_DRAG_ACTIVE)
+    sourceHit?.element.classList.remove(CLASS_NAME_DRAGGING)
+    ghost?.remove()
+    indicator?.remove()
+    ghost = null
+    indicator = null
+    sourceHit = null
+    dragging = false
+    drop = null
+    sticky = null
+    pointerId = -1
+    document.removeEventListener('pointermove', onPointerMove)
+    document.removeEventListener('pointerup', onPointerUp)
+    document.removeEventListener('pointercancel', cancel)
+    document.removeEventListener('keydown', onKeydown)
+  }
+
+  function cancel() {
+    if (dragging) {
+      const home = settleTarget(false)
+      if (home) {
+        settleGhost(home.x, home.y)
+      }
+    }
+
+    cleanup()
+  }
+
+  function onKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      cancel()
+    }
+  }
+
+  function onPointerMove(event: PointerEvent) {
+    if (event.pointerId !== pointerId || !sourceHit) {
+      return
+    }
+
+    pointer = { x: event.clientX, y: event.clientY }
+
+    if (!dragging) {
+      const travelled = Math.max(Math.abs(pointer.x - origin.x), Math.abs(pointer.y - origin.y))
+      if (travelled < DRAG_THRESHOLD) {
+        return
+      }
+
+      startDrag()
+    }
+
+    // Suppresses the text selection a pointer drag would otherwise paint
+    // across the header or the rows.
+    event.preventDefault()
+    moveGhost()
+    updateTarget()
+
+    if (!scrollFrame) {
+      scrollFrame = requestAnimationFrame(autoScroll)
+    }
+  }
+
+  function onPointerUp(event: PointerEvent) {
+    if (event.pointerId !== pointerId) {
+      return
+    }
+
+    const sourceId = sourceHit?.id
+    const source = sourceHit?.element
+    const pending = drop
+    const wasDragging = dragging
+    if (wasDragging) {
+      const committed = Boolean(pending && pending.id !== sourceId)
+      const landing = settleTarget(committed)
+      if (landing) {
+        settleGhost(landing.x, landing.y)
+      }
+    }
+
+    cleanup()
+
+    if (!wasDragging) {
+      return
+    }
+
+    // A drag that ends on the element it started from is still followed by a
+    // click there — which on a header cell would toggle the sort. Swallow
+    // exactly that one. Releasing anywhere else fires the click on the common
+    // ancestor instead (never the sort button), so arming there would only
+    // risk eating an unrelated click; the 0 ms disarm covers the rest.
+    if (source?.contains(event.target as Node)) {
+      document.addEventListener('click', swallowClick, { capture: true, once: true })
+      setTimeout(disarmSwallowClick, 0)
+    }
+
+    if (sourceId && pending && pending.id !== sourceId) {
+      options.onDrop(sourceId, pending)
+    }
+  }
+
+  const onPointerDown = (event: PointerEvent) => {
+    // Primary button / single touch only — a right-click or a second finger
+    // must not start a reorder.
+    if (!event.isPrimary || (event.pointerType === 'mouse' && event.button !== 0) || sourceHit) {
+      return
+    }
+
+    const element = (event.target as HTMLElement | null)?.closest<HTMLElement>(options.handle)
+    if (!element) {
+      return
+    }
+
+    const hit = options.resolveSource(element, event.target as HTMLElement)
+    if (!hit) {
+      return
+    }
+
+    sourceHit = hit
+    pointerId = event.pointerId
+    origin = { x: event.clientX, y: event.clientY }
+    pointer = origin
+
+    document.addEventListener('pointermove', onPointerMove)
+    document.addEventListener('pointerup', onPointerUp)
+    document.addEventListener('pointercancel', cancel)
+    document.addEventListener('keydown', onKeydown)
+  }
+
+  root.addEventListener('pointerdown', onPointerDown)
+
+  return {
+    dispose() {
+      root.removeEventListener('pointerdown', onPointerDown)
+      disarmSwallowClick()
+      cleanup()
+    }
+  }
+}
+
+const SELECTOR_DRAGGABLE_COLUMN = 'th[data-coreui-draggable]'
+const SELECTOR_RESIZER = '[data-coreui-resizer]'
+// Spacer and empty rows have a single colSpan cell, so a positional lookup
+// would land on the wrong thing.
+const SELECTOR_PREVIEW_ROWS = 'thead tr, tbody tr:not(.data-grid-spacer):not(.data-grid-empty)'
+
+// A column's cells are found by POSITION, not by a data attribute: the body
+// only marks `data-coreui-column` when cellNavigation is on, while the header
+// always does — so the header cell's index is the reliable way in, and it
+// already accounts for the leading handle and select columns.
+const columnItems = (root: HTMLElement): DragItems => ({
+  getOrderedIds: () =>
+    [...root.querySelectorAll<HTMLTableCellElement>('thead tr:first-child th[data-coreui-column]')]
+      .map(cell => cell.dataset.coreuiColumn ?? ''),
+  getElements(id) {
+    const header = root.querySelector<HTMLTableCellElement>(`thead th[data-coreui-column="${id}"]`)
+    if (!header) {
+      return []
+    }
+
+    const { cellIndex } = header
+    const elements: HTMLElement[] = []
+    for (const row of root.querySelectorAll<HTMLTableRowElement>(SELECTOR_PREVIEW_ROWS)) {
+      const cell = row.children[cellIndex] as HTMLElement | undefined
+      if (cell) {
+        elements.push(cell)
+      }
+    }
+
+    return elements
+  }
+})
+
+export interface ColumnDragOptions {
+  root: HTMLElement
+  getScrollElement: () => HTMLElement | null
+  // Vetoes a target: the source itself, or a column in another pinned region —
+  // reordering never crosses a pinning boundary.
+  canDrop: (sourceKey: string, targetKey: string) => boolean
+  onReorder: (sourceKey: string, targetKey: string, after: boolean) => void
+}
+
+// The column half of the wiring, shared so each edition's adapter is the four
+// lines that resolve its own table rather than a copy of the drag setup.
+export const createColumnDragController = (options: ColumnDragOptions): DragController =>
+  createDragController({
+    axis: 'x',
+    root: options.root,
+    handle: SELECTOR_DRAGGABLE_COLUMN,
+    getScrollElement: options.getScrollElement,
+    resolveSource(element, target) {
+      // A press on the resize handle is a resize, not a reorder.
+      if (target.closest(SELECTOR_RESIZER)) {
+        return null
+      }
+
+      const id = element.dataset.coreuiColumn
+      return id ? { id, element } : null
+    },
+    items: columnItems(options.root),
+    // Only a column the header marks as draggable is a slot, on top of the
+    // consumer's own veto — an immovable column is not somewhere to land.
+    canDrop: (sourceId, targetId) =>
+      sourceId !== targetId &&
+      Boolean(options.root.querySelector(`th[data-coreui-column="${targetId}"][data-coreui-draggable]`)) &&
+      options.canDrop(sourceId, targetId),
+    preview: true,
+    onDrop: (sourceKey, drop) => options.onReorder(sourceKey, drop.id, drop.after)
+  })
+
+const SELECTOR_ROW_HANDLE = '[data-coreui-row-handle]'
+const SELECTOR_ROW = 'tr[data-coreui-index]'
+
+const rowItems = (root: HTMLElement): DragItems => ({
+  getOrderedIds: () =>
+    [...root.querySelectorAll<HTMLElement>(`tbody ${SELECTOR_ROW}`)].map(row => row.dataset.coreuiIndex ?? ''),
+  getElements(id) {
+    const row = root.querySelector<HTMLElement>(`tbody tr[data-coreui-index="${id}"]`)
+    return row ? [row] : []
+  }
+})
+
+export interface RowDragOptions {
+  root: HTMLElement
+  getScrollElement: () => HTMLElement | null
+  onReorder: (sourceIndex: number, targetIndex: number, after: boolean) => void
+}
+
+// The row half. Unlike columns, the whole row travels but only the grip cell
+// starts the drag — a row is covered in interactive content (checkboxes,
+// editors, custom cells) that a whole-row handle would swallow.
+export const createRowDragController = (options: RowDragOptions): DragController =>
+  createDragController({
+    axis: 'y',
+    root: options.root,
+    handle: SELECTOR_ROW_HANDLE,
+    getScrollElement: options.getScrollElement,
+    resolveSource(handle) {
+      const row = handle.closest<HTMLElement>(SELECTOR_ROW)
+      const id = row?.dataset.coreuiIndex
+      return row && id ? { id, element: row } : null
+    },
+    items: rowItems(options.root),
+    canDrop: (sourceId, targetId) => sourceId !== targetId,
+    // The row's own text is every cell run together; the first data cell reads
+    // as the row's name in practice.
+    // The row's own text is every cell run together, so the ghost carries the
+    // first DATA cell instead — found by skipping the leading handle and
+    // select cells rather than by data-coreui-column, which the body only
+    // carries when cellNavigation is on (without it the ghost came up empty).
+    ghostLabel: source =>
+      collapse(
+        source.element.querySelector(
+          'td:not(.data-grid-row-handle-cell):not(.data-grid-select-cell)'
+        )?.textContent ?? ''
+      ),
+    preview: true,
+    onDrop: (sourceId, drop) => options.onReorder(Number(sourceId), Number(drop.id), drop.after)
+  })