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

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

@@ -1,5 +1,5 @@
 <!-- source-hash: db6e303b7af152f7914246835dde7146 -->
-Draggable and static board ticket card components for a kanban-style board view, providing both a `dnd-kit`-powered sortable card and a standalone presentational variant.
+Draggable and static board ticket card components for a kanban-style board view, providing both a card that registers its own drag and drop behaviour and a standalone presentational variant.
 
 ## Key Components
 
@@ -7,16 +7,38 @@ Draggable and static board ticket card components for a kanban-style board view,
 |---|---|---|
 | `TicketCardBody` | Component | Pure presentational inner content — title, device/org row, priority flag, assignees, tags, timestamp, new message badge, and approval row |
 | `TicketCardView` | Component | Static, non-draggable card using the same shell and body as the board card; suitable for embeds, previews, and marketing |
-| `TicketCard` | Component | Full draggable board card powered by `useSortable` from `@dnd-kit/sortable`; supports overlay mode, optional `href` link, and drag-disabled state |
+| `TicketCard` | Component | Full board card: registers itself as both draggable and drop target, fades in place while carried, draws the insertion line for the shared aim, and supports an optional `href` link plus drag/drop-disabled state |
 | `TicketCardBodyProps` | Interface | Props for the shared body: `ticket`, `columnColor`, `renderAssignSlot`, `onApprove`, `onReject` |
