@nocobase/plugin-workflow 2.2.0-alpha.1 → 2.2.0-alpha.2

package/dist/client-v2/canvas/Instruction.d.ts

@@ -0,0 +1,139 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * The `Instruction` base class — the workflow node extension contract — and its
+ * pure logic hooks, relocated to client-v2 so a single definition serves both
+ * canvases (ADR-0002 as amended by ADR-0003, doc §2).
+ *
+ * Only the data/type parts move here. The legacy Formily *rendering*
+ * (`Node`, `NodeDefaultView`, the `SchemaComponent` config drawer) stays in
+ * `src/client/nodes/index.tsx`. v1 re-exports this class + the pure hooks from
+ * here via the allowed `v1 → v2` import direction, so the ~16 node files that
+ * `extends Instruction` from the `./nodes` barrel are unchanged.
+ *
+ * Iron-rule notes:
+ *  - `ISchema` is a **type-only** import from `@formily/react` (erased at build,
+ *    zero runtime — explicitly allowed; see the migration skill).
+ *  - `SchemaInitializerItemType` (the legacy `useInitializers` return type) is
+ *    NOT imported from `@nocobase/client` (forbidden). It is typed structurally
+ *    as `unknown` here — the modern canvas never calls `useInitializers` (it
+ *    uses `getCreateModelMenuItem`), and v1 callers cast as needed.
+ */
+import type { ComponentType } from 'react';
+import type { ISchema } from '@formily/react';
+import type { MetaTreeNode, SubModelItem } from '@nocobase/flow-engine';
+import type { UseVariableOptions, VariableOption } from './collectionFieldOptions';
+/** `() => Promise<{ default: Component }>` loader, matching the trigger `*Loader` convention (doc §9.5). */
+export type LoaderOf<P = {}> = () => Promise<{
+    default: ComponentType<P>;
+}>;
+export type NodeAvailableContext = {
+    /** The workflow client plugin instance (v1 `WorkflowPlugin` / v2 `PluginWorkflowClientV2`). */
+    engine: any;
+    workflow: object;
+    upstream: object;
+    branchIndex: number;
+    syncOnly?: boolean;
+};
+type Config = Record<string, any>;
+type Options = {
+    label: string;
+    value: any;
+}[];
+export type TempAssociationSource = {
+    collection: string;
+    nodeId: string | number;
+    nodeKey: string;
+    nodeType: 'workflow' | 'node';
+};
+export declare abstract class Instruction {
+    title: string;
+    type: string;
+    group: string;
+    description?: string;
+    icon?: JSX.Element;
+    async?: boolean;
+    /**
+     * @deprecated migrate to `presetFieldset` instead
+     */
+    options?: {
+        label: string;
+        value: any;
+        key: string;
+    }[];
+    fieldset: Record<string, ISchema>;
+    /**
+     * @experimental
+     */
+    presetFieldset?: Record<string, ISchema>;
+    /**
+     * @experimental
+     */
+    view?: ISchema;
+    scope?: Record<string, any>;
+    components?: Record<string, any>;
+    /** Legacy in-canvas node render (Formily canvas). */
+    Component?(props: any): JSX.Element;
+    /** Modern in-canvas node render (branch nodes self-render nested `<Branch>`).
+     *  Absent → the modern canvas uses its default card. */
+    ComponentLoader?: LoaderOf<{
+        data: any;
+    }>;
+    /** Modern config-drawer form. Absent → the drawer shows a "not yet migrated"
+     *  placeholder (never a Formily fallback). */
+    FieldsetLoader?: LoaderOf;
+    /** Modern add-time preset form (v1 `presetFieldset`). */
+    PresetFieldsetLoader?: LoaderOf;
+    /**
+     * To presentation if the instruction is creating a branch
+     * @experimental
+     */
+    branching?: boolean | Options | ((config: Config) => boolean | Options);
+    /**
+     * @experimental
+     */
+    createDefaultConfig?(): Config;
+    useVariables?(node: any, options?: UseVariableOptions): VariableOption;
+    useScopeVariables?(node: any, options?: any): VariableOption[] | MetaTreeNode[];
+    /** Legacy block initializer (v1 Schema Initializer). Return type is the
+     *  legacy `SchemaInitializerItemType`, kept structural to avoid importing
+     *  `@nocobase/client` into client-v2; v1 callers cast as needed. */
+    useInitializers?(node: any): unknown | null;
+    /**
+     * @experimental
+     */
+    isAvailable?(ctx: NodeAvailableContext): boolean;
+    end?: boolean | ((node: any) => boolean);
+    testable?: boolean;
+    /**
+     * 2.0 — v2-native block-creation menu item (the `useInitializers` counterpart).
+     */
+    getCreateModelMenuItem?({ node, workflow }: {
+        node: any;
+        workflow: any;
+    }): SubModelItem | null;
+    /**
+     * @experimental
+     */
+    useTempAssociationSource?(node: any): TempAssociationSource | null;
+}
+/**
+ * @experimental
+ * Walk the upstream chain of a node (exclusive of the node itself), optionally
+ * filtered. Pure linked-list traversal — no hooks, despite the `use*` name kept
+ * for v1 call-site compatibility.
+ */
+export declare function useAvailableUpstreams(node: any, filter?: any): any[];
+/**
+ * @experimental
+ * Collect the upstream branching scopes for a node (upstreams that open a
+ * branch the node sits inside). Pure traversal.
+ */
+export declare function useUpstreamScopes(node: any): any[];
+export { NodeContext, useNodeContext } from './contexts';

