@flamingo-stack/openframe-frontend-core 0.0.556 → 0.0.557-1828.4873.1

package/dist/utils/drag-effect.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Holds a native drag started from `element` to the "move" effect, from its very
+ * first frame.
+ *
+ * The browser picks the drag cursor from `dataTransfer.dropEffect`, and the
+ * value it starts each drag with comes from `effectAllowed`. Pragmatic never
+ * writes `effectAllowed`, so it stays `uninitialized` — which the browser reads
+ * as "all", whose initial `dropEffect` is `copy`. That is the green plus cursor
+ * flashing for one frame at the start of every drag, before the first `dragover`
+ * has had a chance to say otherwise.
+ *
+ * This is a raw listener rather than a Pragmatic callback because `effectAllowed`
+ * can only be written during the `dragstart` event itself, and none of
+ * Pragmatic's callbacks are handed the event.
+ *
+ * Distinct from `preventUnhandled`, which answers the other half of the same
+ * question: this sets what the drag starts as, that keeps it from falling back
+ * to "no drop" over everything that is not a drop target.
+ */
+export declare function holdMoveDragEffect(element: HTMLElement): () => void;
+//# sourceMappingURL=drag-effect.d.ts.map

package/dist/utils/drag-effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag-effect.d.ts","sourceRoot":"","sources":["../../src/utils/drag-effect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,IAAI,CAMnE"}

package/dist/utils/scroll-parent.d.ts

@@ -0,0 +1,11 @@
+/** Every scrollable ancestor of `element`, innermost first. */
+export declare function scrollableAncestorsOf(element: HTMLElement): HTMLElement[];
+/**
+ * The nearest scrollable ancestor, or `null`.
+ *
+ * Stands in for "the working area this thing lives in": in an app whose layout
+ * scrolls a `<main>` rather than the document, that element is exactly the
+ * region a user considers to be the page.
+ */
+export declare function nearestScrollableAncestor(element: HTMLElement): HTMLElement | null;
+//# sourceMappingURL=scroll-parent.d.ts.map

package/dist/utils/scroll-parent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-parent.d.ts","sourceRoot":"","sources":["../../src/utils/scroll-parent.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,EAAE,CAOzE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,IAAI,CAElF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flamingo-stack/openframe-frontend-core",
-  "version": "0.0.556",
+  "version": "0.0.557-1828.4873.1",
   "description": "Shared design system and components for all Flamingo platforms",
   "type": "module",
   "main": "./dist/index.js",
