@allbluecn/web-app 0.17.2 → 0.18.1

package/src/components/design/canvas/react/__tests__/workbench.test.tsx

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { HotkeysProvider } from "@tanstack/react-hotkeys"
+import { fireEvent, render, screen, waitFor } from "@testing-library/react"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import { LeaferEngine } from "@/design-engine/engine/app"
+import { createBoardNode, createEmptyDoc, type SceneDocument } from "../../document/types"
+import { CanvasWorkbench } from "../workbench"
+
+vi.mock("@/design-engine/engine/app", () => ({
+  LeaferEngine: { create: vi.fn() },
+}))
+
+function docWithRect(): SceneDocument {
+  return {
+    version: 1,
+    meta: { device: "desktop" },
+    nodes: [
+      createBoardNode("desktop"),
+      {
+        id: "n_1",
+        kind: "shape",
+        type: "rect",
+        parentId: "board",
+        name: "标题栏",
+        x: 20,
+        y: 20,
+        width: 240,
+        height: 48,
+      },
+    ],
+  }
+}
+
+function makeFakeEngine() {
+  let doc: SceneDocument = createEmptyDoc("desktop")
+  let selection: string[] = []
+  const docListeners = new Set<(doc: SceneDocument) => void>()
+  return {
+    mount: vi.fn(),
+    dispose: vi.fn(),
+    getZoom: vi.fn(() => 1.25),
+    setTool: vi.fn(),
+    undo: vi.fn(),
+    redo: vi.fn(),
+    history: { canUndo: false, canRedo: false },
+    getDoc: vi.fn(() => doc),
+    loadDoc: vi.fn((next: SceneDocument) => {
+      doc = next
+      for (const cb of [...docListeners]) cb(doc)
+    }),
+    onDocChange: vi.fn((cb: (doc: SceneDocument) => void) => {
+      docListeners.add(cb)
+      return () => {
+        docListeners.delete(cb)
+      }
+    }),
+    onSelectionChange: vi.fn(() => () => {}),
+    onFrameRenameRequest: vi.fn(() => () => {}),
+    frameRenameClientPos: vi.fn(() => null),
+    onToolChange: vi.fn(() => () => {}),
+    zoomTo: vi.fn(),
+    fit: vi.fn(),
+    focusNode: vi.fn(),
+    // 预设画板创建后 frame-tool 调用（自动定位到新画板）
+    zoomToFrame: vi.fn(),
+    // canvas-context 在 document focus/blur 时调用（TextEditor 官方键盘开关）
+    setKeyEventEnabled: vi.fn(),
+    select: vi.fn((ids: string[]) => {
+      selection = ids
+    }),
+    getSelection: vi.fn(() => selection),
+    applyNodePatch: vi.fn(),
+    applyNodesAppend: vi.fn(),
+    toCanvas: vi.fn(() => ({ x: 0, y: 0 })),
+  }
+}
+
+type RenderOptions = {
+  mode?: "design" | "doc"
+  readOnly?: boolean
+  initialDoc?: SceneDocument
+  toolbar?: React.ReactNode
+  leftPanel?: React.ReactNode
+  rightPanel?: React.ReactNode
+}
+
+function renderWorkbench(options: RenderOptions = {}) {
+  return render(
+    <HotkeysProvider>
+      <CanvasWorkbench
+        mode={options.mode}
+        readOnly={options.readOnly}
+        initialDoc={options.initialDoc}
+        toolbar={options.toolbar}
+        leftPanel={options.leftPanel}
+        rightPanel={options.rightPanel}
+      />
+    </HotkeysProvider>,
+  )
+}
+
+describe("CanvasWorkbench", () => {
+  let engine: ReturnType<typeof makeFakeEngine>
+
+  beforeEach(() => {
+    engine = makeFakeEngine()
+    vi.mocked(LeaferEngine.create).mockReset()
+    vi.mocked(LeaferEngine.create).mockResolvedValue(engine as never)
+  })
+
+  it("默认渲染工具栏、组件库、图层与属性面板", async () => {
+    renderWorkbench({ initialDoc: docWithRect() })
+
+    await waitFor(() => expect(screen.getByText("标题栏")).toBeInTheDocument())
+
+    expect(screen.getByLabelText("选择")).toBeInTheDocument()
+    expect(screen.getByLabelText("画板")).toBeInTheDocument()
+    expect(screen.getByLabelText("形状")).toBeInTheDocument()
+    expect(screen.getByLabelText("钢笔")).toBeInTheDocument()
+    expect(screen.getByLabelText("文本")).toBeInTheDocument()
+    expect(screen.getByText("组件库")).toBeInTheDocument()
+    expect(screen.getByText("按钮")).toBeInTheDocument()
+    expect(screen.getByText("图层")).toBeInTheDocument()
+    expect(screen.getByText("未选中元素")).toBeInTheDocument()
+
+    fireEvent.click(screen.getByText("标题栏"))
+
+    await waitFor(() => expect(screen.getByText("属性")).toBeInTheDocument())
+    expect(screen.getByDisplayValue("240")).toBeInTheDocument()
+  })
+
+  it("工具栏显示当前缩放百分比", async () => {
+    renderWorkbench()
+
+    await waitFor(() => expect(screen.getByText("125%")).toBeInTheDocument())
+  })
+
+  it("UI 区域标记 data-canvas-ui 以豁免画板绘制", async () => {
+    renderWorkbench()
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+    expect(document.querySelectorAll("[data-canvas-ui]").length).toBeGreaterThanOrEqual(3)
+  })
+
+  it("readOnly 隐藏两侧面板与顶部工具栏", async () => {
+    renderWorkbench({ readOnly: true })
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+    expect(screen.queryByText("组件库")).toBeNull()
+    expect(screen.queryByText("图层")).toBeNull()
+    expect(screen.queryByText("属性")).toBeNull()
+    expect(screen.queryByLabelText("矩形")).toBeNull()
+    expect(screen.queryByLabelText("选择")).toBeNull()
+    expect(document.querySelectorAll("[data-canvas-ui]").length).toBe(0)
+  })
+
+  it("toolbar / leftPanel / rightPanel 插槽覆盖默认面板", async () => {
+    renderWorkbench({
+      toolbar: <span data-testid="my-toolbar">自定义工具栏</span>,
+      leftPanel: <span data-testid="my-left">自定义左侧</span>,
+      rightPanel: <span data-testid="my-right">自定义右侧</span>,
+    })
+
+    await waitFor(() => expect(engine.mount).toHaveBeenCalledTimes(1))
+
+    expect(screen.getByTestId("my-toolbar")).toBeInTheDocument()
+    expect(screen.getByTestId("my-left")).toBeInTheDocument()
+    expect(screen.getByTestId("my-right")).toBeInTheDocument()
+    expect(screen.queryByText("组件库")).toBeNull()
+    expect(screen.queryByText("属性")).toBeNull()
+  })
+})