package/dist/{client/triggers/schedule/EndsByField.d.ts → client-v2/canvas/JobButton.d.ts}

@@ -7,7 +7,7 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import React from 'react';
-export declare function EndsByField({ value, onChange }: {
-    value: any;
-    onChange: any;
+export declare function JobButton({ data }: {
+    data: any;
 }): React.JSX.Element;
+export default JobButton;

package/dist/client-v2/canvas/Node.d.ts

@@ -0,0 +1,36 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * Modern canvas node card (doc §9.5/§9.6). A second copy of the v1 `Node`,
+ * rebuilt with native antd + the v2 contexts/registry — it shares no Formily
+ * code, but reuses the *same* stylesheet classes (`nodeBlockClass`,
+ * `nodeClass`, `nodeCardClass`, `nodeHeaderClass`, `nodeMetaClass`) and DOM
+ * shape so the card is visually 1:1 with v1. Renders:
+ *  - a registered node → type tag + editable title (+ optional `ComponentLoader`
+ *    self-render for branch nodes);
+ *  - an unregistered type (only implemented in v1) → a placeholder card,
+ *    keeping topology intact (mirrors v1's "unknown node" branch, doc §9.1).
+ */
+import React from 'react';
+/**
+ * The default node card — type tag + editable title + actions menu, wrapped in
+ * the canvas `nodeClass`/`nodeCardClass` chrome (drag mousedown, click-to-open
+ * config, copy/drag highlight). Exported and given a `children` slot so a node's
+ * `ComponentLoader` can reuse the exact card and append its own subtree after it
+ * (e.g. the condition node's Yes/No branches) — the v2 mirror of v1's
+ * `NodeDefaultView` (doc §9.5, ADR-0003). Assumes the type is registered; the
+ * unregistered placeholder is handled by `NodeCard`.
+ */
+export declare function NodeDefaultView({ data, children }: {
+    data: any;
+    children?: React.ReactNode;
+}): React.JSX.Element;
+export declare function Node({ data }: {
+    data: any;
+}): React.JSX.Element;

package/dist/client-v2/canvas/NodeClipboardContext.d.ts

@@ -0,0 +1,64 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * Canvas copy/paste, shared by BOTH canvases (ADR-0003). Copy a node to the
+ * clipboard; an add-slot becomes a paste zone; pasting into a position where the
+ * node's variable references are no longer in scope prompts to strip them (or
+ * keep, with a warning). Pastes via `flow_nodes.duplicate`.
+ *
+ * The provider's runtime-neutral dependencies (`api`, `t`, antd `modal`/`message`)
+ * resolve identically in either runtime (flow-engine `ctx.api`, `useT`,
+ * `App.useApp`). The two genuinely runtime-specific bits — the canvas flow data
+ * (`{ workflow, nodes, refresh }`) and the `executed` flag — are read through an
+ * injected `useCanvasRuntime` hook so each canvas supplies its own source: the
+ * modern canvas reads its `FlowContext` + `workflow.executed`, the legacy canvas
+ * its own `FlowContext` + `versionStats.executed`. v1 imports this provider from
+ * here (the allowed `v1 → v2` direction) and passes its own runtime hook, so a
+ * single implementation serves both.
+ */
+import React from 'react';
+type ClipboardNode = {
+    sourceId?: number;
+    sourceKey?: string;
+    type: string;
+    title?: string;
+    config?: Record<string, any>;
+};
+type PasteImpactItem = {
+    key: string;
+    title: string;
+};
+type PasteImpact = {
+    status: 'safe' | 'warning' | 'disabled';
+    impactedSelf: PasteImpactItem[];
+    impactedDependents: PasteImpactItem[];
+};
+type NodeClipboardContextValue = {
+    clipboard: ClipboardNode | null;
+    copyNode: (node: any) => void;
+    clearClipboard: () => void;
+    getPasteImpact: (target: any) => PasteImpact;
+    pasteNode: (target: any) => Promise<void>;
+};
+/** The per-canvas runtime data the provider needs but that differs by runtime —
+ *  injected via `NodeClipboardContextProvider`'s `useCanvasRuntime` prop. */
+export type CanvasClipboardRuntime = {
+    workflow: any;
+    nodes: any[] | undefined;
+    refresh?: () => void;
+    executed: boolean;
+};
+export declare function useNodeClipboardContext(): NodeClipboardContextValue;
+export declare function NodeClipboardContextProvider(props: {
+    children: React.ReactNode;
+    /** Injected per-canvas runtime source. Defaults to the modern canvas's. The
+     *  legacy canvas passes its own (v1 `FlowContext` + `versionStats.executed`). */
+    useCanvasRuntime?: () => CanvasClipboardRuntime;
+}): React.JSX.Element;
+export {};

package/dist/client-v2/canvas/NodeConfigDrawer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { Instruction } from './Instruction';
+/**
+ * Open the node config drawer for a node. Call from a card click handler.
+ * `ctx` is the flow-engine context (from `useFlowContext()`).
+ *
+ * `workflow` is threaded in explicitly because the drawer renders at the React
+ * root (`ctx.viewer.drawer`), OUTSIDE the canvas `FlowContext.Provider` — so the
+ * config form can't read the workflow from the canvas tree. It is re-provided via
+ * `CurrentWorkflowContext`, and the legacy canvas `FlowContext` is mirrored with
+ * the same workflow so reused v1 hooks still resolve inside migrated drawers.
+ */
+export declare function openNodeConfigDrawer(opts: {
+    ctx: any;
+    data: any;
+    instruction?: Instruction;
+    t: (key: string, options?: Record<string, any>) => string;
+    workflow?: any;
+    refresh?: () => void;
+}): void;

package/dist/client-v2/canvas/NodeDragContext.d.ts

@@ -0,0 +1,83 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * Canvas node drag-to-reorder, shared by BOTH canvases (ADR-0003, doc §9.6). The
+ * ~700-line pointer machinery (mousemove tracking, RAF drag preview, auto-scroll,
+ * drop-zone hit-testing, the move API) is framework-agnostic DOM logic; the
+ * runtime-specific bits at the top (`api`, the i18n functions, the instruction
+ * registry, the executed flag) are read through an injected `useCanvasRuntime`
+ * so v1 can re-import this single provider and pass its own runtime (the allowed
+ * v1 → v2 direction). `workflow`/`nodes`/`refresh` come from the now-shared
+ * `FlowContext` directly, and the pure graph walks from the relocated modules.
+ */
+import React from 'react';
+import { type CanvasNode } from './contexts';
+import type { Instruction } from './Instruction';
+/** Per-canvas runtime the drag provider needs but that differs by runtime —
+ *  injected via `NodeDragContextProvider`'s `useCanvasRuntime` prop. */
+export type CanvasDragRuntime = {
+    api: any;
+    /** Plain-key translation (no `{{t("…")}}` expansion) — v1 `lang`, v2 `useWorkflowTranslation().t`. */
+    lang: (key: string, options?: Record<string, unknown>) => string;
+    /** Template expander for instruction titles (`{{t("…")}}`) — v1 `useCompile()`, v2 `useT()`. */
+    compile: (source: string) => string;
+    /** Resolve an instruction by type — for the drag-preview node title. */
+    getInstruction: (type: string) => Instruction | undefined;
+    /** Whether the workflow has been executed (read-only) — the move API is disabled. */
+    executed: boolean;
+};
+/**
+ * A drop target: the add-slot's position in the graph, identified by its upstream
+ * node (`null`/absent = the root slot) and, for a branch slot, its branch index.
+ * Built by `AddNodeSlot`'s `DropZone` as `{ upstream, branchIndex }`.
+ */
+export type DropTarget = {
+    upstream?: CanvasNode | null;
+    branchIndex?: number | null;
+};
+/** The result of dropping the dragged node onto a target: whether the move is
+ *  allowed (`safe`), allowed-with-consequences (`warning` — lists the nodes whose
+ *  variable references would break), or forbidden (`disabled`). */
+export type DropImpact = {
+    status: 'safe' | 'warning' | 'disabled';
+    impactedSelf: CanvasNode[];
+    impactedDependents: CanvasNode[];
+};
+/** The minimal node snapshot driving the floating drag preview (set on drag start,
+ *  read by the preview-rendering effect). */
+export type DragPreviewNode = {
+    id: number;
+    key?: string;
+    title?: string;
+    type?: string;
+    hasBranches: boolean;
+};
+/** What `useNodeDragContext()` exposes to node cards / add-slots / the canvas. */
+export type NodeDragContextValue = {
+    dragging: boolean;
+    dragNode: DragPreviewNode | null;
+    onNodeMouseDown: (node: CanvasNode, event: React.MouseEvent) => void;
+    getDropImpact: (target: DropTarget) => DropImpact;
+    setActiveDrop: (target: DropTarget | null) => void;
+    clearActiveDrop: (target: DropTarget) => void;
+    /** Registers an add-slot's DOM element as a drop zone; returns a cleanup fn
+     *  that unregisters it (used directly as a `useEffect` teardown). */
+    registerDropZone: (target: DropTarget, element: HTMLElement | null) => () => void;
+    getDropKey: (target: DropTarget) => string;
+    activeDropKey: string | null;
+    consumeClick: () => boolean;
+};
+export declare function useNodeDragContext(): NodeDragContextValue;
+export declare function NodeDragContextProvider(props: {
+    children: React.ReactNode;
+    /** Injected per-canvas runtime source. Defaults to the modern canvas's; the
+     *  legacy canvas passes its own (v1 `useAPIClient` / `lang` / `useCompile` /
+     *  `usePlugin` registry / `useWorkflowExecuted`). */
+    useCanvasRuntime?: () => CanvasDragRuntime;
+}): React.JSX.Element;

package/dist/client-v2/canvas/RemoveNodeContext.d.ts

@@ -0,0 +1,45 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * Canvas remove-node flow, shared by BOTH canvases (ADR-0003, doc §9.6). A leaf
+ * node deletes after the variable-reference safety check (blocked when another
+ * node still references its result, else a confirm); a branching node opens a
+ * "keep which branch" modal, then runs the same safety check over the kept-branch
+ * + downstream subtree before deleting. Deletes via `flow_nodes.destroy` + refresh.
+ *
+ * This aligns the modern canvas to v1: the previous v2 implementation deleted
+ * immediately and skipped the reference guard entirely. The check logic is the
+ * shared pure `findNodesReferencing` / `collectBranchNodes`; the runtime-specific
+ * bits (`api`, `nodes`, `refresh`, the instruction registry for branch labels)
+ * are read through an injected `useCanvasRuntime` so v1 can re-import this single
+ * provider and pass its own runtime (the allowed v1 → v2 direction).
+ */
+import React from 'react';
+type RemoveNodeContextValue = {
+    /** Request deletion of a node — runs the safety check and confirm/keep-branch
+     *  flow, then deletes. Mirrors v1's `RemoveButton.onRemove`. */
+    requestRemove: (node: any) => void;
+};
+/** Per-canvas runtime the provider needs but that differs by runtime — injected
+ *  via `RemoveNodeContextProvider`'s `useCanvasRuntime` prop. */
+export type CanvasRemoveRuntime = {
+    api: any;
+    nodes: any[] | undefined;
+    refresh?: () => void;
+    /** Resolve an instruction by type — for the branch-label `branching` metadata. */
+    getInstruction: (type: string) => any;
+};
+export declare function useRemoveNodeContext(): RemoveNodeContextValue;
+export declare function RemoveNodeContextProvider(props: {
+    children: React.ReactNode;
+    /** Injected per-canvas runtime source. Defaults to the modern canvas's; the
+     *  legacy canvas passes its own (v1 `FlowContext` + `usePlugin` registry). */
+    useCanvasRuntime?: () => CanvasRemoveRuntime;
+}): React.JSX.Element;
+export {};

package/dist/client-v2/canvas/WorkflowTypedVariableInput.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import React from 'react';
+import { type TypedConstantSpec, type TypedVariableInputProps } from '@nocobase/client-v2';
+import { type UseWorkflowVariableOptions } from './useWorkflowVariableOptions';
+export declare const WORKFLOW_TYPED_CONSTANT_TYPES: TypedConstantSpec[];
+export type WorkflowTypedVariableInputProps = Omit<TypedVariableInputProps, 'extraNodes' | 'metaTree' | 'namespaces'> & {
+    variableOptions?: UseWorkflowVariableOptions;
+};
+export declare function WorkflowTypedVariableInput({ variableOptions, ...rest }: WorkflowTypedVariableInputProps): React.JSX.Element;

package/dist/client-v2/canvas/WorkflowVariableInput.d.ts

@@ -0,0 +1,39 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * The v2 workflow variable picker (doc §5). A downstream node author drops this
+ * into a `FieldsetLoader` form like any antd input — it reads the current node
+ * from NodeContext and the upstream chain itself, so the author never wires
+ * context.
+ *
+ * It reuses flow-engine's low-level `VariableHybridInput` (fed a
+ * workflow-constructed `MetaTreeNode` tree from `useWorkflowVariableOptions`),
+ * NOT the top-level global `VariableInput` (whose tree is the global registry).
+ *
+ * Workflow variables serialize as `{{$jobsMapByNodeKey.<nodeKey>.<field>}}` —
+ * the adapter already builds `paths` as `['$jobsMapByNodeKey', nodeKey, …]`, so
+ * the converters here just join/split that path inside `{{ }}`.
+ */
+import React from 'react';
+import { type UseWorkflowVariableOptions } from './useWorkflowVariableOptions';
+export type WorkflowVariableInputProps = {
+    value?: string;
+    onChange?: (value: string) => void;
+    disabled?: boolean;
+    placeholder?: string;
+    className?: string;
+    style?: React.CSSProperties;
+    /** Validation status (red/amber border). Usually omitted — inside a
+     *  `Form.Item` the status is inherited automatically. */
+    status?: 'error' | 'warning';
+    /** Variable-tree options forwarded to each upstream `useVariables` (types
+     *  filter, appends, depth, fieldNames). */
+    variableOptions?: UseWorkflowVariableOptions;
+};
+export declare function WorkflowVariableInput(props: WorkflowVariableInputProps): React.JSX.Element;

package/dist/client-v2/canvas/WorkflowVariableJsonTextArea.d.ts

@@ -0,0 +1,15 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { type JsonTextAreaProps } from '@nocobase/client-v2';
+import React from 'react';
+import { type UseWorkflowVariableOptions } from './useWorkflowVariableOptions';
+export interface WorkflowVariableJsonTextAreaProps extends JsonTextAreaProps {
+    variableOptions?: UseWorkflowVariableOptions;
+}
+export declare function WorkflowVariableJsonTextArea(props: WorkflowVariableJsonTextAreaProps): React.JSX.Element;

package/dist/client-v2/canvas/WorkflowVariableTextArea.d.ts

@@ -0,0 +1,18 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { TextAreaProps } from 'antd/es/input';
+import React from 'react';
+import { type UseWorkflowVariableOptions } from './useWorkflowVariableOptions';
+export interface WorkflowVariableTextAreaProps extends Omit<TextAreaProps, 'value' | 'onChange'> {
+    value?: string;
+    onChange?: (value: string) => void;
+    variableOptions?: UseWorkflowVariableOptions;
+    delimiters?: readonly [string, string];
+}
+export declare function WorkflowVariableTextArea(props: WorkflowVariableTextAreaProps): React.JSX.Element;

package/dist/client-v2/canvas/adaptVariableOptionToMetaTree.d.ts

@@ -0,0 +1,48 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+/**
+ * Single, core, one-way adapter `VariableOption → MetaTreeNode` (ADR-0003,
+ * migration doc §6). The modern canvas reuses the mature legacy field-tree
+ * logic (`getCollectionFieldOptions`, which returns `VariableOption`) unchanged,
+ * and converts its aggregated upstream variables to the flow-engine
+ * `MetaTreeNode` shape with this adapter just before feeding `VariableHybridInput`.
+ *
+ * Pure, side-effect-free, React-context-free — so it is independently unit
+ * testable and the whole suite is deletable in one move when the legacy
+ * field-tree logic is finally rewritten to produce `MetaTreeNode` natively.
+ *
+ * The modern consumers (`FlowContextSelector` cascader, `VariableHybridInput.walk`,
+ * `VariableTag`) read exactly 7 `MetaTreeNode` fields; this adapter maps:
+ *   title          ← label                (reactNode preserved; walk plain-texts it)
+ *   name           ← value (or label)     direct, with name fallback
+ *   children        ← children / loadChildren → () => Promise<MetaTreeNode[]>
+ *   disabled        ← disabled            direct
+ *   disabledReason  ← (v1 has none)       left undefined
+ *   type/interface  ← field.type/.interface (only used by custom render)
+ *   paths           ← (no v1 counterpart) constructed here, accumulated down
+ *                                          the recursion (incl. lazy children).
+ *
+ * The v1-only keys (`field`/`types`/`appends`/`depth`) are captured in the
+ * `loadChildren` closure and never surface on the produced `MetaTreeNode`.
+ */
+import type { MetaTreeNode } from '@nocobase/flow-engine';
+import type { VariableOption } from './collectionFieldOptions';
+/**
+ * @param option   a single VariableOption (as produced by getCollectionFieldOptions
+ *                 / useWorkflowVariableOptions).
+ * @param parentPaths  the path array accumulated from the root down to (but not
+ *                 including) this node. Top-level callers pass `[]` (or a custom
+ *                 root prefix, e.g. `['$jobsMapByNodeKey', nodeKey]`).
+ */
+export declare function adaptVariableOptionToMetaTree(option: VariableOption, parentPaths?: string[]): MetaTreeNode;
+/**
+ * Adapt a list of top-level options (e.g. one aggregated variable scope) under
+ * an optional root path prefix.
+ */
+export declare function adaptVariableOptionsToMetaTree(options: VariableOption[], rootPaths?: string[]): MetaTreeNode[];

package/dist/client-v2/canvas/addNodeController.d.ts

@@ -0,0 +1,70 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { Instruction } from './Instruction';
+import type { SharedAddNodeAnchor } from './AddNodeContext.shared';
+export type AddNodeControllerRuntime = {
+    workflow: any;
+    nodes: any[];
+    getInstruction: (type: string) => Instruction | undefined;
+    getInstructionAvailable?: (instruction: Instruction, context: Record<string, any>) => string | null;
+    translateTitle: (title: string) => string;
+    api: any;
+    refresh?: () => void;
+};
+export type AddNodeDraft = {
+    key: string;
+    type: string;
+    upstreamId: any;
+    branchIndex: number | null | undefined;
+    title: string;
+    config: Record<string, any>;
+};
+export type AddNodeDecision = {
+    kind: 'missing';
+    type: string;
+} | {
+    kind: 'blocked';
+    message: string;
+    instruction: Instruction;
+} | {
+    kind: 'legacy-preset';
+    instruction: Instruction;
+    draft: AddNodeDraft;
+} | {
+    kind: 'modern-preset';
+    instruction: Instruction;
+    anchor: SharedAddNodeAnchor;
+    hasDownstream: boolean;
+} | {
+    kind: 'branch-fallback';
+    instruction: Instruction;
+    draft: AddNodeDraft;
+} | {
+    kind: 'direct';
+    instruction: Instruction;
+    draft: AddNodeDraft;
+};
+export declare function findDownstream(nodes?: any[], upstream?: any, branchIndex?: number | null): any;
+export declare function createNodeDraft({ instruction, anchor, translateTitle, }: {
+    instruction: Instruction;
+    anchor: SharedAddNodeAnchor;
+    translateTitle: (title: string) => string;
+}): AddNodeDraft;
+export declare function resolveAddNodeDecision({ type, anchor, runtime, }: {
+    type: string;
+    anchor: SharedAddNodeAnchor;
+    runtime: Pick<AddNodeControllerRuntime, 'workflow' | 'nodes' | 'getInstruction' | 'getInstructionAvailable' | 'translateTitle'>;
+}): AddNodeDecision;
+export declare function createNodeAndMaybeReparent({ workflowId, api, refresh, values, downstreamBranchIndex, }: {
+    workflowId: any;
+    api: any;
+    refresh?: () => void;
+    values: Record<string, any>;
+    downstreamBranchIndex?: number | null;
+}): Promise<any>;