@multiplatform.one/components 6.1.0 → 6.4.0

package/src/views/Kanban.native.tsx

@@ -1,6 +1,16 @@
 import { FlashList, type FlashListRef } from "@shopify/flash-list";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
-import React, { useCallback, useId, useRef, useState } from "react";
+import { animationConfig, useResolvedKnobs } from "@multiplatform.one/theme";
+import React, {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { useTranslation } from "react-i18next";
+import { AccessibilityInfo, Animated } from "react-native";
 import {
   Card,
   ListItem,
@@ -12,6 +22,18 @@ import {
   YStack,
   type YStackProps,
 } from "tamagui";
+import { AsyncBoundary, useAsyncCount } from "../layouts/AsyncBoundary";
+import {
+  autoScrollVelocity,
+  describeCancel,
+  describeDragState,
+  gapPosition,
+  resolveDrop,
+  siblingOffset,
+  uniformInsertionIndex,
+  type KanbanBoardColumnSnapshot,
+  type KanbanDropTarget,
+} from "./kanbanDnd";
 
 /**
  * A column definition for the Kanban board.
@@ -44,6 +66,10 @@ export interface KanbanHotkeys {
   prevCard?: string;
   /** Select the focused card (default: Enter) */
   select?: string;
+  /** Lift / drop the focused card (web only, default: Space) */
+  lift?: string;
+  /** Cancel an active keyboard drag (web only, default: Escape) */
+  cancel?: string;
 }
 
 /**
@@ -56,16 +82,32 @@ export interface KanbanProps<T> extends Omit<YStackProps, "children"> {
   columns: KanbanColumn<T>[];
   /** Render function for each card */
   renderCard: (item: T) => React.ReactNode;
-  /** Called when a card is moved between columns */
-  onCardMove?: (item: T, fromColumn: string, toColumn: string) => void;
+  /**
+   * Called when a card is moved between columns. `toIndex` is the insertion
+   * position inside the destination column (0-based).
+   */
+  onCardMove?: (item: T, fromColumn: string, toColumn: string, toIndex?: number) => void;
+  /**
+   * Called when a card is reordered inside its own column. Without this
+   * handler, same-column drops settle back to their origin.
+   */
+  onCardReorder?: (item: T, columnId: string, fromIndex: number, toIndex: number) => void;
   /** Called when a card is selected via keyboard or click */
   onCardSelect?: (item: T, columnId: string) => void;
   /** Called when user scrolls near the bottom (infinite scroll) */
   onLoadMore?: () => void;
+  /** Stable key extractor for virtualized cards (defaults to the item index) */
+  getItemKey?: (item: T, index: number) => string | number;
+  /** Human label for a card, used in screen-reader drag announcements */
+  getItemLabel?: (item: T) => string;
   /** Whether more items are available */
   hasMore?: boolean;
   /** Whether data is loading */
   isLoading?: boolean;
+  /** Failed board load (DG-ST-01 / W9). Wins over empty; hides count badges. */
+  error?: boolean | string | Error | ReactNode | null;
+  /** Retry handler for the default error UI. */
+  onRetry?: () => void;
   /** Column width in pixels (default: 280) */
   columnWidth?: number;
   /** Minimum column height in pixels (default: 400) */
@@ -80,60 +122,633 @@ export interface KanbanProps<T> extends Omit<YStackProps, "children"> {
   hotkeys?: KanbanHotkeys;
 }
 
+// ── Interaction constants (gesture recognition, not animation timing) ──
+
+/** Pixels of finger travel before a hold is treated as a scroll. */
+const DRAG_THRESHOLD_PX = 4;
+/** Hold duration before lift so vertical swipes still scroll the column. */
+const TOUCH_LONG_PRESS_MS = 200;
+/** Distance from a scroll edge where auto-scroll engages. */
+const AUTO_SCROLL_EDGE_PX = 48;
+/** Auto-scroll speed cap in px per frame; ramps with edge proximity. */
+const AUTO_SCROLL_MAX_SPEED = 16;
+
+// Raised drag shadow — house $4 elevation tier (blur = 2 x y-offset, Axiom 14).
+const LIFT_SHADOW = {
+  shadowColor: "#000",
+  shadowOffset: { width: 0, height: 10 },
+  shadowOpacity: 0.15,
+  shadowRadius: 20,
+  elevation: 8,
+} as const;
+
+interface NativeColumnHandle {
+  /** List container node for measureInWindow hit testing. */
+  node: any;
+  list: FlashListRef<any> | null;
+  scrollOffset: number;
+  layout: { x: number; y: number; width: number; height: number } | null;
+}
+
+interface NativeDragSession<T> {
+  item: T;
+  itemLabel: string;
+  sourceColumnId: string;
+  sourceIndex: number;
+  /** Uniform slot size (estimateSize) — FlashList has no per-item measurements. */
+  size: number;
+  target: KanbanDropTarget;
+  settling?: boolean;
+}
+
 /**
  * Generic Kanban board component with column-level virtualization.
- * Native implementation using FlashList for cross-platform virtualization.
+ * Native implementation using FlashList plus responder-system drag-and-drop.
+ *
+ * Drag anatomy mirrors the web contract with transforms only (the RN driver
+ * cannot animate layout props — Axiom 4): long-press lifts (scale/rotate/
+ * shadow), the ghost tracks the finger 1:1 via `Animated.ValueXY.setValue`,
+ * siblings displace with translate offsets from the shared `kanbanDnd` math,
+ * and drops/cancels settle with `Animated.spring` using the canonical
+ * animation vocabulary. `animation=none` lands everything instantly while
+ * 1:1 tracking keeps working (A-GESTURE).
  *
  * @typeParam T - The card item type
  */
 export function Kanban<T>({
   columns,
   renderCard,
-  onCardMove: _onCardMove,
+  onCardMove,
+  onCardReorder,
   onCardSelect,
   onLoadMore,
   hasMore = false,
   isLoading = false,
+  error = null,
+  onRetry,
   columnWidth: columnWidthProp,
   minColumnHeight: minColumnHeightProp,
   estimateSize: estimateSizeProp,
   overscan = 5,
-  emptyColumnMessage = "No items",
+  emptyColumnMessage: emptyColumnMessageProp,
+  getItemKey,
+  getItemLabel,
   hotkeys: _hotkeyOverrides,
   ...stackProps
 }: KanbanProps<T>) {
+  const { t } = useTranslation();
+  const emptyColumnMessage = emptyColumnMessageProp ?? t("No items");
   const { knobProps } = useResolvedKnobs();
   const sz = knobProps.sizeToken;
   const columnWidth = columnWidthProp ?? (sz === "$3" ? 240 : sz === "$5" ? 320 : 280);
   const minColumnHeight = minColumnHeightProp ?? (sz === "$3" ? 320 : sz === "$5" ? 480 : 400);
   const estimateSize = estimateSizeProp ?? (sz === "$3" ? 64 : sz === "$5" ? 96 : 80);
   const kanbanId = useId();
+  const boardLoading = !error && isLoading && columns.every((c) => c.items.length === 0);
+  const boardEmpty = !error && columns.length === 0;
+
+  const canDrag = Boolean(onCardMove || onCardReorder);
+
+  // ── Drag state ──────────────────────────────────────────────
+  const [drag, setDrag] = useState<NativeDragSession<T> | null>(null);
+  const dragStateRef = useRef<NativeDragSession<T> | null>(null);
+  dragStateRef.current = drag;
+
+  const columnHandles = useRef(new Map<string, NativeColumnHandle>());
+  const containerNodeRef = useRef<any>(null);
+  const containerOffsetRef = useRef({ x: 0, y: 0 });
+  const boardScrollRef = useRef<any>(null);
+  const boardScrollXRef = useRef(0);
+  const boardLayoutRef = useRef<{ x: number; y: number; width: number } | null>(null);
+  const fingerRef = useRef({ x: 0, y: 0 });
+  const suppressTapRef = useRef(false);
+  const autoScrollRafRef = useRef<number | null>(null);
+
+  // Ghost transforms (translate/scale/rotate only — native-driver safe).
+  const ghostPos = useRef(new Animated.ValueXY({ x: 0, y: 0 })).current;
+  const liftValue = useRef(new Animated.Value(0)).current;
+
+  const gestureRef = useRef<{
+    item: T;
+    columnId: string;
+    index: number;
+    startX: number;
+    startY: number;
+    lifted: boolean;
+    timer: ReturnType<typeof setTimeout> | null;
+  } | null>(null);
+
+  const board = useMemo(
+    (): KanbanBoardColumnSnapshot[] =>
+      columns.map((c) => ({ id: c.id, title: c.title, count: c.items.length })),
+    [columns],
+  );
+
+  const springToken =
+    typeof knobProps.transition === "string" && knobProps.transition in animationConfig
+      ? (knobProps.transition as keyof typeof animationConfig)
+      : knobProps.transition
+        ? ("quick" as const)
+        : null;
+
+  const getHandle = useCallback((columnId: string): NativeColumnHandle => {
+    let handle = columnHandles.current.get(columnId);
+    if (!handle) {
+      handle = { node: null, list: null, scrollOffset: 0, layout: null };
+      columnHandles.current.set(columnId, handle);
+    }
+    return handle;
+  }, []);
+
+  const announce = useCallback(
+    (
+      type: "lift" | "move" | "drop" | "cancel",
+      session: Pick<NativeDragSession<T>, "sourceColumnId" | "sourceIndex" | "target">,
+      label: string,
+    ) => {
+      const a =
+        type === "cancel"
+          ? describeCancel(session, board, label)
+          : describeDragState(type, session, board, label);
+      const text =
+        a.type === "cancel"
+          ? t("Movement cancelled. {{card}} returned to {{column}}.", a)
+          : a.type === "lift"
+            ? t("Lifted {{card}} in {{column}}, position {{position}} of {{count}}.", a)
+            : a.type === "move"
+              ? t("Moved {{card}} to {{column}}, position {{position}} of {{count}}.", a)
+              : t("Dropped {{card}} in {{column}}, position {{position}} of {{count}}.", a);
+      AccessibilityInfo.announceForAccessibility?.(text);
+    },
+    [board, t],
+  );
+
+  // ── Geometry ────────────────────────────────────────────────
+
+  const measureLayouts = useCallback(() => {
+    containerNodeRef.current?.measureInWindow?.((x: number, y: number) => {
+      containerOffsetRef.current = { x, y };
+    });
+    for (const [, handle] of columnHandles.current) {
+      handle.node?.measureInWindow?.((x: number, y: number, width: number, height: number) => {
+        handle.layout = { x, y, width, height };
+      });
+    }
+    boardScrollRef.current?.measureInWindow?.((x: number, y: number, width: number) => {
+      boardLayoutRef.current = { x, y, width };
+    });
+  }, []);
+
+  const hitTest = useCallback(
+    (pageX: number, pageY: number, session: NativeDragSession<T>): KanbanDropTarget => {
+      for (const [columnId, handle] of columnHandles.current) {
+        const layout = handle.layout;
+        if (!layout) continue;
+        if (
+          pageX < layout.x ||
+          pageX > layout.x + layout.width ||
+          pageY < layout.y - 40 ||
+          pageY > layout.y + layout.height
+        ) {
+          continue;
+        }
+        const column = columns.find((c) => c.id === columnId);
+        if (!column) continue;
+        const localY = pageY - layout.y + handle.scrollOffset;
+        const wdCount = column.items.length - (columnId === session.sourceColumnId ? 1 : 0);
+        const index = uniformInsertionIndex(localY, session.size, Math.max(wdCount, 0));
+        return { columnId, index };
+      }
+      return { columnId: session.sourceColumnId, index: session.sourceIndex };
+    },
+    [columns],
+  );
+
+  /** Container-relative position of the gap slot for settle destinations. */
+  const gapPositionInContainer = useCallback(
+    (session: NativeDragSession<T>): { x: number; y: number } | null => {
+      const handle = columnHandles.current.get(session.target.columnId);
+      const layout = handle?.layout;
+      const column = columns.find((c) => c.id === session.target.columnId);
+      if (!handle || !layout || !column) return null;
+      const gapY = gapPosition({
+        gapIndex: session.target.index,
+        sourceIndex:
+          session.target.columnId === session.sourceColumnId ? session.sourceIndex : null,
+        count: column.items.length,
+        size: session.size,
+        totalSize: column.items.length * session.size,
+        getStart: (index) => index * session.size,
+      });
+      return {
+        x: layout.x - containerOffsetRef.current.x,
+        y: layout.y - containerOffsetRef.current.y + gapY - handle.scrollOffset,
+      };
+    },
+    [columns],
+  );
+
+  // ── Auto-scroll ─────────────────────────────────────────────
+
+  const stopAutoScroll = useCallback(() => {
+    if (autoScrollRafRef.current != null) cancelAnimationFrame(autoScrollRafRef.current);
+    autoScrollRafRef.current = null;
+  }, []);
+
+  const startAutoScroll = useCallback(() => {
+    stopAutoScroll();
+    const tick = () => {
+      const session = dragStateRef.current;
+      if (!session || session.settling) {
+        autoScrollRafRef.current = null;
+        return;
+      }
+      const { x, y } = fingerRef.current;
+      const handle = columnHandles.current.get(session.target.columnId);
+      const layout = handle?.layout;
+      let scrolled = false;
+      if (handle && layout) {
+        const vy = autoScrollVelocity({
+          pos: y,
+          start: layout.y,
+          end: layout.y + layout.height,
+          edge: AUTO_SCROLL_EDGE_PX,
+          maxSpeed: AUTO_SCROLL_MAX_SPEED,
+        });
+        if (vy !== 0 && handle.list) {
+          handle.scrollOffset = Math.max(handle.scrollOffset + vy, 0);
+          handle.list.scrollToOffset({ offset: handle.scrollOffset, animated: false });
+          scrolled = true;
+        }
+      }
+      const boardLayout = boardLayoutRef.current;
+      if (boardLayout && boardScrollRef.current) {
+        const vx = autoScrollVelocity({
+          pos: x,
+          start: boardLayout.x,
+          end: boardLayout.x + boardLayout.width,
+          edge: AUTO_SCROLL_EDGE_PX,
+          maxSpeed: AUTO_SCROLL_MAX_SPEED,
+        });
+        if (vx !== 0) {
+          boardScrollXRef.current = Math.max(boardScrollXRef.current + vx, 0);
+          boardScrollRef.current.scrollTo?.({ x: boardScrollXRef.current, animated: false });
+          scrolled = true;
+          // Column window positions shift when the board scrolls.
+          measureLayouts();
+        }
+      }
+      if (scrolled) {
+        const target = hitTest(x, y, session);
+        setDrag((prev) =>
+          prev &&
+          !prev.settling &&
+          (prev.target.columnId !== target.columnId || prev.target.index !== target.index)
+            ? { ...prev, target }
+            : prev,
+        );
+      }
+      autoScrollRafRef.current = requestAnimationFrame(tick);
+    };
+    autoScrollRafRef.current = requestAnimationFrame(tick);
+  }, [hitTest, measureLayouts, stopAutoScroll]);
+
+  useEffect(() => () => stopAutoScroll(), [stopAutoScroll]);
+
+  // ── Drop / cancel ───────────────────────────────────────────
+
+  const finishDrag = useCallback(
+    (commit: boolean) => {
+      const session = dragStateRef.current;
+      if (!session || session.settling) return;
+      stopAutoScroll();
+
+      const resolved = resolveDrop(session);
+      const crossColumn = resolved.to.columnId !== resolved.from.columnId;
+      const canCommit =
+        commit && resolved.commit && (crossColumn ? Boolean(onCardMove) : Boolean(onCardReorder));
+
+      const settleSession: NativeDragSession<T> = canCommit
+        ? { ...session, settling: true }
+        : {
+            ...session,
+            settling: true,
+            target: { columnId: session.sourceColumnId, index: session.sourceIndex },
+          };
+      const dest = gapPositionInContainer(settleSession);
+
+      const complete = () => {
+        setDrag(null);
+        dragStateRef.current = null;
+        liftValue.setValue(0);
+        if (canCommit) {
+          announce("drop", settleSession, session.itemLabel);
+          if (crossColumn) {
+            onCardMove?.(
+              session.item,
+              resolved.from.columnId,
+              resolved.to.columnId,
+              resolved.to.index,
+            );
+          } else {
+            onCardReorder?.(
+              session.item,
+              resolved.from.columnId,
+              resolved.from.index,
+              resolved.to.index,
+            );
+          }
+        } else {
+          announce("cancel", settleSession, session.itemLabel);
+        }
+      };
+
+      setDrag(settleSession);
+      dragStateRef.current = settleSession;
+
+      if (dest && springToken) {
+        // Settle leap tweens with the canonical spring vocabulary (LC-25);
+        // Animated.spring provides the completion callback Tamagui lacks.
+        const config = animationConfig[springToken];
+        Animated.parallel([
+          Animated.spring(ghostPos, {
+            toValue: dest,
+            useNativeDriver: true,
+            damping: config.damping,
+            stiffness: config.stiffness,
+            ...("mass" in config ? { mass: config.mass } : undefined),
+          }),
+          Animated.spring(liftValue, {
+            toValue: 0,
+            useNativeDriver: true,
+            damping: config.damping,
+            stiffness: config.stiffness,
+          }),
+        ]).start(complete);
+      } else {
+        // animation=none: no decorative settling — land instantly (Axiom 3).
+        if (dest) ghostPos.setValue(dest);
+        complete();
+      }
+    },
+    [
+      announce,
+      gapPositionInContainer,
+      ghostPos,
+      liftValue,
+      onCardMove,
+      onCardReorder,
+      springToken,
+      stopAutoScroll,
+    ],
+  );
+
+  // ── Gesture handlers (responder system, Calendar pattern) ───
+
+  const liftCard = useCallback(() => {
+    const gesture = gestureRef.current;
+    if (!gesture || gesture.lifted) return;
+    gesture.lifted = true;
+    measureLayouts();
+    const label = getItemLabel?.(gesture.item) ?? t("Card");
+    const session: NativeDragSession<T> = {
+      item: gesture.item,
+      itemLabel: label,
+      sourceColumnId: gesture.columnId,
+      sourceIndex: gesture.index,
+      size: estimateSize,
+      target: { columnId: gesture.columnId, index: gesture.index },
+    };
+    ghostPos.setValue({
+      x: fingerRef.current.x - containerOffsetRef.current.x - columnWidth / 2,
+      y: fingerRef.current.y - containerOffsetRef.current.y - estimateSize / 2,
+    });
+    if (springToken) {
+      const config = animationConfig[springToken];
+      Animated.spring(liftValue, {
+        toValue: 1,
+        useNativeDriver: true,
+        damping: config.damping,
+        stiffness: config.stiffness,
+      }).start();
+    } else {
+      liftValue.setValue(1);
+    }
+    setDrag(session);
+    dragStateRef.current = session;
+    announce("lift", session, label);
+    startAutoScroll();
+  }, [
+    announce,
+    columnWidth,
+    estimateSize,
+    getItemLabel,
+    ghostPos,
+    liftValue,
+    measureLayouts,
+    springToken,
+    startAutoScroll,
+    t,
+  ]);
+
+  const handleGrant = useCallback(
+    (item: T, columnId: string, index: number, e: any) => {
+      if (!canDrag) return;
+      const pageX = e.nativeEvent?.pageX ?? 0;
+      const pageY = e.nativeEvent?.pageY ?? 0;
+      fingerRef.current = { x: pageX, y: pageY };
+      gestureRef.current = {
+        item,
+        columnId,
+        index,
+        startX: pageX,
+        startY: pageY,
+        lifted: false,
+        timer: setTimeout(liftCard, TOUCH_LONG_PRESS_MS),
+      };
+    },
+    [canDrag, liftCard],
+  );
+
+  const handleMove = useCallback(
+    (e: any) => {
+      const gesture = gestureRef.current;
+      if (!gesture) return;
+      const pageX = e.nativeEvent?.pageX ?? 0;
+      const pageY = e.nativeEvent?.pageY ?? 0;
+      fingerRef.current = { x: pageX, y: pageY };
+      if (!gesture.lifted) {
+        // Finger moved before the hold elapsed — this is a scroll, not a drag.
+        if (Math.hypot(pageX - gesture.startX, pageY - gesture.startY) >= DRAG_THRESHOLD_PX) {
+          if (gesture.timer != null) clearTimeout(gesture.timer);
+          gestureRef.current = null;
+        }
+        return;
+      }
+      // 1:1 finger tracking — no tween while the finger carries the card.
+      ghostPos.setValue({
+        x: pageX - containerOffsetRef.current.x - columnWidth / 2,
+        y: pageY - containerOffsetRef.current.y - estimateSize / 2,
+      });
+      const session = dragStateRef.current;
+      if (!session || session.settling) return;
+      const target = hitTest(pageX, pageY, session);
+      setDrag((prev) =>
+        prev &&
+        !prev.settling &&
+        (prev.target.columnId !== target.columnId || prev.target.index !== target.index)
+          ? { ...prev, target }
+          : prev,
+      );
+    },
+    [columnWidth, estimateSize, ghostPos, hitTest],
+  );
+
+  const handleRelease = useCallback(
+    (item: T, columnId: string) => {
+      const gesture = gestureRef.current;
+      gestureRef.current = null;
+      if (!gesture) return;
+      if (gesture.timer != null) clearTimeout(gesture.timer);
+      if (!gesture.lifted) {
+        // Responders steal onPress when drag is enabled — a short tap selects.
+        if (!suppressTapRef.current) onCardSelect?.(item, columnId);
+        return;
+      }
+      suppressTapRef.current = true;
+      setTimeout(() => {
+        suppressTapRef.current = false;
+      }, 0);
+      finishDrag(true);
+    },
+    [finishDrag, onCardSelect],
+  );
+
+  const handleTerminate = useCallback(() => {
+    const gesture = gestureRef.current;
+    gestureRef.current = null;
+    if (!gesture) return;
+    if (gesture.timer != null) clearTimeout(gesture.timer);
+    if (gesture.lifted) finishDrag(false);
+  }, [finishDrag]);
+
+  const getCardDragProps = useCallback(
+    (item: T, columnId: string, index: number) => {
+      if (!canDrag) return {};
+      return {
+        onStartShouldSetResponder: () => true,
+        onMoveShouldSetResponder: () => true,
+        onResponderTerminationRequest: () => !gestureRef.current?.lifted,
+        onResponderGrant: (e: any) => handleGrant(item, columnId, index, e),
+        onResponderMove: handleMove,
+        onResponderRelease: () => handleRelease(item, columnId),
+        onResponderTerminate: handleTerminate,
+      };
+    },
+    [canDrag, handleGrant, handleMove, handleRelease, handleTerminate],
+  );
+
+  const dragActive = drag != null && !drag.settling;
 
   return (
-    <YStack {...stackProps}>
-      <ScrollView horizontal showsHorizontalScrollIndicator={false}>
-        <XStack {...knobProps.gap}>
-          {columns.map((column, colIndex) => (
-            <KanbanColumnView
-              key={column.id}
-              kanbanId={kanbanId}
-              column={column}
-              columnIndex={colIndex}
-              renderCard={renderCard}
-              columnWidth={columnWidth}
-              minColumnHeight={minColumnHeight}
-              estimateSize={estimateSize}
-              overscan={overscan}
-              emptyColumnMessage={emptyColumnMessage}
-              onLoadMore={onLoadMore}
-              hasMore={hasMore}
-              isLoading={isLoading}
-              onCardSelect={onCardSelect}
-            />
-          ))}
-        </XStack>
-      </ScrollView>
-    </YStack>
+    <AsyncBoundary
+      loading={boardLoading}
+      empty={boardEmpty}
+      error={error}
+      onRetry={onRetry}
+      layout="kanban"
+      emptyTitle="No columns"
+      {...stackProps}
+    >
+      <View
+        flex={1}
+        position="relative"
+        ref={(node: any) => {
+          containerNodeRef.current = node;
+        }}
+      >
+        <ScrollView
+          ref={boardScrollRef}
+          horizontal
+          showsHorizontalScrollIndicator={false}
+          scrollEnabled={!dragActive}
+          onScroll={(e: any) => {
+            boardScrollXRef.current = e.nativeEvent?.contentOffset?.x ?? 0;
+          }}
+          scrollEventThrottle={64}
+        >
+          <XStack {...knobProps.gap}>
+            {columns.map((column, colIndex) => (
+              <KanbanColumnView
+                key={column.id}
+                kanbanId={kanbanId}
+                column={column}
+                columnIndex={colIndex}
+                renderCard={renderCard}
+                columnWidth={columnWidth}
+                minColumnHeight={minColumnHeight}
+                estimateSize={estimateSize}
+                overscan={overscan}
+                emptyColumnMessage={emptyColumnMessage}
+                onLoadMore={onLoadMore}
+                getItemKey={getItemKey}
+                hasMore={hasMore}
+                isLoading={isLoading}
+                onCardSelect={onCardSelect}
+                getCardDragProps={canDrag ? getCardDragProps : undefined}
+                handle={getHandle(column.id)}
+                drag={drag}
+                scrollEnabled={!dragActive}
+              />
+            ))}
+          </XStack>
+        </ScrollView>
+
+        {/* Drag ghost: 1:1 finger tracking + lift transforms (A-GESTURE). */}
+        {drag && (
+          <Animated.View
+            pointerEvents="none"
+            style={{
+              position: "absolute",
+              top: 0,
+              left: 0,
+              width: columnWidth,
+              zIndex: 1000,
+              transform: [
+                { translateX: ghostPos.x },
+                { translateY: ghostPos.y },
+                {
+                  scale: liftValue.interpolate({
+                    inputRange: [0, 1],
+                    outputRange: [1, 1.03],
+                  }),
+                },
+                {
+                  rotate: liftValue.interpolate({
+                    inputRange: [0, 1],
+                    outputRange: ["0deg", "2.5deg"],
+                  }),
+                },
+              ],
+            }}
+          >
+            <View padding="$1">
+              <Card
+                size={knobProps.sizeToken}
+                {...knobProps.borderRadius}
+                borderWidth={1}
+                borderColor="$borderColor"
+                backgroundColor="$background"
+                overflow="hidden"
+                {...LIFT_SHADOW}
+              >
+                {renderCard(drag.item)}
+              </Card>
+            </View>
+          </Animated.View>
+        )}
+      </View>
+    </AsyncBoundary>
   );
 }
 
@@ -148,9 +763,14 @@ interface KanbanColumnViewProps<T> {
   overscan: number;
   emptyColumnMessage: string;
   onLoadMore?: () => void;
+  getItemKey?: (item: T, index: number) => string | number;
   hasMore?: boolean;
   isLoading?: boolean;
   onCardSelect?: (item: T, columnId: string) => void;
+  getCardDragProps?: (item: T, columnId: string, index: number) => Record<string, unknown>;
+  handle: NativeColumnHandle;
+  drag: NativeDragSession<T> | null;
+  scrollEnabled: boolean;
 }
 
 function KanbanColumnView<T>({
@@ -164,13 +784,23 @@ function KanbanColumnView<T>({
   overscan,
   emptyColumnMessage,
   onLoadMore,
+  getItemKey,
   hasMore,
   isLoading,
   onCardSelect,
+  getCardDragProps,
+  handle,
+  drag,
+  scrollEnabled,
 }: KanbanColumnViewProps<T>) {
+  const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
-  const flashListRef = useRef<FlashListRef<T>>(null);
-  const [selectedIndex, setSelectedIndex] = useState(-1);
+  const itemCount = useAsyncCount(column.items.length);
+
+  const isSource = drag?.sourceColumnId === column.id;
+  const gapIndex =
+    drag && !drag.settling && drag.target.columnId === column.id ? drag.target.index : null;
+  const isDropTarget = gapIndex != null;
 
   // Handle infinite scroll
   const handleEndReached = useCallback(() => {
@@ -179,14 +809,27 @@ function KanbanColumnView<T>({
     }
   }, [onLoadMore, hasMore, isLoading]);
 
+  const gapY =
+    gapIndex != null && drag
+      ? gapPosition({
+          gapIndex,
+          sourceIndex: isSource ? drag.sourceIndex : null,
+          count: column.items.length,
+          size: drag.size,
+          totalSize: column.items.length * drag.size,
+          getStart: (index) => index * drag.size,
+        })
+      : null;
+
   return (
     <Card
       size={knobProps.sizeToken}
-      {...{ backgroundColor: "$color2" }}
+      {...{ backgroundColor: isDropTarget ? "$color3" : "$color2" }}
+      transition={knobProps.transition}
       width={columnWidth}
       minHeight={minColumnHeight}
       borderWidth={1}
-      borderColor="$borderColor"
+      borderColor={isDropTarget ? "$color7" : "$borderColor"}
       overflow="hidden"
     >
       {/* Column Header */}
@@ -198,60 +841,114 @@ function KanbanColumnView<T>({
           ) : undefined
         }
         iconAfter={
-          <Text
-            color="$color10"
-            fontSize={knobProps.sizeToken}
-            {...{ backgroundColor: "$color2" }}
-            paddingHorizontal="$2"
-            borderRadius={knobProps.borderRadius.borderRadius}
-          >
-            {column.items.length}
-          </Text>
+          itemCount !== undefined ? (
+            <Text
+              color="$color10"
+              fontSize={knobProps.sizeToken}
+              {...{ backgroundColor: "$color2" }}
+              paddingHorizontal="$2"
+              borderRadius={knobProps.borderRadius.borderRadius}
+              data-async-count
+            >
+              {itemCount}
+            </Text>
+          ) : undefined
         }
         size={knobProps.sizeToken}
         borderBottomWidth={1}
         borderBottomColor="$borderColor"
       />
 
-      {/* Cards Container - virtualized with FlashList */}
-      {column.items.length === 0 ? (
-        <YStack
-          {...knobProps.panelPadding}
-          alignItems="center"
-          justifyContent="center"
-          opacity={0.5}
-          flex={1}
-        >
-          <Text color="$color10" fontSize="$2">
-            {emptyColumnMessage}
-          </Text>
-        </YStack>
-      ) : (
-        <View style={{ flex: 1, minHeight: minColumnHeight - 60 }}>
+      {/* Cards container — always rendered so empty columns stay drop targets. */}
+      <View
+        style={{ flex: 1, minHeight: minColumnHeight - 60 }}
+        position="relative"
+        ref={(node: any) => {
+          handle.node = node;
+        }}
+      >
+        {column.items.length === 0 ? (
+          !isDropTarget && (
+            <YStack
+              {...knobProps.panelPadding}
+              alignItems="center"
+              justifyContent="center"
+              opacity={0.5}
+              flex={1}
+            >
+              <Text color="$color10" fontSize="$2">
+                {emptyColumnMessage}
+              </Text>
+            </YStack>
+          )
+        ) : (
           <FlashList
-            ref={flashListRef}
+            ref={(list: any) => {
+              handle.list = list;
+            }}
             data={column.items}
+            extraData={drag}
             drawDistance={estimateSize * overscan}
             onEndReached={handleEndReached}
             onEndReachedThreshold={0.5}
-            keyExtractor={(_, index) => `${kanbanId}-col-${columnIndex}-card-${index}`}
+            scrollEnabled={scrollEnabled}
+            onScroll={(e: any) => {
+              handle.scrollOffset = e.nativeEvent?.contentOffset?.y ?? 0;
+            }}
+            scrollEventThrottle={64}
+            keyExtractor={(item, index) =>
+              getItemKey
+                ? String(getItemKey(item, index))
+                : `${kanbanId}-col-${columnIndex}-card-${index}`
+            }
             renderItem={({ item, index }) => {
-              const isSelected = selectedIndex === index;
+              const isDragged = isSource && drag != null && index === drag.sourceIndex;
+              let offset = 0;
+              let ghost = false;
+              let hidden = false;
+              if (drag && !drag.settling) {
+                if (isDragged) {
+                  if (gapIndex != null && gapY != null) {
+                    offset = gapY - index * drag.size;
+                    ghost = true;
+                  } else {
+                    hidden = true;
+                  }
+                } else {
+                  offset = siblingOffset({
+                    index,
+                    sourceIndex: isSource && drag ? drag.sourceIndex : null,
+                    gapIndex,
+                    size: drag.size,
+                  });
+                }
+              } else if (drag?.settling && isDragged) {
+                // The ghost overlay is this card's visual while it settles.
+                hidden = true;
+              }
+              const dragProps = getCardDragProps?.(item, column.id, index) ?? {};
               return (
-                <View padding="$1">
+                <View
+                  padding="$1"
+                  y={offset}
+                  transition={drag && !drag.settling ? knobProps.transition : undefined}
+                  opacity={hidden ? 0 : ghost ? 0.4 : 1}
+                  {...dragProps}
+                >
                   <Card
                     id={`${kanbanId}-col-${columnIndex}-card-${index}`}
                     size={knobProps.sizeToken}
                     elevation={knobProps.elevation}
                     borderWidth={1}
-                    borderColor={isSelected ? "$accentBackground" : "$borderColor"}
-                    backgroundColor={isSelected ? "$accentBackground" : undefined}
-                    pressStyle={{ scale: 0.97 }}
+                    borderColor={ghost ? "$color7" : "$borderColor"}
+                    borderStyle={ghost ? ("dashed" as any) : undefined}
+                    pressStyle={{ scale: 0.98 }}
                     overflow="hidden"
-                    onPress={() => {
-                      setSelectedIndex(index);
-                      onCardSelect?.(item, column.id);
-                    }}
+                    onPress={
+                      getCardDragProps
+                        ? undefined // responders own the tap; handled on release
+                        : () => onCardSelect?.(item, column.id)
+                    }
                   >
                     {renderCard(item)}
                   </Card>
@@ -266,8 +963,40 @@ function KanbanColumnView<T>({
               ) : null
             }
           />
-        </View>
-      )}
+        )}
+
+        {/* Insertion slot outline for cross-column targets and empty columns. */}
+        {drag && !drag.settling && gapIndex != null && !isSource && (
+          <View
+            position="absolute"
+            top={0}
+            left={0}
+            right={0}
+            y={(gapY ?? 0) - handle.scrollOffset}
+            height={drag.size}
+            padding="$1"
+            pointerEvents="none"
+            transition={knobProps.transition}
+          >
+            <View
+              flex={1}
+              {...knobProps.borderRadius}
+              borderStyle="dashed"
+              borderColor="$color7"
+              backgroundColor="$color3"
+              opacity={0.8}
+              alignItems="center"
+              justifyContent="center"
+            >
+              {column.items.length === 0 && (
+                <Text color="$color11" fontSize="$2">
+                  {t("Drop here")}
+                </Text>
+              )}
+            </View>
+          </View>
+        )}
+      </View>
     </Card>
   );
 }