@arronqzy/react-blueprint 1.0.0

package/src/hooks/useBlueprintPageLifecycle.ts

@@ -0,0 +1,245 @@
+import { useEffect, useRef, useState } from "react";
+import {
+  BlueprintGraphRunner,
+  detectBlueprintReferenceCycle,
+  type LibraryBlueprintResolver,
+  type PageLifecyclePhase,
+} from "@arronqzy/blueprint-dsl";
+
+import type { BlueprintGraph } from "../graph/blueprint-graph";
+import { documentToRunnableGraph } from "../runtime/document-to-runnable-graph";
+
+const PAGE_BOOT_PHASES: PageLifecyclePhase[] = [
+  "created",
+  "beforeMount",
+  "mounted",
+];
+
+const PAGE_TEARDOWN_PHASES: PageLifecyclePhase[] = [
+  "beforeDestroy",
+  "destroy",
+];
+
+async function waitForPagePaint() {
+  if (document.readyState !== "complete") {
+    await new Promise<void>((resolve) => {
+      window.addEventListener("load", () => resolve(), { once: true });
+    });
+  }
+  await new Promise<void>((resolve) => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => resolve());
+    });
+  });
+}
+
+export type UseBlueprintPageLifecycleOptions = {
+  graph: BlueprintGraph;
+  /** 页面（工作区）是否处于激活状态，用于 activated / deactivated */
+  active?: boolean;
+  /** 为 false 时不触发任何生命周期阶段 */
+  enabled?: boolean;
+  /** 挂载时要执行的阶段；默认 created → beforeMount → mounted */
+  bootPhases?: PageLifecyclePhase[];
+  /**
+   * 挂载流程的触发键。提供后会在键变化时重新执行 bootPhases；
+   * 未提供时仅在首次满足 enabled 时执行一次。
+   */
+  bootKey?: unknown;
+  /** 为 true 时在执行 bootPhases 前等待 window load 与双 rAF（页面绘制完成） */
+  waitForPageReady?: boolean;
+  /** 元素或图层变更时是否触发 updated */
+  onUpdated?: unknown;
+  /** 解析蓝图库记录为可执行子图 */
+  resolveLibraryBlueprint?: LibraryBlueprintResolver;
+  /** 蓝图库 id -> 名称，用于 signal 中的 blueprintName */
+  libraryNameById?: ReadonlyMap<string, string>;
+  /** 当前蓝图在蓝图库中的 id；未入库时为 null */
+  rootLibraryBlueprintId?: string | null;
+  /** 检测到蓝图相互引用死循环时回调 */
+  onExecutionBlocked?: (message: string) => void;
+  /** 视图绑定节点收到真信号时，为关联视图元素写入 scope */
+  onViewScopeUpdate?: (
+    viewElementIds: string[],
+    scope: unknown
+  ) => void;
+};
+
+type RunnerOptions = Pick<
+  UseBlueprintPageLifecycleOptions,
+  | "resolveLibraryBlueprint"
+  | "libraryNameById"
+  | "rootLibraryBlueprintId"
+  | "onExecutionBlocked"
+  | "onViewScopeUpdate"
+>;
+
+function resolveBlueprintName(
+  libraryNameById: ReadonlyMap<string, string> | undefined,
+  id: string
+) {
+  return libraryNameById?.get(id) ?? id;
+}
+
+function createRunner(graph: BlueprintGraph, options: RunnerOptions) {
+  return new BlueprintGraphRunner(
+    documentToRunnableGraph(graph.document, {
+      libraryNameById: options.libraryNameById,
+    }),
+    {
+      resolveLibraryBlueprint: options.resolveLibraryBlueprint,
+      rootLibraryBlueprintId: options.rootLibraryBlueprintId,
+      resolveBlueprintName: (id) =>
+        resolveBlueprintName(options.libraryNameById, id),
+      onViewScopeUpdate: options.onViewScopeUpdate,
+    }
+  );
+}
+
+async function emitPhases(
+  graph: BlueprintGraph,
+  phases: PageLifecyclePhase[],
+  options: RunnerOptions
+) {
+  if (!phases.length) return;
+
+  if (options.resolveLibraryBlueprint) {
+    const result = await detectBlueprintReferenceCycle({
+      rootGraph: documentToRunnableGraph(graph.document, {
+        libraryNameById: options.libraryNameById,
+      }),
+      rootLibraryBlueprintId: options.rootLibraryBlueprintId,
+      resolveLibraryBlueprint: options.resolveLibraryBlueprint,
+      resolveBlueprintName: (id) =>
+        resolveBlueprintName(options.libraryNameById, id),
+    });
+    if (!result.ok) {
+      options.onExecutionBlocked?.(result.message);
+      return;
+    }
+  }
+
+  const runner = createRunner(graph, options);
+  for (const phase of phases) {
+    await runner.emitLifecycle(phase);
+  }
+}
+
+/**
+ * 将蓝图中的生命周期节点与当前页面生命周期对齐。
+ * 在编辑器工作区挂载/卸载、图层切换时自动触发对应钩子。
+ */
+export function useBlueprintPageLifecycle({
+  graph,
+  active = true,
+  enabled = true,
+  bootPhases = PAGE_BOOT_PHASES,
+  bootKey,
+  waitForPageReady = false,
+  onUpdated,
+  resolveLibraryBlueprint,
+  libraryNameById,
+  rootLibraryBlueprintId = null,
+  onExecutionBlocked,
+  onViewScopeUpdate,
+}: UseBlueprintPageLifecycleOptions) {
+  const graphRef = useRef(graph);
+  graphRef.current = graph;
+
+  const runnerOptionsRef = useRef<RunnerOptions>({
+    resolveLibraryBlueprint,
+    libraryNameById,
+    rootLibraryBlueprintId,
+    onExecutionBlocked,
+    onViewScopeUpdate,
+  });
+  runnerOptionsRef.current = {
+    resolveLibraryBlueprint,
+    libraryNameById,
+    rootLibraryBlueprintId,
+    onExecutionBlocked,
+    onViewScopeUpdate,
+  };
+
+  const bootPhasesKey = bootPhases.join("|");
+  const bootTrigger = bootKey ?? "__initial__";
+  const [bootCompleted, setBootCompleted] = useState(false);
+  const hadBootRef = useRef(false);
+  const activeRef = useRef(active);
+  activeRef.current = active;
+  const prevActiveRef = useRef<boolean | undefined>(undefined);
+
+  useEffect(() => {
+    if (!enabled) {
+      setBootCompleted(false);
+      return;
+    }
+
+    let cancelled = false;
+
+    const runBoot = async () => {
+      if (waitForPageReady) {
+        await waitForPagePaint();
+      }
+      if (cancelled) return;
+
+      await emitPhases(
+        graphRef.current,
+        bootPhases,
+        runnerOptionsRef.current
+      );
+      if (cancelled) return;
+
+      if (activeRef.current) {
+        await emitPhases(
+          graphRef.current,
+          ["activated"],
+          runnerOptionsRef.current
+        );
+      }
+      if (cancelled) return;
+
+      hadBootRef.current = true;
+      prevActiveRef.current = activeRef.current;
+      setBootCompleted(true);
+    };
+
+    void runBoot();
+
+    return () => {
+      cancelled = true;
+      setBootCompleted(false);
+      prevActiveRef.current = undefined;
+      if (hadBootRef.current) {
+        hadBootRef.current = false;
+        void emitPhases(
+          graphRef.current,
+          PAGE_TEARDOWN_PHASES,
+          runnerOptionsRef.current
+        );
+      }
+    };
+  }, [bootPhasesKey, bootTrigger, enabled, waitForPageReady]);
+
+  useEffect(() => {
+    if (!enabled || !bootCompleted) return;
+
+    const prev = prevActiveRef.current;
+    if (prev === undefined || prev === active) {
+      prevActiveRef.current = active;
+      return;
+    }
+    prevActiveRef.current = active;
+
+    void emitPhases(
+      graphRef.current,
+      [active ? "activated" : "deactivated"],
+      runnerOptionsRef.current
+    );
+  }, [active, bootCompleted, enabled]);
+
+  useEffect(() => {
+    if (!enabled || !bootCompleted) return;
+    void emitPhases(graphRef.current, ["updated"], runnerOptionsRef.current);
+  }, [bootCompleted, enabled, onUpdated]);
+}

