@allbluecn/web-app 0.18.2 → 0.19.0

package/src/components/reui/kanban.tsx

@@ -0,0 +1,1227 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import * as React from "react"
+import type { CSSProperties, ReactNode } from "react"
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  useEffect,
+} from "react"
+import { mergeProps } from "@base-ui/react/merge-props"
+import { useRender } from "@base-ui/react/use-render"
+import type {
+  Active,
+  CollisionDetection,
+  DragCancelEvent,
+  DragEndEvent,
+  DragMoveEvent,
+  DragOverEvent,
+  DragStartEvent,
+  DropAnimation,
+  Modifiers,
+  Over,
+  UniqueIdentifier,
+} from "@dnd-kit/core"
+import {
+  closestCenter,
+  DndContext,
+  DragOverlay,
+  getFirstCollision,
+  MeasuringStrategy,
+  MouseSensor,
+  pointerWithin,
+  rectIntersection,
+  TouchSensor,
+  useSensor,
+  useSensors,
+  type DraggableAttributes,
+  type DraggableSyntheticListeners,
+} from "@dnd-kit/core"
+import {
+  arrayMove,
+  defaultAnimateLayoutChanges,
+  rectSortingStrategy,
+  SortableContext,
+  useSortable,
+  verticalListSortingStrategy,
+  type AnimateLayoutChanges,
+} from "@dnd-kit/sortable"
+import { CSS } from "@dnd-kit/utilities"
+import { createPortal } from "react-dom"
+
+import { cn } from "@/lib/utils"
+
+import {
+  KanbanKeyboardSensor,
+  makeKanbanKeyboardCoordinateGetter,
+} from "./kanban-keyboard"
+
+interface KanbanDataContextProps<T> {
+  columns: Record<string, T[]>
+  setColumns: (columns: Record<string, T[]>) => void
+  getItemId: (item: T) => string
+  columnIds: string[]
+  findContainer: (id: UniqueIdentifier) => string | undefined
+}
+
+/**
+ * 拖拽状态与数据状态分居两个 context：`columns` 在每次 onDragOver 都换新对象，
+ * 而 `activeId` 只在拖拽起止变化。同处一个 context 时，只读 `activeId` 的
+ * KanbanItem/KanbanColumn 会被列内容更新拖着整板重渲染（大看板下是主要开销）。
+ */
+interface KanbanDragContextProps {
+  activeId: UniqueIdentifier | null
+  isColumn: (id: UniqueIdentifier) => boolean
+  modifiers?: Modifiers
+}
+
+const KanbanDataContext = createContext<KanbanDataContextProps<any>>({
+  columns: {},
+  setColumns: () => {},
+  getItemId: () => "",
+  columnIds: [],
+  findContainer: () => undefined,
+})
+
+const KanbanDragContext = createContext<KanbanDragContextProps>({
+  activeId: null,
+  isColumn: () => false,
+  modifiers: undefined,
+})
+
+const ColumnContext = createContext<{
+  attributes: DraggableAttributes
+  listeners: DraggableSyntheticListeners | undefined
+  isDragging?: boolean
+  disabled?: boolean
+}>({
+  attributes: {} as DraggableAttributes,
+  listeners: undefined,
+  isDragging: false,
+  disabled: false,
+})
+
+const ItemContext = createContext<{
+  listeners: DraggableSyntheticListeners | undefined
+  isDragging?: boolean
+  disabled?: boolean
+}>({
+  listeners: undefined,
+  isDragging: false,
+  disabled: false,
+})
+
+const IsOverlayContext = createContext(false)
+
+/**
+ * 拖拽落点指示：拖拽期由 Kanban 写入目标列 + 插入位，列内容按列订阅后渲染落点槽、
+ * 并用 transform 让位（不插入 DOM、不改数据）。
+ *
+ * 为什么不用 context state：context 更新会穿透 memo 让整板列内容一起重渲染
+ * （200 卡下即卡顿）；外部 store + 按列选取器让非目标列拿到稳定的 null，
+ * 完全不参与重渲染。也不能用「插入真实占位元素」的写法：布局变化会触发
+ * dnd-kit 的 droppable 重测（拖拽期 queue 已空 → 全量 re-measure），
+ * 同样卡顿；transform 不触发布局，故最稳。
+ */
+export interface KanbanDropIndicator {
+  /** 目标列 key */
+  container: string
+  /** 目标列当前顺序中的插入下标（0..len） */
+  insertIndex: number
+  /** 拖拽起始列 */
+  sourceContainer: string
+  /** 拖拽起始下标（同列原位判定用） */
+  sourceIndex: number
+  /** 拖拽卡高度（px）：落点槽高度与让位位移都用它 */
+  height: number
+  /** 被拖卡片的 item key：落点处渲染同款淡化卡 */
+  itemId: string
+  /** 落点 hover 到的卡（或列）的 id：用于判断落在哪张卡上/哪一子分组末尾 */
+  overItemKey: string
+}
+
+/** 按列取用的视图数据；非目标列恒为 null（引用稳定 → 不触发重渲染） */
+export interface KanbanDropIndicatorView {
+  insertIndex: number
+  height: number
+  /** 被拖卡片的 item key */
+  itemId: string
+  /** 落点 hover 到的卡（或列）的 id */
+  overItemKey: string
+}
+
+interface KanbanDropIndicatorStore {
+  subscribe: (listener: () => void) => () => void
+  set: (state: KanbanDropIndicator | null) => void
+  getForColumn: (column: string) => KanbanDropIndicatorView | null
+}
+
+/** 落点指示器 store 工厂：导出供测试与自定义落点渲染使用 */
+export function createDropIndicatorStore(): KanbanDropIndicatorStore {
+  let state: KanbanDropIndicator | null = null
+  let derivedColumn: string | null = null
+  let derivedView: KanbanDropIndicatorView | null = null
+  const listeners = new Set<() => void>()
+  const publish = () => {
+    derivedColumn = state ? state.container : null
+    derivedView = state
+      ? {
+          insertIndex: state.insertIndex,
+          height: state.height,
+          itemId: state.itemId,
+          overItemKey: state.overItemKey,
+        }
+      : null
+    listeners.forEach((listener) => listener())
+  }
+  return {
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    set(next) {
+      if (next === null) {
+        if (state === null) return
+        state = null
+        publish()
+        return
+      }
+      // onDragMove 每帧调用：仅在目标列 / 插入位 / 卡高变化时才通知
+      const prev = state
+      if (
+        prev !== null &&
+        prev.container === next.container &&
+        prev.insertIndex === next.insertIndex &&
+        prev.height === next.height &&
+        prev.itemId === next.itemId &&
+        prev.overItemKey === next.overItemKey
+      ) {
+        return
+      }
+      state = next
+      publish()
+    },
+    getForColumn(column) {
+      return derivedColumn === column ? derivedView : null
+    },
+  }
+}
+
+const KanbanDropIndicatorContext =
+  createContext<KanbanDropIndicatorStore | null>(null)
+
+export function useKanbanDropIndicator(
+  column: string
+): KanbanDropIndicatorView | null {
+  const store = useContext(KanbanDropIndicatorContext)
+  const getSnapshot = useCallback(
+    () => (store ? store.getForColumn(column) : null),
+    [store, column]
+  )
+  return useSyncExternalStore(
+    store ? store.subscribe : subscribeToNothing,
+    getSnapshot,
+    getSnapshot
+  )
+}
+
+const animateLayoutChanges: AnimateLayoutChanges = (args) =>
+  defaultAnimateLayoutChanges({ ...args, wasDragging: true })
+
+// drop 后 overlay 的收尾动画必须关掉：默认动画把 overlay 从指针位置平移回
+// activeNodeRect（源卡片位置），而源卡片在拖拽期已经不再移动，动画会先把卡片
+// 「飞回原位」再跳到落点列。落位由 drop 时的 re-render 直接呈现，无动画更准。
+const dropAnimationConfig: DropAnimation | null = null
+
+/**
+ * Client-mount gate for the `createPortal` call in KanbanOverlay, which needs
+ * `document.body` and so must not run on the server or during hydration.
+ */
+const subscribeToNothing = () => () => {}
+const getIsMounted = () => true
+const getIsMountedOnServer = () => false
+
+const MOUSE_SENSOR_OPTIONS = { activationConstraint: { distance: 10 } }
+const TOUCH_SENSOR_OPTIONS = {
+  activationConstraint: { delay: 250, tolerance: 5 },
+}
+const MEASURING_CONFIG = {
+  droppable: { strategy: MeasuringStrategy.WhileDragging },
+}
+
+export interface KanbanMoveEvent {
+  event: DragEndEvent
+  activeContainer: string
+  activeIndex: number
+  overContainer: string
+  overIndex: number
+}
+
+export interface KanbanCommitMeta<T> {
+  kind: "item" | "column"
+  event: DragEndEvent
+  activeContainer: string
+  activeIndex: number
+  overContainer: string
+  overIndex: number
+  previousValue: Record<string, T[]>
+}
+
+export interface KanbanRootProps<T> extends Omit<
+  useRender.ComponentProps<"div">,
+  "children" | "onDragStart" | "onDragEnd"
+> {
+  value: Record<string, T[]>
+  onValueChange: (value: Record<string, T[]>) => void
+  getItemValue: (item: T) => string
+  children: ReactNode
+  onMove?: (event: KanbanMoveEvent) => void
+  onValueCommit?: (
+    value: Record<string, T[]>,
+    meta: KanbanCommitMeta<T>
+  ) => void
+  restoreOnCancel?: boolean
+  onDragStart?: (event: DragStartEvent) => void
+  onDragEnd?: (event: DragEndEvent) => void
+  onDragCancel?: (event?: DragCancelEvent) => void
+  accessibility?: React.ComponentProps<typeof DndContext>["accessibility"]
+  modifiers?: Modifiers
+}
+
+function Kanban<T>({
+  value,
+  onValueChange,
+  getItemValue,
+  children,
+  className,
+  render,
+  onMove,
+  onValueCommit,
+  restoreOnCancel = false,
+  onDragStart,
+  onDragEnd,
+  onDragCancel,
+  accessibility,
+  modifiers,
+  ...props
+}: KanbanRootProps<T>) {
+  const columns = value
+  const setColumns = onValueChange
+  const [activeId, setActiveId] = useState<UniqueIdentifier | null>(null)
+  // 落点指示器的外部 store：列内容按列订阅，非目标列不参与重渲染（见 createDropIndicatorStore）
+  const [dropIndicatorStore] = useState(createDropIndicatorStore)
+
+  // Always-current mirrors so the drag handlers can read fresh values without
+  // widening their dependency arrays (keeps handler identity stable).
+  const valueRef = useRef(value)
+  const getItemValueRef = useRef(getItemValue)
+  useLayoutEffect(() => {
+    valueRef.current = value
+    getItemValueRef.current = getItemValue
+  })
+  // 被拖卡片在「列内」的真实高度：dnd-kit 的 active/over rect 都取自 DragOverlay 节点
+  // （overlay 用 w-72，比列内卡宽 16px → 少折一行、矮 ~20px），直接用会让位步长与落点
+  // 淡化卡高度对不齐（实测重叠 11px）。拖拽开始时从激活事件的目标节点量一次即可。
+  const dragHeightRef = useRef(0)
+  // Esc 软取消标记：pointer 传感器不处理 Esc（dnd-kit 只在键盘传感器实现），
+  // 这里自己补：Esc 时清空拖拽视觉态，等真实 mouseup 触发的 handleDragEnd 跳过提交
+  const cancelledRef = useRef(false)
+  const dragOriginRef = useRef<{
+    value: Record<string, T[]>
+    container: string | undefined
+    index: number
+  } | null>(null)
+
+  const columnIds = useMemo(() => {
+    const keys = Object.keys(columns)
+    if (process.env.NODE_ENV !== "production") {
+      const seen = new Set<string>()
+      for (const key of keys) {
+        for (const item of columns[key]) {
+          const itemId = getItemValue(item)
+          if (seen.has(itemId)) {
+            console.warn(
+              `[Kanban] Duplicate item id "${itemId}". Item ids must be unique across all columns, or drag and drop will misbehave.`
+            )
+            break
+          }
+          seen.add(itemId)
+        }
+      }
+    }
+    return keys
+  }, [columns, getItemValue])
+
+  const isColumn = useCallback(
+    (id: UniqueIdentifier) => columnIds.includes(id as string),
+    [columnIds]
+  )
+
+  const keyboardCoordinateGetter = useMemo(
+    () => makeKanbanKeyboardCoordinateGetter(isColumn),
+    [isColumn]
+  )
+
+  const sensors = useSensors(
+    useSensor(MouseSensor, MOUSE_SENSOR_OPTIONS),
+    useSensor(TouchSensor, TOUCH_SENSOR_OPTIONS),
+    // 键盘传感器为 fork 内实现（kanban-keyboard.ts）：上游对视口外目标「只滚动不
+    // 下发 move」，窄屏下列拖拽原地踏步（#470）
+    useSensor(KanbanKeyboardSensor, { coordinateGetter: keyboardCoordinateGetter })
+  )
+
+  const findContainer = useCallback(
+    (id: UniqueIdentifier) => {
+      if (isColumn(id)) return id as string
+      return columnIds.find((key) =>
+        columns[key].some((item) => getItemValue(item) === id)
+      )
+    },
+    [columns, columnIds, getItemValue, isColumn]
+  )
+
+  // The droppable under the pointer, not the one the dragged rect overlaps most.
+  const lastOverIdRef = useRef<UniqueIdentifier | null>(null)
+  const collisionDetection = useCallback<CollisionDetection>(
+    (args) => {
+      if (isColumn(args.active.id)) {
+        return closestCenter({
+          ...args,
+          droppableContainers: args.droppableContainers.filter((container) =>
+            isColumn(container.id)
+          ),
+        })
+      }
+
+      // Keyboard drags carry no pointer.
+      if (!args.pointerCoordinates) return rectIntersection(args)
+
+      let overId = getFirstCollision(pointerWithin(args), "id")
+      if (overId != null) {
+        // Over a column's empty space: resolve to its closest item, if any.
+        if (isColumn(overId)) {
+          const itemIds = new Set(columns[overId as string].map(getItemValue))
+          overId =
+            closestCenter({
+              ...args,
+              droppableContainers: args.droppableContainers.filter(
+                (container) => itemIds.has(container.id as string)
+              ),
+            })[0]?.id ?? overId
+        }
+        lastOverIdRef.current = overId
+        return [{ id: overId }]
+      }
+
+      // Between droppables: hold the last target so the preview stays put.
+      return lastOverIdRef.current != null
+        ? [{ id: lastOverIdRef.current }]
+        : rectIntersection(args)
+    },
+    [columns, getItemValue, isColumn]
+  )
+
+  const commitChange = useCallback(
+    (
+      finalValue: Record<string, T[]>,
+      event: DragEndEvent,
+      kind: "item" | "column"
+    ) => {
+      if (!onValueCommit) return
+      const origin = dragOriginRef.current
+      if (!origin) return
+
+      const id = event.active.id
+
+      if (kind === "column") {
+        const keys = Object.keys(finalValue)
+        const overIndex = keys.indexOf(id as string)
+        if (overIndex === -1 || overIndex === origin.index) return
+        onValueCommit(finalValue, {
+          kind: "column",
+          event,
+          activeContainer: id as string,
+          activeIndex: origin.index,
+          overContainer: String(event.over?.id ?? id),
+          overIndex,
+          previousValue: origin.value,
+        })
+        return
+      }
+
+      const getId = getItemValueRef.current
+      let overContainer: string | undefined
+      let overIndex = -1
+      for (const key of Object.keys(finalValue)) {
+        const found = finalValue[key].findIndex((item) => getId(item) === id)
+        if (found !== -1) {
+          overContainer = key
+          overIndex = found
+          break
+        }
+      }
+      if (overContainer === undefined) return
+      if (overContainer === origin.container && overIndex === origin.index) {
+        return
+      }
+      onValueCommit(finalValue, {
+        kind: "item",
+        event,
+        activeContainer: origin.container ?? overContainer,
+        activeIndex: origin.index,
+        overContainer,
+        overIndex,
+        previousValue: origin.value,
+      })
+    },
+    [onValueCommit]
+  )
+
+  /**
+   * 解析落点插入位（目标列当前顺序中的下标）。
+   * 拖拽卡中心越过 hover 卡中线 → 插到它下面（+1）。落点指示与 drop 提交必须共用
+   * 同一份解析：否则「看到的淡化卡位置」与「真正落库的位置」会差一位，跨子分组时
+   * 就会落到相邻子分组里。
+   */
+  const resolveInsertIndex = useCallback(
+    (active: Active, over: Over): number | null => {
+      const overItems = columns[findContainer(over.id) ?? ""]
+      if (!overItems) return null
+      if (isColumn(over.id)) return overItems.length
+      const overIndex = overItems.findIndex(
+        (item: T) => getItemValue(item) === over.id
+      )
+      if (overIndex === -1) return null
+      const translated = active.rect.current.translated
+      const below =
+        translated != null &&
+        translated.top + translated.height / 2 >
+          over.rect.top + over.rect.height / 2
+      return below ? overIndex + 1 : overIndex
+    },
+    [columns, findContainer, getItemValue, isColumn]
+  )
+
+  /**
+   * 计算并发布拖拽落点（目标列 + 插入位）。只读 dnd-kit 事件里已测好的 rect
+   * （`over.rect` 是拖拽开始时的测量值，不会被落点槽的 transform 影响），
+   * 因此不会产生「插入 → 位置变化 → 落点抖动」的反馈环，也不需要额外的
+   * getBoundingClientRect（整板测量是拖拽卡顿的主因之一）。
+   */
+  const updateDropIndicator = useCallback(
+    (event: DragMoveEvent | DragOverEvent) => {
+      const { active, over } = event
+      if (!over || isColumn(active.id)) {
+        dropIndicatorStore.set(null)
+        return
+      }
+      const activeContainer = findContainer(active.id)
+      const overContainer = findContainer(over.id)
+      if (!activeContainer || !overContainer) {
+        dropIndicatorStore.set(null)
+        return
+      }
+      const insertIndex = resolveInsertIndex(active, over)
+      if (insertIndex === null) {
+        dropIndicatorStore.set(null)
+        return
+      }
+      const activeItems = columns[activeContainer] ?? []
+      const sourceIndex = activeItems.findIndex(
+        (item) => getItemValue(item) === active.id
+      )
+      // 同列且落回原位（插入点等于自身位置或紧邻其后）→ 不显示落点
+      if (
+        activeContainer === overContainer &&
+        (insertIndex === sourceIndex || insertIndex === sourceIndex + 1)
+      ) {
+        dropIndicatorStore.set(null)
+        return
+      }
+      dropIndicatorStore.set({
+        container: overContainer,
+        insertIndex,
+        sourceContainer: activeContainer,
+        sourceIndex,
+        itemId: String(active.id),
+        overItemKey: String(over.id),
+        height: dragHeightRef.current,
+      })
+    },
+    [columns, dropIndicatorStore, findContainer, getItemValue, isColumn, resolveInsertIndex]
+  )
+
+  // Esc 取消拖拽（pointer 拖拽）：清视觉态 + 打标记，mouseup 时按取消收尾
+  useEffect(() => {
+    if (activeId === null) return
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape" && event.code !== "Escape") return
+      if (cancelledRef.current) return
+      cancelledRef.current = true
+      const origin = dragOriginRef.current
+      if (restoreOnCancel && origin && !onMove) {
+        setColumns(origin.value)
+      }
+      dropIndicatorStore.set(null)
+      lastOverIdRef.current = null
+      setActiveId(null)
+      onDragCancel?.()
+    }
+    document.addEventListener("keydown", onKeyDown)
+    return () => document.removeEventListener("keydown", onKeyDown)
+  }, [activeId, restoreOnCancel, onMove, setColumns, dropIndicatorStore, onDragCancel])
+
+  const handleDragStart = useCallback(
+    (event: DragStartEvent) => {
+      lastOverIdRef.current = null
+      dropIndicatorStore.set(null)
+      const activator = event.activatorEvent as Event | null
+      const target = (activator?.target ?? null) as Element | null
+      const cardEl = target?.closest?.('[data-slot="kanban-item"]')
+      dragHeightRef.current = cardEl instanceof HTMLElement ? cardEl.offsetHeight : 0
+      setActiveId(event.active.id)
+      onDragStart?.(event)
+
+      if (onValueCommit || restoreOnCancel) {
+        const snapshot = valueRef.current
+        const id = event.active.id
+        const keys = Object.keys(snapshot)
+        if (keys.includes(id as string)) {
+          dragOriginRef.current = {
+            value: snapshot,
+            container: id as string,
+            index: keys.indexOf(id as string),
+          }
+        } else {
+          const getId = getItemValueRef.current
+          let container: string | undefined
+          let index = -1
+          for (const key of keys) {
+            const found = snapshot[key].findIndex((item) => getId(item) === id)
+            if (found !== -1) {
+              container = key
+              index = found
+              break
+            }
+          }
+          dragOriginRef.current = { value: snapshot, container, index }
+        }
+      }
+    },
+    [dropIndicatorStore, onDragStart, onValueCommit, restoreOnCancel]
+  )
+
+  // 拖拽期不做任何顺序变更：每次 dragOver 提交都会让 dnd-kit 的 useDerivedTransform
+  // 在 render 阶段逐项 getClientRect，强制刷新已脏的整板布局（实测每次提交固定
+  // 100–155ms 长任务，板内 200 卡 / 16k 节点），拖拽中的重排节点数越多越卡。
+  // 顺序变更统一推迟到 drop 时一次性提交（见 handleDragEnd），拖拽期仅由 transform
+  // 与 DragOverlay 提供视觉反馈。
+
+  const handleDragCancel = useCallback(
+    (event: DragCancelEvent) => {
+      const origin = dragOriginRef.current
+
+      // 拖拽期已不改写顺序，正常取消无需恢复；仅在拖拽期间值确实被整体替换
+      // （服务端刷新、或上游插入幽灵空列）时才回滚快照。
+      if (
+        restoreOnCancel &&
+        origin &&
+        !onMove &&
+        origin.value !== valueRef.current
+      ) {
+        setColumns(origin.value)
+      }
+
+      dragOriginRef.current = null
+      lastOverIdRef.current = null
+      dropIndicatorStore.set(null)
+      setActiveId(null)
+      onDragCancel?.(event)
+    },
+    [dropIndicatorStore, restoreOnCancel, onMove, setColumns, onDragCancel]
+  )
+
+  const handleDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event
+      lastOverIdRef.current = null
+      dropIndicatorStore.set(null)
+      if (cancelledRef.current) {
+        // Esc 已取消：视觉态在 Esc 时已清，这里只需丢弃这次提交
+        cancelledRef.current = false
+        dragOriginRef.current = null
+        setActiveId(null)
+        return
+      }
+      setActiveId(null)
+      onDragEnd?.(event)
+
+      if (!over) {
+        // Released over nothing. In default mode the live preview during
+        // dragOver may have already moved the item, so commit the current value.
+        commitChange(valueRef.current, event, "item")
+        dragOriginRef.current = null
+        return
+      }
+
+      // Handle item move callback
+      if (onMove && !isColumn(active.id)) {
+        const activeContainer = findContainer(active.id)
+        const overContainer = findContainer(over.id)
+
+        if (activeContainer && overContainer) {
+          const activeIndex = columns[activeContainer].findIndex(
+            (item: T) => getItemValue(item) === active.id
+          )
+          const overIndex = isColumn(over.id)
+            ? columns[overContainer].length
+            : columns[overContainer].findIndex(
+                (item: T) => getItemValue(item) === over.id
+              )
+
+          onMove({
+            event,
+            activeContainer,
+            activeIndex,
+            overContainer,
+            overIndex,
+          })
+        }
+        // In onMove mode the consumer owns applying the item move, so do not
+        // fire onValueCommit for item moves; column reorders still commit below.
+        dragOriginRef.current = null
+        return
+      }
+
+      // Handle column reordering
+      if (isColumn(active.id) && isColumn(over.id)) {
+        const activeIndex = columnIds.indexOf(active.id as string)
+        const overIndex = columnIds.indexOf(over.id as string)
+        if (activeIndex !== overIndex) {
+          const newOrder = arrayMove(
+            Object.keys(columns),
+            activeIndex,
+            overIndex
+          )
+          const newColumns: Record<string, T[]> = {}
+          newOrder.forEach((key) => {
+            newColumns[key] = columns[key]
+          })
+          setColumns(newColumns)
+          commitChange(newColumns, event, "column")
+        }
+        dragOriginRef.current = null
+        return
+      }
+
+      // A column drag that ends over a non-column droppable is not an item move.
+      if (isColumn(active.id)) {
+        dragOriginRef.current = null
+        return
+      }
+
+      const activeContainer = findContainer(active.id)
+      const overContainer = findContainer(over.id)
+
+      // Handle item reordering within the same column
+      if (
+        activeContainer &&
+        overContainer &&
+        activeContainer === overContainer
+      ) {
+        const container = activeContainer
+        const activeIndex = columns[container].findIndex(
+          (item: T) => getItemValue(item) === active.id
+        )
+        // 与落点指示共用插入位解析（含「越过中线插到下面」），否则提交位置与
+        // 用户看到的淡化卡位置差一位
+        const rawIndex = resolveInsertIndex(active, over)
+        const insertIndex =
+          rawIndex === null ? activeIndex : rawIndex
+        if (activeIndex !== -1 && insertIndex !== activeIndex) {
+          const items = [...columns[container]]
+          const [moved] = items.splice(activeIndex, 1)
+          items.splice(
+            insertIndex > activeIndex ? insertIndex - 1 : insertIndex,
+            0,
+            moved
+          )
+          const newColumns = { ...columns, [container]: items }
+          setColumns(newColumns)
+          commitChange(newColumns, event, "item")
+        } else {
+          commitChange(columns, event, "item")
+        }
+      } else if (activeContainer && overContainer) {
+        // 跨列落位：拖拽期不再即时改写顺序，改为在这里一次性提交
+        const activeItems = columns[activeContainer]
+        const overItems = columns[overContainer]
+
+        const activeIndex = activeItems.findIndex(
+          (item: T) => getItemValue(item) === active.id
+        )
+        const overIndex = resolveInsertIndex(active, over)
+
+        if (activeIndex === -1 || overIndex === null) {
+          commitChange(columns, event, "item")
+        } else {
+          const newActiveItems = [...activeItems]
+          const newOverItems = [...overItems]
+          const [movedItem] = newActiveItems.splice(activeIndex, 1)
+          newOverItems.splice(overIndex, 0, movedItem)
+          const newColumns = {
+            ...columns,
+            [activeContainer]: newActiveItems,
+            [overContainer]: newOverItems,
+          }
+          setColumns(newColumns)
+          commitChange(newColumns, event, "item")
+        }
+      } else {
+        commitChange(columns, event, "item")
+      }
+      dragOriginRef.current = null
+    },
+    [
+      columnIds,
+      columns,
+      findContainer,
+      getItemValue,
+      isColumn,
+      setColumns,
+      onMove,
+      onDragEnd,
+      commitChange,
+      dropIndicatorStore,
+      resolveInsertIndex,
+    ]
+  )
+
+  const dataContextValue = useMemo(
+    () => ({
+      columns,
+      setColumns,
+      getItemId: getItemValue,
+      columnIds,
+      findContainer,
+    }),
+    [columns, setColumns, getItemValue, columnIds, findContainer]
+  )
+
+  const dragContextValue = useMemo(
+    () => ({ activeId, isColumn, modifiers }),
+    [activeId, isColumn, modifiers]
+  )
+
+  const defaultProps = {
+    "data-slot": "kanban",
+    "data-dragging": activeId !== null,
+    className: cn(activeId !== null && "cursor-grabbing!", className),
+    children,
+  }
+
+  return (
+    <KanbanDragContext.Provider value={dragContextValue}>
+      <KanbanDataContext.Provider value={dataContextValue}>
+        <KanbanDropIndicatorContext.Provider value={dropIndicatorStore}>
+        <DndContext
+          sensors={sensors}
+          modifiers={modifiers}
+          accessibility={accessibility}
+          measuring={MEASURING_CONFIG}
+          collisionDetection={collisionDetection}
+          onDragStart={handleDragStart}
+          onDragMove={updateDropIndicator}
+          onDragOver={updateDropIndicator}
+          onDragEnd={handleDragEnd}
+          onDragCancel={handleDragCancel}
+        >
+          {useRender({
+            defaultTagName: "div",
+            render,
+            props: mergeProps<"div">(defaultProps, props),
+          })}
+        </DndContext>
+        </KanbanDropIndicatorContext.Provider>
+      </KanbanDataContext.Provider>
+    </KanbanDragContext.Provider>
+  )
+}
+
+export type KanbanBoardProps = useRender.ComponentProps<"div">
+
+function KanbanBoard({ className, render, ...props }: KanbanBoardProps) {
+  const { columnIds } = useContext(KanbanDataContext)
+
+  const defaultProps = {
+    "data-slot": "kanban-board",
+    className: cn(
+      "flex size-full items-stretch gap-3 overflow-x-auto overflow-y-hidden",
+      className
+    ),
+    children: props.children,
+  }
+
+  return (
+    <SortableContext items={columnIds} strategy={rectSortingStrategy}>
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </SortableContext>
+  )
+}
+
+export interface KanbanColumnProps extends useRender.ComponentProps<"div"> {
+  value: string
+  disabled?: boolean
+}
+
+function KanbanColumn({
+  value,
+  className,
+  render,
+  disabled,
+  ...props
+}: KanbanColumnProps) {
+  const isOverlay = useContext(IsOverlayContext)
+
+  const {
+    setNodeRef,
+    transform,
+    transition,
+    attributes,
+    listeners,
+    isDragging: isSortableDragging,
+  } = useSortable({
+    id: value,
+    disabled: disabled || isOverlay,
+    animateLayoutChanges,
+  })
+
+  // Hooks must run unconditionally; the derived value below is used only in the non-overlay branch.
+  const { activeId, isColumn } = useContext(KanbanDragContext)
+  const isColumnDragging = activeId ? isColumn(activeId) : false
+
+  const style = {
+    transition,
+    transform: CSS.Transform.toString(transform),
+  } as CSSProperties
+
+  const defaultProps = isOverlay
+    ? {
+        "data-slot": "kanban-column",
+        "data-value": value,
+        "data-dragging": true,
+        className: cn("group/kanban-column flex flex-col", className),
+        children: props.children,
+      }
+    : {
+        "data-slot": "kanban-column",
+        "data-value": value,
+        "data-dragging": isSortableDragging,
+        "data-disabled": disabled,
+        ref: setNodeRef,
+        style,
+        className: cn(
+          "group/kanban-column flex flex-col",
+          isSortableDragging && "opacity-50 z-50",
+          disabled && "opacity-50",
+          className
+        ),
+        children: props.children,
+      }
+
+  return (
+    <ColumnContext.Provider
+      value={
+        isOverlay
+          ? {
+              attributes: {} as DraggableAttributes,
+              listeners: undefined,
+              isDragging: true,
+              disabled: false,
+            }
+          : { attributes, listeners, isDragging: isColumnDragging, disabled }
+      }
+    >
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </ColumnContext.Provider>
+  )
+}
+
+export interface KanbanColumnHandleProps extends useRender.ComponentProps<"div"> {
+  cursor?: boolean
+}
+
+function KanbanColumnHandle({
+  className,
+  render,
+  cursor = true,
+  ...props
+}: KanbanColumnHandleProps) {
+  const { attributes, listeners, isDragging, disabled } =
+    useContext(ColumnContext)
+
+  const defaultProps = {
+    "data-slot": "kanban-column-handle",
+    "data-dragging": isDragging,
+    "data-disabled": disabled,
+    ...attributes,
+    ...listeners,
+    className: cn(
+      /* Keyboard focus shows it too. focus-within would also match the focus
+         a mousedown gives the handle, so it would stay shown after a drag. */
+      "opacity-0 transition-opacity group-hover/kanban-column:opacity-100 focus-visible:opacity-100 has-focus-visible:opacity-100",
+      cursor && (isDragging ? "cursor-grabbing!" : "cursor-grab!"),
+      className
+    ),
+    children: props.children,
+  }
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  })
+}
+
+export interface KanbanItemProps extends useRender.ComponentProps<"div"> {
+  value: string
+  disabled?: boolean
+}
+
+function KanbanItem({
+  value,
+  className,
+  render,
+  disabled,
+  ...props
+}: KanbanItemProps) {
+  const isOverlay = useContext(IsOverlayContext)
+
+  const {
+    setNodeRef,
+    transform,
+    transition,
+    attributes,
+    listeners,
+    isDragging: isSortableDragging,
+  } = useSortable({
+    id: value,
+    disabled: disabled || isOverlay,
+    animateLayoutChanges,
+  })
+
+  // 故意不消费 KanbanDragContext：拖拽激活时 activeId 会变，若每张卡都订阅，
+  // 整板 200 张卡会同时重渲染（实测起手一帧 700ms：200 次 setProp + 108ms 样式重算 +
+  // GC）。handle 的 grabbing 光标用 useSortable 本地的 isSortableDragging 即可，
+  // 语义相同（只有被拖的那张卡才需要 grabbing）。
+  const style = {
+    transition,
+    transform: CSS.Transform.toString(transform),
+  } as CSSProperties
+
+  const defaultProps = isOverlay
+    ? {
+        "data-slot": "kanban-item",
+        "data-value": value,
+        "data-dragging": true,
+        className: cn(className),
+        children: props.children,
+      }
+    : {
+        "data-slot": "kanban-item",
+        "data-value": value,
+        "data-dragging": isSortableDragging,
+        "data-disabled": disabled,
+        ref: setNodeRef,
+        style,
+        ...attributes,
+        className: cn(
+          isSortableDragging && "opacity-50 z-50",
+          disabled && "opacity-50",
+          className
+        ),
+        children: props.children,
+      }
+
+  return (
+    <ItemContext.Provider
+      value={
+        isOverlay
+          ? { listeners: undefined, isDragging: true, disabled: false }
+          : { listeners, isDragging: isSortableDragging, disabled }
+      }
+    >
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </ItemContext.Provider>
+  )
+}
+
+export interface KanbanItemHandleProps extends useRender.ComponentProps<"div"> {
+  cursor?: boolean
+}
+
+function KanbanItemHandle({
+  className,
+  render,
+  cursor = true,
+  ...props
+}: KanbanItemHandleProps) {
+  const { listeners, isDragging, disabled } = useContext(ItemContext)
+
+  const defaultProps = {
+    "data-slot": "kanban-item-handle",
+    "data-dragging": isDragging,
+    "data-disabled": disabled,
+    ...listeners,
+    className: cn(
+      cursor && (isDragging ? "cursor-grabbing!" : "cursor-grab!"),
+      className
+    ),
+    children: props.children,
+  }
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  })
+}
+
+export interface KanbanColumnContentProps extends useRender.ComponentProps<"div"> {
+  value: string
+}
+
+function KanbanColumnContent({
+  value,
+  className,
+  render,
+  ...props
+}: KanbanColumnContentProps) {
+  const { columns, getItemId } = useContext(KanbanDataContext)
+
+  const items = columns[value]
+  const itemIdsCache = useRef<{
+    ids: string[]
+    source: unknown
+    getItemId: (item: unknown) => string
+  } | null>(null)
+
+  const itemIds = useMemo(() => {
+    if (!items) {
+      throw new Error(
+        `KanbanColumnContent: column "${value}" was not found in the Kanban value. ` +
+          `Available columns: ${Object.keys(columns).join(", ") || "(none)"}.`
+      )
+    }
+    const cached = itemIdsCache.current
+    if (cached && cached.source === items && cached.getItemId === getItemId) {
+      return cached.ids
+    }
+    const next = items.map(getItemId)
+    // 列内 id 序列逐元素相同时复用旧数组：SortableContext 的 items 引用一变，
+    // 该列所有 useSortable 都会重渲染并重新测量，拖拽期重建数组会让整板抖动。
+    if (
+      cached &&
+      cached.ids.length === next.length &&
+      cached.ids.every((id, index) => id === next[index])
+    ) {
+      itemIdsCache.current = { ids: cached.ids, source: items, getItemId }
+      return cached.ids
+    }
+    itemIdsCache.current = { ids: next, source: items, getItemId }
+    return next
+  }, [columns, getItemId, items, value])
+
+  const defaultProps = {
+    "data-slot": "kanban-column-content",
+    className: cn("flex flex-col gap-2", className),
+    children: props.children,
+  }
+
+  return (
+    <SortableContext items={itemIds} strategy={verticalListSortingStrategy}>
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </SortableContext>
+  )
+}
+
+export interface KanbanOverlayProps extends Omit<
+  React.ComponentProps<typeof DragOverlay>,
+  "children"
+> {
+  children?:
+    | ReactNode
+    | ((params: {
+        value: UniqueIdentifier
+        variant: "column" | "item"
+      }) => ReactNode)
+}
+
+function KanbanOverlay({ children, className, ...props }: KanbanOverlayProps) {
+  const { activeId, isColumn, modifiers } = useContext(KanbanDragContext)
+  const mounted = useSyncExternalStore(
+    subscribeToNothing,
+    getIsMounted,
+    getIsMountedOnServer
+  )
+
+  const variant = activeId ? (isColumn(activeId) ? "column" : "item") : "item"
+
+  const content =
+    activeId && children
+      ? typeof children === "function"
+        ? children({ value: activeId, variant })
+        : children
+      : null
+
+  if (!mounted) return null
+
+  return createPortal(
+    <DragOverlay
+      dropAnimation={dropAnimationConfig}
+      modifiers={modifiers}
+      className={cn("z-50", activeId && "cursor-grabbing", className)}
+      {...props}
+    >
+      <IsOverlayContext.Provider value={true}>
+        {content}
+      </IsOverlayContext.Provider>
+    </DragOverlay>,
+    document.body
+  )
+}
+
+export {
+  Kanban,
+  KanbanBoard,
+  KanbanColumn,
+  KanbanColumnHandle,
+  KanbanItem,
+  KanbanItemHandle,
+  KanbanColumnContent,
+  KanbanOverlay,
+}