package/src/components/design/canvas/react/canvas-context.tsx

@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import {
+  createContext,
+  useEffect,
+  useRef,
+  type ReactNode,
+  type RefObject,
+} from "react"
+
+import { isTypingTarget } from "../tools/dom"
+import { LeaferEngine } from "@/design-engine/engine/app"
+import { createEmptyDoc, type DeviceType, type SceneDocument, type ToolId } from "../document/types"
+
+export type CanvasSnapshot = {
+  engine: LeaferEngine | null
+  ready: boolean
+  readOnly: boolean
+  device: DeviceType
+  doc: SceneDocument
+  selection: string[]
+  tool: ToolId
+  zoom: number
+  canUndo: boolean
+  canRedo: boolean
+  panMode: boolean
+}
+
+export type CanvasStore = {
+  subscribe: (listener: () => void) => () => void
+  getSnapshot: () => CanvasSnapshot
+}
+
+export type CanvasContextValue = CanvasStore & {
+  hostRef: RefObject<HTMLDivElement | null>
+  /** host 容器 ref callback：DOM 被 React 换新（HMR/条件渲染）时把现有画布移入新容器 */
+  attachHost: (node: HTMLDivElement | null) => void
+  attach: (engine: LeaferEngine | null) => void
+  pushDoc: (doc: SceneDocument) => void
+  pushSelection: (ids: string[]) => void
+  pushTool: (tool: ToolId) => void
+  pushZoom: () => void
+  /** 空格按键的持有状态，与右键拖动任一为 true 时 panMode 即 true。 */
+  setSpaceHeld: (held: boolean) => void
+  /** 右键拖动按下状态，与空格任一为 true 时 panMode 即 true。 */
+  setRightHeld: (held: boolean) => void
+}
+
+export type CanvasProviderProps = {
+  readOnly?: boolean
+  device?: DeviceType
+  initialDoc?: SceneDocument
+  onDocChange?: (doc: SceneDocument) => void
+  children?: ReactNode
+}
+
+type MutableState = {
+  engine: LeaferEngine | null
+  doc: SceneDocument
+  selection: string[]
+  tool: ToolId
+  zoom: number
+  canUndo: boolean
+  canRedo: boolean
+  ready: boolean
+  device: DeviceType
+  panMode: boolean
+  spaceHeld: boolean
+  rightHeld: boolean
+}
+
+export const CanvasContext = createContext<CanvasContextValue | null>(null)
+
+function buildSnapshot(state: MutableState, flags: { readOnly: boolean }): CanvasSnapshot {
+  return {
+    engine: state.engine,
+    ready: state.ready,
+    readOnly: flags.readOnly,
+    device: state.device,
+    doc: state.doc,
+    selection: state.selection,
+    tool: state.tool,
+    zoom: state.zoom,
+    canUndo: state.canUndo,
+    canRedo: state.canRedo,
+    panMode: state.panMode,
+  }
+}
+
+export function CanvasProvider({
+  readOnly = false,
+  device = "desktop",
+  initialDoc,
+  onDocChange,
+  children,
+}: CanvasProviderProps) {
+  const hostRef = useRef<HTMLDivElement | null>(null)
+  const flagsRef = useRef({ readOnly })
+  const callbacksRef = useRef({ initialDoc, onDocChange })
+  const storeRef = useRef<CanvasContextValue | null>(null)
+  const engineRef = useRef<LeaferEngine | null>(null)
+  const lastEmittedDocRef = useRef<SceneDocument | null>(null)
+  const selectionNotifyRafRef = useRef<number | null>(null)
+
+  flagsRef.current = { readOnly }
+  callbacksRef.current = { initialDoc, onDocChange }
+
+  if (!storeRef.current) {
+    const listeners = new Set<() => void>()
+    const state: MutableState = {
+      engine: null,
+      doc: createEmptyDoc(device),
+      selection: [],
+      tool: "select",
+      zoom: 1,
+      canUndo: false,
+      canRedo: false,
+      ready: false,
+      device,
+      panMode: false,
+      spaceHeld: false,
+      rightHeld: false,
+    }
+    let snapshot = buildSnapshot(state, flagsRef.current)
+
+    const emit = () => {
+      for (const listener of [...listeners]) listener()
+    }
+
+    const refreshMetrics = () => {
+      const engine = state.engine
+      if (!engine) return
+      state.zoom = engine.getZoom()
+      state.canUndo = engine.history.canUndo
+      state.canRedo = engine.history.canRedo
+    }
+
+    const rebuild = () => {
+      snapshot = buildSnapshot(state, flagsRef.current)
+      emit()
+    }
+
+    storeRef.current = {
+      hostRef,
+      attachHost: (node) => {
+        hostRef.current = node
+        // mount effect 的 deps 不含 host：React 换新 host DOM（HMR/条件渲染）
+        // 时 effect 不会重跑，引擎还持有已 detach 的旧容器 → 画布消失。
+        // 引擎已在则把现有 view 移入新容器（文档/历史/选中状态全保留）
+        if (node && engineRef.current) engineRef.current.remount(node)
+      },
+      subscribe: (listener) => {
+        listeners.add(listener)
+        return () => {
+          listeners.delete(listener)
+        }
+      },
+      getSnapshot: () => snapshot,
+      attach: (engine) => {
+        if (state.engine === engine) return
+        state.engine = engine
+        state.ready = engine !== null
+        refreshMetrics()
+        rebuild()
+      },
+      pushDoc: (doc) => {
+        lastEmittedDocRef.current = doc
+        state.doc = doc
+        if (doc.meta?.device) state.device = doc.meta.device
+        callbacksRef.current.onDocChange?.(doc)
+        refreshMetrics()
+        rebuild()
+      },
+      pushSelection: (ids) => {
+        // last-write-wins + rAF 合并通知：leafer editor 的 SELECT 事件是异步派发
+        // （applyScene 重建后，tick 里会迟到一个「空选中」），若立即通知，面板会在
+        // 同一帧内先收到 [] 再收到恢复值 → 卸载重建属性面板（弹窗类 UI 状态丢失）。
+        // 同一帧内的多次推送合并为一次最终值通知。
+        state.selection = ids
+        if (selectionNotifyRafRef.current !== null) return
+        selectionNotifyRafRef.current = requestAnimationFrame(() => {
+          selectionNotifyRafRef.current = null
+          rebuild()
+        })
+      },
+      pushTool: (tool) => {
+        state.tool = tool
+        rebuild()
+      },
+      pushZoom: () => {
+        refreshMetrics()
+        rebuild()
+      },
+      setSpaceHeld: (held) => {
+        if (state.spaceHeld === held) return
+        state.spaceHeld = held
+        const next = state.spaceHeld || state.rightHeld
+        if (state.panMode === next) return
+        state.panMode = next
+        rebuild()
+      },
+      setRightHeld: (held) => {
+        if (state.rightHeld === held) return
+        state.rightHeld = held
+        const next = state.spaceHeld || state.rightHeld
+        if (state.panMode === next) return
+        state.panMode = next
+        rebuild()
+      },
+    }
+  }
+
+  const store = storeRef.current
+
+  useEffect(() => {
+    const host = hostRef.current
+    if (!host) return
+    let cancelled = false
+    let engine: LeaferEngine | null = null
+    const unsubs: Array<() => void> = []
+
+    void LeaferEngine.create({ readOnly, device }).then((created) => {
+      if (cancelled) {
+        created.dispose()
+        return
+      }
+      engine = created
+      engineRef.current = created
+      created.mount(host, { readOnly, device })
+      unsubs.push(
+        created.onDocChange(store.pushDoc),
+        created.onSelectionChange(store.pushSelection),
+        created.onToolChange(store.pushTool),
+      )
+      const initial = callbacksRef.current.initialDoc
+      if (initial) created.loadDoc(initial)
+      store.attach(created)
+      // 诊断埋点：dev 环境暴露引擎引用，供真实页面逐层调试命中/选中链路
+      if (import.meta.env.DEV) {
+        // SAFETY: window 扩展字段仅 dev 调试用，生产构建整体剔除
+        ;(window as unknown as { __canvasEngine?: unknown }).__canvasEngine = created
+      }
+
+      const observer = new ResizeObserver(() => {
+        store.pushZoom()
+      })
+      observer.observe(host)
+      unsubs.push(() => observer.disconnect())
+
+      let wheelRaf: number | null = null
+      const wheelHandler = (): void => {
+        if (wheelRaf !== null) return
+        wheelRaf = requestAnimationFrame(() => {
+          wheelRaf = null
+          const eng = engineRef.current
+          if (!eng) return
+          if (eng.getZoom() !== store.getSnapshot().zoom) {
+            store.pushZoom()
+          }
+        })
+      }
+      host.addEventListener("wheel", wheelHandler, { passive: true })
+      unsubs.push(() => {
+        if (wheelRaf !== null) cancelAnimationFrame(wheelRaf)
+        host.removeEventListener("wheel", wheelHandler)
+      })
+    }).catch((e: unknown) => {
+      // mount 链路禁止静默失败：create/mount 抛错曾导致 HMR 后画布消失且
+      // 无任何日志（void promise 吞掉 unhandled rejection）
+      console.error("[canvas] engine create/mount failed:", e)
+    })
+
+    return () => {
+      cancelled = true
+      for (const unsub of unsubs) unsub()
+      store.attach(null)
+      engineRef.current = null
+      if (engine) engine.dispose()
+    }
+  }, [readOnly, device, store])
+
+  useEffect(() => {
+    const eng = engineRef.current
+    if (!eng || !initialDoc) return
+    if (initialDoc === lastEmittedDocRef.current) return
+    eng.loadDoc(initialDoc)
+  }, [initialDoc])
+
+  // 空格键：按下进入 pan 模式（手型光标 + 左键可拖动），松开退出。
+  // 输入框/textarea/contenteditable 聚焦时不响应（否则会打断用户输入）。
+  // 与右键拖动并列：任一持有时 panMode 即为 true。
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== " ") return
+      if (isTypingTarget(e.target as HTMLElement)) return
+      store.setSpaceHeld(true)
+      e.preventDefault()
+    }
+    const onKeyUp = (e: KeyboardEvent) => {
+      if (e.key !== " ") return
+      store.setSpaceHeld(false)
+    }
+    document.addEventListener("keydown", onKeyDown)
+    document.addEventListener("keyup", onKeyUp)
+    return () => {
+      document.removeEventListener("keydown", onKeyDown)
+      document.removeEventListener("keyup", onKeyUp)
+    }
+  }, [store])
+
+  // 输入框聚焦时关闭 leafer-editor 的键盘监听（leafer-editor 官方方案）。
+  // 从 leafer-editor 2.3.0 源码定位：
+  //   Interaction.keyDown（web.js:10344）检查 `this.config.keyEvent`，
+  //   Interaction 的 config 来自 app.config，不是 editor.config。
+  //   EditTool.onArrow（web.js:14107）读 `this.mergeConfig.keyEvent`。
+  //   TextEditor Widget（web.js:17293）禁用键盘时用的正是
+  //     `editor.app.config.keyEvent = false`（离开时 restore）。
+  // 之前尝试的 stopPropagation / stopImmediatePropagation 方案失败，因为
+  // leafer-editor 的 keydown listener 在 document 上注册早于我们的 handler，
+  // 同元素同阶段 listener 按注册顺序执行，后注册的无法阻断已执行的 handler。
+  useEffect(() => {
+    const isInsideTyping = (): boolean => {
+      const el = document.activeElement
+      return isTypingTarget(el as HTMLElement | null)
+    }
+    const onDocFocus = (): void => {
+      engineRef.current?.setKeyEventEnabled(!isInsideTyping())
+    }
+    document.addEventListener("focusin", onDocFocus)
+    document.addEventListener("focusout", onDocFocus)
+    // 初始状态同步一次（防止 mount 时焦点已在输入框）
+    engineRef.current?.setKeyEventEnabled(!isInsideTyping())
+    return () => {
+      document.removeEventListener("focusin", onDocFocus)
+      document.removeEventListener("focusout", onDocFocus)
+    }
+  }, [])
+
+  return <CanvasContext.Provider value={store}>{children}</CanvasContext.Provider>
+}