package/src/index.tsx

@@ -0,0 +1,271 @@
+import {
+  FC,
+  useCallback,
+  useRef,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from "react";
+import {
+  ReactFlow,
+  ReactFlowProvider,
+  ConnectionMode,
+  useReactFlow,
+  type Node,
+  type Edge,
+} from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import "./blueprint.css";
+
+import { BlueprintGraph, type BlueprintFlowNodeData } from "./graph";
+import {
+  BlueprintContextMenu,
+  type BlueprintContextMenuState,
+} from "./BlueprintContextMenu";
+import { BlueprintCanvasProvider } from "./BlueprintCanvasContext";
+import { blueprintNodeTypes } from "./blueprintNodeTypes";
+import { createBlueprintEdgeTypes } from "./createBlueprintEdgeTypes";
+import { BLUEPRINT_DEFAULT_EDGE_OPTIONS } from "./flowDefaults";
+import { useBlueprintFlowColorMode } from "./hooks/useBlueprintFlowColorMode";
+import { useBlueprintFlowState } from "./hooks/useBlueprintFlowState";
+import { useBlueprintFlowViewport } from "./hooks/useBlueprintFlowViewport";
+import { clientToFlowNodePosition } from "./flowCoordinates";
+import type { BlueprintExecutionOverlay } from "./runtime/execution-overlay";
+
+export type { BlueprintExecutionOverlay } from "./runtime/execution-overlay";
+
+export type { BlueprintNodeConfigSidebarProps, BlueprintViewElementOption, BlueprintLibraryOption } from "./BlueprintNodeConfigSidebar";
+export { BlueprintNodeConfigSidebar } from "./BlueprintNodeConfigSidebar";
+
+export type BluePrintReactRootProps = {
+  style?: React.CSSProperties;
+  graph: BlueprintGraph;
+  onGraphChange: Dispatch<SetStateAction<BlueprintGraph>>;
+  selectedNodeId?: string | null;
+  onSelectNode?: (nodeId: string | null) => void;
+  /** 中止正在运行的时钟节点 */
+  onAbortClock?: (nodeId: string) => void;
+  /** 调试执行时的画布高亮（节点 + 边线信号色） */
+  executionOverlay?: BlueprintExecutionOverlay | null;
+  /** 蓝图库 id -> 名称，用于画布节点展示引用蓝图名 */
+  libraryNameById?: ReadonlyMap<string, string>;
+};
+
+type BlueprintCanvasProps = Omit<BluePrintReactRootProps, "style"> & {
+  containerRef: React.RefObject<HTMLDivElement | null>;
+};
+
+const blueprintEdgeTypes = createBlueprintEdgeTypes();
+
+function BlueprintCanvas({
+  graph,
+  onGraphChange,
+  selectedNodeId = null,
+  executionOverlay = null,
+  onSelectNode,
+  onAbortClock,
+  libraryNameById,
+  containerRef,
+}: BlueprintCanvasProps) {
+  const { screenToFlowPosition } = useReactFlow();
+  const [menu, setMenu] = useState<BlueprintContextMenuState | null>(null);
+
+  const applyGraphChange = useCallback(
+    (updater: (prev: BlueprintGraph) => BlueprintGraph) => {
+      onGraphChange((prev) => updater(prev));
+    },
+    [onGraphChange]
+  );
+
+  const {
+    nodes,
+    edges,
+    onNodesChange,
+    onEdgesChange,
+    onNodeDragStop,
+    onConnect,
+    isValidConnection,
+  } = useBlueprintFlowState({
+    graph,
+    selectedNodeId,
+    executionOverlay,
+    libraryNameById,
+    onGraphChange: applyGraphChange,
+    onSelectNode,
+  });
+
+  const flowColorMode = useBlueprintFlowColorMode();
+
+  useBlueprintFlowViewport(containerRef, true);
+
+  const onPaneContextMenu = useCallback(
+    (event: MouseEvent | React.MouseEvent) => {
+      event.preventDefault();
+      setMenu({
+        kind: "pane",
+        clientX: event.clientX,
+        clientY: event.clientY,
+      });
+    },
+    []
+  );
+
+  const onNodeContextMenu = useCallback(
+    (
+      event: MouseEvent | React.MouseEvent,
+      node: Node<BlueprintFlowNodeData>
+    ) => {
+      event.preventDefault();
+      onSelectNode?.(node.id);
+      setMenu({
+        kind: "node",
+        clientX: event.clientX,
+        clientY: event.clientY,
+        nodeId: node.id,
+        role: node.data.role,
+      });
+    },
+    [onSelectNode]
+  );
+
+  const onEdgeContextMenu = useCallback(
+    (event: MouseEvent | React.MouseEvent, edge: Edge) => {
+      event.preventDefault();
+      setMenu({
+        kind: "edge",
+        clientX: event.clientX,
+        clientY: event.clientY,
+        edgeId: edge.id,
+      });
+    },
+    []
+  );
+
+  const onEdgeClick = useCallback(() => {
+    setMenu(null);
+  }, []);
+
+  const onPaneClick = useCallback(() => {
+    setMenu(null);
+    onSelectNode?.(null);
+  }, [onSelectNode]);
+
+  const setGraph = useCallback(
+    (updater: (prev: BlueprintGraph) => BlueprintGraph) => {
+      applyGraphChange(updater);
+    },
+    [applyGraphChange]
+  );
+
+  const handleAddBlueprintNode = useCallback(
+    (clientX: number, clientY: number) => {
+      const position = clientToFlowNodePosition(
+        (point) => screenToFlowPosition(point, { snapToGrid: false }),
+        clientX,
+        clientY
+      );
+      setGraph((prev) => prev.addBlueprintNode(position));
+    },
+    [screenToFlowPosition, setGraph]
+  );
+
+  const handleDeleteNode = useCallback(
+    (nodeId: string) => {
+      if (nodeId === selectedNodeId) {
+        onSelectNode?.(null);
+      }
+      setGraph((prev) => prev.removeNode(nodeId));
+    },
+    [onSelectNode, selectedNodeId, setGraph]
+  );
+
+  const handleDeleteEdge = useCallback(
+    (edgeId: string) => {
+      setGraph((prev) => prev.removeEdge(edgeId));
+    },
+    [setGraph]
+  );
+
+  return (
+    <>
+      <ReactFlow
+        className="bp-flow h-full w-full"
+        colorMode={flowColorMode}
+        nodes={nodes}
+        edges={edges}
+        nodeTypes={blueprintNodeTypes}
+        edgeTypes={blueprintEdgeTypes}
+        onNodesChange={onNodesChange}
+        onEdgesChange={onEdgesChange}
+        onConnect={onConnect}
+        isValidConnection={isValidConnection}
+        onPaneContextMenu={onPaneContextMenu}
+        onNodeContextMenu={onNodeContextMenu}
+        onEdgeContextMenu={onEdgeContextMenu}
+        onEdgeClick={onEdgeClick}
+        onNodeDragStop={onNodeDragStop}
+        onPaneClick={onPaneClick}
+        nodesConnectable
+        elementsSelectable
+        edgesFocusable
+        connectionMode={ConnectionMode.Strict}
+        defaultEdgeOptions={BLUEPRINT_DEFAULT_EDGE_OPTIONS}
+        selectNodesOnDrag={false}
+        elevateNodesOnSelect={false}
+        nodeClickDistance={8}
+        proOptions={{ hideAttribution: true }}
+      />
+      <BlueprintContextMenu
+        menu={menu}
+        onClose={() => setMenu(null)}
+        onAddBlueprintNode={handleAddBlueprintNode}
+        onDeleteNode={handleDeleteNode}
+        onDeleteEdge={handleDeleteEdge}
+      />
+    </>
+  );
+}
+
+export const BluePrintReactRoot: FC<BluePrintReactRootProps> = ({
+  style,
+  graph,
+  onGraphChange,
+  selectedNodeId,
+  executionOverlay,
+  onSelectNode,
+  onAbortClock,
+  libraryNameById,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <div
+      ref={containerRef}
+      data-workspace-region="blueprint"
+      className="bp-canvas h-full w-full bg-background text-foreground"
+      style={{
+        width: "100%",
+        height: "100%",
+        minHeight: 0,
+        ...style,
+      }}
+    >
+      <BlueprintCanvasProvider
+        onSelectNode={onSelectNode}
+        onAbortClock={onAbortClock}
+      >
+        <ReactFlowProvider>
+          <BlueprintCanvas
+            containerRef={containerRef}
+            graph={graph}
+            onGraphChange={onGraphChange}
+            selectedNodeId={selectedNodeId}
+            executionOverlay={executionOverlay}
+            onSelectNode={onSelectNode}
+            libraryNameById={libraryNameById}
+          />
+        </ReactFlowProvider>
+      </BlueprintCanvasProvider>
+    </div>
+  );
+};

package/src/library/blueprint-io.ts

@@ -0,0 +1,108 @@
+import type { BlueprintDocument } from "../graph/document";
+import { createNodeId } from "../graph/document";
+import {
+  BLUEPRINT_EXPORT_KIND,
+  BLUEPRINT_EXPORT_VERSION,
+  type BlueprintExportPayload,
+  type BlueprintLibraryRecord,
+  type BlueprintLibrarySource,
+  type BlueprintMetaDraft,
+} from "./types";
+
+export function createLibraryBlueprintId() {
+  return createNodeId("lib_bp");
+}
+
+export function blueprintDocumentsEqual(
+  a: BlueprintDocument,
+  b: BlueprintDocument
+): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function buildBlueprintExportPayload(
+  document: BlueprintDocument,
+  meta: BlueprintMetaDraft
+): BlueprintExportPayload {
+  return {
+    kind: BLUEPRINT_EXPORT_KIND,
+    version: BLUEPRINT_EXPORT_VERSION,
+    name: meta.name.trim() || "未命名蓝图",
+    remark: meta.remark.trim() || undefined,
+    exportedAt: Date.now(),
+    document: {
+      ...document,
+      name: meta.name.trim() || document.name,
+    },
+  };
+}
+
+export function parseBlueprintImportFile(raw: unknown): BlueprintExportPayload {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("invalid-format");
+  }
+  const data = raw as Partial<BlueprintExportPayload>;
+  if (data.kind !== BLUEPRINT_EXPORT_KIND || data.version !== BLUEPRINT_EXPORT_VERSION) {
+    throw new Error("unsupported-version");
+  }
+  if (!data.document || !Array.isArray(data.document.nodes) || !Array.isArray(data.document.edges)) {
+    throw new Error("invalid-document");
+  }
+  return {
+    kind: BLUEPRINT_EXPORT_KIND,
+    version: BLUEPRINT_EXPORT_VERSION,
+    name: typeof data.name === "string" ? data.name : "导入的蓝图",
+    remark: typeof data.remark === "string" ? data.remark : undefined,
+    exportedAt: typeof data.exportedAt === "number" ? data.exportedAt : Date.now(),
+    document: data.document,
+  };
+}
+
+export function downloadBlueprintExport(payload: BlueprintExportPayload) {
+  const blob = new Blob([JSON.stringify(payload, null, 2)], {
+    type: "application/json",
+  });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  const safeName = payload.name
+    .replace(/[\\/:*?"<>|]/g, "-")
+    .replace(/\s+/g, "-");
+  anchor.download = `${safeName || "blueprint"}-${Date.now()}.json`;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+export function buildLibraryRecord(args: {
+  document: BlueprintDocument;
+  meta: BlueprintMetaDraft;
+  source: BlueprintLibrarySource;
+  id?: string;
+  createdAt?: number;
+}): BlueprintLibraryRecord {
+  const now = Date.now();
+  const name = args.meta.name.trim() || "未命名蓝图";
+  return {
+    id: args.id ?? createLibraryBlueprintId(),
+    name,
+    remark: args.meta.remark.trim() || undefined,
+    source: args.source,
+    createdAt: args.createdAt ?? now,
+    updatedAt: now,
+    document: {
+      ...args.document,
+      name,
+    },
+  };
+}
+
+export function libraryRecordFromImport(payload: BlueprintExportPayload): BlueprintLibraryRecord {
+  return buildLibraryRecord({
+    document: payload.document,
+    meta: {
+      name: payload.name,
+      remark: payload.remark ?? "",
+    },
+    source: "imported",
+  });
+}