-| `TicketCardProps` | Interface | Extends body props with `columnId`, `href`, `isOverlay`, `dragDisabled`, and board-aware approve/reject signatures |
+| `TicketCardProps` | Interface | Extends body props with `columnId`, `href`, `dragDisabled`, `dropDisabled`, `allowedFromColumns`, and board-aware approve/reject signatures |
+
+**Nothing about the lane moves during a drag.** The card being carried stays exactly where it is,
+faded (0.4), and where it would land is drawn as a **line** on the nearest edge of the card it would
+displace — matched on the lane as well as the card id, because a ticket mid-status-change is briefly
+listed by two lanes at once. No room opens, no slot closes, so there is no layout to keep balanced
+and no lane height to wander. A no-op slot (the card's own place) draws nothing.
+
+That is a performance decision as much as a visual one. Opening a card's worth of room and drawing a
+copy of the card in it costs a lane relayout plus a whole card render — avatars, tags, tooltips, the
+host's assignee slot — on every edge flip, and the flips come as fast as the pointer moves. The line
+is one absolutely positioned span and says the same thing.
+
+The card under the pointer is the browser's **native drag image** — a DOM clone of the card, taken
+in `onGenerateDragPreview` (`setCustomNativeDragPreview` + `preserveOffsetOnSource`), at 0.9 opacity
+with a held shadow. A clone, not a second React tree: it is a photograph of exactly what is on
+screen, assignee slot included, with no providers to re-supply. Native, not a positioned element:
+an element in the page cannot leave the page, so a hand-drawn preview froze whenever the pointer
+crossed into the browser's own chrome.
+
+After the drop the board shows the move immediately (see `pending-move.ts`); the landed card is
+hidden under the portal copy gliding into its slot (`useIsLanding`) for the 160ms of that flight,
+and no longer than that.
 
 **Constants:** `MAX_VISIBLE_TAGS = 2`, `MAX_VISIBLE_ASSIGNEES = 3`, `PRIORITY_COLOR_CLASS` maps `low | medium | high | urgent` to ODS color tokens.
 
 ## Usage Example
 
 ```typescript
-// Draggable board card (inside a <Board> with dnd-kit context)
+// Draggable board card (inside a <Board>)
 <TicketCard
   ticket={ticket}
   columnId="in-progress"
@@ -26,7 +48,7 @@ Draggable and static board ticket card components for a kanban-style board view,
   onReject={(ticketId, requestId) => handleReject(ticketId, requestId)}
 />
 
-// Static preview card (no dnd-kit context required)
+// Static preview card (renders anywhere, registers nothing)
 <TicketCardView
   ticket={ticket}
   columnColor="#6366f1"

package/src/components/features/board/aim.ts

@@ -0,0 +1,131 @@
+import { extractClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge'
+import type { BoardChange, BoardColumnDef } from './types'
+
+/**
+ * Where a card being moved currently points: a lane, and a slot among the cards
+ * ALREADY in it — the card being moved never counts as one of them.
+ *
+ * This is the board's ONE description of a landing place, and everything is
+ * expressed in it: the pointer, the keyboard, the line that gets drawn and the
+ * change that gets reported. An index cannot say the same thing two ways, which
+ * matters more than it sounds — "below card X" and "above card Y" are the same
+ * slot, and drawing a line for whichever one a hit test happened to return makes
+ * it jump between two positions as the pointer crosses the boundary.
+ */
+export interface BoardAim {
+  columnId: string
+  /** Insertion index among the other cards, so `0..others.length`. */
+  index: number
+}
+
+export type ArrowKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight'
+
+/** Whether a lane will take this card — the board's own rules, passed in so this
+ *  module stays arithmetic. */
+type LaneFilter = (column: BoardColumnDef) => boolean
+
+const othersIn = (columns: readonly BoardColumnDef[], columnId: string, ticketId: string) =>
+  (columns.find(c => c.id === columnId)?.tickets ?? []).filter(t => t.id !== ticketId)
+
+/** The lane a card is in right now, or `null` if it is in none of them. */
+export function laneOf(columns: readonly BoardColumnDef[], ticketId: string): BoardColumnDef | null {
+  return columns.find(c => c.tickets.some(t => t.id === ticketId)) ?? null
+}
+
+/** Where a card starts: exactly where it already sits. */
+export function initialAim(columns: readonly BoardColumnDef[], ticketId: string): BoardAim | null {
+  const lane = laneOf(columns, ticketId)
+  if (!lane) return null
+  // Its index among the others is its own index: dropping it back at that slot
+  // puts it exactly where it came from.
+  return { columnId: lane.id, index: lane.tickets.findIndex(t => t.id === ticketId) }
+}
+
+/**
+ * The aim after one arrow key, or the aim unchanged when the move would leave
+ * the board or land in a lane that will not take the card.
+ *
+ * Up and down step through slots; left and right step through lanes, skipping
+ * any the card is not allowed into rather than stopping dead at it — a lane the
+ * user cannot use should cost a keypress, not end the journey.
+ */
+/**
+ * The slot a resolved drop target points at.
+ *
+ * Card targets carry the edge the pointer is nearest; a lane target means "past
+ * the last card". Either way the answer comes out as an index, so the caller
+ * never has to care which kind of target replied.
+ */
+export function aimFromTarget(
+  columns: readonly BoardColumnDef[],
+  ticketId: string,
+  target: Record<string | symbol, unknown>,
+): BoardAim | null {
+  const columnId = String(target.columnId)
+  if (!columns.some(c => c.id === columnId)) return null
+  const others = othersIn(columns, columnId, ticketId)
+  if (target.type !== 'ticket') return { columnId, index: others.length }
+  const over = others.findIndex(t => t.id === String(target.ticketId))
+  if (over < 0) return { columnId, index: others.length }
+  return { columnId, index: over + (extractClosestEdge(target) === 'bottom' ? 1 : 0) }
+}
+
+export function moveAim(
+  columns: readonly BoardColumnDef[],
+  ticketId: string,
+  aim: BoardAim,
+  key: ArrowKey,
+  accepts: LaneFilter,
+): BoardAim {
+  if (key === 'ArrowUp' || key === 'ArrowDown') {
+    const limit = othersIn(columns, aim.columnId, ticketId).length
+    const index = Math.min(Math.max(aim.index + (key === 'ArrowUp' ? -1 : 1), 0), limit)
+    return index === aim.index ? aim : { ...aim, index }
+  }
+
+  const step = key === 'ArrowLeft' ? -1 : 1
+  const from = columns.findIndex(c => c.id === aim.columnId)
+  for (let i = from + step; i >= 0 && i < columns.length; i += step) {
+    const column = columns[i]
+    if (!accepts(column)) continue
+    // Keep the slot the card had, as far as the new lane allows.
+    const limit = othersIn(columns, column.id, ticketId).length
+    return { columnId: column.id, index: Math.min(aim.index, limit) }
+  }
+  return aim
+}
+
+/** The card the preview hangs off, and which side of it — `null` for a lane with
+ *  nothing else in it. */
+export function aimAnchor(
+  columns: readonly BoardColumnDef[],
+  ticketId: string,
+  aim: BoardAim,
+): { ticketId: string | null; edge: 'top' | 'bottom' | null } {
+  const others = othersIn(columns, aim.columnId, ticketId)
+  if (others.length === 0) return { ticketId: null, edge: null }
+  if (aim.index < others.length) return { ticketId: others[aim.index].id, edge: 'top' }
+  return { ticketId: others[others.length - 1].id, edge: 'bottom' }
+}
+
+/**
+ * The move to report, or `null` when the card would land back where it started.
+ *
+ * Same rule as a pointer drop, and deliberately so: a keyboard move that ends
+ * where it began must be as silent as a card picked up and put down again.
+ */
+export function aimToChange(columns: readonly BoardColumnDef[], ticketId: string, aim: BoardAim): BoardChange | null {
+  const lane = laneOf(columns, ticketId)
+  if (!lane) return null
+
+  const others = othersIn(columns, aim.columnId, ticketId)
+  const afterTicketId = others[aim.index - 1]?.id ?? null
+  const beforeTicketId = others[aim.index]?.id ?? null
+
+  if (lane.id === aim.columnId) {
+    const currentIndex = lane.tickets.findIndex(t => t.id === ticketId)
+    if ((lane.tickets[currentIndex - 1]?.id ?? null) === afterTicketId) return null
+  }
+
+  return { ticketId, fromColumnId: lane.id, toColumnId: aim.columnId, afterTicketId, beforeTicketId }
+}

package/src/components/features/board/board-column-header.tsx

@@ -54,15 +54,8 @@ export function BoardColumnHeader({
   return (
     <div className="flex items-center gap-[var(--spacing-system-xsf)]">
       <div className="flex min-w-0 flex-1 items-center gap-[var(--spacing-system-xsf)]">
-        <TicketStatusTag
-          status={tagStatus}
-          label={column.label}
-          color={useStatusVariant ? undefined : column.color}
-        />
-        <span
-          className="text-h5"
-          style={useStatusVariant ? undefined : { color: column.color }}
-        >
+        <TicketStatusTag status={tagStatus} label={column.label} color={useStatusVariant ? undefined : column.color} />
+        <span className="text-h5" style={useStatusVariant ? undefined : { color: column.color }}>
           {count}
         </span>
       </div>

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

@@ -1,24 +1,29 @@
 'use client'
 
-import { useDroppable } from '@dnd-kit/core'
-import { SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable'
-import * as React from 'react'
+import { dropTargetForElements } from '@atlaskit/pragmatic-drag-and-drop/element/adapter'
+import { memo, useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
 import { TagIcon } from '../../icons-v2-generated/shopping/tag-icon'
 import { cn } from '../../../utils/cn'
+import { attachClosestEdge } from '@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge'
+import { autoScrollColumn } from '../../../utils/auto-scroll-ancestors'
 import { BoardColumnHeader } from './board-column-header'
+import { useDropAim } from './drop-aim'
+import { DROP_LINE_ATTRIBUTE, nearestCardIn } from './lane-geometry'
 import { tintOnDark } from './color-utils'
 import { TicketCard } from './ticket-card'
 import { TicketCardSkeleton } from './ticket-card-skeleton'
+import { TICKET_ID_ATTRIBUTE, useLaneScrollAnchor } from './use-lane-scroll-anchor'
 import type { BoardColumnDef, BoardTicket } from './types'
 
 export interface BoardColumnProps {
   column: BoardColumnDef
   collapsed?: boolean
-  onToggleCollapse: () => void
+  /** Takes the id so the board can pass one stable handler to every lane. */
+  onToggleCollapse: (columnId: string) => void
   onAddTicket?: (columnId: string) => void
   onArchive?: (columnId: string) => void
   getTicketHref?: (ticketId: string) => string
-  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>
   onLoadMore?: (columnId: string) => void
@@ -27,7 +32,10 @@ export interface BoardColumnProps {
   joinRight?: boolean
 }
 
-export function BoardColumn({
+/** Memoized: `Board` rebuilds only the two columns a drag touches, so the
+ *  untouched ones keep their object identity and can skip the render entirely.
+ *  Without this, every pointer move that shifts a card re-renders all lanes. */
+export const BoardColumn = memo(function BoardColumn({
   column,
   collapsed = false,
   onToggleCollapse,
@@ -42,8 +50,59 @@ export function BoardColumn({
   joinLeft = false,
   joinRight = false,
 }: BoardColumnProps) {
+  // The drop zone is the WHOLE lane, header included — not just the list. A
+  // target that stops at the list leaves dead strips (the header, the padding)
+  // where the pointer is over a column yet hits nothing. Collapsed lanes stay
+  // out: they render no list to drop into.
+  //
+  // A card sitting inside this lane is a drop target too, and Pragmatic reports
+  // the innermost one first — so the lane only ever answers for the gaps, and
+  // "which card" never has to be guessed from rect overlap.
+  const laneRef = useRef<HTMLDivElement>(null)
+  const [isOver, setIsOver] = useState(false)
+
+  useEffect(() => {
+    const element = laneRef.current
+    if (!element || collapsed || column.dropDisabled) return
+
+    return dropTargetForElements({
+      element,
+      canDrop: ({ source }) => {
+        if (source.data.type !== 'ticket') return false
+        const from = source.data.columnId
+        if (from === column.id) return true
+        return !column.allowedFromColumns || column.allowedFromColumns.includes(String(from))
+      },
+      // A drop that lands between cards — most of the lane, once a hovered card
+      // has opened the room the preview is drawn in — answers with the nearest
+      // card and the edge of it the pointer is on, exactly as that card would
+      // have. Reporting a bare lane instead sent the ticket to the BOTTOM of the
+      // column, which is what made small moves look like they had not worked and
+      // large ones like the only thing that did.
+      getData: ({ input, element: lane, source }) => {
+        const nearest = nearestCardIn(lane, input.clientY, String(source.data.ticketId))
+        const ticketId = nearest?.dataset.ticketId
+        // An empty lane, or one whose only card is the one being dragged: the
+        // drop appends, which is the only place it could go.
+        if (!nearest || !ticketId) return { type: 'column', columnId: column.id }
+        return attachClosestEdge(
+          { type: 'ticket', ticketId, columnId: column.id },
+          { input, element: nearest, allowedEdges: ['top', 'bottom'] },
+        )
+      },
+      onDragEnter: () => setIsOver(true),
+      onDragLeave: () => setIsOver(false),
+      onDrop: () => setIsOver(false),
+    })
+  }, [column.id, column.dropDisabled, column.allowedFromColumns, collapsed])
+
+  // The header's own prop stays zero-arg; the id is bound here, where it is
+  // already known, rather than by the board building one closure per lane.
+  const handleToggleCollapse = useCallback(() => onToggleCollapse(column.id), [onToggleCollapse, column.id])
+
   return (
     <div
+      ref={laneRef}
       className={cn(
         'flex h-full shrink-0 flex-col gap-[var(--spacing-system-sf)] overflow-hidden rounded-md border border-ods-border p-[var(--spacing-system-sf)]',
         'transition-[width] duration-300 ease-out',
@@ -51,13 +110,14 @@ export function BoardColumn({
         column.system && 'bg-ods-card',
         joinLeft && 'rounded-l-none border-l-0',
         joinRight && 'rounded-r-none',
+        isOver && 'outline outline-2 -outline-offset-2 outline-ods-focus',
       )}
       style={column.system ? undefined : { backgroundColor: tintOnDark(column.color) }}
     >
       <BoardColumnHeader
         column={column}
         collapsed={collapsed}
-        onToggleCollapse={onToggleCollapse}
+        onToggleCollapse={handleToggleCollapse}
         onAddTicket={!collapsed && onAddTicket ? () => onAddTicket(column.id) : undefined}
         onArchive={!collapsed && column.archivable && onArchive ? () => onArchive(column.id) : undefined}
       />
@@ -77,40 +137,49 @@ export function BoardColumn({
       )}
     </div>
   )
-}
+})
 
 interface ColumnBodyProps {
   column: BoardColumnDef
   getTicketHref?: (ticketId: string) => string
-  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>
   onLoadMore?: (columnId: string) => void
   loadMoreRootMargin: string
 }
 
-function ColumnBody({ column, getTicketHref, renderAssignSlot, onApprove, onReject, onLoadMore, loadMoreRootMargin }: ColumnBodyProps) {
-  const ticketIds = React.useMemo(() => column.tickets.map(t => t.id), [column.tickets])
+function ColumnBody({
+  column,
+  getTicketHref,
+  renderAssignSlot,
+  onApprove,
+  onReject,
+  onLoadMore,
+  loadMoreRootMargin,
+}: ColumnBodyProps) {
+  const scrollRef = useRef<HTMLDivElement | null>(null)
+  const sentinelRef = useRef<HTMLDivElement | null>(null)
 
-  const droppableData = React.useMemo(
-    () => ({ columnId: column.id, type: 'column' as const }),
-    [column.id],
-  )
-  const { setNodeRef: setDroppableRef, isOver } = useDroppable({
-    id: `column:${column.id}`,
-    data: droppableData,
-    disabled: column.dropDisabled,
-  })
+  useLaneScrollAnchor(scrollRef, column.tickets)
 
-  const scrollRef = React.useRef<HTMLDivElement | null>(null)
-  const sentinelRef = React.useRef<HTMLDivElement | null>(null)
+  // Dragging near the top or bottom of a long lane scrolls THIS lane, and only
+  // this one — the reach past the lane's edges is vertical, so a pointer below
+  // the board is below exactly one column. The page's own scrollers are
+  // registered once by the board, not once per lane: registering them here gave
+  // `<main>` one auto-scroller per column, all pulling at the same time.
+  useEffect(() => {
+    const element = scrollRef.current
+    if (!element) return
+    return autoScrollColumn(element)
+  }, [])
 
-  const loadMoreRef = React.useRef(onLoadMore)
+  const loadMoreRef = useRef(onLoadMore)
   loadMoreRef.current = onLoadMore
-  const columnIdRef = React.useRef(column.id)
+  const columnIdRef = useRef(column.id)
   columnIdRef.current = column.id
 
-  React.useEffect(() => {
+  useEffect(() => {
     if (!column.hasMore || column.isLoadingMore) return
     const sentinel = sentinelRef.current
     const root = scrollRef.current
@@ -128,43 +197,40 @@ function ColumnBody({ column, getTicketHref, renderAssignSlot, onApprove, onReje
     return () => observer.disconnect()
   }, [column.hasMore, column.isLoadingMore, loadMoreRootMargin])
 
-  const setBodyRef = React.useCallback(
-    (el: HTMLDivElement | null) => {
-      scrollRef.current = el
-      setDroppableRef(el)
-    },
-    [setDroppableRef],
-  )
-
   return (
+    // `overflow-anchor:none` hands scroll anchoring to `useLaneScrollAnchor`
+    // wholesale. The browser's own anchoring is unusable here — it silently
+    // skips transformed elements, so it works between drags and does nothing
+    // during one — and leaving both on double-corrects every insertion.
     <div
-      ref={setBodyRef}
-      className={cn(
-        'flex min-h-0 flex-1 flex-col gap-[var(--spacing-system-xs)] overflow-y-auto',
-        isOver && 'rounded-md outline outline-2 outline-offset-2 outline-ods-focus',
-      )}
+      ref={scrollRef}
+      // `py-[5px]`: the insertion line sits in the middle of the gap between two
+      // cards, and the first and last card have no gap on their outer side. This
+      // is the sliver it lives in there — without it the line is clipped away by
+      // this element's own overflow exactly when a card is aimed at either end.
+      className="flex min-h-0 flex-1 flex-col gap-[var(--spacing-system-xs)] overflow-y-auto py-[5px] [overflow-anchor:none]"
     >
-      <SortableContext items={ticketIds} strategy={verticalListSortingStrategy}>
-        {column.isLoading ? (
-          <SkeletonStack />
-        ) : column.tickets.length === 0 ? (
-          <EmptyState />
-        ) : (
-          column.tickets.map(t => (
-            <TicketCard
-              key={t.id}
-              ticket={t}
-              columnId={column.id}
-              columnColor={column.color}
-              href={getTicketHref?.(t.id)}
-              renderAssignSlot={renderAssignSlot}
-              onApprove={onApprove}
-              onReject={onReject}
-              dragDisabled={column.dragDisabled}
-            />
-          ))
-        )}
-      </SortableContext>
+      {column.isLoading ? (
+        <SkeletonStack />
+      ) : column.tickets.length === 0 ? (
+        <EmptyState columnId={column.id} />
+      ) : (
+        column.tickets.map(t => (
+          <TicketCard
+            key={t.id}
+            ticket={t}
+            columnId={column.id}
+            columnColor={column.color}
+            href={getTicketHref?.(t.id)}
+            renderAssignSlot={renderAssignSlot}
+            onApprove={onApprove}
+            onReject={onReject}
+            dragDisabled={column.dragDisabled}
+            dropDisabled={column.dropDisabled}
+            allowedFromColumns={column.allowedFromColumns}
+          />
+        ))
+      )}
       {column.isLoadingMore && !column.isLoading && <TicketCardSkeleton />}
       {column.hasMore && <div ref={sentinelRef} aria-hidden className="h-1 shrink-0" />}
     </div>
@@ -172,20 +238,25 @@ function ColumnBody({ column, getTicketHref, renderAssignSlot, onApprove, onReje
 }
 
 function SkeletonStack({ count = 4 }: { count?: number }) {
-  const keys = React.useMemo(
-    () => Array.from({ length: count }, () => Math.random().toString(36).slice(2)),
-    [count],
-  )
+  // Position IS the identity here: the rows are interchangeable placeholders in
+  // a fixed-length list, so the index is the correct key. Random keys remounted
+  // every row whenever this re-rendered with a different `count`.
   return (
     <>
-      {keys.map(k => (
-        <TicketCardSkeleton key={k} />
+      {Array.from({ length: count }, (_, i) => (
+        <TicketCardSkeleton key={`skeleton-${i}`} />
       ))}
     </>
   )
 }
 
-function EmptyState() {
+/** Also carries the insertion line when a drop is aimed here, since the lane has
+ *  no card to hang it off. */
+function EmptyState({ columnId }: { columnId: string }) {
+  const aim = useDropAim()
+  if (aim && aim.columnId === columnId) {
+    return <div aria-hidden {...{ [DROP_LINE_ATTRIBUTE]: '' }} className="h-0.5 shrink-0 rounded-full bg-ods-accent" />
+  }
   return (
     <div className="flex flex-1 flex-col items-center justify-center gap-[var(--spacing-system-lf)] p-[var(--spacing-system-lf)] text-center text-ods-text-secondary">
       <TagIcon className="h-6 w-6 shrink-0" />