react-extjs 0.0.1

package/src/components/dnd/DndContext.tsx

@@ -0,0 +1,328 @@
+import React, {
+  useEffect,
+  useState,
+} from 'react';
+import ReactDOM from 'react-dom';
+
+/**
+ * DndContext —— 拖放引擎内核 + StatusProxy 渲染层。
+ *
+ * 保真复刻 Ext.dd 的全局单例 DragDropMgr（DDM）与 Ext.dd.StatusProxy：
+ *  - DndManager 为模块级单例（等价 Ext.dd.DDM），管理所有已注册的 DropTarget、
+ *    当前拖拽状态、pointer 事件派发、相交检测与 enter/over/out/drop 回调。
+ *  - StatusProxy 为跟随指针的全局拖放代理层（x-dd-drag-proxy），含 drop 状态图标
+ *    （x-dd-drop-ok / x-dd-drop-nodrop / x-dd-drop-ok-add）与 ghost 内容。
+ *
+ * 与 Ext 的差异（React 化）：
+ *  - 不逐字移植 YUI 的全局 mousemove/mouseup 监听，改为「拖拽启动时」绑定 window
+ *    级 pointer 监听、结束解绑，天然适配 React 组件生命周期。
+ *  - 相交检测默认 POINT 模式（Ext 默认 mode=0）：指针点落在 target 矩形内即 over。
+ *  - 多个 DndProvider 通过「订阅同一 manager 数据源」渲染，保证全局唯一视觉状态。
+ */
+
+export type DropStatusClass =
+  | 'x-dd-drop-ok'
+  | 'x-dd-drop-nodrop'
+  | 'x-dd-drop-ok-add';
+
+export interface DropTargetReg {
+  id: string;
+  groups: string[];
+  el: HTMLElement;
+  overClass?: string;
+  /** 返回 true 表示允许放置（drop-ok），false 表示禁止（drop-nodrop） */
+  validate?: (data: any, e: PointerEvent) => boolean;
+  /** 允许放置时 StatusProxy 显示的状态图标类（等价原生 StatusProxy.setStatus）。
+   *  默认 'x-dd-drop-ok'（对勾）；放入列表/区域追加可用 'x-dd-drop-ok-add'（加号）。
+   *  视觉由原生 ext-all.css / visual/dd.css / 各 theme dd.css 提供，随主题切换。 */
+  dropStatus?: DropStatusClass;
+  onEnter?: (data: any, e: PointerEvent) => void;
+  onOver?: (data: any, e: PointerEvent) => void;
+  onOut?: (data: any, e: PointerEvent) => void;
+  /** 返回 true 表示有效放置（不触发 repair 回弹） */
+  onDrop?: (data: any, e: PointerEvent) => boolean;
+}
+
+export interface StartDragOptions {
+  data: any;
+  groups: string[];
+  /** StatusProxy 的 ghost 内容（克隆节点或自定义 React 节点） */
+  ghost: React.ReactNode;
+  /** 抓取点相对被拖元素左上角的偏移（等价 Ext.dd.DDProxy 的 deltaX/deltaY）。
+   *  代理按「指针 - 该偏移」定位，使抓取点始终停在光标下，避免起拖瞬间代理跳变。
+   *  默认 0（元素左上角即抓取点）。由 Draggable 在 pointerdown 时按真实抓取位置传入。 */
+  offsetX?: number;
+  offsetY?: number;
+  /** 无效放置时回弹终点（源元素 viewport 位置） */
+  repairXY?: { x: number; y: number };
+  /** 有效放置回调。第 4 个参数 ghostXY 为当前 StatusProxy 代理层的视口左上角
+   *  （等价 Ext.dd.DDProxy 的 proxy.getXY()：即「光标 - 抓取偏移」后的代理位置），
+   *  调用方应用它（而非裸光标 e.clientX/Y）来定位被拖元素，才能做到「所见即所放」、
+   *  与拖动中看到的 ghost 完全重合（Ext 原生即把 moveProxy 放到 proxy.getXY()）。
+   *  注意参数顺序保持兼容：第 2 个始终是拖拽 data，第 3 个始终是事件 e，ghostXY 追加在第 4。 */
+  onValidDrop?: (
+    target: DropTargetReg | null,
+    data: any,
+    e: PointerEvent,
+    ghostXY?: { x: number; y: number },
+  ) => void;
+  onInvalidDrop?: (e: PointerEvent) => void;
+}
+
+interface ProxyState {
+  visible: boolean;
+  status: DropStatusClass;
+  x: number;
+  y: number;
+  ghost: React.ReactNode;
+  repairing: boolean;
+  /** 当前悬浮（且允许放置）的 DropTarget id，供目标做 over 高亮（响应式） */
+  overId: string | null;
+}
+
+const INITIAL_PROXY: ProxyState = {
+  visible: false,
+  status: 'x-dd-drop-nodrop',
+  x: 0,
+  y: 0,
+  ghost: null,
+  repairing: false,
+  overId: null,
+};
+
+class DndManager {
+  private drops = new Map<string, DropTargetReg>();
+  private drag:
+    | { opts: StartDragOptions; overIds: Set<string>; lastOver: DropTargetReg | null }
+    | null = null;
+  private subscribers = new Set<(s: ProxyState) => void>();
+  private proxyState: ProxyState = INITIAL_PROXY;
+  private lastX = 0;
+  private lastY = 0;
+
+  subscribe(fn: (s: ProxyState) => void): () => void {
+    this.subscribers.add(fn);
+    fn(this.proxyState);
+    return () => {
+      this.subscribers.delete(fn);
+    };
+  }
+
+  getProxyState(): ProxyState {
+    return this.proxyState;
+  }
+
+  private emit() {
+    this.subscribers.forEach((fn) => fn(this.proxyState));
+  }
+
+  private setProxy(s: Partial<ProxyState>) {
+    this.proxyState = { ...this.proxyState, ...s };
+    this.emit();
+  }
+
+  registerDrop(reg: DropTargetReg) {
+    this.drops.set(reg.id, reg);
+  }
+
+  unregisterDrop(id: string) {
+    this.drops.delete(id);
+  }
+
+  isDragging(): boolean {
+    return !!this.drag;
+  }
+
+  startDrag(opts: StartDragOptions, startEvent: PointerEvent) {
+    if (this.drag) return;
+    this.drag = { opts, overIds: new Set(), lastOver: null };
+    const ox = opts.offsetX ?? 0;
+    const oy = opts.offsetY ?? 0;
+    // 代理左上角 = 指针 - 抓取偏移，使抓取点保持在光标下（等价 Ext.dd.DDProxy 行为）
+    this.lastX = startEvent.clientX - ox;
+    this.lastY = startEvent.clientY - oy;
+    this.setProxy({
+      visible: true,
+      status: 'x-dd-drop-nodrop',
+      ghost: opts.ghost,
+      x: this.lastX,
+      y: this.lastY,
+      repairing: false,
+      overId: null,
+    });
+    window.addEventListener('pointermove', this.onMove);
+    window.addEventListener('pointerup', this.onUp);
+  }
+
+  private onMove = (e: PointerEvent) => {
+    if (!this.drag) return;
+    const { opts } = this.drag;
+    const ox = opts.offsetX ?? 0;
+    const oy = opts.offsetY ?? 0;
+    const x = e.clientX - ox;
+    const y = e.clientY - oy;
+    this.lastX = x;
+    this.lastY = y;
+    this.setProxy({ x, y });
+
+    const groups = opts.groups;
+    const pt = { x: e.clientX, y: e.clientY };
+    const newOvers: DropTargetReg[] = [];
+    this.drops.forEach((d) => {
+      if (d.groups.length === 0 || !d.groups.some((g) => groups.includes(g))) return;
+      const r = d.el.getBoundingClientRect();
+      const over =
+        pt.x >= r.left && pt.x <= r.right && pt.y >= r.top && pt.y <= r.bottom;
+      if (over) newOvers.push(d);
+    });
+
+    // 离开（out）检测：上一帧 over 但本帧不在
+    this.drag.overIds.forEach((id) => {
+      if (!newOvers.some((d) => d.id === id)) {
+        const d = this.drops.get(id);
+        if (d) d.onOut?.(opts.data, e);
+      }
+    });
+
+    // 进入（enter）/ 悬浮（over）+ 状态图标
+    let allowedStatus: DropStatusClass | null = null;
+    let allowedId: string | null = null;
+    newOvers.forEach((d) => {
+      const isEnter = !this.drag!.overIds.has(d.id);
+      const allowed = d.validate ? d.validate(opts.data, e) : true;
+      if (isEnter) d.onEnter?.(opts.data, e);
+      else d.onOver?.(opts.data, e);
+      // 记录首个允许放置的目标：其 dropStatus 决定 StatusProxy 图标（默认对勾 ok）
+      if (allowed && allowedStatus === null) {
+        allowedStatus = d.dropStatus ?? 'x-dd-drop-ok';
+        allowedId = d.id;
+      }
+    });
+
+    this.drag.overIds = new Set(newOvers.map((d) => d.id));
+    this.drag.lastOver = newOvers.length ? newOvers[newOvers.length - 1] : null;
+
+    // 状态图标：有目标且至少允许一个 → 首个允许目标的 dropStatus（默认 ok）；
+    // 有目标但全部禁止 → nodrop；无目标 → nodrop。
+    const status: DropStatusClass = newOvers.length
+      ? allowedStatus ?? 'x-dd-drop-nodrop'
+      : 'x-dd-drop-nodrop';
+    // 当前允许放置的目标（供响应式 over 高亮）；取首个允许
+    const overId = newOvers.length ? allowedId : null;
+    this.setProxy({ status, overId });
+  };
+
+  private onUp = (e: PointerEvent) => {
+    if (!this.drag) return;
+    const { opts } = this.drag;
+    window.removeEventListener('pointermove', this.onMove);
+    window.removeEventListener('pointerup', this.onUp);
+
+    const target = this.drag.lastOver;
+    let valid = false;
+    if (target) {
+      const allowed = target.validate ? target.validate(opts.data, e) : true;
+      if (allowed) {
+        valid = target.onDrop ? target.onDrop(opts.data, e) : true;
+      }
+    }
+
+    if (valid) {
+      // 代理层（x-dd-drag-proxy）的视口左上角 = 光标 - 抓取偏移（lastX/lastY），
+      // 等价 Ext.dd.DDProxy.getXY()。把它传给 onValidDrop，调用方据此定位被拖元素，
+      // 使落点「所见即所放」（与拖动中看到的 ghost 对齐），避免裸光标 e.clientX/Y
+      // 把面板偏移「抓取偏移」量、落点错位。
+      opts.onValidDrop?.(target, opts.data, e, { x: this.lastX, y: this.lastY });
+      this.setProxy({ visible: false, ghost: null, repairing: false, overId: null });
+    } else {
+      opts.onInvalidDrop?.(e);
+      const xy = opts.repairXY ?? { x: this.lastX, y: this.lastY };
+      this.setProxy({ repairing: true, x: xy.x, y: xy.y, overId: null });
+      window.setTimeout(() => {
+        this.setProxy({ visible: false, ghost: null, repairing: false, overId: null });
+      }, 500);
+    }
+    this.drag = null;
+  };
+}
+
+export const dndManager = new DndManager();
+
+/* ----------------------------- DndProvider ----------------------------- */
+
+/**
+ * DndProvider —— 保真复刻 Ext 中「一个拖放上下文」的语义容器。
+ *
+ * 在 React 化架构中，Draggable / DropTarget 通过模块级单例 `dndManager` 通信，
+ * 不依赖 React context，因此 DndProvider 仅作语义包裹（保留与 Ext 一致的写法：
+ * 把一组拖放源/目标放进同一个 DndProvider）。全局唯一的 StatusProxy 由
+ * `DndStatusProxy` 在应用根挂载一次，避免每个 DndProvider 都渲染一个代理。
+ */
+export interface DndProviderProps {
+  children?: React.ReactNode;
+}
+
+export const DndProvider: React.FC<DndProviderProps> = ({ children }) => {
+  return <>{children}</>;
+};
+
+/**
+ * useDndState —— 订阅 DndManager 的 proxyState（含拖放代理视觉状态与当前
+ * over 的 DropTarget id）。用于在 React 渲染周期内响应式反映拖放状态，
+ * 替代 Ext 中命令式操作 DOM class 的做法。
+ */
+export function useDndState(): ProxyState {
+  const [state, setState] = useState<ProxyState>(dndManager.getProxyState());
+  useEffect(() => dndManager.subscribe(setState), []);
+  return state;
+}
+
+/**
+ * DndStatusProxy —— 全局唯一的 StatusProxy 渲染层。
+ *
+ * 等价于 Ext 在 document 上唯一存在的拖放代理节点。应且仅应在应用根挂载一次
+ * （见 docs/src/App.tsx）。订阅 dndManager 的 proxyState，把跟随指针的代理
+ * 通过 createPortal 渲染到 document.body。
+ */
+export const DndStatusProxy: React.FC = () => {
+  const proxy = useDndState();
+  return <StatusProxyLayer state={proxy} />;
+};
+
+function StatusProxyLayer({ state }: { state: ProxyState }) {
+  if (!state.visible || typeof document === 'undefined') return null;
+  return ReactDOM.createPortal(
+    <div
+      className={
+        'x-dd-drag-proxy ' +
+        state.status +
+        (state.repairing ? ' x-dd-drag-repair' : '')
+      }
+      style={{
+        // 等价原生 Ext.dd.StatusProxy：代理层全程跟随「视口坐标」的指针。
+        // 这里用 position:fixed（相对视口），与 DragSource 计算 grabOffset / repairXY /
+        // onDrop 时统一使用的 clientX/clientY（视口坐标）一致，避免原生 absolute 把 left/top
+        // 当页面坐标解释——一旦页面或内部滚动容器滚动，代理就会相对光标偏移（抓取点漂移）。
+        position: 'fixed',
+        left: state.x + 'px',
+        top: state.y + 'px',
+        zIndex: 15000,
+        visibility: 'visible',
+        pointerEvents: 'none',
+        // 等价原生 .x-dd-drag-proxy 的 user-select:none（原生 x-unselectable 的
+        // -webkit-user-select:ignore 在 Chrome 失效，故显式声明；内联以删除独立 css 文件）。
+        userSelect: 'none',
+        WebkitUserSelect: 'none',
+        // 回弹动画：等价 Ext StatusProxy.repair 的 .5s 位移（原生用动画框架，这里以
+        // 组件内联 transition 复刻，避免往主题表写规则）。图标外观仍由原生 ext-all.css 提供。
+        transition: state.repairing
+          ? 'left .5s ease-out, top .5s ease-out'
+          : undefined,
+      }}
+    >
+      <div className="x-dd-drop-icon" />
+      <div className="x-dd-drag-ghost">{state.ghost}</div>
+    </div>,
+    document.body,
+  );
+}

