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

package/src/DesignGrid.vue

@@ -0,0 +1,851 @@
+<template>
+  <!-- dragstart.prevent：画布内一律不走浏览器原生拖拽（选区 / 图片 / 链接）。gridstack 用的是 mouse 事件，原生拖拽一旦起来会抢走指针，
+       库收不到 mousemove / mouseup 就卡在拖拽态（松手不归位、再点一下才恢复）；配合样式里的 user-select: none 让选区根本形不成 -->
+  <div ref="host" :class="['epx-dashboard-design-grid', { 'epx-dashboard-design-grid--root': !subGridOf }]" :style="hostStyle" @dragstart.prevent>
+    <div ref="root" class="grid-stack epx-dashboard-design-grid__stack" :style="stackStyle" @mousedown="onMouseDown"></div>
+    <!-- 悬浮层：第二个 gridstack 实例（无碰撞、可叠放），与碰撞层同几何参数、绝对定位盖在其上；空白处不吃指针，只有壳吃。
+         元素常驻，实例只在有悬浮项时才建（spec §9.4） -->
+    <div ref="floatRoot" class="grid-stack epx-dashboard-design-grid__float" :style="stackStyle" @mousedown="onMouseDown"></div>
+    <!-- 内容由 Vue 持有、Teleport 进库造的壳；壳还没造好（首帧）或已被库搬到别的网格时不渲染 -->
+    <template v-for="item in liveItems" :key="item.id">
+      <Teleport v-if="shells[item.id]" :to="shells[item.id]">
+        <slot name="item" :item="item"></slot>
+        <slot name="chrome" :item="item"></slot>
+      </Teleport>
+    </template>
+  </div>
+</template>
+
+<script>
+// 看板网格（设计态）：封装 gridstack 13。壳（.grid-stack-item）由库经 GridStack.addRemoveCB 创建，
+// 内容由本组件用 <Teleport> 渲染进壳，库搬 DOM 时 Vue 不会去删元素（spec §9.0）。
+// items 是唯一真值：库触发 change 时就地改 item.x/y/w/h（设计器外壳的 deep watch 据此自动保存）；
+// 外部改了坐标（属性面板）则同步到引擎。库实例挂 this.gridstack / this.floatstack（prop grid 是 v3 网格参数）、不进 data（响应式代理会破坏库内部）。
+// 两层实例（spec §9.4）：碰撞层 this.gridstack 渲染 float !== true 的项（PushOnlyEngine，推挤 + 紧凑），
+// 悬浮层 this.floatstack 渲染 float === true 的项（NoCollideEngine + float，可叠放、按 z 定层级）；grid.mode === 'float' 时只有悬浮层。
+// 容器内的子网格是另一个本组件实例（:sub-grid-of 传父 api），其碰撞层 .grid-stack 由父实例 makeSubGrid 收编；悬浮层永远是独立实例。
+import { markRaw } from 'vue'
+import { GridStack, DDManager } from 'gridstack'
+import 'gridstack/dist/gridstack.min.css'
+import { normalizeGridParams, convertItemBetweenGrids, partitionItems } from './grid/model'
+import { resolveGrid } from './grid/geometry'
+import { normalizeGridItem } from './layout-util'
+import { toGridstackOptions, rootStyle, toWidget, gridLineStyle } from './grid/gridstackParams'
+import { PushOnlyEngine, NoCollideEngine } from './grid/engines'
+
+// 子网格登记：父 makeSubGrid 前把「壳元素 → 子实例渲染的 .grid-stack」登记在此，
+// 库建子网格时经 addRemoveCB(isGrid) 取回，收编 Vue 的元素而不是自己造一个
+const pendingSubGrids = new Map()
+// 无 id 项的兜底计数
+let idSeq = 0
+// 子网格里按在锁定项上时给所在层根元素打的标记，上级网格里容器项的 draggable.cancel 命中它就不起拖（锁定的是子项、别把整个容器拖走）
+const PRESSED_CLASS = 'epx-dashboard-design-grid__stack--pressed'
+// 悬浮层根元素的类：碰撞层的 acceptWidgets 据此拒收来自悬浮层的壳
+const FLOAT_CLASS = 'epx-dashboard-design-grid__float'
+// 拖拽进行中打在根宿主上的标记：期间所有悬浮壳不吃指针（见样式说明）
+const DRAGGING_CLASS = 'epx-dashboard-design-grid--dragging'
+// 拖拽结束的兜底事件（document 捕获阶段）：权威来源是两层实例的 dragstop 与跨网格的 dropped，这里只兜库不发事件的路径
+const DRAG_END_EVENTS = ['mouseup', 'touchend', 'touchcancel']
+// 碰到「还没进入的容器」时临时打开的落位停顿（ms，写进库的全局开关 DDManager.pauseDrag，每次 mousemove 都会读）：
+// 平时不停顿、占位块实时跟手；被拖的壳一碰到某个容器的子网格区域就停顿——不停顿的话碰撞会先把容器推开、指针永远进不去（R27 实测），
+// 进去之后（或离开）又关掉，容器内的碰撞同样实时。原 R27 是全局常开 100ms，占位块要等指针停下才落位、手感拖沓
+const NEAR_CONTAINER_PAUSE = 100
+// 选中项的壳（R31）：z-index 抬到 600 > 悬浮层根 500，碰撞层选中项的操作条 / 把手不被悬浮项遮住，悬浮层内也压过其它悬浮壳
+const SELECTED_CLASS = 'epx-dashboard-design-grid__item--selected'
+
+// 全局回调只装一次：造壳按网格元素反查所属实例（el.__epxDesignGrid）
+let callbacksInstalled = false
+function installCallbacks () {
+  if (callbacksInstalled) return
+  callbacksInstalled = true
+  GridStack.addRemoveCB = (parent, w, add, isGrid) => {
+    // 删除交给库（removeWidget 自己 remove DOM）
+    if (!add) return undefined
+    if (isGrid) {
+      // parent 是容器壳的内容盒
+      const shell = parent.closest('.grid-stack-item')
+      return shell ? pendingSubGrids.get(shell) : undefined
+    }
+    const owner = parent.__epxDesignGrid
+    // 非本组件管理的实例退回库默认造壳
+    if (!owner) return parent.gridstack ? parent.gridstack.createWidgetDivs(w) : undefined
+    return owner.createShell(w)
+  }
+}
+
+// 项必须有 id（引擎按 id 对账、Teleport 按 id 找壳）：normalizeGridItem 只在有 id 时补 i，
+// 无 id 的旧数据用 i 兜底，再没有就按计数造一个；计数 id 带前缀并对当前列表查重，避免撞上持久化的同名 id
+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
+}
+
+// 引擎节点与目标 widget 的差异，只含变化的键（update 只对传入的键做事，避免无谓的拖放重建）；
+// 锁定切换要同时改 locked / noMove / noResize
+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
+}
+
+export default {
+  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 () {
+    // shells：id → 壳的内容盒（.grid-stack-item-content），Teleport 目标；两层共用一张表（id 唯一）
+    // floatRows：悬浮层当前行数（含 minRow），驱动宿主最小高度（悬浮层绝对定位、不撑宿主）
+    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`
+      // 宿主高度取两层最大：碰撞层是流内元素自然撑起宿主，悬浮层绝对定位不参与，其高度（上外边距 + 行数 × cellHeight）
+      // 作为宿主最小高度——悬浮项拖到碰撞层内容之下时宿主跟着撑高、网格线延伸，与运行态 layoutHeight（含悬浮项坐标）语义一致
+      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
+    // 实例已就绪（init 完成、teardown 前）：items → 引擎的同步只在此期间进行
+    this.ready = false
+    this.children = new Set()
+    // items → 引擎同步期间，库回调的 change 只回写不上报；同步结束按是否改了值统一 emit 一次
+    this.syncing = false
+    this.syncTouched = false
+    // rebuild 进行中 / 组件已卸载的竞态守卫
+    this.rebuilding = false
+    this.unmounted = false
+    // 拖拽结束的 document 兜底监听（mouseup / touchend / touchcancel），只有根实例持有
+    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
+      })
+      // 碰撞层接受跨网格拖入，但不收来自悬浮层的壳（悬浮项只经属性面板开关进出悬浮层，不靠拖拽跨层）；悬浮层不建 droppable。
+      // 子网格会继承父 opts（含 minRow），这两个键都显式给；悬浮层另有 maxRow（R32，根实例 / 碰撞层为 0 不限）
+      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
+      // 整页悬浮（grid.mode === 'float'）只有悬浮层实例，碰撞层不建
+      if (!this.floatOnly) {
+        const options = this.gridOptions(false)
+        // 子网格：壳由父实例造，Teleport 内容（含本组件）在壳里，由父实例把本组件的 .grid-stack 收编成子网格
+        const shell = this.subGridOf ? el.closest('.grid-stack-item') : null
+        if (shell) {
+          this.gridstack = this.subGridOf.makeSubGrid(shell, options, el)
+          if (!this.gridstack) {
+            // eslint-disable-next-line no-console
+            console.error('[epx-dashboard-design-grid] 父网格未就绪，子网格未创建')
+            return
+          }
+        } else {
+          this.gridstack = GridStack.init(options, el)
+        }
+        // change / added 只在最外层 el 派发（子网格的也冒到根），根实例按 node.grid 反查所属实例分发；
+        // dragstart / dragstop 同样只报到最外层实例（子网格的拖拽起手 / 落位也在这里收到）
+        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))
+          // 容器壳缩放结束（子网格的也报到根）：壳里的子实例把悬浮层 maxRow 夹一次（缩放过程中不逐格夹，见 applyFloatMaxRow）
+          this.gridstack.on('resizestop', (ev, el) => this.onShellResizeStop(el))
+        }
+        // dropped 在接收方实例触发、不冒泡：每个实例都挂
+        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)
+      // 库构造时按最近的壳（容器项）自动把实例挂成该壳的子网格，会顶掉碰撞层的子网格登记（一个壳只能有一个子网格）；
+      // 悬浮层是独立实例（事件在自己的 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')
+      }
+      // change / added 同样按 node 所属实例分发：挂在悬浮层壳里的容器子网格（整页悬浮 / 悬浮的容器项）事件冒到这里
+      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))
+      // 拖动 / 缩放进行中（每落一格触发一次）就撑高宿主，指针到碰撞层内容之下时网格线跟着延伸；
+      // 结束时再算一次：Esc 取消会把节点放回原位而不发 change（实测），行数要跟着回落
+      grid.on('drag', () => this.updateFloatRows())
+      grid.on('resize', () => this.updateFloatRows())
+      // 拖拽 / 缩放结束：拖动中被跳过的 maxRow 夹回（容器在拖拽期间变矮）在这里补做，再算行数
+      grid.on('dragstop', () => {
+        this.rootApi.owner.markDragging(false)
+        this.applyFloatMaxRow(this.floatMaxRow)
+        this.updateFloatRows()
+      })
+      grid.on('resizestop', (ev, el) => {
+        // 悬浮层里的容器壳缩放结束：壳内子实例夹一次（与碰撞层根的 resizestop 同一处理）
+        this.onShellResizeStop(el)
+        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) {
+      // 壳还没进任何实例（父重建中 / 已拆）时不建子网格：父重建完成后 Teleport 会重新挂载子实例
+      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, undefined, false)
+      } finally {
+        pendingSubGrids.delete(shellEl)
+      }
+    },
+    // 按 node 所属实例分组后回调（子网格的节点 node.grid 是子实例）
+    dispatch (nodes, method) {
+      const groups = 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)
+      // load / addWidget 会把传入对象直接当引擎节点用，必须传纯拷贝（toWidget 返回新对象）
+      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 {
+          // 先按同步前两层引擎的状态把全部差异算齐再应用：批内 update 的推挤会改别的节点，
+          // 边算边应用会把 items 里没改过的项又「更新」回旧位置、和推挤打架
+          const byId = 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()
+      // 层级只属于悬浮层（回碰撞层清掉；进悬浮层由 applyFloatZ 重设）
+      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) {
+      // 跨网格搬运时源实例不发 dragstop（库在目标网格接手后早退），拖拽标记在这里摘
+      this.rootApi.owner.markDragging(false)
+      // 外部拖入（阶段 5 预留）
+      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 })
+      // 取引擎落定后的位置（update 可能被边界夹住或推挤）
+      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)
+      // 子网格里按在本实例的锁定项上（它的 DD 已停用、事件会一路冒到容器壳）→ 本次事件派发期间给所在层（碰撞层 / 悬浮层）的根打「按下」标记，
+      // 随后冒泡到容器项内容盒时其 draggable.cancel 命中标记、容器不起拖（锁定的是子项、别把整个容器拖走）；派发完（宏任务）即摘除。
+      // 子网格空白处按下不标记：事件冒到容器壳内容盒、容器由此起拖（容器没有专门的起手区，与旧版「空白处可拖容器」一致）；
+      // 子项内按下也不标记（子项自己的 DD 起拖并置 mouseHandled）
+      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 () {
+      // 竞态守卫：重建进行中再触发不重复排队（init 读的是最新 resolved）；等待期间组件卸载则不再建
+      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) {
+        // eslint-disable-next-line no-console
+        console.error('[epx-dashboard-design-grid] 重建网格失败', e)
+      } finally {
+        this.rebuilding = false
+      }
+    }
+  }
+}
+</script>
+
+<style lang="scss">
+@include b(dashboard-design-grid) {
+  position: relative;
+  min-height: 60px;
+  // 设计态不需要选中文字：在不起拖的位置（子网格空白 / 按钮 / 锁定项，库不 preventDefault）按下拖动会拉出文字选区，
+  // 下次按在选区上拖就变成浏览器原生拖选区（幽灵图里是文字 + 图表 canvas）、把 gridstack 的拖拽卡死；从根上不让选区形成
+  user-select: none;
+  // R31：根宿主自成堆叠上下文，两层的 z-index（悬浮层根 500 / 选中壳 600 / 拖动中 10000）只在画布内比较、不与画布外元素比；
+  // 容器内的子宿主不隔离：子实例两层的 z 直接参与根宿主的上下文（容器壳 / 子宿主都不建上下文），
+  // 容器里的选中项（600）与拖动中的子壳（10000）才压得过页面级悬浮层（500）
+  @include m(root) {
+    isolation: isolate;
+  }
+  @include e(stack) {
+    min-height: var(--epx-design-grid-min-height, 60px);
+  }
+  // 悬浮层根：同几何参数（宽 / 外边距由 stackStyle 给）绝对定位盖在碰撞层上；空白处不吃指针（点击 / 拖动穿透到碰撞层），只有壳吃。
+  // 自成堆叠上下文并压过碰撞层项的缩放把手（库 100 / 101）与操作条（200），但低于选中壳（600）与拖动 / 缩放中的项（10000）；
+  // 碰撞层根不设 z-index（其壳的 z 直接参与宿主上下文）。选择器比库的 .grid-stack { position: relative } 多一级，不靠样式加载顺序
+  > .epx-dashboard-design-grid__float {
+    position: absolute;
+    top: 0;
+    left: 0;
+    z-index: 500;
+    pointer-events: none;
+    > .grid-stack-item {
+      pointer-events: auto;
+    }
+  }
+  // R31：选中项的壳置顶——碰撞层的选中壳压过悬浮层根（500），操作条 / 8 向把手不被悬浮项遮住；悬浮层内的选中壳同样压过其它悬浮壳
+  // （悬浮壳的 z 按 10 + z 写在 inline 样式上，要 !important 才压得过）。拖动 / 缩放中的壳（下一条，同优先级、靠后者胜）仍最高
+  .grid-stack > .grid-stack-item > .grid-stack-item-content {
+    // 选中 / 悬停边框画在内容盒上（与缩放圆点同一层，对齐不受壳 margin 影响）；
+    // 内容盒 overflow:visible 不会裁切伪元素
+    &::after {
+      content: '';
+      position: absolute;
+      inset: 0;
+      border: 1px dashed transparent;
+      pointer-events: none;
+      z-index: 601;
+    }
+  }
+  .grid-stack > .grid-stack-item {
+    &:hover > .grid-stack-item-content::after,
+    &.epx-dashboard-design-grid__item--selected > .grid-stack-item-content::after {
+      border-color: rgba(var(--color-primary), 1);
+    }
+    // 容器 / 标签页：指针移到子网格里的项上、或子项被选中时，只显示最内层项的边框、圆点和操作条
+    &:has(.grid-stack-item:hover, .grid-stack-item.epx-dashboard-design-grid__item--selected) {
+      > .grid-stack-item-content::after {
+        border-color: transparent !important;
+      }
+      > .grid-stack-item-content > .epx-dashboard-design-item > .epx-dashboard-design-item__handle,
+      > .grid-stack-item-content > .epx-dashboard-design-item > .epx-dashboard-design-item__operates {
+        display: none !important;
+      }
+    }
+  }
+  .grid-stack > .grid-stack-item.epx-dashboard-design-grid__item--selected {
+    z-index: 600 !important;
+  }
+  .grid-stack > .grid-stack-item.ui-draggable-dragging,
+  .grid-stack > .grid-stack-item.ui-resizable-resizing {
+    z-index: 10000 !important;
+  }
+  // 拖拽进行中（标记打在根实例宿主上，盖住容器内的悬浮层）：所有悬浮壳不吃指针，
+  // 否则指针进悬浮壳时碰撞层根元素收到 mouseleave、库临时摘掉被拖节点（3.0 探针 Step 5）
+  @include m(dragging) {
+    .epx-dashboard-design-grid__float > .grid-stack-item {
+      pointer-events: none;
+    }
+    // 拖拽进行中不显示任何项的选中 / 悬停虚线框（含正在拖的项——拖的时候把原本的选中框也取消，画面干净；
+    // 被指针穿透经过的下方项也不亮）
+    .grid-stack > .grid-stack-item > .grid-stack-item-content::after {
+      border-color: transparent !important;
+    }
+    // 缩放圆点与操作条同样全隐：拖是移位不是缩放，选中态的 chrome（圆点 / 操作按钮）在拖拽时都多余
+    .epx-dashboard-design-item__handle,
+    .epx-dashboard-design-item__operates {
+      display: none !important;
+    }
+  }
+  // 壳只负责定位；内容盒撑满且不裁切（选中边框 / 操作条要露出壳外），选择器优先级压过库的 overflow 规则
+  .grid-stack > .grid-stack-item > .grid-stack-item-content {
+    overflow: visible;
+  }
+  // 图表限高：在 design-item__body 层裁切溢出，design-item 自身保持 overflow:visible 让 outline 选中边框正常渲染。
+  // 设计态结构：壳 → design-item → __body → .drag-component → epx-chart
+  // 运行态结构：壳 → .dashboard-component → epx-chart
+  .grid-stack-item-content > .epx-dashboard-design-item {
+    > .epx-dashboard-design-item__body {
+      height: 100%;
+      overflow: hidden;
+    }
+    .drag-component,
+    .epx-chart {
+      height: 100% !important;
+      min-height: 0 !important;
+      max-height: 100% !important;
+      overflow: hidden !important;
+    }
+  }
+  .grid-stack-item-content > .dashboard-component {
+    height: 100% !important;
+    overflow: hidden !important;
+    .epx-chart {
+      height: 100% !important;
+      min-height: 0 !important;
+      max-height: 100% !important;
+      overflow: hidden !important;
+    }
+  }
+  // 拖动中的壳连同内部元素都不吃指针：库给壳写了 inline pointer-events:none 让指针下的目标网格能收到 mouseenter / mouseleave，
+  // 但容器组件根元素（dashboard-div / dashboard-tabs）带 pointer-events:all !important 会把它盖回去，容器就永远拖不进别的网格
+  .grid-stack-item.ui-draggable-dragging,
+  .grid-stack-item.ui-draggable-dragging * {
+    pointer-events: none !important;
+  }
+  // 占位块不吃指针：它贴着指针走（与被拖的壳几乎重合），吃指针的话指针永远进不到旁边容器的壳里，
+  // 容器收不到 mouseenter 就不会接手拖入（实测：慢速拖动只会把容器推开、进不去）
+  .grid-stack-placeholder {
+    pointer-events: none;
+  }
+}
+</style>