@flamingo-stack/openframe-frontend-core 0.0.552 → 0.0.553-1815.4815.1

package/src/components/features/board/drop-target.ts

@@ -0,0 +1,188 @@
+import {
+  closestCorners,
+  pointerWithin,
+  rectIntersection,
+  type Collision,
+  type CollisionDetection,
+  type UniqueIdentifier,
+} from '@dnd-kit/core'
+
+export type CollisionArgs = Parameters<CollisionDetection>[0]
+
+/** Data every board droppable carries, so a collision can be read back. */
+export interface BoardDroppableData {
+  type?: 'ticket' | 'column'
+  columnId?: string
+}
+
+function droppableDataOf(collision: Collision): BoardDroppableData | undefined {
+  return collision.data?.droppableContainer?.data?.current as BoardDroppableData | undefined
+}
+
+/**
+ * Picks the one droppable a drop would land in. The board registers two kinds —
+ * a ticket (`type: 'ticket'`) and a column (`type: 'column'`) — and the order
+ * below is what turns "somewhere over that lane" into a concrete position:
+ *
+ * 1. a ticket under the pointer wins outright: it is the anchor the move is
+ *    ordered against (`afterTicketId` / `beforeTicketId`);
+ * 2. otherwise a column under the pointer (its empty space, its header, the gap
+ *    between two cards) resolves to the nearest ticket *inside that column*, so
+ *    the drop still gets a position; an empty column returns itself, which the
+ *    board reads as "append";
+ * 3. otherwise nothing is under the pointer and geometry alone decides.
+ *
+ * `pointerHits` is passed in already computed: the caller has to know whether
+ * the pointer hit anything at all before it decides to run this — see
+ * {@link createDropTargetResolver}. With a pointer, step 3 and the
+ * `rectIntersection` fallback are only ever reached on the first collision of a
+ * drag; they stay for the keyboard sensor, which drags with no pointer at all.
+ */
+export function detectCollisions(args: CollisionArgs, pointerHits: Collision[]): Collision[] {
+  const intersections = pointerHits.length > 0 ? pointerHits : rectIntersection(args)
+
+  const ticketHit = intersections.find(c => droppableDataOf(c)?.type === 'ticket')
+  if (ticketHit) return [ticketHit]
+
+  const columnHit = intersections.find(c => droppableDataOf(c)?.type === 'column')
+  if (columnHit) {
+    const { columnId } = droppableDataOf(columnHit) ?? {}
+    // The dragged card is a droppable too, and it is the one card that must not
+    // be the answer: a collision on the active id reads as "no change" and the
+    // move is dropped, which would swallow a legitimate hover over a column.
+    const ticketsInColumn = args.droppableContainers.filter(container => {
+      if (container.id === args.active.id) return false
+      const data = container.data.current as BoardDroppableData | undefined
+      return data?.type === 'ticket' && data.columnId === columnId
+    })
+    if (ticketsInColumn.length > 0) {
+      const closest = closestCorners({ ...args, droppableContainers: ticketsInColumn })
+      if (closest.length > 0) return closest
+    }
+    return [columnHit]
+  }
+
+  return closestCorners(args)
+}
+
+/** Schedules `callback` for after the current frame; returns a canceller. */
+export type FrameScheduler = (callback: () => void) => () => void
+
+const animationFrameScheduler: FrameScheduler = callback => {
+  const id = requestAnimationFrame(callback)
+  return () => cancelAnimationFrame(id)
+}
+
+export interface DropTargetResolver {
+  /** Pass straight to `DndContext`'s `collisionDetection`. */
+  detect: CollisionDetection
+  /** Call right before a state update moves a card between columns. */
+  freeze: () => void
+  /**
+   * Call from an effect keyed on the moved list, so the freeze outlives the
+   * commit that caused it rather than a fixed slice of wall clock.
+   *
+   * `freeze` alone releases one frame after the HANDLER runs, which assumes the
+   * state update it guards has committed by then. That holds today — dnd-kit
+   * dispatches `onDragOver` from an effect, so the update flushes in the same
+   * commit phase — but it is an assumption about scheduling, and React is free
+   * to break it. Re-arming from the commit removes the assumption.
+   *
+   * A no-op while nothing is frozen, and the frame `freeze` scheduled stays as a
+   * ceiling: a move that resolves to no change commits nothing, and the guard
+   * still has to open on its own.
+   */
+  settle: () => void
+  /** Call on drag start / end / cancel. */
+  release: () => void
+  /** Call on unmount — drops any pending frame. */
+  dispose: () => void
+}
+
+/**
+ * {@link detectCollisions} plus the two rules that keep the answer stable. Both
+ * exist because moving a card to another column re-mounts it under a different
+ * parent, so dnd-kit unregisters + re-registers its droppable and re-measures
+ * EVERY rect — and dnd-kit dispatches `onDragOver` from an effect keyed on the
+ * over id, so any target change that a move causes schedules another move.
+ *
+ * 1. **Freeze after a move.** For one frame after a cross-column move the last
+ *    target is returned verbatim. The re-measure → re-collide → `onDragOver`
+ *    cascade runs synchronously off the state update, so releasing on the next
+ *    frame lands strictly after it: a move can never trigger the next one.
+ *    Without this the two columns keep handing the card back and forth inside a
+ *    single commit until React aborts the tree ("Maximum update depth exceeded").
+ * 2. **Hold when the pointer is over nothing.** In the lane between two columns
+ *    or off the board, the rect-based fallback ranks columns by how much the
+ *    dragged card's rect overlaps each — and that ranking flips as soon as a
+ *    move re-lays out the lists, so the card ping-pongs while the pointer sits
+ *    perfectly still. The drop target only changes when the pointer is inside
+ *    something.
+ *
+ * Kept out of the component (and out of React) so both rules are unit-testable:
+ * pass a manual {@link FrameScheduler} to step frames by hand.
+ */
+export function createDropTargetResolver(scheduleFrame: FrameScheduler = animationFrameScheduler): DropTargetResolver {
+  let settling = false
+  let cancelFrame: (() => void) | null = null
+  let lastOverId: UniqueIdentifier | null = null
+
+  const clearFrame = () => {
+    cancelFrame?.()
+    cancelFrame = null
+  }
+
+  /** Replaces any pending release with a fresh one, one frame out. */
+  const scheduleRelease = () => {
+    clearFrame()
+    cancelFrame = scheduleFrame(() => {
+      cancelFrame = null
+      settling = false
+    })
+  }
+
+  const keepLastTarget = (args: CollisionArgs): Collision[] | null => {
+    if (lastOverId === null) return null
+    const last = args.droppableContainers.find(c => c.id === lastOverId)
+    return last ? [{ id: last.id, data: { droppableContainer: last, value: 0 } }] : null
+  }
+
+  return {
+    detect: args => {
+      if (settling) {
+        const frozen = keepLastTarget(args)
+        if (frozen) return frozen
+      }
+
+      const pointerHits = args.pointerCoordinates ? pointerWithin(args) : []
+      if (args.pointerCoordinates && pointerHits.length === 0) {
+        const held = keepLastTarget(args)
+        if (held) return held
+      }
+
+      const collisions = detectCollisions(args, pointerHits)
+      // Only remember a real answer: forgetting on an empty result would drop
+      // the guard exactly when it is needed, and the next frame would fall back
+      // to the rect ranking that ping-pongs.
+      if (collisions.length > 0) lastOverId = collisions[0].id
+      return collisions
+    },
+
+    freeze: () => {
+      settling = true
+      scheduleRelease()
+    },
+
+    settle: () => {
+      if (settling) scheduleRelease()
+    },
+
+    release: () => {
+      clearFrame()
+      settling = false
+      lastOverId = null
+    },
+
+    dispose: clearFrame,
+  }
+}