package/src/components/design/canvas/react/canvas-hooks.ts

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+/**
+ * 画布 store hooks（react-refresh 纪律）：hook 与 Provider 分文件——
+ * hook 文件的改动不再令 Provider 组件树的 Fast Refresh 失效。
+ */
+import { useContext, useSyncExternalStore, type RefObject } from "react"
+import { CanvasContext, type CanvasContextValue, type CanvasSnapshot } from "./canvas-context"
+
+export function useCanvasStore(): CanvasContextValue {
+  const value = useContext(CanvasContext)
+  if (!value) throw new Error("Canvas context missing: use canvas hooks inside <CanvasProvider>")
+  return value
+}
+
+export function useCanvasHost(): RefObject<HTMLDivElement | null> {
+  return useCanvasStore().hostRef
+}
+
+/** host 容器的 ref callback：CanvasStage 挂载用；DOM 被 React 换新时自动把现有画布移入新容器 */
+export function useCanvasHostAttach(): (node: HTMLDivElement | null) => void {
+  return useCanvasStore().attachHost
+}
+
+export function useCanvasSnapshot(): CanvasSnapshot {
+  const { subscribe, getSnapshot } = useCanvasStore()
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}
+
+export function useCanvasSnapshotOptional(): CanvasSnapshot | null {
+  const value = useContext(CanvasContext)
+  if (!value) return null
+  return useSyncExternalStore(value.subscribe, value.getSnapshot, value.getSnapshot)
+}