@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Kanban/Kanban.tsx

@@ -0,0 +1,951 @@
+import {
+  Children,
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  DndContext,
+  KeyboardSensor,
+  PointerSensor,
+  getScrollableAncestors,
+  useDroppable,
+  useSensor,
+  useSensors,
+  type CollisionDetection,
+  type DragEndEvent,
+  type DragOverEvent,
+  type DragStartEvent,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS, type Transform } from '@dnd-kit/utilities';
+import clsx from 'clsx';
+import {
+  SortableHandle,
+  SortableItemContext,
+  type SortableItemContextValue,
+} from '../Sortable/Sortable';
+import {
+  containerName,
+  dragLabelOf,
+  useDragAccessibility,
+  type DescribeDragTarget,
+} from '../_internal/dragAnnouncements';
+import { useTranslation } from '../../i18n/useTranslation';
+import {
+  containerAwareClosestCorners,
+  isPointerOutsideContainers,
+} from '../Sortable/containerAwareCollision';
+import styles from './Kanban.module.scss';
+
+// ---------------------------------------------------------------------------
+// Internal context: Root → Column, passes effective cardIds for SortableContext
+// ---------------------------------------------------------------------------
+
+const KanbanColumnItemsContext = createContext<readonly (string | number)[] | null>(null);
+
+// ---------------------------------------------------------------------------
+// Public interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * Payload fired by `onMove` after a successful drag-drop across or within
+ * a column. Consumer applies the move by updating their items state.
+ */
+export interface KanbanMoveEvent {
+  /** Source position — where the card was before the drag. */
+  from: { columnId: string | number; index: number };
+  /** Destination position — where the card landed after the drop. */
+  to: { columnId: string | number; index: number };
+  /** The id of the card that was dragged. */
+  cardId: string | number;
+}
+
+export interface KanbanProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Fires once per drag (on drop) with the from/to positions and the cardId.
+   * NOT fired on drag cancel. NOT fired when from === to (no-op drop).
+   *
+   * Consumer should update their items state immutably, e.g.:
+   * ```ts
+   * const [cols, setCols] = useState({ todo: ['a', 'b'], done: ['c'] });
+   * const handleMove = ({ from, to, cardId }) => {
+   *   setCols((prev) => {
+   *     const next = { ...prev };
+   *     next[from.columnId] = [...prev[from.columnId]];
+   *     next[from.columnId].splice(from.index, 1);
+   *     next[to.columnId] = [...prev[to.columnId]];
+   *     next[to.columnId].splice(to.index, 0, cardId);
+   *     return next;
+   *   });
+   * };
+   * ```
+   */
+  onMove?: (event: KanbanMoveEvent) => void;
+}
+
+export interface KanbanColumnProps extends Omit<HTMLAttributes<HTMLDivElement>, 'id'> {
+  /**
+   * Stable identifier for this column. Must be unique within a `<Kanban>`.
+   * Used internally to track which cards belong to which column.
+   */
+  id: string | number;
+  children?: ReactNode;
+}
+
+export interface KanbanCardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'id'> {
+  /**
+   * Stable identifier for this card. Must be unique across ALL columns in
+   * the `<Kanban>`. Used by dnd-kit to track the card during drag.
+   */
+  id: string | number;
+  children: ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// containsHandle — mirrors Sortable's implementation; checks for KanbanHandle
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively walk the children subtree looking for a `Kanban.Handle`
+ * (`SortableHandle`). Mirrors Sortable's `containsHandle` function.
+ *
+ * Limitation: only walks `React.Children` and `props.children` — a Handle
+ * wrapped inside a custom component is invisible to this walk.
+ */
+function containsHandle(children: ReactNode): boolean {
+  let found = false;
+  function walk(node: ReactNode) {
+    if (found) return;
+    if (!isValidElement(node)) return;
+    if (node.type === SortableHandle) {
+      found = true;
+      return;
+    }
+    const { children: nested } = node.props as { children?: ReactNode };
+    if (nested != null) Children.forEach(nested, walk);
+  }
+  Children.forEach(children, walk);
+  return found;
+}
+
+// ---------------------------------------------------------------------------
+// Drag bounds — the dragged card may not leave the board's scrollable content
+// ---------------------------------------------------------------------------
+
+/**
+ * Where the dragged card sits inside its scroll container, and how big that
+ * container's content is. Everything is expressed in the container's CONTENT
+ * space (origin = scroll offset 0), which is scroll-invariant: the numbers stay
+ * valid while auto-scroll moves the board under the card.
+ *
+ * @internal exported for unit tests; not part of the public API.
+ */
+export interface KanbanDragBounds {
+  /** Card centre, x, in content space. */
+  centerX: number;
+  /** Card centre, y, in content space. */
+  centerY: number;
+  /** Card layout width (untransformed). */
+  width: number;
+  /** Card layout height (untransformed). */
+  height: number;
+  /** `scrollWidth` of the container, measured with the card untransformed. */
+  contentWidth: number;
+  /** `scrollHeight` of the container, measured with the card untransformed. */
+  contentHeight: number;
+}
+
+/**
+ * Measure `node` against its nearest scrollable ancestor.
+ *
+ * The card's own transform (and transition) are stripped for the duration of
+ * the measurement — both readings would otherwise be poisoned by the transform:
+ * `getBoundingClientRect()` returns the TRANSFORMED box, and a card already
+ * hanging past the content edge inflates the very `scrollWidth` we are about to
+ * use as the bound. Stripping makes the measurement a fixed point, so repeated
+ * measurements during one drag cannot ratchet the bound outwards. The
+ * transition goes too: a keyboard drag leaves a real `transition` on the drag
+ * source (a pointer drag does not), and strip-then-restore would otherwise read
+ * as a computed-value change and animate the card back from identity. Both are
+ * restored before the browser paints (this runs in a layout effect), so nothing
+ * is visible.
+ *
+ * Which container: only the NEAREST scrollable ancestor matters — it clips
+ * everything below it, so no ancestor further up ever sees the overhang. Inside
+ * a `<Kanban>` that is always the board. It is whatever else the consumer made
+ * scrollable, though: a `<Kanban.Column>` given `overflow-y: auto` becomes the
+ * nearest scroller for its own cards.
+ *
+ * Returns null when nothing is measurable — no node, or a zero-sized scroll
+ * area, which is every element under jsdom (it lays nothing out). A null bound
+ * means "don't clamp", i.e. the pre-#373 behaviour. Note there is no
+ * "unscrollable" case to bail out of in a real browser:
+ * `getScrollableAncestors` falls back to `document.scrollingElement`, so a card
+ * with no scrollable ancestor is bounded by the page instead.
+ *
+ * @internal exported for unit tests; not part of the public API.
+ */
+export function measureKanbanDragBounds(node: HTMLElement | null): KanbanDragBounds | null {
+  if (!node) return null;
+  const [scroller] = getScrollableAncestors(node, 1);
+  if (!scroller) return null;
+
+  const previousTransform = node.style.transform;
+  const previousTransition = node.style.transition;
+  node.style.transform = 'none';
+  node.style.transition = 'none';
+  const rect = node.getBoundingClientRect();
+  const box = scroller.getBoundingClientRect();
+  const { scrollLeft, scrollTop, scrollWidth, scrollHeight, clientLeft, clientTop } = scroller;
+  node.style.transform = previousTransform;
+  node.style.transition = previousTransition;
+
+  if (scrollWidth === 0 || scrollHeight === 0) return null;
+
+  // Content-space origin: the padding-box corner, un-scrolled. The root
+  // scrolling element is the exception — its OWN box already moves with page
+  // scroll, so `box` is the un-scrolled origin and subtracting the scroll
+  // offset again would count it twice.
+  const isRootScroller = scroller === scroller.ownerDocument.scrollingElement;
+  const originX = box.left + clientLeft - (isRootScroller ? 0 : scrollLeft);
+  const originY = box.top + clientTop - (isRootScroller ? 0 : scrollTop);
+
+  return {
+    centerX: rect.left + rect.width / 2 - originX,
+    centerY: rect.top + rect.height / 2 - originY,
+    width: rect.width,
+    height: rect.height,
+    contentWidth: scrollWidth,
+    contentHeight: scrollHeight,
+  };
+}
+
+/**
+ * Bound `transform` so the transformed card stays inside the scroll
+ * container's content box. Pass-through when either argument is null.
+ *
+ * This is what stops horizontal auto-scroll from running away (#373). The card
+ * is rendered IN FLOW (there is no `DragOverlay`), so a transform that carries
+ * it past the content edge extends the container's `scrollWidth`; dnd-kit's
+ * auto-scroll then chases the edge it just created, which moves the card
+ * further out, which extends the edge again — measured at 8910px of `scrollLeft`
+ * against a real maximum of 597. Clamping the APPLIED transform breaks the loop
+ * at its source: `scrollWidth` never changes, so `scrollLeft` plateaus at the
+ * real maximum and the last column becomes reachable.
+ *
+ * It has to happen here, where the transform is written to the DOM — a
+ * `DndContext` modifier is not enough, because dnd-kit computes
+ * `scrollAdjustedTranslate = modifiedTranslate + scrollAdjustment` and adds the
+ * scroll adjustment AFTER modifiers run (same reason `DataTable` clamps
+ * `event.delta` rather than only its modifier — see `useColumnDragShift`).
+ *
+ * `scaleX` / `scaleY` are honoured because dnd-kit scales the drag source to
+ * the `over` rect; the scaled half-extent, not the layout half-extent, is what
+ * reaches the edge.
+ *
+ * @internal exported for unit tests; not part of the public API.
+ */
+export function clampKanbanTransform(
+  transform: Transform | null,
+  bounds: KanbanDragBounds | null,
+): Transform | null {
+  if (!transform || !bounds) return transform;
+  const halfWidth = (bounds.width * transform.scaleX) / 2;
+  const halfHeight = (bounds.height * transform.scaleY) / 2;
+  return {
+    ...transform,
+    x: clamp(
+      transform.x,
+      halfWidth - bounds.centerX,
+      bounds.contentWidth - halfWidth - bounds.centerX,
+    ),
+    y: clamp(
+      transform.y,
+      halfHeight - bounds.centerY,
+      bounds.contentHeight - halfHeight - bounds.centerY,
+    ),
+  };
+}
+
+const clamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);
+
+// ---------------------------------------------------------------------------
+// KanbanCard
+// ---------------------------------------------------------------------------
+
+/**
+ * One draggable card inside a `<Kanban.Column>`; needs a stable `id`.
+ * @see docs/components/Kanban.md
+ */
+export const KanbanCard = forwardRef<HTMLDivElement, KanbanCardProps>(function KanbanCard(
+  { id, className, children, ...rest },
+  ref,
+) {
+  // Announcement label: the consumer's `aria-label`, else the card's RENDERED
+  // text (so a closed menu inside the card contributes nothing — see
+  // `dragLabelOf`). The same ref is the drag-bounds node ref below.
+  const cardRef = useRef<HTMLDivElement | null>(null);
+  const dragLabel = rest['aria-label'];
+  const dragData = useMemo(() => ({ dragLabel, dragNode: cardRef }), [dragLabel]);
+
+  const {
+    setNodeRef,
+    setActivatorNodeRef,
+    listeners,
+    attributes,
+    transform,
+    transition,
+    isDragging,
+    index,
+    items,
+  } = useSortable({ id, data: dragData });
+
+  const hasHandle = useMemo(() => containsHandle(children), [children]);
+
+  const ctxValue = useMemo<SortableItemContextValue>(
+    () => ({ listeners, attributes, setActivatorNodeRef }),
+    [listeners, attributes, setActivatorNodeRef],
+  );
+
+  // Travel available to the dragged card, in its scroll container's content
+  // space (#373). Re-measured only when the card's LAYOUT position can have
+  // changed, which is never a plain pointer move — while the card only
+  // translates, its layout position and the content size are both constant, so
+  // measuring per move would force a full layout per move for no gain. It
+  // changes in exactly two ways:
+  //  - a live re-seat WITHIN a column (`index` / `items` change, same parent —
+  //    React moves the node), and
+  //  - a live re-seat ACROSS columns, where `KanbanRoot` re-parents the card
+  //    into another `KanbanColumnItemsContext` subtree. That is a remount, not
+  //    a move: this component gets a fresh instance with `boundsRef` back to
+  //    null, so its FIRST render clamps against nothing at all.
+  //
+  // The write-back below exists for that first render. Measuring alone can't
+  // fix it: React's mutation phase writes the frame's transform BEFORE refs
+  // attach and layout effects run, so by then the unbounded value is already on
+  // the node and nothing re-reads `boundsRef` until the next render. Only
+  // writing the bounded value back changes what that frame paints, and a layout
+  // effect does it pre-paint. `transform` is deliberately NOT a dependency —
+  // this effect runs only on the renders that (re)measure, and on those the
+  // closed-over `transform` is exactly the one just committed.
+  //
+  // Be clear about what it is: on today's dnd-kit it is a NO-OP, not a fix.
+  // `transform` is null on precisely these frames — a re-seat mutates the
+  // SortableContext items, so `itemsHaveChanged` forces `displaceItem` false;
+  // and on a transit `over` is the column, so `overIndex` is -1 and it's false
+  // again. A null transform short-circuits every guard below, so nothing is
+  // written. Matching that, the frame could not be made to inflate
+  // `scrollWidth` in the browser: 635 rAF-sampled frames over 14 transits at
+  // max scroll with the pointer held outside the board, write-back disabled,
+  // yielded a single distinct `scrollWidth`.
+  //
+  // It is kept as insurance against exactly that internal changing. If a
+  // dnd-kit bump ever emits a non-null transform on a re-seat frame, deleting
+  // these lines silently reinstates the runaway — and no test can catch it,
+  // because jsdom lays nothing out, so the clamp's only evidence is a manual
+  // browser drag. Two inert guarded lines against a hand-only regression.
+  const boundsRef = useRef<KanbanDragBounds | null>(null);
+  useLayoutEffect(() => {
+    const node = cardRef.current;
+    if (!isDragging || !node) {
+      boundsRef.current = null;
+      return;
+    }
+    boundsRef.current = measureKanbanDragBounds(node);
+    const bounded = CSS.Transform.toString(clampKanbanTransform(transform, boundsRef.current));
+    if (bounded) node.style.transform = bounded;
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- transform is deliberately not a dependency, see above
+  }, [isDragging, index, items]);
+
+  const setRef = (node: HTMLDivElement | null) => {
+    cardRef.current = node;
+    setNodeRef(node);
+    // When no Handle is present, the Card itself is the drag activator.
+    if (!hasHandle) setActivatorNodeRef(node);
+    if (typeof ref === 'function') ref(node);
+    else if (ref) ref.current = node;
+  };
+
+  return (
+    <SortableItemContext.Provider value={ctxValue}>
+      <div
+        ref={setRef}
+        // Reading the ref during render is deliberate: the bound is written by
+        // the layout effect above and must be applied on the very next pointer
+        // move, without a re-render of its own.
+        style={{
+          transform: CSS.Transform.toString(clampKanbanTransform(transform, boundsRef.current)),
+          transition,
+        }}
+        data-dragging={isDragging ? 'true' : undefined}
+        className={clsx(styles.card, className)}
+        // dnd-kit drag attrs BEFORE {...rest} so consumer rest wins.
+        {...(hasHandle ? {} : listeners)}
+        {...(hasHandle ? {} : attributes)}
+        {...rest}
+        // role="article" AFTER {...rest} so it wins, but only when a Handle
+        // is present. Without a Handle, dnd-kit's role="button" is correct
+        // (Card IS the drag activator).
+        {...(hasHandle ? { role: 'article' } : {})}
+      >
+        {children}
+      </div>
+    </SortableItemContext.Provider>
+  );
+});
+KanbanCard.displayName = 'KanbanCard';
+
+// ---------------------------------------------------------------------------
+// KanbanColumn
+// ---------------------------------------------------------------------------
+
+/**
+ * One swimlane in a `<Kanban>`; needs a stable `id`.
+ * @see docs/components/Kanban.md
+ */
+export const KanbanColumn = forwardRef<HTMLDivElement, KanbanColumnProps>(function KanbanColumn(
+  { id, className, children, ...rest },
+  ref,
+) {
+  const { setNodeRef } = useDroppable({ id });
+
+  // Effective card ids are injected by KanbanRoot via context so that this
+  // column's SortableContext sees the live-reordered order.
+  const ctxCardIds = useContext(KanbanColumnItemsContext);
+
+  // Fallback: derive card ids from children if not in context (standalone use).
+  const fallbackCardIds = useMemo(() => {
+    if (ctxCardIds !== null) return null; // skip computation
+    const ids: (string | number)[] = [];
+    Children.forEach(children, (card) => {
+      if (!isValidElement(card) || card.type !== KanbanCard) return;
+      ids.push((card.props as KanbanCardProps).id);
+    });
+    return ids;
+  }, [children, ctxCardIds]);
+
+  const cardIds = ctxCardIds ?? fallbackCardIds ?? [];
+
+  const setRef = (node: HTMLDivElement | null) => {
+    setNodeRef(node);
+    if (typeof ref === 'function') ref(node);
+    else if (ref) ref.current = node;
+  };
+
+  return (
+    <div
+      ref={setRef}
+      className={clsx(styles.column, className)}
+      {...rest}
+      // A name on a role-less <div> is inert, so a labelled column gets a role
+      // to hang it on. AFTER {...rest} — but only when the consumer didn't
+      // already pick a role — so labelling can't silently do nothing.
+      {...((rest['aria-label'] || rest['aria-labelledby']) && rest.role == null
+        ? { role: 'group' }
+        : {})}
+    >
+      <SortableContext
+        items={cardIds as (string | number)[]}
+        strategy={verticalListSortingStrategy}
+      >
+        {children}
+      </SortableContext>
+    </div>
+  );
+});
+KanbanColumn.displayName = 'KanbanColumn';
+
+// ---------------------------------------------------------------------------
+// KanbanRoot
+// ---------------------------------------------------------------------------
+
+/**
+ * Multi-column drag-and-drop board with live cross-column reflow (`Kanban`, `Kanban.Column`, `Kanban.Card`, `Kanban.Handle`).
+ * @see docs/components/Kanban.md
+ */
+const KanbanRoot = forwardRef<HTMLDivElement, KanbanProps>(function KanbanRoot(
+  { onMove, className, children, ...rest },
+  ref,
+) {
+  const t = useTranslation();
+  // ------------------------------------------------------------------
+  // Parse children: extract column order, initial items, card elements,
+  // and the before/after non-card slices for each column.
+  // columnElements is built in the same pass so render-time lookup is O(1)
+  // instead of O(N) per column (i.e., O(N²) total per render).
+  // ------------------------------------------------------------------
+  const { columnOrder, columnElements, initialItems, cardElements, columnChildrenSlices } =
+    useMemo(() => {
+      const colOrder: (string | number)[] = [];
+      const colElems = new Map<string | number, ReactElement<KanbanColumnProps>>();
+      const initItems = new Map<string | number, (string | number)[]>();
+      const cardElems = new Map<string | number, ReactElement<KanbanCardProps>>();
+      const colSlices = new Map<string | number, { before: ReactNode[]; after: ReactNode[] }>();
+
+      Children.forEach(children, (child) => {
+        if (!isValidElement(child) || child.type !== KanbanColumn) return;
+        const columnElement = child as ReactElement<KanbanColumnProps>;
+        const colProps = columnElement.props;
+        const colId = colProps.id;
+        colOrder.push(colId);
+        colElems.set(colId, columnElement);
+
+        const colCardIds: (string | number)[] = [];
+        let firstCardIdx = -1;
+        let lastCardIdx = -1;
+        const colChildren = Children.toArray(colProps.children);
+
+        colChildren.forEach((grandchild, idx) => {
+          if (!isValidElement(grandchild) || grandchild.type !== KanbanCard) return;
+          const cardProps = grandchild.props as KanbanCardProps;
+          colCardIds.push(cardProps.id);
+          cardElems.set(cardProps.id, grandchild as ReactElement<KanbanCardProps>);
+          if (firstCardIdx < 0) firstCardIdx = idx;
+          lastCardIdx = idx;
+        });
+
+        // Split into before/after slices (non-card children outside the card block).
+        const before: ReactNode[] =
+          firstCardIdx >= 0 ? colChildren.slice(0, firstCardIdx) : colChildren;
+        const after: ReactNode[] = lastCardIdx >= 0 ? colChildren.slice(lastCardIdx + 1) : [];
+
+        initItems.set(colId, colCardIds);
+        colSlices.set(colId, { before, after });
+      });
+
+      return {
+        columnOrder: colOrder,
+        columnElements: colElems,
+        initialItems: initItems,
+        cardElements: cardElems,
+        columnChildrenSlices: colSlices,
+      };
+    }, [children]);
+
+  // ------------------------------------------------------------------
+  // Stable serialization of initialItems to detect consumer state changes.
+  // JSON.stringify is robust against ids that contain `:` or `,` characters,
+  // unlike a hand-rolled delimiter-join.
+  // ------------------------------------------------------------------
+  const initialItemsKey = useMemo(
+    () => JSON.stringify(Array.from(initialItems.entries())),
+    [initialItems],
+  );
+
+  // ------------------------------------------------------------------
+  // Internal drag state: null when idle, populated on drag start
+  // ------------------------------------------------------------------
+  const [liveItems, setLiveItems] = useState<Map<string | number, (string | number)[]> | null>(
+    null,
+  );
+
+  // Reset live items when consumer state mutates (e.g. external update mid-drag).
+  useEffect(() => {
+    setLiveItems(null);
+  }, [initialItemsKey]);
+
+  const effectiveItems = liveItems ?? initialItems;
+
+  // ------------------------------------------------------------------
+  // Sensors
+  // ------------------------------------------------------------------
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  // ------------------------------------------------------------------
+  // Container lookup: given an id (card or column), find which column owns it
+  // ------------------------------------------------------------------
+  const findContainer = useCallback(
+    (
+      id: string | number,
+      items: Map<string | number, (string | number)[]>,
+    ): string | number | null => {
+      if (items.has(id)) return id; // id is a column id itself (drop on empty column)
+      for (const [colId, cards] of items) {
+        if (cards.includes(id)) return colId;
+      }
+      return null;
+    },
+    [],
+  );
+
+  // ------------------------------------------------------------------
+  // Drag handlers
+  // ------------------------------------------------------------------
+  const originRef = useRef<string | number | null>(null);
+
+  // Was the pointer outside every column the last time a drop target was
+  // resolved? `DragEndEvent` carries no pointer position — only `delta`, which
+  // is `translate - nodeRectDelta + scrollAdjustment` and so drifts from the
+  // real pointer by however far the board auto-scrolled and however far a live
+  // re-seat moved the card. Collision detection, on the other hand, is handed
+  // dnd-kit's own `pointerCoordinates` alongside the very rects `over` was
+  // ranked from, so answering the question there and remembering the answer
+  // makes the cancel decision agree with `over` by construction (#387).
+  //
+  // Written during render (collision detection runs in `DndContext`'s render);
+  // that is safe because it is a pure function of the arguments, so a double
+  // render under StrictMode writes the same value.
+  const outsideBoardRef = useRef(false);
+  const collisionDetection = useCallback<CollisionDetection>((args) => {
+    const isOutsideBoard = isPointerOutsideContainers(args);
+    outsideBoardRef.current = isOutsideBoard;
+    // Force an `over` transition to null at the board boundary. dnd-kit's
+    // announcement callback only runs when `over.id` changes, so retaining the
+    // nearest collision here would leave screen readers naming a stale column.
+    if (isOutsideBoard) return [];
+    return containerAwareClosestCorners(args);
+  }, []);
+
+  const handleDragStart = useCallback(
+    (event: DragStartEvent) => {
+      outsideBoardRef.current = false;
+      // The column the card started in. Used by handleDragOver to tell a
+      // genuine same-column reorder apart from "already transited, still
+      // moving inside the destination".
+      originRef.current = findContainer(event.active.id as string | number, initialItems);
+      // Snapshot: shallow-copy each cards array so mutations don't leak into initialItems.
+      const snapshot = new Map<string | number, (string | number)[]>();
+      for (const [colId, cards] of initialItems) snapshot.set(colId, [...cards]);
+      setLiveItems(snapshot);
+    },
+    [initialItems, findContainer],
+  );
+
+  const handleDragOver = useCallback(
+    (event: DragOverEvent) => {
+      const { active, over } = event;
+      if (!over) return;
+      const activeId = active.id as string | number;
+      const overId = over.id as string | number;
+      if (activeId === overId) return;
+
+      setLiveItems((prev) => {
+        if (!prev) return prev;
+        const activeContainer = findContainer(activeId, prev);
+        const overContainer = findContainer(overId, prev);
+        if (activeContainer == null || overContainer == null) return prev;
+
+        const isTransit = activeContainer !== overContainer;
+        // Pointer in the padding of the column the card has already transited
+        // into (no card under it). `over` is the column, so the sortable
+        // strategy computes overIndex === -1 and applies NO displacement —
+        // re-appending here is therefore stable (it can't fight a transform)
+        // and it's exactly what the user sees. Cheap to keep in sync.
+        const isForeignAppend =
+          !isTransit && overId === overContainer && overContainer !== originRef.current;
+        // Everything else with active and over in the same column is finalized
+        // at dragEnd from `over` (see handleDragEnd). Re-seating the card here
+        // on every dragOver would oscillate: the insertion re-measures the
+        // rects, which changes `over`, which re-fires this handler — and the
+        // strategy would still displace siblings on top of the new order, so
+        // the commit would drift from the preview again.
+        if (!isTransit && !isForeignAppend) return prev;
+
+        const activeCards = prev.get(activeContainer) ?? [];
+        if (!activeCards.includes(activeId)) return prev;
+        if (isForeignAppend && activeCards[activeCards.length - 1] === activeId) return prev;
+
+        // Slot math runs against the destination WITHOUT the active card, so
+        // the card's own slot is never counted (off-by-one when moving down).
+        const overCards = (prev.get(overContainer) ?? []).filter((id) => id !== activeId);
+
+        // Resolve the target slot inside overContainer:
+        //   - over.id is a sibling card → use that card's index, plus 1 if
+        //     the cursor is past the over card's vertical midpoint (active's
+        //     translated rect tracks the cursor centered around it).
+        //   - over.id is the column itself (empty drop / padding) → append
+        //
+        // The `isBelow` +1 rarely survives to the commit: the strategy
+        // immediately re-renders the card at `overIndex` and dragEnd commits
+        // from `over`, so both sides of the +1 produce the same drop. It still
+        // decides the seeded slot the frame after transit (while dnd-kit has
+        // transforms disabled to re-measure), and dragEnd's fallbacks — `over`
+        // resolving to the column or to the dragged card itself — commit that
+        // seeded slot verbatim. Keep it; without it the card visibly jumps a
+        // slot on entry.
+        let insertAt: number;
+        if (overCards.includes(overId)) {
+          const overIdx = overCards.indexOf(overId);
+          const activeRect = active.rect.current.translated;
+          const overRect = over.rect;
+          const isBelow =
+            activeRect != null &&
+            activeRect.top + activeRect.height / 2 > overRect.top + overRect.height / 2;
+          insertAt = overIdx + (isBelow ? 1 : 0);
+        } else if (overId === overContainer) {
+          insertAt = overCards.length;
+        } else {
+          return prev;
+        }
+
+        const next = new Map(prev);
+        if (isTransit) {
+          next.set(
+            activeContainer,
+            activeCards.filter((id) => id !== activeId),
+          );
+        }
+        const newOver = [...overCards];
+        newOver.splice(insertAt, 0, activeId);
+        next.set(overContainer, newOver);
+        return next;
+      });
+    },
+    [findContainer],
+  );
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event;
+      const activeId = active.id as string | number;
+
+      // Two ways a drag ends in nothing, and `over` only reports the first:
+      //  - `over == null` — collision detection returned nothing at all, i.e.
+      //    no droppable was measured.
+      //  - the pointer left the board. `containerAwareClosestCorners` falls
+      //    back to `closestCorners`, which ranks every measured droppable and
+      //    rejects none, so `over` still names the nearest column after a
+      //    release over unrelated page content — a column the user never aimed
+      //    at and never saw highlighted. Committing it silently reassigns the
+      //    card's column (#387), so the pointer test decides instead.
+      // Both snap the card back: dropping `liveItems` re-renders every column
+      // from the consumer's untouched state, and no `onMove` fires.
+      if (!over || outsideBoardRef.current) {
+        setLiveItems(null);
+        return;
+      }
+
+      const overId = over.id as string | number;
+      const finalItems = liveItems ?? initialItems;
+
+      // Source (from-position): the card's pre-drag location.
+      let fromColumn: string | number | null = null;
+      let fromIndex = -1;
+      for (const [colId, cards] of initialItems) {
+        const idx = cards.indexOf(activeId);
+        if (idx >= 0) {
+          fromColumn = colId;
+          fromIndex = idx;
+          break;
+        }
+      }
+
+      if (fromColumn == null) {
+        setLiveItems(null);
+        return;
+      }
+
+      // Where does active currently live in liveItems? handleDragOver seats
+      // it in the destination on transit; the exact slot is resolved HERE,
+      // from `over`, because that's what the user was looking at:
+      // `verticalListSortingStrategy` renders each column as
+      // `arrayMove(liveItems[col], activeIndex, overIndex)` with
+      // `overIndex = liveItems[col].indexOf(over.id)`, so the previewed slot
+      // is `overIndex` whenever `over` is a sibling card, and the card's live
+      // slot when it isn't (`overIndex === -1` → the strategy displaces
+      // nothing). Committing the live slot alone would pin the drop to the
+      // boundary-crossing point (#376).
+      let liveColumn: string | number | null = null;
+      let liveIdx = -1;
+      for (const [colId, cards] of finalItems) {
+        const idx = cards.indexOf(activeId);
+        if (idx >= 0) {
+          liveColumn = colId;
+          liveIdx = idx;
+          break;
+        }
+      }
+
+      let toColumn: string | number;
+      let toIndex: number;
+
+      if (liveColumn != null && liveColumn !== fromColumn) {
+        // Cross-column drop: the previewed slot wins (see the comment above).
+        toColumn = liveColumn;
+        const destCards = finalItems.get(liveColumn) ?? [];
+        const overIdx = overId === activeId ? -1 : destCards.indexOf(overId);
+        toIndex = overIdx >= 0 ? overIdx : liveIdx;
+      } else if (initialItems.has(overId)) {
+        // Within-source-column drop on the column's padding (no card target).
+        // Default to "drop at end" so the card lands where the user dragged
+        // it, rather than snapping back to its original slot.
+        toColumn = fromColumn;
+        const fromCol = initialItems.get(fromColumn) ?? [];
+        toIndex = fromCol.length - 1;
+      } else if (overId === activeId) {
+        // Cursor over the dragged card itself. The strategy displaces nothing
+        // (overIndex === activeIndex), so the preview IS the live order —
+        // commit that. A barely-moved drag resolves to its own starting index
+        // and gets dropped by the no-op guard below; a card that came back to
+        // its origin column lands where the preview put it.
+        toColumn = fromColumn;
+        toIndex = liveIdx;
+      } else {
+        // Within-column drop on a sibling card. arrayMove semantics:
+        //   toIndex = sibling's index in the live column — same rule as the
+        // cross-column branch. For a plain same-column drag liveItems is
+        // untouched, so this is the sibling's index in the consumer's
+        // pre-move state; if the card visited another column and came back,
+        // the live order is what the preview showed, so it wins.
+        // For cross-column drops where the transit didn't commit (rare
+        // stale-closure case at the very first dragOver), the sibling may
+        // live in a different column — resolve the column from the card.
+        let overCol: string | number | null = null;
+        for (const [colId, cards] of finalItems) {
+          if (cards.includes(overId)) {
+            overCol = colId;
+            break;
+          }
+        }
+        if (overCol == null) {
+          setLiveItems(null);
+          return;
+        }
+        toColumn = overCol;
+        toIndex = (finalItems.get(toColumn) ?? []).indexOf(overId);
+      }
+
+      setLiveItems(null);
+
+      if (toIndex < 0) return;
+      if (fromColumn === toColumn && fromIndex === toIndex) return;
+
+      onMove?.({
+        from: { columnId: fromColumn, index: fromIndex },
+        to: { columnId: toColumn, index: toIndex },
+        cardId: activeId,
+      });
+    },
+    [liveItems, initialItems, onMove],
+  );
+
+  const handleDragCancel = useCallback(() => {
+    setLiveItems(null);
+  }, []);
+
+  // ------------------------------------------------------------------
+  // Screen-reader announcements (Hard rule 9, #390)
+  // ------------------------------------------------------------------
+  // Names a card by its own text and a column by the `aria-label` the consumer
+  // put on `<Kanban.Column>` (falling back to its board position), so a drag
+  // says "Acme — 40 seats, position 2 of 3 in Qualified" rather than dnd-kit's
+  // "deal-1 was moved over droppable area col-2". Slots are read from
+  // `effectiveItems` — the order the user is actually looking at mid-drag.
+  // `||`, not `??`, for the reason SortableGroup's twin site states: already
+  // safe, because `containerName` rejects a blank `aria-label` itself, but
+  // aligned so the operator is not the thing a reader has to verify.
+  const columnLabel = (colId: string | number): string =>
+    containerName(columnElements.get(colId)?.props ?? {}) ||
+    t('kanban.unnamedColumn', {
+      index: columnOrder.indexOf(colId) + 1,
+      total: columnOrder.length,
+    });
+  const describeDrag: DescribeDragTarget = (entry, activeId) => {
+    if (!entry) return null;
+    const id = entry.id as string | number;
+    const isColumn = effectiveItems.has(id);
+    const colId = isColumn ? id : findContainer(id, effectiveItems);
+    if (colId == null) return null;
+    const cards = effectiveItems.get(colId) ?? [];
+    const label = dragLabelOf(entry.data.current);
+    const container = columnLabel(colId);
+    if (!isColumn) return { label, index: cards.indexOf(id) + 1, total: cards.length, container };
+    // `over` is the column itself (empty column, or the padding below the
+    // cards). If the dragged card has already been live-seated here it keeps
+    // its slot; otherwise it would be appended, so count it as one more.
+    const seated = cards.indexOf(activeId as string | number);
+    return seated >= 0
+      ? { label, index: seated + 1, total: cards.length, container }
+      : { label, index: cards.length + 1, total: cards.length + 1, container };
+  };
+  // A release outside the board is a cancel, not a drop — `over` is non-null on
+  // that path (closestCorners rejects nothing), so without this dnd-kit would
+  // announce a drop that handleDragEnd deliberately threw away (#387).
+  const accessibility = useDragAccessibility(describeDrag, () => outsideBoardRef.current);
+
+  // ------------------------------------------------------------------
+  // Render
+  // ------------------------------------------------------------------
+  return (
+    <DndContext
+      accessibility={accessibility}
+      sensors={sensors}
+      collisionDetection={collisionDetection}
+      onDragStart={handleDragStart}
+      onDragOver={handleDragOver}
+      onDragEnd={handleDragEnd}
+      onDragCancel={handleDragCancel}
+    >
+      {/*
+        aria-label BEFORE {...rest} so consumer can pass a more specific
+        label (e.g. "Q3 sales pipeline") and have it win.
+        role="region" AFTER {...rest} so it stays locked — non-overridable
+        semantic guarantee.
+      */}
+      <div
+        ref={ref}
+        aria-label={t('kanban.board')}
+        className={clsx(styles.board, className)}
+        {...rest}
+        role="region"
+      >
+        {columnOrder.map((colId) => {
+          const columnElement = columnElements.get(colId);
+          if (!columnElement) return null;
+
+          const cardIds = effectiveItems.get(colId) ?? [];
+          const cards = cardIds
+            .map((id) => cardElements.get(id))
+            .filter((c): c is ReactElement<KanbanCardProps> => c != null);
+
+          const slice = columnChildrenSlices.get(colId) ?? { before: [], after: [] };
+
+          // Re-clone the column with re-arranged children. KanbanColumn reads
+          // cardIds via KanbanColumnItemsContext so its SortableContext.items
+          // matches what's rendered.
+          return (
+            <KanbanColumnItemsContext.Provider key={colId} value={cardIds}>
+              {cloneElement(columnElement, {}, ...slice.before, ...cards, ...slice.after)}
+            </KanbanColumnItemsContext.Provider>
+          );
+        })}
+      </div>
+    </DndContext>
+  );
+});
+KanbanRoot.displayName = 'Kanban';
+
+// ---------------------------------------------------------------------------
+// Compound export
+// ---------------------------------------------------------------------------
+
+export const Kanban = Object.assign(KanbanRoot, {
+  Column: KanbanColumn,
+  Card: KanbanCard,
+  /**
+   * Re-exported from `<Sortable.Handle>`. Attaches drag listeners when placed
+   * inside a `<Kanban.Card>`. When present, only the Handle initiates drag
+   * (the Card div gets `role="article"`).
+   */
+  Handle: SortableHandle,
+});