package/src/components/features/board/ticket-card.tsx

@@ -3,7 +3,7 @@
 import { useSortable } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
 import Link from '../../../embed-shims/next-link'
-import * as React from 'react'
+import { memo, useMemo, type CSSProperties, type MouseEvent, type ReactNode } from 'react'
 import { ClockIcon, DotsLoaderIcon, LaptopIcon, Flag02Icon, MessagesIcon, UserCheckIcon } from '../../icons-v2-generated'
 import { DeletedUserAvatar } from '../../ui/deleted-user-avatar'
 import { SquareAvatar } from '../../ui/square-avatar'
@@ -13,6 +13,7 @@ import { cn } from '../../../utils/cn'
 import { getReadableTextColor } from '../../../utils/ods-color-utils'
 import { formatTicketRelativeTime, formatTicketFullTimestamp } from '../../../utils/date-utils'
 import { BoardTicketApproval } from './board-ticket-approval'
+import { TICKET_ID_ATTRIBUTE } from './use-lane-scroll-anchor'
 import type { BoardPriority, BoardTicket, BoardTicketActivityKind } from './types'
 
 const PRIORITY_COLOR_CLASS: Record<BoardPriority, string> = {
@@ -45,7 +46,7 @@ const TICKET_CARD_SHELL =
 export interface TicketCardBodyProps {
   ticket: BoardTicket
   columnColor?: string
-  renderAssignSlot?: (ticket: BoardTicket) => React.ReactNode
+  renderAssignSlot?: (ticket: BoardTicket) => ReactNode
   /** Approval callbacks receive the request id directly (the draggable
    *  `TicketCard` adapts its own `(ticketId, requestId)` signature onto these). */
   onApprove?: (requestId?: string) => void | Promise<void>
@@ -202,12 +203,17 @@ export interface TicketCardProps {
   href?: string
   isOverlay?: boolean
   dragDisabled?: boolean
-  renderAssignSlot?: (ticket: BoardTicket) => React.ReactNode
+  renderAssignSlot?: (ticket: BoardTicket) => ReactNode
   onApprove?: (ticketId: string, requestId?: string) => void | Promise<void>
   onReject?: (ticketId: string, requestId?: string) => void | Promise<void>
 }
 
-export function TicketCard({
+/** Memoized: a drag moves one card, but it re-renders the column lists around
+ *  it, and a board carries dozens of cards whose props did not change. Hosts
+ *  must pass stable `renderAssignSlot` / `onApprove` / `onReject` (useCallback)
+ *  for this to bite — an inline arrow re-renders every card on every keystroke
+ *  anywhere in the page. dnd-kit recommends memoizing sortable items. */
+export const TicketCard = memo(function TicketCard({
   ticket,
   columnId,
   columnColor,
@@ -218,12 +224,12 @@ export function TicketCard({
   onApprove,
   onReject,
 }: TicketCardProps) {
-  const sortableData = React.useMemo(() => ({ columnId, type: 'ticket' as const }), [columnId])
+  const sortableData = useMemo(() => ({ columnId, type: 'ticket' as const }), [columnId])
   const sortable = useSortable({ id: ticket.id, data: sortableData, disabled: dragDisabled })
 
   const showNewMessage = !!ticket.hasNewMessage && !!columnColor
 
-  const style: React.CSSProperties = isOverlay
+  const style: CSSProperties = isOverlay
     ? {}
     : {
         transform: CSS.Transform.toString(sortable.transform),
@@ -231,18 +237,29 @@ export function TicketCard({
       }
   if (showNewMessage) style.borderColor = columnColor
 
-  const handleClick = (e: React.MouseEvent) => {
+  const handleClick = (e: MouseEvent) => {
     if (sortable.isDragging) e.preventDefault()
   }
 
-  const body = (
-    <TicketCardBody
-      ticket={ticket}
-      columnColor={columnColor}
-      renderAssignSlot={renderAssignSlot}
-      onApprove={onApprove ? requestId => onApprove(ticket.id, requestId) : undefined}
-      onReject={onReject ? requestId => onReject(ticket.id, requestId) : undefined}
-    />
+  // Held as one memoized element, not re-created per render. `useSortable`
+  // subscribes to dnd-kit's context, and that context changes whenever a drag
+  // starts, ends or moves a card between columns — memo cannot stop a
+  // context update, so every card on the board re-renders at those moments. By
+  // keeping the same element object, React bails out of the whole subtree and
+  // only this thin wrapper (transform + drag classes) re-renders. That is what
+  // keeps a heavy card body — avatars, tags, tooltips, a host's assignee
+  // picker with its own queries — out of the drag's hot path.
+  const body = useMemo(
+    () => (
+      <TicketCardBody
+        ticket={ticket}
+        columnColor={columnColor}
+        renderAssignSlot={renderAssignSlot}
+        onApprove={onApprove ? requestId => onApprove(ticket.id, requestId) : undefined}
+        onReject={onReject ? requestId => onReject(ticket.id, requestId) : undefined}
+      />
+    ),
+    [ticket, columnColor, renderAssignSlot, onApprove, onReject],
   )
 
   const cardClasses = cn(
@@ -256,6 +273,9 @@ export function TicketCard({
     ref: isOverlay ? undefined : sortable.setNodeRef,
     style,
     className: cardClasses,
+    // Read by the lane's scroll anchor to keep the list still when tickets are
+    // inserted above the viewport — see `use-lane-scroll-anchor.ts`.
+    ...(isOverlay ? {} : { [TICKET_ID_ATTRIBUTE]: ticket.id }),
     ...(isOverlay ? {} : sortable.attributes),
     ...(isOverlay ? {} : sortable.listeners),
   }
@@ -297,7 +317,7 @@ export function TicketCard({
       <div className={cn('pointer-events-none', innerWrapperClass)}>{body}</div>
     </div>
   )
-}
+})
 
 function TicketTagRow({ tags }: { tags: string[] }) {
   const visible = tags.slice(0, MAX_VISIBLE_TAGS)

package/src/components/features/board/use-lane-scroll-anchor.ts

@@ -0,0 +1,75 @@
+'use client'
+
+import { useRef, type RefObject } from 'react'
+import { useIsomorphicLayoutEffect } from '../../../hooks/ui/use-isomorphic-layout-effect'
+import type { BoardTicket } from './types'
+
+/** Attribute the lane's cards carry so the anchor can find them again. */
+export const TICKET_ID_ATTRIBUTE = 'data-ticket-id'
+
+interface CardPosition {
+  id: string
+  /**
+   * Position in LAYOUT space, absolute within the lane — not the painted one.
+   * `offsetTop` ignores transforms, and during a drag dnd-kit transforms every
+   * card in the lane; anchoring on painted positions would read a card's shifted
+   * position before the drop and its resting position after, then "correct" the
+   * scroll by that difference and throw the lane hundreds of pixels off. Absolute
+   * rather than viewport-relative so that scrolling between two list changes —
+   * the drag's own auto-scroll, most of all — cannot stale the reading.
+   */
+  offsetTop: number
+}
+
+function cardPositions(root: HTMLElement): CardPosition[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(`[${TICKET_ID_ATTRIBUTE}]`)).map(element => ({
+    id: element.getAttribute(TICKET_ID_ATTRIBUTE) ?? '',
+    offsetTop: element.offsetTop,
+  }))
+}
+
+/**
+ * Keeps a scrolled lane visually still when its list changes above the viewport.
+ *
+ * Browsers do this themselves — it is called scroll anchoring — but Chrome skips
+ * candidates that carry a `transform`, and during a drag dnd-kit transforms every
+ * card in the lane to open the gap. So a ticket arriving from a live update (or
+ * landing when a drop reveals one that arrived mid-drag) is inserted above the
+ * viewport with nothing to compensate, and the whole list slides down by a card.
+ * From the outside that reads as: you drop a card and it lands one row lower than
+ * where you left it.
+ *
+ * The fix is one measurement: whichever card sits at the top of the viewport,
+ * note where it is, and after the list changes put the viewport back the same
+ * distance from it.
+ *
+ * Deliberately inert at the very top of a lane (`scrollTop === 0`), matching what
+ * browsers do — there a new ticket is meant to be seen, not scrolled away.
+ */
+export function useLaneScrollAnchor(scrollRef: RefObject<HTMLDivElement | null>, tickets: readonly BoardTicket[]): void {
+  const positionsRef = useRef<CardPosition[]>([])
+
+  useIsomorphicLayoutEffect(() => {
+    const root = scrollRef.current
+    if (!root) return
+
+    const previous = positionsRef.current
+    const scrollTop = root.scrollTop
+    // Measured once and reused: this runs for every lane on every list change —
+    // live updates, the host's refetch, each step of a cross-lane drag — and
+    // reading `offsetTop` after the DOM changed forces a synchronous layout.
+    const current = cardPositions(root)
+
+    if (previous.length > 0 && scrollTop > 0) {
+      // The card at the top of the viewport right now, by its previous position.
+      const anchor = previous.find(card => card.offsetTop >= scrollTop) ?? previous[previous.length - 1]
+      const moved = current.find(card => card.id === anchor.id)
+      if (moved) {
+        const drift = moved.offsetTop - anchor.offsetTop
+        if (Math.abs(drift) >= 1) root.scrollTop = scrollTop + drift
+      }
+    }
+
+    positionsRef.current = current
+  }, [tickets])
+}

package/src/stories/Board.stories.tsx

@@ -232,7 +232,10 @@ export const Pagination: Story = {
   render: function Render() {
     const TOTAL = 50
     const PAGE = 10
-    const allTickets = Array.from({ length: TOTAL }, (_, i) => baseTicket(i, 'ACTIVE'))
+    // Built once: rebuilding per render hands every card a new object, which
+    // defeats the memoization the board relies on to stay smooth under a drag.
+    const allTickets = React.useMemo(() => Array.from({ length: TOTAL }, (_, i) => baseTicket(i, 'ACTIVE')), [])
+    const loadedRef = React.useRef(PAGE)
 
     const [columns, setColumns] = React.useState<BoardColumnDef[]>([
       columnFromTicketStatus('ACTIVE', allTickets.slice(0, PAGE), { total: TOTAL, hasMore: true }),
@@ -243,13 +246,19 @@ export const Pagination: Story = {
     const handleLoadMore = (columnId: string) => {
       setColumns(prev => prev.map(c => (c.id === columnId ? { ...c, isLoadingMore: true } : c)))
       setTimeout(() => {
+        // APPEND the next page. Re-slicing the seed from 0 also threw away every
+        // drop the person had made, and a drag that auto-scrolls a lane to its
+        // bottom loads a page mid-drag — so the card silently snapped back to
+        // where it started, moments after landing where it was dropped.
+        const from = loadedRef.current
+        loadedRef.current = Math.min(from + PAGE, TOTAL)
+        const page = allTickets.slice(from, loadedRef.current)
         setColumns(prev =>
-          prev.map(c => {
-            if (c.id !== columnId) return c
-            const nextTickets = allTickets.slice(0, c.tickets.length + PAGE)
-            const hasMore = nextTickets.length < TOTAL
-            return { ...c, tickets: nextTickets, hasMore, isLoadingMore: false }
-          }),
+          prev.map(c =>
+            c.id === columnId
+              ? { ...c, tickets: [...c.tickets, ...page], hasMore: loadedRef.current < TOTAL, isLoadingMore: false }
+              : c,
+          ),
         )
       }, 600)
     }