@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/Sortable/Sortable.tsx

@@ -0,0 +1,572 @@
+import {
+  Children,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import {
+  closestCenter,
+  DndContext,
+  DragOverlay,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+  type DragStartEvent,
+  type Modifier,
+} from '@dnd-kit/core';
+import {
+  SortableContext,
+  rectSortingStrategy,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable';
+import { CSS, type Transform } from '@dnd-kit/utilities';
+import clsx from 'clsx';
+import { useTranslation } from '../../i18n/useTranslation';
+import { mergeRefs } from '../_internal/refs';
+import { useFloatingSurface } from '../_internal/overlay';
+import {
+  resolveGridItemSpan,
+  resolveCollapsedGridItemSpan,
+  type GridItemSpan,
+} from '../_internal/gridSpan';
+import {
+  CollapseColumnsContext,
+  COLLAPSE_BREAKPOINTS,
+  collapseTrackTemplate,
+  type CollapseBreakpoint,
+  type CollapseColumnsMap,
+} from '../_internal/collapse';
+import { sortableTarget, useDragAccessibility } from '../_internal/dragAnnouncements';
+import styles from './Sortable.module.scss';
+
+/**
+ * Layout arrangement of the sortable items.
+ * - `'list'` (default) — a single vertical column (`verticalListSortingStrategy`).
+ * - `'grid'` — a `columns`-track CSS grid where items carry column spans and
+ *   siblings reflow in 2D during a drag (`rectSortingStrategy`).
+ */
+export type SortableArrangement = 'list' | 'grid';
+
+/**
+ * Payload fired by `onReorder` after a successful drag-drop or keyboard move.
+ * Consumer applies the move via an immutable `arrayMove(items, from, to)`
+ * (3-line utility, not shipped by the library; `@dnd-kit/sortable` ships an
+ * `arrayMove` consumers can import if they want).
+ */
+export interface SortableReorderEvent {
+  from: number;
+  to: number;
+  id: string | number;
+}
+
+/**
+ * Clamp a drag `transform` so the dragged node (`nodeRect`) stays within
+ * `boundingRect`. Pure function mirroring dnd-kit's `restrictToBoundingRect`;
+ * exported so the clamp math can be unit-tested without a real DOM / drag.
+ *
+ * `scaleX` / `scaleY` pass through untouched — only the translation is clamped.
+ */
+export function restrictTransformToRect(
+  transform: Transform,
+  nodeRect: { top: number; bottom: number; left: number; right: number },
+  boundingRect: { top: number; left: number; width: number; height: number },
+): Transform {
+  const value = { ...transform };
+  if (nodeRect.top + transform.y <= boundingRect.top) {
+    value.y = boundingRect.top - nodeRect.top;
+  } else if (nodeRect.bottom + transform.y >= boundingRect.top + boundingRect.height) {
+    value.y = boundingRect.top + boundingRect.height - nodeRect.bottom;
+  }
+  if (nodeRect.left + transform.x <= boundingRect.left) {
+    value.x = boundingRect.left - nodeRect.left;
+  } else if (nodeRect.right + transform.x >= boundingRect.left + boundingRect.width) {
+    value.x = boundingRect.left + boundingRect.width - nodeRect.right;
+  }
+  return value;
+}
+
+export interface SortableProps extends HTMLAttributes<HTMLOListElement> {
+  /**
+   * Fires after a drag or keyboard move with the new position. Consumer
+   * holds the items array and re-renders with the new order.
+   *
+   * Not fired if the drop position equals the source position (no-op).
+   */
+  onReorder?: (event: SortableReorderEvent) => void;
+  /**
+   * When `true` (default), the dragged item is clamped to the list's bounding
+   * box — it can't be dragged outside the `<ol>`. Set `false` for free-drag
+   * (the item can be dragged anywhere on the page). For a vertical list this
+   * constrains the drag vertically to the list's extent.
+   */
+  restrictToContainer?: boolean;
+  /**
+   * Layout arrangement of the items.
+   * - `'list'` (default) — single vertical column; existing behavior unchanged.
+   * - `'grid'` — the `<ol>` becomes a `columns`-track CSS grid. Items carry
+   *   column spans (`Sortable.Item span`), rows are equal-height, and siblings
+   *   reflow in 2D during a drag. Reorder semantics stay order-based (a drop
+   *   reorders the flow; nothing here persists an x/y position).
+   */
+  arrangement?: SortableArrangement;
+  /**
+   * Number of equal-width grid tracks. Only applies when `arrangement="grid"`
+   * (ignored for a list). Default `12`, matching `Grid.Item`'s 12-column
+   * fraction spans (`'25%'`→3 … `'75%'`→9 tracks). Set another count for a
+   * simpler grid, but the named fraction spans then won't map to their
+   * fraction (documented, not validated — same as `Grid`).
+   */
+  columns?: number;
+  /**
+   * Responsive collapse for the grid arrangement — mirrors `Grid`'s
+   * `collapseBelow` exactly (same breakpoints, same container-query
+   * mechanism). Ignored unless `arrangement="grid"`.
+   * - `'sm' | 'md' | 'lg'` — below the container-width threshold (480 / 640 /
+   *   768px of the LIST'S OWN width) every item spans the full row: a single
+   *   visual column.
+   * - `{ lg?: n, md?: n, sm?: n }` — graduated: below each breakpoint the grid
+   *   re-templates to that many columns and item spans clamp to fit (a span
+   *   wider than the step becomes a full row). E.g. `{ md: 6, sm: 1 }`.
+   *
+   * ❌ Anti-pattern: a collapsible Sortable must get its width from its
+   * parent — `container-type: inline-size` zeroes the list's contribution to
+   * intrinsic sizing (same caveat as `Grid`'s `collapseBelow`).
+   *
+   * ⚠️ The map form (and ONLY the map form) wraps the `<ol>` in an extra
+   * `<div>` carrying `container-type: inline-size` — re-templating the `<ol>`
+   * requires querying an ancestor, not the `<ol>` itself. A `> child` selector
+   * aimed at the list from its parent hits that wrapper instead, and layout the
+   * parent applies via `className` lands on the `<ol>` inside it. `ref`,
+   * `className`, `style` and spread props all stay on the `<ol>`.
+   */
+  collapseBelow?: CollapseBreakpoint | CollapseColumnsMap;
+}
+
+export interface SortableItemProps extends Omit<HTMLAttributes<HTMLLIElement>, 'id'> {
+  /**
+   * Stable identifier for this item. Used by dnd-kit for tracking the item
+   * across reorders. String or number — typically the consumer's database id.
+   */
+  id: string | number;
+  /** Item content — typically a `<Card>` or a row of text + icons. */
+  children: ReactNode;
+  /**
+   * Column span, only meaningful under `<Sortable arrangement="grid">`
+   * (ignored in a list). Mirrors `Grid.Item`'s `span` exactly:
+   * - number — `span N` of the grid's `columns`.
+   * - `'25%' | '33%' | '50%' | '67%' | '75%'` — fractions of a 12-column grid.
+   * - `'100%'` / `'full'` — the entire row (`1 / -1`); safe with any `columns`.
+   * Omit for a single track (auto placement).
+   */
+  span?: GridItemSpan;
+}
+
+export interface SortableHandleProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * Decorative content — typically a grip icon (e.g. `<GripVertical size={14} />`).
+   * Rendered inside the Handle's `<button>` wrapped with `aria-hidden`.
+   */
+  children?: ReactNode;
+}
+
+export interface SortableItemContextValue {
+  listeners: ReturnType<typeof useSortable>['listeners'];
+  attributes: ReturnType<typeof useSortable>['attributes'];
+  setActivatorNodeRef: ReturnType<typeof useSortable>['setActivatorNodeRef'];
+}
+
+export const SortableItemContext = createContext<SortableItemContextValue | null>(null);
+
+// Inert context for the DragOverlay clone — the overlay is a static visual; its
+// Handle (if any) must render without wiring real drag listeners.
+const OVERLAY_ITEM_CONTEXT: SortableItemContextValue = {
+  listeners: undefined,
+  attributes: {} as SortableItemContextValue['attributes'],
+  setActivatorNodeRef: () => {},
+};
+
+/**
+ * Recursively check whether the children subtree contains a `Sortable.Handle`.
+ * Used by `Sortable.Item` to decide whether to attach drag listeners to itself
+ * (no Handle present) or rely on the Handle to attach them.
+ *
+ * **Limitation:** only walks `React.Children` and direct `props.children`.
+ * If a consumer wraps `<Sortable.Handle>` inside their own custom component
+ * (e.g. `<TaskRow>` whose JSX internally renders the Handle), the walk sees
+ * `<TaskRow>` but not the Handle inside it — the Item is classified as
+ * no-Handle and gets whole-item drag. Workaround: put `<Sortable.Handle>` at
+ * the same JSX nesting level as the rest of the Item's content.
+ */
+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;
+}
+
+const collapseClass: Record<CollapseBreakpoint, string> = {
+  sm: styles.collapseSm,
+  md: styles.collapseMd,
+  lg: styles.collapseLg,
+};
+const stepClass: Record<CollapseBreakpoint, string> = {
+  sm: styles.stepSm,
+  md: styles.stepMd,
+  lg: styles.stepLg,
+};
+
+const SortableRoot = forwardRef<HTMLOListElement, SortableProps>(function SortableRoot(
+  {
+    onReorder,
+    restrictToContainer = true,
+    arrangement = 'list',
+    columns = 12,
+    collapseBelow,
+    className,
+    style,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const isGrid = arrangement === 'grid';
+  const collapse = isGrid ? collapseBelow : undefined;
+  const collapseMap = typeof collapse === 'object' ? collapse : undefined;
+  const collapseKeys = collapseMap
+    ? COLLAPSE_BREAKPOINTS.filter((b) => collapseMap[b] !== undefined)
+    : [];
+  const [activeId, setActiveId] = useState<string | number | null>(null);
+  // #282: a keyboard drag is an Escape-consuming MODE (Escape cancels the
+  // drag). Register it as a floating surface while active so a host Modal/Drawer
+  // yields that Escape — the drag cancels, the host survives that press.
+  useFloatingSurface(activeId != null);
+  // Internal handle on the <ol> so the restrict modifier can read the live
+  // list rect, independent of whether the consumer forwards a ref.
+  const olRef = useRef<HTMLOListElement | null>(null);
+
+  const itemIds = useMemo(() => {
+    const ids: (string | number)[] = [];
+    Children.forEach(children, (child) => {
+      if (isValidElement(child) && child.type === SortableItem) {
+        ids.push((child.props as SortableItemProps).id);
+      }
+    });
+    return ids;
+  }, [children]);
+
+  // The active item's content, rendered into the DragOverlay clone. Looking it
+  // up by id (rather than capturing a snapshot on drag-start) keeps the overlay
+  // in sync if the consumer's item content re-renders mid-drag.
+  const activeChildren = useMemo<ReactNode>(() => {
+    if (activeId == null) return null;
+    let content: ReactNode = null;
+    Children.forEach(children, (child) => {
+      if (
+        isValidElement(child) &&
+        child.type === SortableItem &&
+        (child.props as SortableItemProps).id === activeId
+      ) {
+        content = (child.props as SortableItemProps).children;
+      }
+    });
+    return content;
+  }, [activeId, children]);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  const handleDragStart = (event: DragStartEvent) => {
+    setActiveId(event.active.id as string | number);
+  };
+
+  const handleDragEnd = (event: DragEndEvent) => {
+    setActiveId(null);
+    const { active, over } = event;
+    if (!over || active.id === over.id) return;
+    const from = itemIds.indexOf(active.id as string | number);
+    const to = itemIds.indexOf(over.id as string | number);
+    if (from < 0 || to < 0) return;
+    onReorder?.({ from, to, id: active.id as string | number });
+  };
+
+  const handleDragCancel = () => {
+    setActiveId(null);
+  };
+
+  // SSR-safe reduced-motion probe; disables the overlay's drop animation.
+  const prefersReducedMotion =
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  // Modifier that confines the drag transform to the live <ol> bounding box.
+  // A modifier is a pure `(args) => Transform`; we read the list rect from the
+  // internal ref rather than dnd-kit's `containerNodeRect` (which is unreliable
+  // through the DragOverlay portal). Memoized once — it closes over the ref,
+  // so it always sees the current node.
+  const restrictModifier = useMemo<Modifier>(
+    () =>
+      ({ transform, draggingNodeRect }) => {
+        const container = olRef.current?.getBoundingClientRect();
+        if (!draggingNodeRect || !container) return transform;
+        return restrictTransformToRect(transform, draggingNodeRect, container);
+      },
+    [],
+  );
+  const modifiers = restrictToContainer ? [restrictModifier] : undefined;
+
+  // Localized screen-reader announcements (Hard rule 9). Every droppable here
+  // IS a sortable item, so dnd-kit's own `data.sortable` supplies the slot and
+  // `sortableTarget` needs no help; the item's name comes from the `aria-label`
+  // / rendered text `<Sortable.Item>` publishes below.
+  const accessibility = useDragAccessibility(sortableTarget);
+
+  const ol = (
+    <ol
+      ref={mergeRefs(olRef, ref)}
+      className={clsx(
+        isGrid ? styles.grid : styles.list,
+        // String form only: those rules query descendants, so the <ol> can be
+        // its own container. The map form's container is the wrapper below.
+        typeof collapse === 'string' && styles.collapsible,
+        typeof collapse === 'string' && collapseClass[collapse],
+        ...collapseKeys.map((b) => stepClass[b]),
+        className,
+      )}
+      // In grid mode the <ol> owns the track template; inject the column
+      // count as a custom prop AFTER the consumer's style so it wins
+      // (mirrors Grid's --grid-columns). List mode leaves style untouched.
+      style={
+        isGrid
+          ? {
+              ...style,
+              ...Object.fromEntries(
+                collapseKeys.map((b) => [
+                  `--sortable-columns-${b}`,
+                  collapseTrackTemplate(collapseMap![b]!),
+                ]),
+              ),
+              ['--sortable-columns' as string]: columns,
+            }
+          : style
+      }
+      {...rest}
+    >
+      {children}
+    </ol>
+  );
+
+  // Map form only: the step rules re-template the <ol> itself, and a container
+  // query never matches its own container — so the size container has to be a
+  // wrapper. `ref`, `className`, `style` and `{...rest}` all stay on the <ol>.
+  const list =
+    collapseMap && collapseKeys.length > 0 ? <div className={styles.stepContainer}>{ol}</div> : ol;
+
+  const tree = (
+    <DndContext
+      accessibility={accessibility}
+      sensors={sensors}
+      modifiers={modifiers}
+      // Grid: closestCenter is dnd-kit's idiomatic pairing for a 2D sortable
+      // grid — the dragged cell reflows to the nearest slot without needing to
+      // physically overlap it (the default rectIntersection requires overlap,
+      // which reads as sticky/unpredictable when cells vary in span). List
+      // keeps the default (undefined) so its behavior is unchanged.
+      collisionDetection={isGrid ? closestCenter : undefined}
+      onDragStart={handleDragStart}
+      onDragEnd={handleDragEnd}
+      onDragCancel={handleDragCancel}
+    >
+      <SortableContext
+        items={itemIds}
+        strategy={isGrid ? rectSortingStrategy : verticalListSortingStrategy}
+      >
+        {list}
+      </SortableContext>
+      {/* The dragged item lives in a portaled, fixed-position overlay that owns
+          the drag + drop animation. The list <li> becomes an invisible
+          placeholder during drag, so a late/async order update from onReorder
+          can never leave a stale dnd-kit transform on a list <li> (#165). The
+          overlay is the *visible* drag, so it must carry the restrict modifier
+          too — DndContext alone constrains the underlying item transform. */}
+      <DragOverlay modifiers={modifiers} dropAnimation={prefersReducedMotion ? null : undefined}>
+        {activeChildren != null ? (
+          <SortableItemContext.Provider value={OVERLAY_ITEM_CONTEXT}>
+            <div className={clsx(styles.item, styles.overlayItem)} data-dragging="true">
+              {activeChildren}
+            </div>
+          </SortableItemContext.Provider>
+        ) : null}
+      </DragOverlay>
+    </DndContext>
+  );
+
+  return collapseMap && collapseKeys.length > 0 ? (
+    <CollapseColumnsContext.Provider value={collapseMap}>{tree}</CollapseColumnsContext.Provider>
+  ) : (
+    tree
+  );
+});
+SortableRoot.displayName = 'Sortable';
+
+/**
+ * One reorderable item in a `<Sortable>`; renders an `<li>` with a stable `id`.
+ * @see docs/components/Sortable.md
+ */
+export const SortableItem = forwardRef<HTMLLIElement, SortableItemProps>(function SortableItem(
+  { id, span, className, children, ...rest },
+  ref,
+) {
+  // Announcement label: the consumer's `aria-label`, else the item's RENDERED
+  // text — so a drag says "Review pricing page mocks, position 2 of 3" instead
+  // of dnd-kit's raw id, and a collapsed menu inside the item contributes
+  // nothing (see `dragLabelOf`).
+  const liRef = useRef<HTMLLIElement | null>(null);
+  const dragLabel = rest['aria-label'];
+  const data = useMemo(() => ({ dragLabel, dragNode: liRef }), [dragLabel]);
+
+  const {
+    setNodeRef,
+    setActivatorNodeRef,
+    listeners,
+    attributes,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({ id, data });
+
+  const hasHandle = useMemo(() => containsHandle(children), [children]);
+
+  const collapseMap = useContext(CollapseColumnsContext);
+
+  const ctxValue = useMemo<SortableItemContextValue>(
+    () => ({ listeners, attributes, setActivatorNodeRef }),
+    [listeners, attributes, setActivatorNodeRef],
+  );
+
+  const setRef = (node: HTMLLIElement | null) => {
+    liRef.current = node;
+    setNodeRef(node);
+    // When no Handle is present, the Item itself is the drag activator —
+    // dnd-kit uses this ref to scope keyboard / pointer events.
+    if (!hasHandle) setActivatorNodeRef(node);
+    if (typeof ref === 'function') ref(node);
+    else if (ref) ref.current = node;
+  };
+
+  return (
+    <SortableItemContext.Provider value={ctxValue}>
+      <li
+        ref={setRef}
+        style={{
+          transform: CSS.Transform.toString(transform),
+          transition,
+          // The DragOverlay renders the dragged item's visual; the in-list copy
+          // is an invisible placeholder so it never carries a stale drag/drop
+          // transform when onReorder commits the new order asynchronously (#165).
+          opacity: isDragging ? 0 : undefined,
+          // Grid-arrangement column span. Always stamped (default 'auto') so a
+          // span-less item never inherits a spanned ancestor's custom property;
+          // ignored by the CSS in list mode (grid-column is inert on a flex
+          // child). Mirrors Grid.Item.
+          ['--sortable-item-span' as string]: resolveGridItemSpan(span) ?? 'auto',
+          // Per-breakpoint clamped span for a graduated (map-form)
+          // `collapseBelow` ancestor — same always-stamp rationale as
+          // `--sortable-item-span` (custom properties inherit).
+          ...(collapseMap
+            ? Object.fromEntries(
+                (Object.keys(collapseMap) as CollapseBreakpoint[]).map((b) => [
+                  `--sortable-item-span-${b}`,
+                  resolveCollapsedGridItemSpan(span, collapseMap[b]!),
+                ]),
+              )
+            : undefined),
+        }}
+        data-dragging={isDragging ? 'true' : undefined}
+        className={clsx(styles.item, className)}
+        // Listeners + attributes go on the Item only when no Handle is present.
+        // When a Handle exists, the Handle attaches them via context.
+        // dnd-kit drag attrs spread BEFORE {...rest} on Item (consumer rest wins).
+        // The Handle does the inverse: drag attrs after rest so they cannot be
+        // disabled. Item is more permissive — consumer may legitimately want to
+        // pre-empt drag on a per-item basis.
+        {...(hasHandle ? {} : listeners)}
+        {...(hasHandle ? {} : attributes)}
+        {...rest}
+      >
+        {children}
+      </li>
+    </SortableItemContext.Provider>
+  );
+});
+SortableItem.displayName = 'SortableItem';
+
+/**
+ * Optional drag-origin marker inside a `<Sortable.Item>`; when present, only the Handle initiates drag.
+ * @see docs/components/Sortable.md
+ */
+export const SortableHandle = forwardRef<HTMLButtonElement, SortableHandleProps>(
+  function SortableHandle({ className, children, 'aria-label': ariaLabel, ...rest }, ref) {
+    const t = useTranslation();
+    const ctx = useContext(SortableItemContext);
+    if (!ctx) {
+      throw new Error('<Sortable.Handle> must be rendered inside a <Sortable.Item>.');
+    }
+
+    const setRef = (node: HTMLButtonElement | null) => {
+      ctx.setActivatorNodeRef(node);
+      if (typeof ref === 'function') ref(node);
+      else if (ref) ref.current = node;
+    };
+
+    return (
+      <button
+        ref={setRef}
+        type="button"
+        aria-label={ariaLabel || t('drag.handleLabel')}
+        className={clsx(styles.handle, className)}
+        {...rest}
+        // {...listeners} + {...attributes} AFTER {...rest} so consumer spread
+        // cannot disable drag detection. data-sortable-handle is a structural
+        // marker for tests / styling.
+        data-sortable-handle="true"
+        {...ctx.listeners}
+        {...ctx.attributes}
+      >
+        <span aria-hidden="true">{children}</span>
+      </button>
+    );
+  },
+);
+SortableHandle.displayName = 'SortableHandle';
+
+/**
+ * Drag-to-reorder list (single column) with `Sortable.Item` and `Sortable.Handle`, in list or grid arrangement.
+ * @see docs/components/Sortable.md
+ */
+export const Sortable = Object.assign(SortableRoot, {
+  Item: SortableItem,
+  Handle: SortableHandle,
+});

package/src/components/Sortable/containerAwareCollision.ts

@@ -0,0 +1,125 @@
+// Container-aware collision detection for multi-container sortable boards
+// (Kanban, SortableGroup). Pure function so it's unit-testable with synthetic
+// rects; imported by both components' DndContexts.
+import {
+  closestCorners,
+  pointerWithin,
+  type CollisionDetection,
+  type DroppableContainer,
+} from '@dnd-kit/core';
+
+/**
+ * A CONTAINER droppable (a `<Kanban.Column>` / `<SortableGroup.Group>`) as
+ * opposed to an ITEM droppable (a card). Containers register via plain
+ * `useDroppable`, so they carry no `data.sortable`; items register via
+ * `useSortable`, which adds it.
+ */
+const isContainer = (droppable: DroppableContainer) => droppable.data.current?.sortable == null;
+
+/**
+ * `closestCorners`, but the pointer's containing container wins first.
+ *
+ * Why: with plain `closestCorners`, every card registers as a droppable
+ * alongside the column containers, and ranking is by corner distance of the
+ * DRAGGED RECT — not by where the pointer is. Next to a tall column, an
+ * empty/sparse sibling column stretches (flex align-items: stretch) far
+ * beyond its content, so its corners sit hundreds of pixels from the dragged
+ * card while a same-Y card in the SOURCE column sits one column-gap away.
+ * The source card out-ranks the geometrically-containing target column, the
+ * cross-column transit is never detected, and the drop silently resolves as
+ * a same-column no-op (#367).
+ *
+ * Strategy:
+ * 1. No pointer (keyboard drags pass `pointerCoordinates: null`) → plain
+ *    `closestCorners` over everything — keyboard behavior unchanged.
+ * 2. Find the container droppable the pointer is inside (`pointerWithin`
+ *    over containers only). Containers are droppables registered via plain
+ *    `useDroppable` — they carry no `data.sortable`; card/item droppables
+ *    registered via `useSortable` do.
+ * 3. Pointer inside a container → rank with `closestCorners` restricted to
+ *    that container plus the droppables whose center lies inside it (its own
+ *    cards). An empty column is its only candidate, so it wins; over a card,
+ *    the card wins; below the last card, the nearest of card/column wins —
+ *    both resolve to "append" downstream.
+ * 4. Pointer in no container (board gap / outside) → plain `closestCorners`.
+ */
+export const containerAwareClosestCorners: CollisionDetection = (args) => {
+  const { droppableContainers, droppableRects, pointerCoordinates } = args;
+  if (!pointerCoordinates) return closestCorners(args);
+
+  const containers = droppableContainers.filter(isContainer);
+  const within = pointerWithin({ ...args, droppableContainers: containers });
+  const containerId = within[0]?.id;
+  const containerRect = containerId != null ? droppableRects.get(containerId) : undefined;
+  if (containerId == null || !containerRect) return closestCorners(args);
+
+  const candidates = droppableContainers.filter((d) => {
+    if (d.id === containerId) return true;
+    const rect = droppableRects.get(d.id);
+    if (!rect) return false;
+    const cx = rect.left + rect.width / 2;
+    const cy = rect.top + rect.height / 2;
+    return (
+      cx >= containerRect.left &&
+      cx <= containerRect.right &&
+      cy >= containerRect.top &&
+      cy <= containerRect.bottom
+    );
+  });
+  return closestCorners({ ...args, droppableContainers: candidates });
+};
+
+/**
+ * True when the pointer sits outside the collective bounding box of every
+ * CONTAINER droppable — i.e. the drag is over unrelated page content rather
+ * than over the board. Callers use it to reject a drop that collision
+ * detection nonetheless resolved to a container (#387).
+ *
+ * It has to be asked separately because no collision detector can answer it:
+ * `closestCorners` — which `containerAwareClosestCorners` falls back to
+ * whenever the pointer is in no container — pushes a collision for EVERY
+ * measured droppable and uses distance only to rank them, never to reject. So
+ * `over` is never null, and "released nowhere" is indistinguishable from
+ * "released on the nearest column" from the drop handler's side.
+ *
+ * Collective bounding box, not each container's own rect: a board with a `gap`
+ * between columns has pointer positions inside the board but inside no column.
+ * Per-rect testing would cancel those, and a release in a 12px gutter means the
+ * column beside it — which is exactly what `closestCorners` returns. Only
+ * leaving the band of columns entirely is a cancel. Containers only (never the
+ * cards') so a pointer in a sparse column's empty space stays a valid drop,
+ * which is the whole point of #367.
+ *
+ * Returns false whenever it cannot tell — no pointer (keyboard drags pass
+ * `pointerCoordinates: null`) or nothing measured (jsdom lays nothing out) —
+ * so an unmeasurable board keeps committing to the nearest container instead of
+ * cancelling every drop.
+ */
+export function isPointerOutsideContainers({
+  droppableContainers,
+  droppableRects,
+  pointerCoordinates,
+}: Pick<
+  Parameters<CollisionDetection>[0],
+  'droppableContainers' | 'droppableRects' | 'pointerCoordinates'
+>): boolean {
+  if (!pointerCoordinates) return false;
+
+  let left = Infinity;
+  let top = Infinity;
+  let right = -Infinity;
+  let bottom = -Infinity;
+  for (const droppable of droppableContainers) {
+    if (!isContainer(droppable)) continue;
+    const rect = droppableRects.get(droppable.id);
+    if (!rect) continue;
+    left = Math.min(left, rect.left);
+    top = Math.min(top, rect.top);
+    right = Math.max(right, rect.right);
+    bottom = Math.max(bottom, rect.bottom);
+  }
+  if (left === Infinity) return false;
+
+  const { x, y } = pointerCoordinates;
+  return x < left || x > right || y < top || y > bottom;
+}