@@ -321,6 +321,9 @@
     }
   },
   "dependencies": {
+    "@atlaskit/pragmatic-drag-and-drop": "^3.0.0",
+    "@atlaskit/pragmatic-drag-and-drop-auto-scroll": "^3.0.1",
+    "@atlaskit/pragmatic-drag-and-drop-hitbox": "^2.1.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -379,6 +382,7 @@
     "react-easy-crop": "^5.5.0",
     "react-hook-form": "^7.62.0",
     "react-markdown": "^10.1.0",
+    "react-remove-scroll": "^2.7.1",
     "react-resizable-panels": "^3.0.4",
     "react-scroll": "^1.9.0",
     "recharts": "^3.1.0",
@@ -393,8 +397,7 @@
     "tailwindcss-animate": "^1.0.7",
     "unist-util-visit": "^5.0.0",
     "use-stick-to-bottom": "^1.1.4",
-    "vaul": "^1.1.2",
-    "react-remove-scroll": "^2.7.1"
+    "vaul": "^1.1.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",

package/src/__tests__/board-aim.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest'
+import { attachClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge'
+import { aimAnchor, aimFromTarget, aimToChange, initialAim, moveAim } from '../components/features/board/aim'
+import type { BoardColumnDef } from '../components/features/board/types'
+
+const ticket = (id: string) => ({ id, title: id, ticketNumber: `#${id}`, status: 'open' })
+
+const COLUMNS: BoardColumnDef[] = [
+  { id: 'open', label: 'Open', color: '#5ea700', tickets: ['a1', 'a2', 'a3'].map(ticket) },
+  { id: 'locked', label: 'Locked', color: '#888888', tickets: ['c1'].map(ticket), dropDisabled: true },
+  { id: 'done', label: 'Done', color: '#1f6feb', tickets: ['b1', 'b2'].map(ticket) },
+  { id: 'empty', label: 'Empty', color: '#333333', tickets: [] },
+]
+
+const accepts = (column: BoardColumnDef) => !column.dropDisabled
+
+describe('initialAim', () => {
+  it('starts a card exactly where it already sits', () => {
+    expect(initialAim(COLUMNS, 'a2')).toEqual({ columnId: 'open', index: 1 })
+  })
+
+  it('has nowhere to start from for a card that is on no lane', () => {
+    expect(initialAim(COLUMNS, 'nope')).toBeNull()
+  })
+})
+
+describe('moveAim', () => {
+  const aim = { columnId: 'open', index: 1 }
+
+  it('steps through slots with up and down', () => {
+    expect(moveAim(COLUMNS, 'a2', aim, 'ArrowUp', accepts)).toEqual({ columnId: 'open', index: 0 })
+    expect(moveAim(COLUMNS, 'a2', aim, 'ArrowDown', accepts)).toEqual({ columnId: 'open', index: 2 })
+  })
+
+  // The dragged card is not among the slots it can take, so a lane of three has
+  // three landing places for it, not four.
+  it('stops at the ends of a lane', () => {
+    expect(moveAim(COLUMNS, 'a2', { columnId: 'open', index: 0 }, 'ArrowUp', accepts)).toEqual({
+      columnId: 'open',
+      index: 0,
+    })
+    expect(moveAim(COLUMNS, 'a2', { columnId: 'open', index: 2 }, 'ArrowDown', accepts)).toEqual({
+      columnId: 'open',
+      index: 2,
+    })
+  })
+
+  it('skips a lane that will not take the card rather than stopping at it', () => {
+    expect(moveAim(COLUMNS, 'a2', aim, 'ArrowRight', accepts)).toEqual({ columnId: 'done', index: 1 })
+  })
+
+  it('keeps the slot it had, as far as the new lane allows', () => {
+    expect(moveAim(COLUMNS, 'a2', { columnId: 'open', index: 2 }, 'ArrowRight', accepts)).toEqual({
+      columnId: 'done',
+      index: 2,
+    })
+    expect(moveAim(COLUMNS, 'a2', { columnId: 'done', index: 2 }, 'ArrowRight', accepts)).toEqual({
+      columnId: 'empty',
+      index: 0,
+    })
+  })
+
+  it('stays put at the ends of the board', () => {
+    const first = { columnId: 'open', index: 1 }
+    expect(moveAim(COLUMNS, 'a2', first, 'ArrowLeft', accepts)).toBe(first)
+    const last = { columnId: 'empty', index: 0 }
+    expect(moveAim(COLUMNS, 'a2', last, 'ArrowRight', accepts)).toBe(last)
+  })
+})
+
+describe('aimFromTarget', () => {
+  const overCard = (ticketId: string, columnId: string, edge: 'top' | 'bottom') => {
+    const element = {
+      getBoundingClientRect: () => ({ top: 0, left: 0, right: 300, bottom: 100, width: 300, height: 100, x: 0, y: 0 }),
+    } as unknown as Element
+    return attachClosestEdge(
+      { type: 'ticket', ticketId, columnId },
+      { input: { clientX: 150, clientY: edge === 'top' ? 5 : 95 } as never, element, allowedEdges: ['top', 'bottom'] },
+    )
+  }
+
+  // The flicker this exists to stop: a hit test answers with whichever card the
+  // pointer happens to be over, so ONE landing place arrives as "below a3" one
+  // frame and "above b-nothing" the next. As an index they are the same slot, so
+  // the line has one position to be drawn at instead of two to jump between.
+  it('reads the same slot from either side of one boundary', () => {
+    const below = aimFromTarget(COLUMNS, 'a2', overCard('a1', 'open', 'bottom'))
+    const above = aimFromTarget(COLUMNS, 'a2', overCard('a3', 'open', 'top'))
+    expect(below).toEqual(above)
+  })
+
+  it('counts slots among the other cards, never the one being moved', () => {
+    expect(aimFromTarget(COLUMNS, 'a2', overCard('a3', 'open', 'bottom'))).toEqual({ columnId: 'open', index: 2 })
+    expect(aimFromTarget(COLUMNS, 'a2', overCard('a1', 'open', 'top'))).toEqual({ columnId: 'open', index: 0 })
+  })
+
+  it('reads a lane target as past the last card', () => {
+    expect(aimFromTarget(COLUMNS, 'a2', { type: 'column', columnId: 'done' })).toEqual({ columnId: 'done', index: 2 })
+  })
+
+  it('has no answer for a lane the board does not have', () => {
+    expect(aimFromTarget(COLUMNS, 'a2', { type: 'column', columnId: 'gone' })).toBeNull()
+  })
+})
+
+describe('aimAnchor', () => {
+  it('hangs the preview above the card it would push down', () => {
+    expect(aimAnchor(COLUMNS, 'a2', { columnId: 'open', index: 0 })).toEqual({ ticketId: 'a1', edge: 'top' })
+  })
+
+  it('hangs it below the last card when it would land at the end', () => {
+    expect(aimAnchor(COLUMNS, 'a2', { columnId: 'open', index: 2 })).toEqual({ ticketId: 'a3', edge: 'bottom' })
+  })
+
+  it('has nothing to hang off in an empty lane', () => {
+    expect(aimAnchor(COLUMNS, 'a2', { columnId: 'empty', index: 0 })).toEqual({ ticketId: null, edge: null })
+  })
+})
+
+describe('aimToChange', () => {
+  it('reports nothing when the card would land back where it started', () => {
+    expect(aimToChange(COLUMNS, 'a2', { columnId: 'open', index: 1 })).toBeNull()
+  })
+
+  it('reports a move within one lane', () => {
+    expect(aimToChange(COLUMNS, 'a2', { columnId: 'open', index: 0 })).toEqual({
+      ticketId: 'a2',
+      fromColumnId: 'open',
+      toColumnId: 'open',
+      afterTicketId: null,
+      beforeTicketId: 'a1',
+    })
+  })
+
+  it('reports a move to another lane', () => {
+    expect(aimToChange(COLUMNS, 'a2', { columnId: 'done', index: 1 })).toEqual({
+      ticketId: 'a2',
+      fromColumnId: 'open',
+      toColumnId: 'done',
+      afterTicketId: 'b1',
+      beforeTicketId: 'b2',
+    })
+  })
+
+  it('reports a move into an empty lane', () => {
+    expect(aimToChange(COLUMNS, 'a2', { columnId: 'empty', index: 0 })).toMatchObject({
+      toColumnId: 'empty',
+      afterTicketId: null,
+      beforeTicketId: null,
+    })
+  })
+})

package/src/__tests__/board-pending-move.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from 'vitest'
+import { applyPendingMove, hasMoveSettled, type PendingMove } from '../components/features/board/pending-move'
+import type { BoardColumnDef } from '../components/features/board/types'
+
+const ticket = (id: string) => ({ id, title: id, ticketNumber: `#${id}`, status: 'open' })
+
+const columns = (open: string[], done: string[]): BoardColumnDef[] => [
+  { id: 'open', label: 'Open', color: '#5ea700', tickets: open.map(ticket) },
+  { id: 'done', label: 'Done', color: '#1f6feb', tickets: done.map(ticket) },
+]
+
+/** `a2` was dragged out of Open and dropped into Done, straight after `b1`. */
+const MOVE: PendingMove = { ticketId: 'a2', fromColumnId: 'open', toColumnId: 'done', afterTicketId: 'b1' }
+
+describe('hasMoveSettled', () => {
+  it('is unsettled while the card is still in the lane it came from', () => {
+    expect(hasMoveSettled(columns(['a1', 'a2', 'a3'], ['b1', 'b2']), MOVE)).toBe(false)
+  })
+
+  it('settles when the card turns up exactly where it was dropped', () => {
+    expect(hasMoveSettled(columns(['a1', 'a3'], ['b1', 'a2', 'b2']), MOVE)).toBe(true)
+  })
+
+  // The failure this test exists for: each lane polls on its own timer and takes
+  // live updates, so the lane a card came FROM changes for reasons that have
+  // nothing to do with the move. Reading any of that as "landed" uncovers the
+  // card in its old place — the flash the whole mechanism exists to remove.
+  it('stays unsettled when the lane it came from changes for unrelated reasons', () => {
+    expect(hasMoveSettled(columns(['a0', 'a1', 'a2', 'a3'], ['b1', 'b2']), MOVE)).toBe(false)
+    expect(hasMoveSettled(columns(['a2'], ['b1', 'b2']), MOVE)).toBe(false)
+  })
+
+  // A server free to sort the destination lane its own way will never reproduce
+  // the dropped index. Holding out for one it will not send means the board
+  // shows a position it has already been told is wrong, until the timeout jerks
+  // it into place seconds later.
+  it('settles anywhere in the new lane once the old one has let go', () => {
+    expect(hasMoveSettled(columns(['a1', 'a3'], ['a2', 'b1', 'b2']), MOVE)).toBe(true)
+    expect(hasMoveSettled(columns(['a1', 'a3'], ['b1', 'b2', 'a2']), MOVE)).toBe(true)
+  })
+
+  // The two lanes are separate queries and answer at their own pace. Handing
+  // back while both still list the card shows it in two places at once.
+  it('stays unsettled while both lanes still list the card', () => {
+    expect(hasMoveSettled(columns(['a1', 'a2', 'a3'], ['b1', 'a2', 'b2']), MOVE)).toBe(false)
+  })
+
+  it('recognises a drop at the head of a lane', () => {
+    const toHead: PendingMove = { ticketId: 'a2', fromColumnId: 'open', toColumnId: 'done', afterTicketId: null }
+    expect(hasMoveSettled(columns(['a1', 'a3'], ['a2', 'b1']), toHead)).toBe(true)
+  })
+
+  // Within one lane the card is in that lane whether the move landed or not, so
+  // here the exact slot is the only thing that can answer.
+  it('holds a reorder inside one lane to the exact slot', () => {
+    const withinLane: PendingMove = { ticketId: 'a1', fromColumnId: 'open', toColumnId: 'open', afterTicketId: 'a2' }
+    expect(hasMoveSettled(columns(['a1', 'a2', 'a3'], []), withinLane)).toBe(false)
+    expect(hasMoveSettled(columns(['a2', 'a1', 'a3'], []), withinLane)).toBe(true)
+  })
+
+  it('is unsettled when the lane it was dropped into is gone', () => {
+    expect(hasMoveSettled([{ id: 'open', label: 'Open', color: '#5ea700', tickets: [] }], MOVE)).toBe(false)
+  })
+})
+
+describe('applyPendingMove', () => {
+  it('shows the card in the lane it was dropped into, in the slot it was dropped in', () => {
+    const moved = applyPendingMove(columns(['a1', 'a2', 'a3'], ['b1', 'b2']), MOVE)
+    expect(moved[0].tickets.map(t => t.id)).toEqual(['a1', 'a3'])
+    expect(moved[1].tickets.map(t => t.id)).toEqual(['b1', 'a2', 'b2'])
+  })
+
+  it('drops the card at the head of the lane', () => {
+    const toHead: PendingMove = { ticketId: 'a2', fromColumnId: 'open', toColumnId: 'done', afterTicketId: null }
+    const moved = applyPendingMove(columns(['a1', 'a2'], ['b1']), toHead)
+    expect(moved[1].tickets.map(t => t.id)).toEqual(['a2', 'b1'])
+  })
+
+  it('reorders inside one lane', () => {
+    const within: PendingMove = { ticketId: 'a1', fromColumnId: 'open', toColumnId: 'open', afterTicketId: 'a3' }
+    const moved = applyPendingMove(columns(['a1', 'a2', 'a3'], []), within)
+    expect(moved[0].tickets.map(t => t.id)).toEqual(['a2', 'a3', 'a1'])
+  })
+
+  // The whole point of the optimistic view: once the host agrees, applying the
+  // move to its answer has to be a no-op, or handing back would move the card
+  // a second time.
+  it('is idempotent once the host has caught up', () => {
+    const settled = columns(['a1', 'a3'], ['b1', 'a2', 'b2'])
+    expect(hasMoveSettled(settled, MOVE)).toBe(true)
+    const moved = applyPendingMove(settled, MOVE)
+    expect(moved[0].tickets.map(t => t.id)).toEqual(['a1', 'a3'])
+    expect(moved[1].tickets.map(t => t.id)).toEqual(['b1', 'a2', 'b2'])
+  })
+
+  it('appends when the card it was dropped after is gone', () => {
+    const moved = applyPendingMove(columns(['a1', 'a2'], ['b2']), MOVE)
+    expect(moved[1].tickets.map(t => t.id)).toEqual(['b2', 'a2'])
+  })
+
+  it('leaves untouched lanes identical, so memoized lanes can skip the render', () => {
+    const before = columns(['a1', 'a2'], ['b1'])
+    const extra = [...before, { id: 'cold', label: 'Cold', color: '#333', tickets: [ticket('c1')] }]
+    const moved = applyPendingMove(extra, MOVE)
+    expect(moved[2]).toBe(extra[2])
+  })
+
+  it('changes nothing when the card or the lane is unknown', () => {
+    const before = columns(['a1'], ['b1'])
+    expect(applyPendingMove(before, { ...MOVE, ticketId: 'ghost' })).toBe(before)
+    expect(applyPendingMove(before, { ...MOVE, toColumnId: 'ghost' })).toBe(before)
+  })
+})

package/src/__tests__/board-resolve-drop.test.ts

@@ -0,0 +1,68 @@
+import { attachClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge'
+import { describe, expect, it } from 'vitest'
+import { resolveBoardDrop } from '../components/features/board/resolve-drop'
+import type { BoardColumnDef } from '../components/features/board/types'
+
+const ticket = (id: string) => ({ id, title: id, ticketNumber: `#${id}`, status: 'open' })
+
+const COLUMNS: BoardColumnDef[] = [
+  { id: 'open', label: 'Open', color: '#5ea700', tickets: ['a1', 'a2', 'a3'].map(ticket) },
+  { id: 'done', label: 'Done', color: '#1f6feb', tickets: ['b1', 'b2'].map(ticket) },
+]
+
+/** A card drop target, with the edge attached the way the hitbox does it. */
+function overCard(ticketId: string, columnId: string, edge: 'top' | 'bottom') {
+  const height = 100
+  const top = edge === 'top' ? 0 : 0
+  const element = {
+    getBoundingClientRect: () => ({ top, left: 0, right: 300, bottom: top + height, width: 300, height, x: 0, y: top }),
+  } as unknown as Element
+  return attachClosestEdge(
+    { type: 'ticket', ticketId, columnId },
+    // A pointer near the top of the box resolves to 'top', near the bottom to
+    // 'bottom' — that is the hitbox's own rule, so the fixture uses it rather
+    // than hand-writing the symbol it stores the edge under.
+    { input: { clientX: 150, clientY: edge === 'top' ? top + 5 : top + height - 5 } as never, element, allowedEdges: ['top', 'bottom'] },
+  )
+}
+
+const overLane = (columnId: string) => ({ type: 'column', columnId })
+const dragging = (ticketId: string, columnId: string) => ({ type: 'ticket', ticketId, columnId })
+
+describe('resolveBoardDrop', () => {
+  it('reports nothing when the card is released outside every target', () => {
+    expect(resolveBoardDrop(COLUMNS, { source: dragging('a1', 'open'), target: undefined })).toBeNull()
+  })
+
+  it('lands above the card whose top edge is closest', () => {
+    const change = resolveBoardDrop(COLUMNS, { source: dragging('a1', 'open'), target: overCard('b2', 'done', 'top') })
+    expect(change).toMatchObject({ toColumnId: 'done', afterTicketId: 'b1', beforeTicketId: 'b2' })
+  })
+
+  it('lands below the card whose bottom edge is closest', () => {
+    const change = resolveBoardDrop(COLUMNS, { source: dragging('a1', 'open'), target: overCard('b1', 'done', 'bottom') })
+    expect(change).toMatchObject({ toColumnId: 'done', afterTicketId: 'b1', beforeTicketId: 'b2' })
+  })
+
+  it('appends when the card is dropped on the lane rather than on a card', () => {
+    const change = resolveBoardDrop(COLUMNS, { source: dragging('a1', 'open'), target: overLane('done') })
+    expect(change).toMatchObject({ toColumnId: 'done', afterTicketId: 'b2', beforeTicketId: null })
+  })
+
+  it('does not count the dragged card as its own neighbour', () => {
+    // Moving a1 below a2 within its own lane: if a1 were still in the list, the
+    // neighbour would come out as a1 itself and the move would be a no-op.
+    const change = resolveBoardDrop(COLUMNS, { source: dragging('a1', 'open'), target: overCard('a2', 'open', 'bottom') })
+    expect(change).toMatchObject({ afterTicketId: 'a2', beforeTicketId: 'a3' })
+  })
+
+  it('reports nothing when the card is dropped back where it already was', () => {
+    // a2 released just below a1 — exactly its current slot.
+    expect(resolveBoardDrop(COLUMNS, { source: dragging('a2', 'open'), target: overCard('a1', 'open', 'bottom') })).toBeNull()
+  })
+
+  it('treats a drop on the first card top edge as the head of the lane', () => {
+    const change = resolveBoardDrop(COLUMNS, { source: dragging('a1', 'open'), target: overCard('b1', 'done', 'top') })
+    expect(change).toMatchObject({ afterTicketId: null, beforeTicketId: 'b1' })
+  })
+})

package/src/__tests__/sortable-slot-geometry.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import { type DragSlots, resolveSlot, shiftFor } from '../components/features/sortable-list/slot-geometry'
+
+// Four items of different heights, 24px apart — mixed heights on purpose, since
+// that is where "nearest neighbour's centre" and "nearest resting place" differ.
+const HEIGHTS = [50, 70, 90, 60]
+const GAP = 24
+
+const TOPS = [0, 74, 168, 282]
+const BOTTOMS = [50, 144, 258, 342]
+
+const slotsFor = (from: number): DragSlots => ({
+  tops: TOPS,
+  bottoms: BOTTOMS,
+  height: HEIGHTS[from],
+  from,
+  step: HEIGHTS[from] + GAP,
+})
+
+/**
+ * The first offset, walking from `start` in `direction`, at which the held slot
+ * changes. `start` matters: the return boundary has to be walked back from where
+ * the item actually IS once it holds the new slot, not from zero.
+ */
+function boundary(slots: DragSlots, held: number, direction: 1 | -1, start = 0): number {
+  for (let offset = start; Math.abs(offset) <= 600; offset += direction) {
+    if (resolveSlot(slots, held, offset) !== held) return offset
+  }
+  throw new Error('no boundary found')
+}
+
+describe('resolveSlot', () => {
+  const slots = slotsFor(0)
+
+  it('holds its own slot until the item has travelled half a slot', () => {
+    expect(resolveSlot(slots, 0, 0)).toBe(0)
+    expect(resolveSlot(slots, 0, 40)).toBe(0)
+    expect(resolveSlot(slots, 0, 80)).toBe(1)
+  })
+
+  it('walks a slot at a time rather than jumping to the end', () => {
+    expect(resolveSlot(slots, 1, 160)).toBe(1)
+    expect(resolveSlot(slots, 1, 200)).toBe(2)
+    expect(resolveSlot(slots, 2, 300)).toBe(3)
+  })
+
+  // The complaint this exists to answer: without the handicap the item ends up
+  // sitting exactly ON the boundary it just crossed, so leaving a slot costs
+  // half an item of dragging and coming back costs a pixel.
+  it('costs the same movement to leave a slot and to come back', () => {
+    const out = boundary(slots, 0, 1)
+    const back = boundary(slots, 1, -1, out)
+    expect(out).toBeGreaterThan(back)
+
+    // Both sit the same distance either side of the midpoint between the two
+    // resting places — 25 and 119 here, so 72, i.e. an offset of 47.
+    const midpoint = 47
+    expect(out - midpoint).toBeCloseTo(midpoint - back, 0)
+  })
+
+  it('measures against resting places, not the neighbours own centres', () => {
+    // Landing at index 1 puts a 50px item against item 1's BOTTOM edge (144),
+    // i.e. centred at 119 — not at item 1's own centre of 109.
+    expect(resolveSlot(slots, 0, 94)).toBe(1)
+    expect(resolveSlot(slots, 1, 94)).toBe(1)
+  })
+
+  it('is symmetric for a drag that starts at the end of the list', () => {
+    const fromLast = slotsFor(3)
+    expect(resolveSlot(fromLast, 3, 0)).toBe(3)
+    expect(resolveSlot(fromLast, 3, -120)).toBe(2)
+    expect(resolveSlot(fromLast, 2, -10)).toBe(3)
+  })
+})
+
+describe('shiftFor', () => {
+  it('stands the passed items aside by exactly one slot', () => {
+    const slots = slotsFor(0)
+    expect(shiftFor(slots, 0, 2)).toBe(0)
+    expect(shiftFor(slots, 1, 2)).toBe(-slots.step)
+    expect(shiftFor(slots, 2, 2)).toBe(-slots.step)
+    expect(shiftFor(slots, 3, 2)).toBe(0)
+  })
+
+  it('pushes the other way when the item is dragged upwards', () => {
+    const slots = slotsFor(3)
+    expect(shiftFor(slots, 3, 1)).toBe(0)
+    expect(shiftFor(slots, 2, 1)).toBe(slots.step)
+    expect(shiftFor(slots, 1, 1)).toBe(slots.step)
+    expect(shiftFor(slots, 0, 1)).toBe(0)
+  })
+
+  it('moves nothing while the drop is still aimed at the slot it came from', () => {
+    const slots = slotsFor(1)
+    expect([0, 1, 2, 3].map(index => shiftFor(slots, index, 1))).toEqual([0, 0, 0, 0])
+  })
+
+  // Every displaced item travels the same distance whatever its own height:
+  // removing the item from one slot and inserting it at another moves each item
+  // in between by exactly the dragged item's height plus the gap.
+  it('travels the dragged items height regardless of the displaced items own', () => {
+    const slots = slotsFor(0)
+    expect(new Set([1, 2, 3].map(index => shiftFor(slots, index, 3))).size).toBe(1)
+  })
+})

package/src/components/features/board/.board-column.md

@@ -7,13 +7,26 @@ A kanban-style board column component with drag-and-drop support, infinite scrol
 The primary column container. Renders a collapsible column with a header, divider, and body. Supports visual joining with adjacent columns via `joinLeft`/`joinRight` props and applies tinted background colors for non-system columns.
 
 ### `ColumnBody` (internal)
-Handles the droppable zone (`@dnd-kit/core`), sortable ticket list (`@dnd-kit/sortable`), and infinite scroll via `IntersectionObserver`. Manages refs for both the scroll container and the droppable drop target.
+Handles the lane-wide drop target, drag auto-scroll, and infinite scroll via `IntersectionObserver`.
+
+Each card is a drop target in its own right and is reported ahead of the lane, so the lane only ever
+answers for the gaps between them — and it answers with the **nearest card and the edge of it the
+pointer is on**, exactly as that card would have. Reporting a bare lane there sent the ticket to the
+BOTTOM of the column, which made small moves look like they had not registered and large ones like
+the only thing that worked.
+
+Auto-scroll on the lane is `autoScrollColumn`: vertical-only overflow reach, so a pointer carried
+below the board scrolls exactly the one lane it is under — a reach that also spread sideways put
+that pointer inside every lane's region at once and scrolled them all. The page's own scrollers are
+registered once by the board, not per lane. The lane body reserves a `py-[5px]` sliver so the
+insertion line is not clipped at the first and last card.
 
 ### `SkeletonStack` (internal)
 Renders a configurable number of `TicketCardSkeleton` placeholders during initial load.
 
 ### `EmptyState` (internal)
-Displays a centered empty state with a tag icon when a column has no tickets.
+Displays a centered empty state with a tag icon when a column has no tickets — and carries the
+insertion line when a drop is aimed at the empty lane, since there is no card to hang it off.
 
 ## Key Props (`BoardColumnProps`)
 
@@ -21,7 +34,7 @@ Displays a centered empty state with a tag icon when a column has no tickets.
 |---|---|---|
 | `column` | `BoardColumnDef` | Column definition including tickets, color, and state flags |
 | `collapsed` | `boolean` | Collapses column to `w-14` |
-| `onToggleCollapse` | `() => void` | Toggle handler |
+| `onToggleCollapse` | `(columnId: string) => void` | Toggle handler — takes the id so one stable handler can serve every lane |
 | `onLoadMore` | `(columnId: string) => void` | Triggered by intersection sentinel |
 | `joinLeft` / `joinRight` | `boolean` | Removes borders/radius for adjacent column groups |
 | `renderAssignSlot` | `(ticket: BoardTicket) => ReactNode` | Custom assignee slot renderer |
@@ -32,7 +45,7 @@ Displays a centered empty state with a tag icon when a column has no tickets.
 <BoardColumn
   column={column}
   collapsed={false}
-  onToggleCollapse={() => setCollapsed(id, !collapsed)}
+  onToggleCollapse={toggle}
   onAddTicket={(colId) => openNewTicketModal(colId)}
   getTicketHref={(ticketId) => `/tickets/${ticketId}`}
   renderAssignSlot={(ticket) => <AvatarPicker ticket={ticket} />}

package/src/components/features/board/.board.md

@@ -1,22 +1,26 @@
 <!-- source-hash: eec2d729297b9f5f1be4e627c13aa43f -->
-Kanban-style drag-and-drop board component built on `@dnd-kit/core`, managing multi-column ticket reordering with cross-column movement, collapse state, and a custom horizontal scrollbar.
+Kanban-style drag-and-drop board built on Pragmatic drag and drop, managing multi-column ticket reordering with cross-column movement, collapse state, and a custom horizontal scrollbar. The board holds no copy of `columns` and changes no state during a drag: a single `monitorForElements` turns the drop into one `onChange`.
 
 ## Key Components
 
 | Export | Description |
 |---|---|
-| `Board` | Main board component rendering columns with full DnD context |
+| `Board` | Main board component rendering the columns it is given |
 | `BoardProps` | Interface defining all board configuration and callback props |
-| `locate()` | Internal helper to find a ticket across all columns by ID |
-| `findIndexInColumn()` | Internal helper to find a ticket's index within a specific column |
 
 ## Key Behaviors
 
-- **Collision detection** — Custom strategy combining `pointerWithin`, `rectIntersection`, and `closestCorners` to prioritize ticket-level hits over column-level hits
-- **Cross-column guards** — Respects `dropDisabled` and `allowedFromColumns` constraints; reverts state on invalid drops
-- **Optimistic UI** — `isDraggingRef` prevents external `columns` prop updates from overwriting in-flight drag state
+- **One monitor, one change** — A single `monitorForElements` watches the whole board; `resolveBoardDrop` (own module, unit-tested) turns the drop into a `BoardChange` or `null`
+- **Which target** — Two nested drop targets answer in the same terms, innermost first: a card, then its lane (for the gaps between cards, resolved to the nearest card and the edge of it the pointer is on). **Outside the lanes there is deliberately no target at all and releasing cancels** — Jira's model; landing a card "somewhere" because the pointer happened to be nearest to it makes a mis-drop unrecoverable. The aim arithmetic itself lives in `aim.ts` (slot indices, so one landing place can never be described two ways), shared verbatim by the pointer, the keyboard and the drop
+- **Nothing moves during a drag** — The dragged card stays put and fades; the landing place is a line. No margins open, no slots close, so the lane's height cannot wander and an edge flip costs one span instead of a relayout plus a card render
+- **One aim, one preview** — Where the drop points is resolved once, in the board's monitor, and handed down (`drop-aim.ts`). Each card used to work it out from its own hover events, which only ever answers for a card the pointer is physically over — so the preview vanished the moment the pointer left the lanes, even though the drop would still have landed. The board's answer is compared before it is stored, so a pointer moving inside one card does not re-render anything
+- **Cross-column guards** — `dropDisabled` and `allowedFromColumns` are enforced by each target's `canDrop`, so an invalid drop is never accepted and nothing has to be reverted
+- **Optimistic view** — The board renders `applyPendingMove(columns, pendingMove)` from the drop until the host's answer arrives (`pending-move.ts`), so the move is on screen instantly and the host's data replaces an identical picture. "Landed" is judged per kind of move: across lanes, arriving in the new lane once the old one has let go (a server may re-sort the lane, so the exact index would never come); within one lane, the exact slot. Weaker tests (a fresh `columns` array, the card leaving its old index) fire on a lane's own poll and snap the card back mid-flight. A 2s timeout is the backstop for a host that never applies the change
+- **Dragged card** — The card under the pointer is the browser's own native drag image (a styled DOM clone via `setCustomNativeDragPreview`), so the browser moves it — over its own chrome included — and carrying a card re-renders nothing and cannot freeze at the viewport edge. On drop, a portal copy takes over for one 160ms FLIP glide from the release point into the slot the move just opened, then hands over to the real card (hidden under it via `LandingCardContext` for exactly that long)
+- **Keyboard move** — Space on a focused card lifts it; the arrows walk it (up/down through slots, left/right through lanes, skipping any that will not take it); space or enter drops it; escape puts it back. Lift-and-place rather than one-press-one-move, because on a board every press would otherwise be its own write to the server. The lifted card feeds the same aim a pointer drag does, and the drop line is scrolled into view on every step — arrow keys bring no auto-scroll of their own. Keys are handled on the board, not the card: once a card is lifted they belong to the move rather than to whatever holds focus. Rules live in `aim.ts`, pure and unit-tested
 - **Collapse persistence** — Column collapsed state stored via `useBoardCollapse` (keyed by `collapseStorageKey`)
 - **Custom scrollbar** — Horizontal scrollbar rendered via `useHorizontalScrollbar` with pointer-drag thumb support
+- **Auto-scroll** — The board registers its own scroller and every scrollable ancestor once (`autoScrollAncestors`); each lane registers itself with a vertical-only overflow reach (`autoScrollColumn`), so a pointer below the board scrolls exactly the one lane it is under. `preventUnhandled` + `holdMoveDragEffect` keep the cursor a plain move cursor for the whole drag — without them the first frame and everything outside the lanes draw the browser's green copy cursor
 - **`onChange` payload** — Emits `BoardChange` with `ticketId`, `fromColumnId`, `toColumnId`, `afterTicketId`, and `beforeTicketId` for precise ordering
 
 ## Usage Example