package/src/components/dnd/DragSource.tsx

@@ -0,0 +1,202 @@
+import React, { useRef } from 'react';
+import { dndManager, type DropTargetReg } from './DndContext';
+
+/**
+ * Draggable —— 保真复刻 Ext.dd.DragSource（含 DDProxy 行为）。
+ *
+ * 交互契约（对齐 Ext）：
+ *  - onPointerDown 记录起点 + 绑定 window 级 pointermove/up，但**不立即起拖**。
+ *  - 只有当指针移动超过 clickPixelThresh（默认 5px，等价 Ext.dd.DragSource.dragThreshold）
+ *    才真正起拖；纯点击（按下后未移动即抬起）不进入拖拽态，按钮的 click 正常触发。
+ *  - 起拖后由 DndManager 驱动 StatusProxy 跟随指针（默认偏移 0，图标贴住光标）。
+ *  - 放置成功时调用 onValidDrop(target, data, e)；无效时调用 onInvalidDrop(data, e)，
+ *    并由 StatusProxy 执行 repair 回弹动画（回弹到源元素位置 repairXY）。
+ *
+ * 底层 DD / DDProxy / DDTarget 作为引擎被 DndManager 复用，无需单独成组件。
+ */
+/** 等价 Ext.dd.DragSource.clickPixelThresh / dragThreshold，默认 5px */
+const DRAG_THRESHOLD = 5;
+
+export interface DraggableProps {
+  /** 拖放组（等价 Ext ddGroup / group），与 DropTarget 同组才交互，默认 ['default'] */
+  ddGroup?: string;
+  groups?: string[];
+  /** 取拖拽数据（等价 getDragData） */
+  getDragData?: (e: React.PointerEvent) => any;
+  /** 起拖前钩子（等价 onBeforeDrag），返回 false 取消拖拽 */
+  onBeforeDrag?: (data: any, e: React.PointerEvent) => boolean;
+  /** 自定义 StatusProxy 的 ghost 内容（等价 onInitDrag 克隆节点） */
+  renderGhost?: (data: any) => React.ReactNode;
+  /** 有效放置回调（等价 onValidDrop 后的 afterValidDrop）。第 4 个参数 ghostXY 为
+   *  StatusProxy 代理层视口左上角（等价 Ext proxy.getXY()），用于「所见即所放」精确定位。 */
+  onValidDrop?: (
+    target: DropTargetReg | null,
+    data: any,
+    e: PointerEvent,
+    ghostXY?: { x: number; y: number },
+  ) => void;
+  /** 无效放置回调（等价 onInvalidDrop） */
+  onInvalidDrop?: (data: any, e: PointerEvent) => void;
+  className?: string;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+}
+
+export const Draggable: React.FC<DraggableProps> = (props) => {
+  const ref = useRef<HTMLDivElement>(null);
+  // 待定拖拽上下文：pointerdown 后、超过阈值前暂存于此
+  const pending = useRef<{
+    startX: number;
+    startY: number;
+    data: any;
+    groups: string[];
+    ghost: React.ReactNode;
+    repairXY?: { x: number; y: number };
+    grabOffset?: { x: number; y: number };
+    onValidDrop?: (
+      t: DropTargetReg | null,
+      data: any,
+      e: PointerEvent,
+      ghostXY?: { x: number; y: number },
+    ) => void;
+    onInvalidDrop?: (data: any, e: PointerEvent) => void;
+    pointerId: number;
+  } | null>(null);
+  const moveRef = useRef<((e: PointerEvent) => void) | null>(null);
+  const upRef = useRef<((e: PointerEvent) => void) | null>(null);
+
+  const clearPending = () => {
+    if (moveRef.current) window.removeEventListener('pointermove', moveRef.current);
+    if (upRef.current) window.removeEventListener('pointerup', upRef.current);
+    window.removeEventListener('pointercancel', upRef.current!);
+    pending.current = null;
+    moveRef.current = null;
+    upRef.current = null;
+  };
+
+  const onPointerDown = (e: React.PointerEvent) => {
+    if (e.button !== 0) return;
+    const data = props.getDragData ? props.getDragData(e) : {};
+    if (props.onBeforeDrag && props.onBeforeDrag(data, e) === false) return;
+
+    const groups =
+      props.groups ?? (props.ddGroup ? [props.ddGroup] : ['default']);
+    // 默认忠实克隆被拖元素（等价 Ext.dd.StatusProxy 克隆 dragEl）：代理尺寸与抓取元素 1:1，
+    // 抓取偏移（grabOffset）精确映射，起拖/拖拽中不跳变。仅当显式传 renderGhost 时才用自定义。
+    const ghost: React.ReactNode = props.renderGhost
+      ? props.renderGhost(data)
+      : ref.current
+        ? // 忠实克隆被拖元素（等价 Ext.dd.StatusProxy 克隆 dragEl）：原生 Ext 克隆时
+          // 会保留源元素宽度（proxy.dom.width = el.dom.width），否则克隆体进入
+          // StatusProxy 的「宽度收缩」容器后会塌缩成内容宽（门户跨列拖拽的 Portlet
+          // 克隆体比原面板窄、布局变乱即此因）。这里捕获包裹 div 的渲染宽度（=列宽）
+          // 并显式设到克隆外层，使 ghost 与原面板 1:1，起拖/拖拽中不跳变、不变形。
+          (() => {
+            const w = ref.current ? ref.current.offsetWidth : 0;
+            return (
+              <div
+                style={w ? { width: w } : undefined}
+                dangerouslySetInnerHTML={{ __html: ref.current!.outerHTML }}
+              />
+            );
+          })()
+        : '';
+
+    let repairXY: { x: number; y: number } | undefined;
+    let grabOffset: { x: number; y: number } | undefined;
+    if (ref.current) {
+      // 取「真实被拖元素」的盒子作抓取偏移基准。默认用包裹 div 自身；但当包裹 div 因内部
+      // 子节点 position:absolute 而高度塌缩为 0 时（如 PanelProxy：被拖面板是绝对定位），
+      // 改用首个有尺寸的子孙元素（即真实面板）的盒子，否则 grabOffset 会带上多余的绝对定位
+      // 偏移（pos.top 等），导致拖拽时光标相对 ghost 整体下移、像「跑到了面板下边框」。
+      // 等价原生 Ext.dd.DD：delta 由 getEl()（真实被拖元素）坐标算出，而非外层包裹。
+      let box: HTMLElement = ref.current;
+      const selfRect = ref.current.getBoundingClientRect();
+      if ((selfRect.height < 1 || selfRect.width < 1) && ref.current.firstElementChild) {
+        box = ref.current.firstElementChild as HTMLElement;
+      }
+      const r = box.getBoundingClientRect();
+      repairXY = { x: r.left, y: r.top };
+      // 抓取点相对被拖元素左上角的偏移（等价 Ext.dd.DDProxy 的 deltaX/deltaY），
+      // 传入后代理按「指针 - 该偏移」定位，抓取点始终停在光标下，起拖不跳变。
+      grabOffset = { x: e.clientX - r.left, y: e.clientY - r.top };
+    }
+
+    pending.current = {
+      startX: e.clientX,
+      startY: e.clientY,
+      data,
+      groups,
+      ghost,
+      repairXY,
+      grabOffset,
+      onValidDrop: props.onValidDrop,
+      onInvalidDrop: props.onInvalidDrop,
+      pointerId: e.pointerId,
+    };
+
+    moveRef.current = (ev: PointerEvent) => {
+      const p = pending.current;
+      if (!p || ev.pointerId !== p.pointerId) return;
+      const dx = ev.clientX - p.startX;
+      const dy = ev.clientY - p.startY;
+      if (Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+
+      // 超过阈值 → 真正起拖；抑制随后冒出的 click，避免误触被包裹的按钮
+      pending.current = null;
+      window.removeEventListener('pointermove', moveRef.current!);
+      window.removeEventListener('pointerup', upRef.current!);
+      window.removeEventListener('pointercancel', upRef.current!);
+      moveRef.current = null;
+      upRef.current = null;
+      const stopClick = (ce: MouseEvent) => {
+        ce.stopPropagation();
+        ce.preventDefault();
+        ce.stopImmediatePropagation();
+        window.removeEventListener('click', stopClick, true);
+      };
+      window.addEventListener('click', stopClick, true);
+
+      dndManager.startDrag(
+        {
+          data: p.data,
+          groups: p.groups,
+          ghost: p.ghost,
+          repairXY: p.repairXY,
+          offsetX: p.grabOffset?.x ?? 0,
+          offsetY: p.grabOffset?.y ?? 0,
+          onValidDrop: (t, data, ev2, ghostXY) =>
+            p.onValidDrop?.(t, data, ev2, ghostXY),
+          onInvalidDrop: (ev2) => p.onInvalidDrop?.(p.data, ev2),
+        },
+        ev,
+      );
+    };
+
+    upRef.current = (ev: PointerEvent) => {
+      const p = pending.current;
+      if (p && ev.pointerId === p.pointerId) {
+        // 未超过阈值即抬起 → 纯点击，清理待定，让 click 正常触发
+        clearPending();
+      }
+    };
+
+    window.addEventListener('pointermove', moveRef.current);
+    window.addEventListener('pointerup', upRef.current);
+    window.addEventListener('pointercancel', upRef.current);
+  };
+
+  return (
+    <div
+      ref={ref}
+      className={props.className}
+      // 等价原生 Ext.dd 给拖拽元素加 x-unselectable：拖拽中不框选文本。
+      // user-select 为继承属性，故作用在 Draggable 包装层即可透传到 .x-combo-list-item
+      // 等子项；内联声明以避免引入独立 css（与 DndContext 中 StatusProxy 的 userSelect 保持一致）。
+      style={{ userSelect: 'none', ...props.style }}
+      onPointerDown={onPointerDown}
+    >
+      {props.children}
+    </div>
+  );
+};

package/src/components/dnd/DragZone.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { Draggable } from './DragSource';
+import type { DropTargetReg } from './DndContext';
+
+/**
+ * DragZone —— 保真复刻 Ext.dd.DragZone（含 DDProxy 行为）。
+ *
+ * DragZone 是一个「拖拽区」容器：其下的子项（item）均可作为拖拽源，等价于
+ * Ext 示例中把容器包成 DragZone 后，内部节点自动可拖。每个 item 渲染为
+ * Draggable（等价 DragSource），并带 `data-dd-item` / `data-id` 标记，供
+ * DropZone 计算插入位置。
+ *
+ * 与 DropTarget/DropZone 配合即可实现「列表重排」「跨列表移动」等经典拖放。
+ */
+export interface DragZoneItem {
+  id: string;
+  content: React.ReactNode;
+}
+
+export interface DragZoneProps {
+  ddGroup?: string;
+  groups?: string[];
+  className?: string;
+  style?: React.CSSProperties;
+  /** 可拖拽项（顺序即视觉顺序） */
+  items: DragZoneItem[];
+  /** 取拖拽数据（等价 DragZone.getDragData），默认返回 { item } */
+  getDragData?: (item: DragZoneItem) => any;
+  /** 自定义 StatusProxy 的 ghost 内容（等价 onInitDrag 克隆节点） */
+  renderGhost?: (item: DragZoneItem) => React.ReactNode;
+  /** 有效放置回调（等价 DragSource.onValidDrop）。第 4 个参数 ghostXY 为
+   *  StatusProxy 代理层视口左上角（等价 Ext proxy.getXY()），用于精确落点定位。 */
+  onValidDrop?: (
+    target: DropTargetReg | null,
+    data: any,
+    e: PointerEvent,
+    ghostXY?: { x: number; y: number },
+  ) => void;
+  /** 单个 item 的 className（等价 Ext 节点 class，如 x-tree-node） */
+  itemClassName?: string;
+}
+
+export const DragZone: React.FC<DragZoneProps> = (props) => {
+  const groups = props.groups ?? (props.ddGroup ? [props.ddGroup] : ['default']);
+  return (
+    <div className={props.className} style={props.style}>
+      {props.items.map((it) => (
+        <Draggable
+          key={it.id}
+          groups={groups}
+          getDragData={() =>
+            props.getDragData ? props.getDragData(it) : { item: it }
+          }
+          renderGhost={() =>
+            props.renderGhost ? props.renderGhost(it) : it.content
+          }
+          onValidDrop={props.onValidDrop}
+        >
+          <div className={props.itemClassName} data-dd-item data-id={it.id}>
+            {it.content}
+          </div>
+        </Draggable>
+      ))}
+    </div>
+  );
+};

package/src/components/dnd/DropTarget.tsx

@@ -0,0 +1,86 @@
+import { useEffect, useId, useRef } from 'react';
+import { dndManager, DropStatusClass, DropTargetReg, useDndState } from './DndContext';
+
+/**
+ * DropTarget —— 保真复刻 Ext.dd.DropTarget（含 DDTarget 行为）。
+ *
+ * 交互契约（对齐 Ext）：
+ *  - 注册到 DndManager（等价 DDTarget 的 isTarget:true + isNotifyTarget:true）。
+ *  - 拖拽源悬浮时：onDragEnter 触发（等价 notifyEnter，加 overClass）、onDragOver（等价 notifyOver）。
+ *  - 拖拽源离开：onDragOut（等价 notifyOut，移除 overClass）。
+ *  - 松手放置：onDrop（等价 notifyDrop，返回 true 表示有效放置，否则触发源 repair）。
+ *  - validate 返回 false 时 StatusProxy 显示 drop-nodrop（红叉）且不会调用 onDrop。
+ *
+ * overClass 默认等价 Ext.dd.DropTarget 的 overClass 配置（如 'x-dd-drop-over'）。
+ */
+export interface DropTargetProps {
+  ddGroup?: string;
+  groups?: string[];
+  /** 悬浮时加到 el 上的 CSS 类（等价 DropTarget.overClass） */
+  overClass?: string;
+  /** 是否允许放置（等价 notifyOver 返回 dropAllowed/dropNotAllowed 的判断） */
+  validate?: (data: any, e: PointerEvent) => boolean;
+  /** 允许放置时 StatusProxy 显示的状态图标类（默认 'x-dd-drop-ok'，落入列表/区域追加用 'x-dd-drop-ok-add'） */
+  dropStatus?: DropStatusClass;
+  onDragEnter?: (data: any, e: PointerEvent) => void;
+  onDragOver?: (data: any, e: PointerEvent) => void;
+  onDragOut?: (data: any, e: PointerEvent) => void;
+  onDrop?: (data: any, e: PointerEvent) => boolean;
+  className?: string;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+  id?: string;
+  /**
+   * 转发容器 DOM 节点。
+   * 供 DropZone 这类需要「以自身节点作为放置区域 + 同时在其内渲染指示线」的组件复用同一节点，
+   * 避免再套一层无类名的内层 div（那会使容器的 padding 区域落在放置区之外，
+   * 与原生 Ext.dd.DropZone「整个 zone 元素都是放置目标」的语义不符）。
+   */
+  innerRef?: React.MutableRefObject<HTMLDivElement | null>;
+}
+
+export const DropTarget: React.FC<DropTargetProps> = (props) => {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const id = props.id ?? useId();
+  const propsRef = useRef(props);
+  propsRef.current = props;
+  const dnd = useDndState();
+  const over = props.overClass ? dnd.overId === id : false;
+
+  useEffect(() => {
+    const reg: DropTargetReg = {
+      id,
+      groups:
+        propsRef.current.groups ??
+        (propsRef.current.ddGroup ? [propsRef.current.ddGroup] : ['default']),
+      el: ref.current!,
+      overClass: propsRef.current.overClass,
+      validate: (data, e) => propsRef.current.validate?.(data, e) ?? true,
+      dropStatus: propsRef.current.dropStatus,
+      onEnter: (data, e) => propsRef.current.onDragEnter?.(data, e),
+      onOver: (data, e) => propsRef.current.onDragOver?.(data, e),
+      onOut: (data, e) => propsRef.current.onDragOut?.(data, e),
+      onDrop: (data, e) => propsRef.current.onDrop?.(data, e) ?? true,
+    };
+    dndManager.registerDrop(reg);
+    return () => dndManager.unregisterDrop(id);
+  }, [id]);
+
+  const cls = [props.className, over ? props.overClass : null]
+    .filter(Boolean)
+    .join(' ');
+
+  // over 高亮：仅按交互态给 el 注入 overClass（默认 'x-dd-drop-over'，与原生 DropTarget.overClass
+  // 对齐）。原生 ext-all.css / structure/dd.css / theme-*/dd.css 均未给该类配视觉规则，故此处亦不
+  // 新增 CSS、不内联颜色——是否渲染由原生 dd.css 或应用决定，本组件只负责加类名（兼容原生 API）。
+  const setRef = (node: HTMLDivElement | null) => {
+    ref.current = node;
+    if (props.innerRef) props.innerRef.current = node;
+  };
+
+  return (
+    <div ref={setRef} className={cls} style={props.style}>
+      {props.children}
+    </div>
+  );
+};