@allbluecn/web-app 0.17.2 → 0.18.0

package/src/components/design/canvas/plugins/leafer-x-board/index.ts

@@ -0,0 +1,492 @@
+// SPDX-License-Identifier: MIT
+//
+// leafer-x-board — Figma 式画板（Frame）名称标签插件
+// （LeaferJS 社区插件规范，leafer-x 系列）
+//
+// 官方没有「画板」概念：Frame 容器的名称标签、点击标签选中画板、拖标签
+// 移动画板，是设计工具的通用需求，官方不提供。本插件在 App 的 sky 装饰层
+// 维护名称标签（不参与缩放变换、不参与序列化），提供：
+// - sync(frames)：业务驱动增量 diff 标签（新增/改名/移除/跟随画板）
+// - pickLabel(clientX, clientY)：标签命中检测（返回业务 id）
+// - 拖标签联动移动画板（sky 空间 → 画板父容器 inner 空间的官方坐标链）
+// - 视口变化（zoomLayer PropertyEvent.CHANGE）自动重投影
+//
+// 契约（自包含，可整体搬移发布）：
+// - 仅 type import leafer 类型 + 插件自身文件；运行时经 installWithModule
+//   注入（SSR 友好、与消费方实例同源）；零业务依赖——画板集合由业务通过
+//   sync() 驱动，插件不感知文档模型
+
+import type { ILeaf, IUI } from "leafer-editor"
+
+/** 单个画板的登记信息（业务文档变更后经 sync 驱动） */
+export interface BoardFrameInput {
+  /** 业务 id（标签 leaf id 为 `${idPrefix}${id}`） */
+  id: string
+  /** 画板 leaf（标签位置随其 world 包围盒投影） */
+  leaf: ILeaf
+  /** 标签文本 */
+  name: string
+  /** 「生成中」脉冲态（FS-8.3 AI 流式生成）：true → 画板视觉 bounds 上渲染
+   *  脉冲虚线边框（id 前缀 `frame_generating:`，skipJSON 装饰，不参与序列化）；
+   *  缺省/false → 清除。脉冲动画由插件内置定时器驱动（透明度往复） */
+  generating?: boolean
+}
+
+export interface BoardOptions {
+  /** 标签挂载的装饰层（默认 target 所属 App 的 sky；也可显式传任意 ILeaf 层） */
+  sky?: ILeaf
+  /** 标签与画板视觉左上的垂直距离（默认 28，负方向朝上） */
+  labelOffsetY?: number
+  /** 标签 id 前缀（默认 "frame_label:"） */
+  idPrefix?: number | string
+  /** 标签命中判定的屏幕像素容差（默认 4，sky 不缩放故为恒定屏幕像素） */
+  hitPadding?: number
+  /** 拖标签移动画板后的回调（业务可在此读回文档） */
+  onFrameMove?: (id: string) => void
+}
+
+export interface BoardFramePlugin {
+  /**
+   * 增量同步标签：按传入集合 diff 现有标签（新增/改名/移除），
+   * 并把每个标签重投影到画板当前视觉位置。业务文档变更后调用。
+   */
+  sync(frames: BoardFrameInput[]): void
+  /** 标签命中检测：client 坐标落在某标签上（含容差）返回业务 id，否则 null */
+  pickLabel(clientX: number, clientY: number): string | null
+  /** 手动触发一次标签重投影（插件已自动监听 zoomLayer CHANGE，自定义视口源时用） */
+  syncPositions(): void
+  destroy(): void
+}
+
+export interface LeaferBoardModule {
+  PropertyEvent: { CHANGE: string }
+  DragEvent?: { START: string; DRAG: string; END: string }
+  Text: { one: (data: unknown, x?: number, y?: number) => IUI }
+  /** 脉冲虚线框用（缺省时「生成中」装饰降级为无渲染，不抛错） */
+  Rect?: { one: (data: unknown, x?: number, y?: number) => IUI }
+}
+
+interface LabelEntry {
+  id: string
+  label: IUI
+  frame: ILeaf
+}
+
+/** 「生成中」脉冲框登记项 */
+interface GeneratingEntry {
+  id: string
+  rect: IUI
+  frame: ILeaf
+}
+
+const DEFAULT_OFFSET_Y = 28
+const DEFAULT_ID_PREFIX = "frame_label:"
+const DEFAULT_HIT_PADDING = 4
+const GENERATING_ID_PREFIX = "frame_generating:"
+/** 脉冲节拍（透明度往复周期）；短周期低开销，装饰 leaf 数量 ≤ 画板数 */
+const PULSE_INTERVAL_MS = 600
+const PULSE_OPACITY_ON = 0.95
+const PULSE_OPACITY_OFF = 0.35
+const GENERATING_STROKE = "rgba(99,102,241,0.9)"
+
+type ClientPoint = { clientX: number; clientY: number }
+type Point = { x: number; y: number }
+
+// 坐标换算面收窄：ILeaf 的坐标方法声明在子接口未随主接口导出（与 engine
+// 的 ReparentTarget 收窄同风格），运行时 tree/sky/任意容器均可用
+type CoordinateLeaf = ILeaf & {
+  getWorldPointByClient: (p: ClientPoint, update?: boolean) => Point
+  getClientPointByWorld: (p: Point) => Point
+  getInnerPoint: (p: Point) => Point
+  worldToLocal: (world: Point, to?: Point, distance?: boolean, relative?: ILeaf) => void
+  getLocalToWorld: (local: Point, to?: Point, distance?: boolean, relative?: ILeaf) => Point
+}
+
+class BoardPlugin implements BoardFramePlugin {
+  private mod: LeaferBoardModule
+  private tree: CoordinateLeaf
+  private sky: CoordinateLeaf
+  private offsetY: number
+  private idPrefix: string
+  private hitPadding: number
+  private onFrameMove?: (id: string) => void
+
+  private entries = new Map<string, LabelEntry>()
+  private generatingEntries = new Map<string, GeneratingEntry>()
+  private pulseTimer: ReturnType<typeof setInterval> | null = null
+  private pulseOn = true
+  private eventIds: unknown[] = []
+  private destroyed = false
+
+  constructor(
+    mod: LeaferBoardModule,
+    tree: CoordinateLeaf,
+    sky: CoordinateLeaf,
+    options: BoardOptions = {},
+  ) {
+    this.mod = mod
+    this.tree = tree
+    this.sky = sky
+    this.offsetY = options.labelOffsetY ?? DEFAULT_OFFSET_Y
+    this.idPrefix = String(options.idPrefix ?? DEFAULT_ID_PREFIX)
+    this.hitPadding = options.hitPadding ?? DEFAULT_HIT_PADDING
+    this.onFrameMove = options.onFrameMove
+    this.listenViewport()
+  }
+
+  // ===== 公共 API =====
+
+  sync(frames: BoardFrameInput[]): void {
+    if (this.destroyed) return
+    const next = new Map(frames.map((frame) => [frame.id, frame]))
+
+    // 移除消失的画板标签
+    for (const [id, entry] of this.entries) {
+      if (!next.has(id)) {
+        this.detach(entry)
+        this.entries.delete(id)
+      }
+    }
+
+    // 「生成中」脉冲框 diff：消失/退出生成中的画板移除装饰
+    for (const [id, entry] of this.generatingEntries) {
+      const frame = next.get(id)
+      if (!frame || frame.generating !== true) {
+        this.detachGenerating(entry)
+        this.generatingEntries.delete(id)
+      }
+    }
+
+    for (const frame of frames) {
+      const existing = this.entries.get(frame.id)
+      if (existing && existing.frame === frame.leaf && this.labelText(existing.label) === frame.name) {
+        // 已存在：仅重投影
+        this.place(existing)
+        continue
+      }
+      if (existing) {
+        // 画板 leaf 或名称变化：重建（保持简单，标签是轻量 Text）
+        this.detach(existing)
+        this.entries.delete(frame.id)
+      }
+      const label = this.createLabel(frame)
+      this.sky.add(label as unknown as IUI)
+      const entry: LabelEntry = { id: frame.id, label, frame: frame.leaf }
+      this.entries.set(frame.id, entry)
+      this.bindDrag(entry)
+      this.place(entry)
+    }
+
+    // 「生成中」脉冲框：与标签同一条投影链，增量 diff（FS-8.3）
+    for (const frame of frames) {
+      if (frame.generating !== true) continue
+      const existing = this.generatingEntries.get(frame.id)
+      if (existing && existing.frame === frame.leaf) {
+        this.placeGenerating(existing)
+        continue
+      }
+      if (existing) {
+        this.detachGenerating(existing)
+        this.generatingEntries.delete(frame.id)
+      }
+      const rect = this.createGeneratingRect(frame)
+      if (!rect) continue
+      this.sky.add(rect as unknown as IUI)
+      const entry: GeneratingEntry = { id: frame.id, rect, frame: frame.leaf }
+      this.generatingEntries.set(frame.id, entry)
+      this.placeGenerating(entry)
+    }
+    this.syncPulseTicker()
+  }
+
+  pickLabel(clientX: number, clientY: number): string | null {
+    if (this.destroyed || !this.entries.size) return null
+    const point = this.sky.getWorldPointByClient({ clientX, clientY }, true)
+    for (const [id, entry] of this.entries) {
+      const b = entry.label.getBounds("box", "world")
+      if (
+        point.x >= b.x - this.hitPadding &&
+        point.x <= b.x + b.width + this.hitPadding &&
+        point.y >= b.y - this.hitPadding &&
+        point.y <= b.y + b.height + this.hitPadding
+      ) {
+        return id
+      }
+    }
+    return null
+  }
+
+  syncPositions(): void {
+    if (this.destroyed) return
+    for (const entry of this.entries.values()) this.place(entry)
+    for (const entry of this.generatingEntries.values()) this.placeGenerating(entry)
+  }
+
+  destroy(): void {
+    if (this.destroyed) return
+    this.destroyed = true
+    if (this.pulseTimer !== null) {
+      clearInterval(this.pulseTimer)
+      this.pulseTimer = null
+    }
+    const zoomLayer = this.zoomLayer()
+    try {
+      ;(zoomLayer as unknown as { off_: (ids: unknown) => void }).off_(this.eventIds)
+    } catch {
+      // 目标可能已销毁
+    }
+    this.eventIds = []
+    for (const entry of this.entries.values()) this.detach(entry)
+    this.entries.clear()
+    for (const entry of this.generatingEntries.values()) this.detachGenerating(entry)
+    this.generatingEntries.clear()
+  }
+
+  // ===== 内部 =====
+
+  private zoomLayer(): ILeaf | undefined {
+    // ILeafer 自身即 zoomLayer 承载者（官方声明 zoomLayer: IGroup），优先直取；
+    // 无 zoomLayer 的叶子回落其 leafer 的 zoomLayer
+    const direct = (this.tree as unknown as { zoomLayer?: ILeaf }).zoomLayer
+    if (direct) return direct
+    return (this.tree as unknown as { leafer?: { zoomLayer?: ILeaf } }).leafer?.zoomLayer
+  }
+
+  private listenViewport(): void {
+    const layer = this.zoomLayer()
+    const drag = this.mod.PropertyEvent?.CHANGE
+    if (!layer || !drag || typeof layer.on_ !== "function") return
+    this.eventIds = [
+      layer.on_(drag, () => {
+        this.syncPositions()
+      }),
+    ]
+  }
+
+  private createLabel(frame: BoardFrameInput): IUI {
+    const b = frame.leaf.getBounds("box", "world")
+    const y = b.y - this.offsetY
+    const Text = this.mod.Text
+    return Text.one(
+      {
+        id: `${this.idPrefix}${frame.id}`,
+        text: frame.name,
+        x: b.x,
+        y,
+        fontSize: 13,
+        fill: "rgba(128,128,128,0.95)",
+        // 不可加 locked：leafer hit 测试跳过 locked 元素，会导致
+        // 双击重命名/拖拽联动永远无法命中标签
+        draggable: true,
+        skipJSON: true,
+      },
+      b.x,
+      y,
+    )
+  }
+
+  private labelText(label: IUI): string {
+    return String((label as unknown as { text?: unknown }).text ?? "")
+  }
+
+  // 标签重投影：画板视觉左上（world 包围盒，天然涵盖翻转/旋转/缩放）→
+  // client（tree.getClientPointByWorld）→ sky 内部坐标（sky.getWorldPointByClient，
+  // sky 无变换即内部坐标）
+  private place(entry: LabelEntry): void {
+    const b = entry.frame.getBounds("box", "world")
+    const pos = this.worldToSky({ x: b.x, y: b.y })
+    if (!pos) return
+    ;(entry.label as unknown as { x: number; y: number }).x = pos.x
+    ;(entry.label as unknown as { x: number; y: number }).y = pos.y - this.offsetY
+  }
+
+  // ===== FS-8.3「生成中」脉冲框 =====
+
+  // 生成中装饰（skipJSON + hittable:false，同钢笔装饰纪律）：虚线描边矩形
+  // 贴合画板视觉 bounds；mod 未注入 Rect 时静默降级（不渲染不抛错）
+  private createGeneratingRect(frame: BoardFrameInput): IUI | null {
+    const Rect = this.mod.Rect
+    if (!Rect) return null
+    const rect = Rect.one(
+      {
+        id: `${GENERATING_ID_PREFIX}${frame.id}`,
+        x: 0,
+        y: 0,
+        width: 0,
+        height: 0,
+        stroke: GENERATING_STROKE,
+        strokeWidth: 1.5,
+        dashPattern: [6, 4],
+        hittable: false,
+        skipJSON: true,
+      },
+      0,
+      0,
+    )
+    ;(rect as unknown as { opacity: number }).opacity = PULSE_OPACITY_ON
+    return rect
+  }
+
+  // 框体贴合画板视觉 bounds：world 包围盒对角两点分别投影到 sky（两点差值
+  // 天然携带视图缩放，标签 place 的单点投影不含尺寸信息故不共用）
+  private placeGenerating(entry: GeneratingEntry): void {
+    const b = entry.frame.getBounds("box", "world")
+    const topLeft = this.worldToSky({ x: b.x, y: b.y })
+    const bottomRight = this.worldToSky({ x: b.x + b.width, y: b.y + b.height })
+    if (!topLeft || !bottomRight) return
+    const rect = entry.rect as unknown as {
+      x: number
+      y: number
+      width: number
+      height: number
+    }
+    rect.x = topLeft.x
+    rect.y = topLeft.y
+    rect.width = Math.max(bottomRight.x - topLeft.x, 1)
+    rect.height = Math.max(bottomRight.y - topLeft.y, 1)
+  }
+
+  private detachGenerating(entry: GeneratingEntry): void {
+    entry.rect.remove()
+  }
+
+  // 脉冲节拍：存在生成中装饰时才运行定时器（lazy 启动/自停），透明度往复
+  private syncPulseTicker(): void {
+    const needed = this.generatingEntries.size > 0
+    if (needed && this.pulseTimer === null) {
+      this.pulseOn = true
+      this.pulseTimer = setInterval(() => {
+        this.pulseOn = !this.pulseOn
+        const opacity = this.pulseOn ? PULSE_OPACITY_ON : PULSE_OPACITY_OFF
+        for (const entry of this.generatingEntries.values()) {
+          ;(entry.rect as unknown as { opacity: number }).opacity = opacity
+        }
+      }, PULSE_INTERVAL_MS)
+    } else if (!needed && this.pulseTimer !== null) {
+      clearInterval(this.pulseTimer)
+      this.pulseTimer = null
+    }
+  }
+
+  // world → sky 内部坐标（sky 无变换即内部坐标）；任一层不可用返回 null
+  private worldToSky(world: Point): Point | null {
+    try {
+      const client = this.tree.getClientPointByWorld(world)
+      return this.sky.getWorldPointByClient(
+        { clientX: client.x, clientY: client.y },
+        true,
+      ) as Point
+    } catch {
+      return null
+    }
+  }
+
+  // 拖标签联动：位移驱动（官方 DragEvent.totalX/totalY 为屏幕累计位移）——
+  // drag.start 记录画板视觉左上的 client 锚点，DRAG 用 total 换算新位置。
+  // 不能读 label.x 绝对位置：editor 选中元素后 selector.proxy 接管拖拽位移
+  // （interaction Dragger.getList 在 hasProxyList 时 realDraggable 返回空表），
+  // 标签不再被 leafer 位移，label.x 恒为起点，导致选中态拖标签拖不动画板。
+  // 位移驱动与标签是否被位移解耦，选中/未选中统一工作；
+  // place() 让标签贴合画板新位置（未选中态与 leafer 位移标签的视觉一致）
+  private bindDrag(entry: LabelEntry): void {
+    const drag = this.mod.DragEvent
+    if (!drag) return
+    const label = entry.label as unknown as {
+      x?: number
+      y?: number
+      on: (type: string, listener: (e?: unknown) => void) => void
+    }
+    const parent = (entry.frame as unknown as { parent?: ILeaf }).parent
+    let startClient: Point | null = null
+    label.on(drag.START, () => {
+      const b = (entry.frame as ILeaf).getBounds("box", "world")
+      startClient = this.tree.getClientPointByWorld({ x: b.x, y: b.y }) as Point
+    })
+    label.on(drag.DRAG, (e?: unknown) => {
+      if (!startClient) return
+      const total = (e ?? {}) as { totalX?: number; totalY?: number }
+      const world = this.tree.getWorldPointByClient(
+        {
+          clientX: startClient.x + (total.totalX ?? 0),
+          clientY: startClient.y + (total.totalY ?? 0),
+        },
+        true,
+      ) as Point
+      if (parent) {
+        const inner = parent.getInnerPoint(world) as Point
+        ;(entry.frame as unknown as { x: number; y: number }).x = inner.x
+        ;(entry.frame as unknown as { x: number; y: number }).y = inner.y
+      } else {
+        ;(entry.frame as unknown as { x: number; y: number }).x = world.x
+        ;(entry.frame as unknown as { x: number; y: number }).y = world.y
+      }
+      this.place(entry)
+    })
+    label.on(drag.END, () => {
+      startClient = null
+      this.syncPositions()
+      this.onFrameMove?.(entry.id)
+    })
+  }
+
+  private detach(entry: LabelEntry): void {
+    entry.label.remove()
+  }
+}
+
+function resolveTreeAndSky(target: unknown, options: BoardOptions): { tree: ILeaf; sky: ILeaf } | null {
+  if (options.sky) {
+    const tree =
+      (target as { tree?: ILeaf }).tree ??
+      ((target as { innerId?: number }).innerId !== undefined ? (target as ILeaf) : undefined)
+    if (tree) return { tree, sky: options.sky }
+  }
+  const app = target as { tree?: ILeaf; sky?: ILeaf }
+  if (app.tree && app.sky) return { tree: app.tree, sky: app.sky }
+  const viaLeaf = target as { leafer?: { app?: { tree?: ILeaf; sky?: ILeaf } } }
+  if (viaLeaf.leafer?.app?.tree && viaLeaf.leafer.app.sky) {
+    return { tree: viaLeaf.leafer.app.tree, sky: viaLeaf.leafer.app.sky }
+  }
+  return null
+}
+
+/**
+ * 安装画板名称标签插件。
+ *
+ * @param mod leafer 运行时模块（与消费方实例同源；需含 Text/PropertyEvent/
+ *            DragEvent）
+ * @param target App（含 tree/sky）或 ILeaf（经其 leafer.app 反查）
+ * @param options 见 {@link BoardOptions}
+ */
+export function installWithModule(
+  mod: LeaferBoardModule,
+  target: unknown,
+  options: BoardOptions = {},
+): BoardFramePlugin {
+  const resolved = resolveTreeAndSky(target, options) as {
+    tree: CoordinateLeaf
+    sky: CoordinateLeaf
+  } | null
+  if (!resolved) {
+    throw new Error(
+      "[leafer-x-board] target must be an App (tree+sky), an ILeaf inside an App, or options.sky must be provided",
+    )
+  }
+  return new BoardPlugin(mod, resolved.tree, resolved.sky, options)
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/src/components/design/canvas/plugins/leafer-x-clipboard/README.md

@@ -0,0 +1,32 @@
+# leafer-x-clipboard
+
+leafer 层复制/剪切/粘贴插件（LeaferJS 社区插件规范，leafer-x 系列）。
+
+以官方 `toJSON` / `UI.one` 序列化为媒介的内部剪贴板：复制选中子树快照，粘贴时重建并按偏移量错位（多次粘贴累加），多选保持相对位置。槽内是 JSON 与实例解耦——跨页/跨文档天然可用。
+
+## 特性
+
+- **相对位置保持**：多选整体偏移，元素间相对关系不变
+- **偏移累加**：连续粘贴每次错位 +20（可配）
+- **跨容器粘贴**：优先回原父容器（innerId 定位），父不存在回落根
+- **零文档模型依赖**：id 重映射、业务父子关系重建由消费方在文档层处理
+
+## 使用
+
+```ts
+import { installWithModule } from "./leafer-x-clipboard"
+
+const mod = await import("leafer-editor")
+const app = new mod.App({ view: el })
+
+const clipboard = installWithModule(mod, app, { offset: 20 })
+
+clipboard.copy(selectedLeaves)   // 复制
+clipboard.cut(selectedLeaves)    // 剪切（复制 + 移除）
+const created = clipboard.paste() // 粘贴（返回新实例，空槽返回 null）
+clipboard.clear()
+```
+
+## License
+
+MIT