@epxing/dashboard 0.0.0-stage → 5.3.0-beta.1

package/dist/src/DesignGrid.js

@@ -0,0 +1,711 @@
+import { openBlock, createElementBlock, withModifiers, normalizeStyle, normalizeClass, createElementVNode, Fragment, renderList, createBlock, Teleport, renderSlot, createCommentVNode, markRaw } from "vue";
+import { DDManager, GridStack } from "gridstack";
+import "gridstack/dist/gridstack.min.css";
+import { convertItemBetweenGrids, partitionItems, normalizeGridParams } from "./grid/model.js";
+import { resolveGrid } from "./grid/geometry.js";
+import { normalizeGridItem } from "./layout-util.js";
+import { toWidget, toGridstackOptions, rootStyle, gridLineStyle } from "./grid/gridstackParams.js";
+import { NoCollideEngine, PushOnlyEngine } from "./grid/engines.js";
+/* empty css               */
+import _export_sfc from "../_virtual/_plugin-vue_export-helper.js";
+const pendingSubGrids = /* @__PURE__ */ new Map();
+let idSeq = 0;
+const PRESSED_CLASS = "epx-dashboard-design-grid__stack--pressed";
+const FLOAT_CLASS = "epx-dashboard-design-grid__float";
+const DRAGGING_CLASS = "epx-dashboard-design-grid--dragging";
+const DRAG_END_EVENTS = ["mouseup", "touchend", "touchcancel"];
+const NEAR_CONTAINER_PAUSE = 100;
+const SELECTED_CLASS = "epx-dashboard-design-grid__item--selected";
+let callbacksInstalled = false;
+function installCallbacks() {
+  if (callbacksInstalled) return;
+  callbacksInstalled = true;
+  GridStack.addRemoveCB = (parent, w, add, isGrid) => {
+    if (!add) return void 0;
+    if (isGrid) {
+      const shell = parent.closest(".grid-stack-item");
+      return shell ? pendingSubGrids.get(shell) : void 0;
+    }
+    const owner = parent.__epxDesignGrid;
+    if (!owner) return parent.gridstack ? parent.gridstack.createWidgetDivs(w) : void 0;
+    return owner.createShell(w);
+  };
+}
+function ensureId(item, list) {
+  normalizeGridItem(item);
+  if (item.id != null && item.id !== "") return;
+  let id = item.i != null && item.i !== "" ? String(item.i) : "";
+  while (!id || list.some((o) => o && o !== item && String(o.id) === id)) id = "epx_item_" + ++idSeq;
+  item.id = id;
+  item.i = id;
+}
+function diffWidget(n, w) {
+  const patch = {};
+  for (const k of ["x", "y", "w", "h"]) if (n[k] !== w[k]) patch[k] = w[k];
+  for (const k of ["minW", "maxW", "minH", "maxH"]) if ((n[k] || 0) !== (w[k] || 0)) patch[k] = w[k] || 0;
+  if (!!n.locked !== !!w.locked) {
+    patch.locked = !!w.locked;
+    patch.noMove = !!w.locked;
+    patch.noResize = !!w.locked;
+  }
+  return Object.keys(patch).length ? patch : null;
+}
+const _sfc_main = {
+  name: "epx-dashboard-design-grid",
+  props: {
+    items: { type: Array, default: () => [] },
+    grid: { type: Object, default: () => ({}) },
+    // rowHeight / gap 为 'auto' 时的换算基准（document.body 高度）
+    bodyHeight: { type: Number, default: 0 },
+    // 显式容器宽度（测试 / 无 ResizeObserver 环境用），缺省由 ResizeObserver 测量；挂载后不可变
+    width: { type: Number, default: 0 },
+    // 画布可视高度（px）：换算成 minRow 让根网格盖满画布，指针移到空白处才不会触发库的「离开网格」
+    minHeight: { type: Number, default: 0 },
+    showGridLines: { type: Boolean, default: false },
+    // 容器内子网格：父 DesignGrid 的 api（容器 inject 后传入）；缺省为根实例
+    subGridOf: { type: Object, default: null }
+  },
+  emits: ["change", "transfer-out", "transfer-in", "select"],
+  // 设计态共享选中态（DashboardDesign provide）：选中项的壳要置顶（R31），缺省（无外壳 / 单测）不处理
+  inject: { epxDashboardDesign: { default: null } },
+  provide() {
+    return { epxDashboardDesignGrid: this.api };
+  },
+  data() {
+    return { measuredWidth: 0, shells: {}, floatRows: 0 };
+  },
+  computed: {
+    gridParams() {
+      return normalizeGridParams(this.grid);
+    },
+    // 整页悬浮：全部项进悬浮层，不建碰撞层
+    floatOnly() {
+      return this.gridParams.mode === "float";
+    },
+    containerWidth() {
+      return this.width || this.measuredWidth;
+    },
+    resolved() {
+      return resolveGrid(this.gridParams, { containerWidth: this.containerWidth, bodyHeight: this.bodyHeight });
+    },
+    cellHeight() {
+      return this.resolved.rowHeight + this.resolved.gapY;
+    },
+    // 扣掉根元素上外边距、向下取整：网格盖满画布又不撑出常驻滚动条（向上取整会多出不到一行 + 外边距的高度，真实画布实测出滚动条）
+    minRow() {
+      if (!(this.minHeight > 0)) return 0;
+      const top = this.resolved.padY - this.resolved.gapY / 2;
+      return Math.max(0, Math.floor((this.minHeight - top) / this.cellHeight));
+    },
+    // R32：容器内子实例的悬浮层以容器可视行数为 maxRow（与 minRow 同一套换算、至少 1 行），悬浮子项不可拖出 / 缩出容器底部；
+    // 页面级根实例与尚未量到高度的容器（minHeight 0）不限（0），否则首帧会把项全夹到 1 行
+    floatMaxRow() {
+      if (!this.subGridOf || !(this.minHeight > 0)) return 0;
+      const top = this.resolved.padY - this.resolved.gapY / 2;
+      return Math.max(1, Math.floor((this.minHeight - top) / this.cellHeight));
+    },
+    activeId() {
+      return this.epxDashboardDesign ? this.epxDashboardDesign.state.activeId : null;
+    },
+    liveItems() {
+      return (this.items || []).filter(Boolean);
+    },
+    // 只追踪身份、几何、所在层与锁定字段的签名：外部改坐标 / 悬浮 / 层级（属性面板）或增删项时同步到引擎，改 configs 等不触发
+    layoutKey() {
+      return this.liveItems.map((i) => [i.id, i.x, i.y, i.w, i.h, i.float ? 1 : 0, i.z, i.static ? 1 : 0, i.minW, i.maxW, i.minH, i.maxH].join(":")).join("|");
+    },
+    // 网格线背景（可选）+ 画布可视高度变量：.grid-stack 的 CSS min-height 用它盖满画布底部那不足一行的带子（minRow 向下取整留下的），
+    // 指针拖到那里才不会触发库的「离开网格」；库的 _updateContainerHeight 只删 inline min-height，不影响这条 CSS 规则
+    hostStyle() {
+      const style = this.showGridLines ? { ...gridLineStyle(this.resolved) } : {};
+      const top = this.resolved.padY - this.resolved.gapY / 2;
+      if (this.minHeight > 0) style["--epx-design-grid-min-height"] = `${Math.max(0, this.minHeight - top)}px`;
+      if (this.floatRows > 0) style.minHeight = `${top + this.floatRows * this.cellHeight}px`;
+      return style;
+    },
+    stackStyle() {
+      return rootStyle(this.resolved);
+    },
+    // 非响应式引用集合：给容器子网格与根网格互相登记
+    api() {
+      const owner = this;
+      return markRaw({
+        owner,
+        makeSubGrid: (shellEl, options, subEl) => owner.makeSubGrid(shellEl, options, subEl),
+        register: (child) => {
+          owner.children.add(child);
+        },
+        unregister: (child) => {
+          owner.children.delete(child);
+        },
+        get root() {
+          return owner.rootApi;
+        }
+      });
+    },
+    rootApi() {
+      return this.subGridOf ? this.subGridOf.root : this.api;
+    }
+  },
+  watch: {
+    // 首帧前把 id / x/y/w/h 落定（Teleport 的 key 与引擎对账都靠 id）；deep: 1 只看数组层与元素身份
+    items: {
+      deep: 1,
+      immediate: true,
+      handler(v) {
+        const list = v || [];
+        for (const item of list) if (item) ensureId(item, list);
+      }
+    },
+    layoutKey() {
+      this.syncToGrid();
+    },
+    // 列数变了整体重建（引擎按列数布局）；行高 / 间距变了动态改 cellHeight / margin，壳与内容都保留
+    resolved(n, o) {
+      if (!this.ready || !o) return;
+      if (n.colNum !== o.colNum) {
+        this.rebuild();
+        return;
+      }
+      if (n.rowHeight !== o.rowHeight || n.gapX !== o.gapX || n.gapY !== o.gapY) {
+        const options = toGridstackOptions(n);
+        for (const grid of this.layers()) {
+          grid.cellHeight(options.cellHeight);
+          grid.margin(options.margin);
+        }
+      }
+    },
+    // 碰撞 / 整页悬浮切换：实例组成变了，整体重建
+    floatOnly() {
+      if (this.ready) this.rebuild();
+    },
+    minRow(v) {
+      for (const grid of this.layers()) grid.updateOptions({ minRow: v });
+      this.updateFloatRows();
+    },
+    floatMaxRow(v) {
+      this.applyFloatMaxRow(v);
+    },
+    activeId() {
+      this.applySelected();
+    }
+  },
+  created() {
+    this.gridstack = null;
+    this.floatstack = null;
+    this.ready = false;
+    this.children = /* @__PURE__ */ new Set();
+    this.syncing = false;
+    this.syncTouched = false;
+    this.rebuilding = false;
+    this.unmounted = false;
+    this.dragEnd = null;
+    installCallbacks();
+  },
+  mounted() {
+    if (!this.width) {
+      this.measure();
+      if (typeof ResizeObserver !== "undefined") {
+        this.resizeObserver = new ResizeObserver(() => this.measure());
+        this.resizeObserver.observe(this.$refs.host);
+      }
+    }
+    this.init();
+  },
+  // 壳先于内容创建（Teleport 要到下一次渲染才把内容放进壳），库建 draggable 时扫不到把手会退化成整壳可拖；内容进壳后重扫
+  updated() {
+    this.refreshDragHandles();
+  },
+  beforeUnmount() {
+    this.unmounted = true;
+    if (this.resizeObserver) this.resizeObserver.disconnect();
+    if (this.subGridOf) this.subGridOf.unregister(this.api);
+    this.markDragging(false);
+    this.teardown();
+    this.shells = {};
+  },
+  methods: {
+    measure() {
+      if (this.$refs.host) this.measuredWidth = this.$refs.host.offsetWidth;
+    },
+    // 当前存在的实例（碰撞层 / 悬浮层）
+    layers() {
+      return [this.gridstack, this.floatstack].filter(Boolean);
+    },
+    owns(grid) {
+      return !!grid && (grid === this.gridstack || grid === this.floatstack);
+    },
+    gridOptions(float) {
+      const options = toGridstackOptions(this.resolved, {
+        float,
+        engineClass: float ? NoCollideEngine : PushOnlyEngine
+      });
+      options.acceptWidgets = float ? false : (el) => !el.closest("." + FLOAT_CLASS);
+      options.minRow = this.minRow;
+      options.maxRow = float ? this.floatMaxRow : 0;
+      return options;
+    },
+    init() {
+      const el = this.$refs.root;
+      el.__epxDesignGrid = this;
+      if (!this.floatOnly) {
+        const options = this.gridOptions(false);
+        const shell = this.subGridOf ? el.closest(".grid-stack-item") : null;
+        if (shell) {
+          this.gridstack = this.subGridOf.makeSubGrid(shell, options, el);
+          if (!this.gridstack) {
+            console.error("[epx-dashboard-design-grid] 父网格未就绪，子网格未创建");
+            return;
+          }
+        } else {
+          this.gridstack = GridStack.init(options, el);
+        }
+        if (!this.gridstack.parentGridNode) {
+          this.gridstack.on("change", (ev, nodes) => this.dispatch(nodes, "applyChanges"));
+          this.gridstack.on("added", (ev, nodes) => this.dispatch(nodes, "onAdded"));
+          this.gridstack.on("dragstart", () => this.rootApi.owner.markDragging(true));
+          this.gridstack.on("dragstop", () => this.rootApi.owner.markDragging(false));
+          this.gridstack.on("resizestop", (ev, el2) => this.onShellResizeStop(el2));
+        }
+        this.gridstack.on("dropped", (ev, prev, node) => this.onDropped(prev, node));
+      }
+      if (this.subGridOf) this.subGridOf.register(this.api);
+      this.ready = true;
+      this.syncToGrid(true);
+    },
+    // 悬浮层实例按需创建：与碰撞层同几何参数，float + NoCollideEngine，不接受拖入
+    ensureFloatLayer() {
+      if (this.floatstack) return this.floatstack;
+      const el = this.$refs.floatRoot;
+      el.__epxDesignGrid = this;
+      const grid = GridStack.init(this.gridOptions(true), el);
+      const shellNode = grid.parentGridNode;
+      if (shellNode) {
+        if (shellNode.subGrid === grid) {
+          if (this.gridstack) shellNode.subGrid = this.gridstack;
+          else delete shellNode.subGrid;
+        }
+        delete grid.parentGridNode;
+        el.classList.remove("grid-stack-nested");
+      }
+      grid.on("change", (ev, nodes) => {
+        this.dispatch(nodes, "applyChanges");
+        this.updateFloatRows();
+      });
+      grid.on("added", (ev, nodes) => this.dispatch(nodes, "onAdded"));
+      grid.on("dragstart", () => this.rootApi.owner.markDragging(true));
+      grid.on("drag", () => this.updateFloatRows());
+      grid.on("resize", () => this.updateFloatRows());
+      grid.on("dragstop", () => {
+        this.rootApi.owner.markDragging(false);
+        this.applyFloatMaxRow(this.floatMaxRow);
+        this.updateFloatRows();
+      });
+      grid.on("resizestop", (ev, el2) => {
+        this.onShellResizeStop(el2);
+        this.applyFloatMaxRow(this.floatMaxRow);
+        this.updateFloatRows();
+      });
+      this.floatstack = grid;
+      return grid;
+    },
+    // 悬浮层空了就销毁实例（元素常驻）
+    destroyFloatLayer(removeDOM = false) {
+      const grid = this.floatstack;
+      if (!grid) return;
+      this.floatstack = null;
+      this.floatRows = 0;
+      grid.offAll();
+      if (removeDOM) grid.removeAll(true, false);
+      grid.destroy(false);
+      if (this.$refs.floatRoot) delete this.$refs.floatRoot.__epxDesignGrid;
+    },
+    // 父实例把容器壳转成子网格：先登记子实例的 .grid-stack，库经 addRemoveCB(isGrid) 取回它。
+    // 挂到壳所在的那层实例：一般是碰撞层；整页悬浮（碰撞层不存在）或容器项本身悬浮时是悬浮层——
+    // 子网格的选项全部显式给出（float / 引擎 / acceptWidgets），不会继承悬浮层的无碰撞语义
+    makeSubGrid(shellEl, options, subEl) {
+      const parent = shellEl && shellEl.gridstackNode && shellEl.gridstackNode.grid;
+      if (!parent || !this.owns(parent)) return null;
+      pendingSubGrids.set(shellEl, subEl);
+      try {
+        return parent.makeSubGrid(shellEl, options, void 0, false);
+      } finally {
+        pendingSubGrids.delete(shellEl);
+      }
+    },
+    // 按 node 所属实例分组后回调（子网格的节点 node.grid 是子实例）
+    dispatch(nodes, method) {
+      const groups = /* @__PURE__ */ new Map();
+      for (const node of nodes || []) {
+        const owner = node.grid && node.grid.el && node.grid.el.__epxDesignGrid;
+        if (!owner) continue;
+        if (!groups.has(owner)) groups.set(owner, []);
+        groups.get(owner).push(node);
+      }
+      for (const [owner, list] of groups) owner[method](list);
+    },
+    createShell(w) {
+      const shell = document.createElement("div");
+      shell.className = "grid-stack-item";
+      const content = document.createElement("div");
+      content.className = "grid-stack-item-content";
+      shell.appendChild(content);
+      this.shells[w.id] = content;
+      return shell;
+    },
+    // items → 引擎：首次 / 重建用 load 一次性建；之后按 id 增 / 删 / 改，按 float 分到碰撞层 / 悬浮层（整页悬浮时全进悬浮层）。
+    // 同步后按引擎落定值对账回写 items：批内 update 被边界 / min-max 夹住的节点（update 后库删了 _orig，
+    // batchUpdate(false) 的 getDirtyNodes(true) 不报它）与 load 时被推挤 / 顶部压紧的节点（added 先清 _dirty）
+    // 都不发 change，不对账的话 items 与引擎永久分叉、每次同步重发无效 update。改了值就 emit 一次 change
+    // （与旧库挂载后 compact 触发 layout-updated 一致，外壳 deep watch 据此保存）
+    syncToGrid(initial = false) {
+      if (!this.ready) return;
+      const list = this.liveItems;
+      for (const item of list) ensureId(item, list);
+      const { flow, float } = this.floatOnly ? { flow: [], float: list } : partitionItems(list);
+      const flowWidgets = flow.map(toWidget);
+      const floatWidgets = float.map(toWidget);
+      if (floatWidgets.length) this.ensureFloatLayer();
+      const plan = [[this.gridstack, flowWidgets], [this.floatstack, floatWidgets]].filter(([grid]) => grid);
+      this.syncing = true;
+      this.syncTouched = false;
+      let touched = false;
+      try {
+        if (initial) {
+          for (const [grid, widgets] of plan) grid.load(widgets);
+        } else {
+          const byId = /* @__PURE__ */ new Map();
+          for (const [grid] of plan) for (const n of grid.engine.nodes) byId.set(n.id, n);
+          const ops = [];
+          for (const [grid, widgets] of plan) {
+            for (const w of widgets) {
+              const n = byId.get(w.id);
+              if (!n) {
+                ops.push(["add", grid, w]);
+                continue;
+              }
+              byId.delete(w.id);
+              if (n.grid !== grid) {
+                ops.push(["move", grid, w, n]);
+                continue;
+              }
+              const patch = diffWidget(n, w);
+              if (patch) ops.push(["update", grid, patch, n]);
+            }
+          }
+          for (const [grid] of plan) grid.batchUpdate();
+          for (const [op, grid, w, n] of ops) {
+            if (op === "add") grid.addWidget(w);
+            else if (op === "update") grid.update(n.el, w);
+            else this.moveShell(n, grid, w);
+          }
+          for (const n of byId.values()) {
+            n.grid.removeWidget(n.el, true, false);
+            delete this.shells[n.id];
+          }
+          for (const [grid] of plan) grid.batchUpdate(false);
+        }
+        for (const [grid] of plan) touched = this.writeBack(grid.engine.nodes) || touched;
+        touched = touched || this.syncTouched;
+      } finally {
+        this.syncing = false;
+        this.syncTouched = false;
+      }
+      this.applyFloatZ();
+      if (!floatWidgets.length) this.destroyFloatLayer();
+      this.applySelected();
+      this.updateFloatRows();
+      if (touched) this.$emit("change", this.items);
+    },
+    // 项换层：把壳从一个实例摘下（不删 DOM）再交给另一个实例收编。同一壳元素、Teleport 目标不变，内容组件不重建；
+    // 用 makeWidget 而不是 addWidget：后者会把壳上残留的 gs-* 属性（如旧的 gs-locked）合并进节点
+    moveShell(node, to, w) {
+      const el = node.el;
+      node.grid.removeWidget(el, false, false);
+      el.remove();
+      el.style.zIndex = "";
+      to.makeWidget(el, w);
+    },
+    // 切换项所在层（悬浮 / 碰撞）：只改 item.float，下一拍由 layoutKey 监听同步（壳在两实例间迁移、坐标不变）。
+    // 不在这里直接 syncToGrid：同一拍内再改回去时监听比较的还是上次基线、不会再触发，引擎会与 items 脱节
+    setFloat(item, on) {
+      const target = item ? this.findItem(item.id) : null;
+      if (target) target.float = !!on;
+      return this.$nextTick();
+    },
+    // 悬浮项壳的层级：zIndex = 10 + z（与运行态 epx-dashboard-grid 一致）；碰撞层的壳不设
+    applyFloatZ() {
+      if (!this.floatstack) return;
+      for (const n of this.floatstack.engine.nodes) {
+        const item = this.findItem(n.id);
+        if (n.el) n.el.style.zIndex = String(10 + (Number(item && item.z) || 0));
+      }
+    },
+    // R31：共享选中态里的选中项（两层任一）的壳加置顶类，其余摘掉；容器内子实例各管自己的壳（选中项属于哪个实例由它自己判定）
+    applySelected() {
+      const id = this.activeId;
+      for (const grid of this.layers()) {
+        for (const n of grid.engine.nodes) {
+          if (n.el) n.el.classList.toggle(SELECTED_CLASS, id != null && String(n.id) === String(id));
+        }
+      }
+    },
+    // 悬浮层行数（含 minRow）→ 宿主最小高度；没有悬浮层归零
+    updateFloatRows() {
+      this.floatRows = this.floatstack ? this.floatstack.getRow() : 0;
+    },
+    // R32：悬浮层 maxRow 动态同步（容器高度 / 行高变了）。不走库的 updateOptions：它在超出时 compact()，会把悬浮项按空位重排
+    // （叠放的项被拆开）；直接改 opts / engine 的 maxRow，超出底部的节点自己夹回（update 走 nodeBoundFix：先压高再抬 y），
+    // 批内 update 不发 change → 对账回写 items、改了值 emit 一次 change。
+    // 正在拖拽的节点（_moving，库在 dragstop 前删）跳过、由本层 dragstop 补夹；所在容器壳缩放中（每格一次 update + change 会连发自动保存）
+    // 也不夹，等壳的 resizestop 报到根实例后 force 夹一次
+    applyFloatMaxRow(v, force = false) {
+      const grid = this.floatstack;
+      if (!grid) return;
+      grid.opts.maxRow = grid.engine.maxRow = v;
+      if (!force && this.shellResizing()) return;
+      const over = v ? grid.engine.nodes.filter((n) => !n._moving && n.y + n.h > v) : [];
+      if (!over.length) return;
+      this.syncing = true;
+      this.syncTouched = false;
+      let touched = false;
+      try {
+        grid.batchUpdate();
+        for (const n of over) {
+          const h = Math.min(n.h, v);
+          grid.update(n.el, { h, y: Math.max(0, v - h) });
+        }
+        grid.batchUpdate(false);
+        touched = this.writeBack(grid.engine.nodes) || this.syncTouched;
+      } finally {
+        this.syncing = false;
+        this.syncTouched = false;
+      }
+      this.updateFloatRows();
+      if (touched) this.$emit("change", this.items);
+    },
+    // 本实例所在的容器壳正在被缩放（库给壳打 ui-resizable-resizing，摘除在 resizestop 回调之后）
+    shellResizing() {
+      const shell = this.$refs.host && this.$refs.host.closest(".grid-stack-item");
+      return !!(shell && shell.classList.contains("ui-resizable-resizing"));
+    },
+    // 根实例收到某个壳的 resizestop：壳里（任意层级）的子实例把悬浮层 maxRow 强制夹一次
+    onShellResizeStop(el) {
+      if (!el || !el.contains) return;
+      this.forEachDescendant((owner) => {
+        if (owner.$refs.host && el.contains(owner.$refs.host)) owner.applyFloatMaxRow(owner.floatMaxRow, true);
+      });
+    },
+    // 遍历树内全部子实例（容器子网格及其下级）
+    forEachDescendant(fn) {
+      for (const child of this.children) {
+        fn(child.owner);
+        child.owner.forEachDescendant(fn);
+      }
+    },
+    findItem(id) {
+      return this.liveItems.find((i) => String(i.id) === String(id));
+    },
+    // 引擎 → items：就地改坐标（设计器外壳的 deep watch 据此自动保存），返回是否真的改了值
+    writeBack(nodes) {
+      let touched = false;
+      for (const node of nodes) {
+        const item = this.findItem(node.id);
+        if (!item) continue;
+        for (const k of ["x", "y", "w", "h"]) {
+          if (item[k] !== node[k]) {
+            item[k] = node[k];
+            touched = true;
+          }
+        }
+      }
+      return touched;
+    },
+    // 库的 change 回调：回写并上报；同步期间只记下「改过值」，由 syncToGrid 结束时统一 emit 一次
+    applyChanges(nodes) {
+      const touched = this.writeBack(nodes);
+      if (this.syncing) this.syncTouched = this.syncTouched || touched;
+      else if (touched) this.$emit("change", this.items);
+    },
+    // 库把别的网格的壳搬进来（跨网格）时壳仍是同一元素：登记它，等父组件把数据 push 进 items 后 Teleport 才会渲染
+    onAdded(nodes) {
+      for (const node of nodes) {
+        if (node.el && !this.shells[node.id]) this.shells[node.id] = node.el.querySelector(".grid-stack-item-content");
+      }
+    },
+    // 跨网格搬运（库已把壳搬到本实例）：按视觉尺寸换算到本网格（spec §7.3）、同步 update 让壳大小跟上，
+    // 再通知两边父组件搬数据：源删、本加（内容组件随之重建，spec §9.0）
+    onDropped(prev, node) {
+      this.rootApi.owner.markDragging(false);
+      if (!prev || !prev.grid) return;
+      const from = prev.grid.el && prev.grid.el.__epxDesignGrid;
+      if (!from || from === this) return;
+      const item = from.findItem(node.id);
+      if (!item) return;
+      const conv = convertItemBetweenGrids({ ...item, x: node.x, y: node.y }, from.resolved, this.resolved);
+      this.gridstack.update(node.el, { w: conv.w, h: conv.h });
+      Object.assign(conv, { x: node.x, y: node.y, w: node.w, h: node.h });
+      delete from.shells[node.id];
+      from.$emit("transfer-out", item);
+      this.$emit("transfer-in", conv, node);
+    },
+    // 拖拽进行中的标记（只打在根实例的宿主上，容器子网格 / 悬浮层的起手都报到这里）：期间所有悬浮壳不吃指针，
+    // 否则指针进悬浮壳时碰撞层根元素收到 mouseleave、库临时摘掉被拖节点（3.0 探针 Step 5）。
+    // 摘除以两层实例的 dragstop（同网格落位、Esc 取消、touch 结束都走它，Esc / touch 没有真实 mouseup）与跨网格的 dropped 为准，
+    // document 捕获阶段的 mouseup / touchend / touchcancel 只兜底；卸载时一并解绑
+    markDragging(on) {
+      const host = this.$refs.host;
+      if (on && host && !this.dragEnd) {
+        host.classList.add(DRAGGING_CLASS);
+        this.dragEnd = () => this.markDragging(false);
+        for (const type of DRAG_END_EVENTS) document.addEventListener(type, this.dragEnd, true);
+        this.dragMove = () => this.updateDragPause();
+        document.addEventListener("mousemove", this.dragMove, { capture: true, passive: true });
+        this.updateDragPause();
+      } else if (!on && this.dragEnd) {
+        if (host) host.classList.remove(DRAGGING_CLASS);
+        for (const type of DRAG_END_EVENTS) document.removeEventListener(type, this.dragEnd, true);
+        this.dragEnd = null;
+        document.removeEventListener("mousemove", this.dragMove, true);
+        this.dragMove = null;
+        DDManager.pauseDrag = false;
+      }
+    },
+    // 所有后代子网格实例的宿主元素（容器内的画布区域，即接手拖入的区域）
+    subHosts() {
+      const hosts = [];
+      const walk = (api) => {
+        for (const child of api.owner.children) {
+          if (child.owner.$refs.host) hosts.push(child.owner.$refs.host);
+          walk(child);
+        }
+      };
+      walk(this.api);
+      return hosts;
+    },
+    // 被拖的壳与某个「还没进入的容器」的子网格区域相交 → 打开落位停顿，否则关掉。
+    // 排除：被拖的壳自己里面的子网格（拖的是容器）、当前接手拖拽的网格所在的容器及其祖先（已经在里面了）。
+    // 悬浮项（壳直接挂在悬浮层根下）本就不能靠拖拽进任何容器（碰撞层 acceptWidgets 拒收悬浮壳、悬浮层自己 acceptWidgets=false，
+    // 悬浮进出只走属性面板开关），碰到容器也不必开停顿——直接关掉，省掉这份拖沓
+    updateDragPause() {
+      const dragging = DDManager.dragElement && DDManager.dragElement.el;
+      if (!dragging) return;
+      const layer = dragging.parentElement;
+      if (layer && layer.classList.contains(FLOAT_CLASS)) {
+        DDManager.pauseDrag = false;
+        return;
+      }
+      const current = DDManager.dropElement && DDManager.dropElement.el;
+      const r = dragging.getBoundingClientRect();
+      const near = this.subHosts().some((host) => {
+        if (dragging.contains(host) || current && host.contains(current)) return false;
+        const h = host.getBoundingClientRect();
+        return r.right > h.left && r.left < h.right && r.bottom > h.top && r.top < h.bottom;
+      });
+      DDManager.pauseDrag = near ? NEAR_CONTAINER_PAUSE : false;
+    },
+    // 拖拽把手落在壳本身、或已不在壳子树内（跨网格搬运时库先 _removeDD 再 _prepareElement 重建 DD，
+    // dragEls 指向源侧旧内容里的元素，随后被 Teleport 卸载）且壳内已有把手元素的项，重扫把手（库会换掉 mousedown 监听）
+    refreshDragHandles() {
+      for (const grid of this.layers()) {
+        const handle = grid.opts.draggable && grid.opts.draggable.handle;
+        if (!handle) continue;
+        for (const n of grid.engine.nodes) {
+          const dd = n.el && n.el.ddElement && n.el.ddElement.ddDraggable;
+          if (!dd || !n.el.querySelector(handle)) continue;
+          if (dd.dragEls.some((h) => h === n.el || !n.el.contains(h))) grid.refreshDragHandles(n.el);
+        }
+      }
+    },
+    // 点击项（含拖拽起手）→ 选中；嵌套时事件会冒到父根元素，只处理属于本实例（两层任一）的壳
+    onMouseDown(e) {
+      const target = e.target && e.target.closest ? e.target : null;
+      if (!target) return;
+      const shell = target.closest(".grid-stack-item");
+      const node = shell && shell.gridstackNode;
+      const grid = node && node.grid;
+      const mine = this.owns(grid);
+      if (this.subGridOf && mine && node.noMove) {
+        const pressed = grid.el;
+        pressed.classList.add(PRESSED_CLASS);
+        setTimeout(() => pressed.classList.remove(PRESSED_CLASS), 0);
+      }
+      if (!mine) return;
+      const item = this.findItem(node.id);
+      if (item) this.$emit("select", item);
+    },
+    // 先拆子网格再拆自己：子网格的事件沿 parentGridNode 冒到根 el，父先销毁会让子销毁时访问已释放的 el
+    teardown(removeDOM = false) {
+      for (const child of Array.from(this.children)) child.owner.teardown();
+      this.children.clear();
+      this.ready = false;
+      this.destroyFloatLayer(removeDOM);
+      const grid = this.gridstack;
+      if (!grid) return;
+      this.gridstack = null;
+      grid.offAll();
+      if (removeDOM) grid.removeAll(true, false);
+      if (grid.parentGridNode) {
+        delete grid.parentGridNode.subGrid;
+        delete grid.parentGridNode;
+      }
+      grid.destroy(false);
+      if (this.$refs.root) delete this.$refs.root.__epxDesignGrid;
+    },
+    // 列数变化：清壳并等 Teleport 卸载内容（子网格随内容一起销毁），再重建引擎与壳；内容组件重建一次
+    async rebuild() {
+      if (this.rebuilding) return;
+      this.rebuilding = true;
+      try {
+        this.teardown(true);
+        this.shells = {};
+        await this.$nextTick();
+        if (this.unmounted || !this.$refs.root || this.ready) return;
+        this.init();
+      } catch (e) {
+        console.error("[epx-dashboard-design-grid] 重建网格失败", e);
+      } finally {
+        this.rebuilding = false;
+      }
+    }
+  }
+};
+function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
+  return openBlock(), createElementBlock("div", {
+    ref: "host",
+    class: normalizeClass(["epx-dashboard-design-grid", { "epx-dashboard-design-grid--root": !$props.subGridOf }]),
+    style: normalizeStyle($options.hostStyle),
+    onDragstart: _cache[2] || (_cache[2] = withModifiers(() => {
+    }, ["prevent"]))
+  }, [
+    createElementVNode("div", {
+      ref: "root",
+      class: "grid-stack epx-dashboard-design-grid__stack",
+      style: normalizeStyle($options.stackStyle),
+      onMousedown: _cache[0] || (_cache[0] = (...args) => $options.onMouseDown && $options.onMouseDown(...args))
+    }, null, 36),
+    createElementVNode("div", {
+      ref: "floatRoot",
+      class: "grid-stack epx-dashboard-design-grid__float",
+      style: normalizeStyle($options.stackStyle),
+      onMousedown: _cache[1] || (_cache[1] = (...args) => $options.onMouseDown && $options.onMouseDown(...args))
+    }, null, 36),
+    (openBlock(true), createElementBlock(Fragment, null, renderList($options.liveItems, (item) => {
+      return openBlock(), createElementBlock(Fragment, {
+        key: item.id
+      }, [
+        $data.shells[item.id] ? (openBlock(), createBlock(Teleport, {
+          key: 0,
+          to: $data.shells[item.id]
+        }, [
+          renderSlot(_ctx.$slots, "item", { item }),
+          renderSlot(_ctx.$slots, "chrome", { item })
+        ], 8, ["to"])) : createCommentVNode("", true)
+      ], 64);
+    }), 128))
+  ], 38);
+}
+const DesignGrid = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
+export {
+  DesignGrid as default
+};