@nocobase/flow-engine 2.2.0-alpha.1 → 2.2.0-alpha.3

package/src/components/variables/VariableHybridInput.tsx

@@ -9,12 +9,17 @@
 
 import { css, cx } from '@emotion/css';
 import { Space, theme } from 'antd';
-import React, { isValidElement, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { FormItemInputContext } from 'antd/es/form/context';
+import React, { isValidElement, useContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { MetaTreeNode } from '../../flowContext';
 import { useFlowContext } from '../../FlowContextProvider';
 import { FlowContextSelector } from '../FlowContextSelector';
 import { useResolvedMetaTree } from './useResolvedMetaTree';
-import { formatPathToValue as defaultFormatPathToValue, parseValueToPath as defaultParseValueToPath } from './utils';
+import {
+  formatPathToValue as defaultFormatPathToValue,
+  loadMetaTreeChildren,
+  parseValueToPath as defaultParseValueToPath,
+} from './utils';
 
 type RangeIndexes = [number, number, number, number];
 
@@ -37,6 +42,14 @@ export interface VariableHybridInputProps {
   converters?: VariableHybridInputConverters;
   style?: React.CSSProperties;
   className?: string;
+  /**
+   * Validation status — turns the input border red (`error`) or amber
+   * (`warning`). Usually omitted: when rendered inside an antd `Form.Item`, the
+   * status is read automatically from `FormItemInputContext`, so dropping this
+   * into a `Form.Item` with failing rules colours the border with no extra
+   * wiring. An explicit prop wins over the inherited form status.
+   */
+  status?: 'error' | 'warning';
 }
 
 function reactNodeToPlainText(node: React.ReactNode): string {
@@ -83,14 +96,38 @@ function normalizeVariableKey(value: string): string {
     .trim();
 }
 
-function renderHTML(value: string, labelMap: Map<string, string>, regExp: RegExp) {
+function renderHTML(value: string, regExp: RegExp, resolveLabel: (matched: string) => string | undefined) {
   const re = new RegExp(regExp.source, regExp.flags.includes('g') ? regExp.flags : `${regExp.flags}g`);
   return escapeHtml(value || '').replace(re, (matched) => {
-    const label = labelMap.get(normalizeVariableKey(matched)) || matched;
+    const label = resolveLabel(matched) || matched;
     return createTagHTML(matched, label);
   });
 }
 
+// Resolve a `{{ … }}` reference path to its slash-joined title chain by walking the (possibly lazily-expanded) meta tree
+// live. Unlike `buildLabelMap` — which pre-walks only already-loaded (array) children into a memoized map — this reads
+// the tree's CURRENT contents at call time, so a level expanded in place (by the cascader's loadData when the user
+// drills in, or by the preload effect) is reflected on the very next render without the memoized map having to rebuild.
+// This is what fixes a just-picked deep node rendering as its raw `{{ … }}` token. Returns undefined if any segment is
+// missing or sits below a still-unresolved (thunk) level — the caller then falls back to the raw token.
+function resolveTitlesByPath(
+  roots: MetaTreeNode[] | undefined,
+  path: string[] | undefined,
+  ctxT: (text: string) => string,
+): string | undefined {
+  if (!roots || !path || !path.length) return undefined;
+  const titles: string[] = [];
+  let nodes: MetaTreeNode[] | undefined = roots;
+  for (const segment of path) {
+    if (!nodes) return undefined;
+    const matched: MetaTreeNode | undefined = nodes.find((node) => node.name === segment);
+    if (!matched) return undefined;
+    titles.push(reactNodeToPlainText(matched.title || matched.name));
+    nodes = Array.isArray(matched.children) ? (matched.children as MetaTreeNode[]) : undefined;
+  }
+  return titles.map(ctxT).join('/');
+}
+
 function buildLabelMap(
   nodes: MetaTreeNode[] | undefined,
   ctxT: (text: string) => string,
@@ -116,6 +153,42 @@ function buildLabelMap(
   return map;
 }
 
+// Collect every variable reference path in `value` (one per `{{ … }}` token). Used to preload lazy meta-tree levels so
+// a saved reference whose label lives below an unexpanded (thunk) level still resolves to a readable tag.
+function collectReferencePaths(
+  value: string,
+  regExp: RegExp,
+  parseValueToPath: (value?: string) => string[] | undefined,
+): string[][] {
+  const re = new RegExp(regExp.source, regExp.flags.includes('g') ? regExp.flags : `${regExp.flags}g`);
+  const paths: string[][] = [];
+  for (const matched of value.match(re) ?? []) {
+    const path = parseValueToPath(matched);
+    if (path && path.length) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+
+// Walk one reference path down the meta tree, resolving each lazy `children` thunk in place. Returns true if it
+// resolved at least one level (so the caller knows to recompute the label map). Mirrors `TypedVariableInput`'s preload.
+async function preloadReferencePath(path: string[], roots: MetaTreeNode[]): Promise<boolean> {
+  let nodes: MetaTreeNode[] | undefined = roots;
+  let didLoad = false;
+  for (const segment of path) {
+    if (!nodes) break;
+    const matched: MetaTreeNode | undefined = nodes.find((node) => node.name === segment);
+    if (!matched) break;
+    if (typeof matched.children === 'function') {
+      matched.children = await loadMetaTreeChildren(matched);
+      didLoad = true;
+    }
+    nodes = Array.isArray(matched.children) ? matched.children : undefined;
+  }
+  return didLoad;
+}
+
 function pasteHTML(container: HTMLElement, html: string, indexes?: RangeIndexes) {
   const selection = window.getSelection?.();
   const range = selection?.rangeCount ? selection.getRangeAt(0) : null;
@@ -226,6 +299,10 @@ const VariableHybridInputComponent: React.FC<VariableHybridInputProps> = (props)
   const { token } = theme.useToken();
   const ctx = useFlowContext();
   const { resolvedMetaTree } = useResolvedMetaTree(metaTree);
+  // Inherit the antd Form.Item validation status (red/amber border) unless an explicit `status` prop overrides it — so
+  // the border colours automatically inside a failing `Form.Item`, no extra wiring for callers.
+  const formItemStatus = useContext(FormItemInputContext)?.status;
+  const effectiveStatus = props.status ?? formItemStatus;
   const inputRef = useRef<HTMLDivElement>(null);
   const [isComposing, setIsComposing] = useState(false);
   const [changed, setChanged] = useState(false);
@@ -233,13 +310,63 @@ const VariableHybridInputComponent: React.FC<VariableHybridInputProps> = (props)
 
   const value = typeof props.value === 'string' ? props.value : props.value == null ? '' : String(props.value);
   const variableRegExp = converters?.variableRegExp ?? DEFAULT_VARIABLE_REGEXP;
+  const parseValueToPath = converters?.parseValueToPath ?? defaultParseValueToPath;
+
+  // Bumped after a saved reference's lazy meta-tree levels are resolved, so the label map (below) recomputes once the
+  // deep titles are actually loaded.
+  const [loadedFlag, setLoadedFlag] = useState(0);
+
+  // Preload the lazy levels every `{{ … }}` reference in `value` points through. `buildLabelMap` only walks
+  // already-loaded (array) children, so without this a reference below an unexpanded thunk level (e.g. a workflow
+  // node's output fields under `$jobsMapByNodeKey.<nodeKey>`) renders as the raw `{{ … }}` text instead of its
+  // node/field labels. Mirrors `TypedVariableInput`'s preload.
+  useEffect(() => {
+    if (!value || !Array.isArray(resolvedMetaTree) || !resolvedMetaTree.length) {
+      return;
+    }
+    const paths = collectReferencePaths(value, variableRegExp, parseValueToPath);
+    if (!paths.length) {
+      return;
+    }
+    let cancelled = false;
+    const run = async () => {
+      let didLoad = false;
+      for (const path of paths) {
+        const loaded = await preloadReferencePath(path, resolvedMetaTree as MetaTreeNode[]);
+        if (cancelled) return;
+        didLoad = didLoad || loaded;
+      }
+      if (didLoad && !cancelled) {
+        setLoadedFlag((prev) => prev + 1);
+      }
+    };
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [value, resolvedMetaTree, variableRegExp, parseValueToPath]);
 
   const labelMap = useMemo(
     () => buildLabelMap(resolvedMetaTree as MetaTreeNode[] | undefined, ctx.t, converters),
-    [resolvedMetaTree, ctx, converters],
+    // `loadedFlag` is read so the map recomputes after a lazy level resolves.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [resolvedMetaTree, ctx, converters, loadedFlag],
+  );
+
+  // Resolve one `{{ … }}` token to its label: the pre-built map first (cheap, covers statically-loaded levels), then a LIVE walk of the current meta tree. The live fallback is what makes a just-picked deep reference render its label immediately — when the user drills into a lazy level, the cascader resolves that level onto the meta tree in place WITHOUT changing the tree reference or bumping `loadedFlag`, so the memoized `labelMap` still misses it; walking the tree's current contents finds the freshly-loaded titles on the same render.
+  const resolveLabel = useCallback(
+    (matched: string): string | undefined => {
+      const mapped = labelMap.get(normalizeVariableKey(matched));
+      if (mapped) return mapped;
+      const path = parseValueToPath(matched);
+      return resolveTitlesByPath(resolvedMetaTree as MetaTreeNode[] | undefined, path, ctx.t);
+    },
+    // `loadedFlag` is read so a resolved lazy level re-creates this callback and re-renders the tags. `ctx` carries the translation fn.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [labelMap, parseValueToPath, resolvedMetaTree, ctx, loadedFlag],
   );
 
-  const [html, setHtml] = useState(() => renderHTML(value, labelMap, variableRegExp));
+  const [html, setHtml] = useState(() => renderHTML(value, variableRegExp, resolveLabel));
 
   const emitChange = useCallback(
     (target: HTMLElement) => {
@@ -249,12 +376,12 @@ const VariableHybridInputComponent: React.FC<VariableHybridInputProps> = (props)
   );
 
   useEffect(() => {
-    setHtml(renderHTML(value, labelMap, variableRegExp));
+    setHtml(renderHTML(value, variableRegExp, resolveLabel));
     if (!changed) {
       setRange([-1, 0, -1, 0]);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [value, labelMap]);
+  }, [value, resolveLabel]);
 
   // Restore caret position after html update
   useEffect(() => {
@@ -492,6 +619,34 @@ const VariableHybridInputComponent: React.FC<VariableHybridInputProps> = (props)
           border-color: ${token.colorBorder};
         }
       }
+
+      &.is-error {
+        border-color: ${token.colorError};
+
+        &:hover {
+          border-color: ${token.colorErrorBorderHover};
+        }
+
+        &:focus,
+        &:focus-visible {
+          border-color: ${token.colorError};
+          box-shadow: 0 0 0 ${token.controlOutlineWidth}px ${token.colorErrorOutline};
+        }
+      }
+
+      &.is-warning {
+        border-color: ${token.colorWarning};
+
+        &:hover {
+          border-color: ${token.colorWarningBorderHover};
+        }
+
+        &:focus,
+        &:focus-visible {
+          border-color: ${token.colorWarning};
+          box-shadow: 0 0 0 ${token.controlOutlineWidth}px ${token.colorWarningOutline};
+        }
+      }
     `;
   }, [token, addonBefore]);
 
@@ -505,6 +660,8 @@ const VariableHybridInputComponent: React.FC<VariableHybridInputProps> = (props)
           aria-label="textbox"
           className={cx(editorClassName, {
             'is-disabled': disabled,
+            'is-error': effectiveStatus === 'error',
+            'is-warning': effectiveStatus === 'warning',
           })}
           contentEditable={!disabled}
           data-placeholder={placeholder}
@@ -519,7 +676,7 @@ const VariableHybridInputComponent: React.FC<VariableHybridInputProps> = (props)
         <FlowContextSelector
           metaTree={metaTree}
           disabled={disabled}
-          parseValueToPath={converters?.parseValueToPath ?? defaultParseValueToPath}
+          parseValueToPath={parseValueToPath}
           formatPathToValue={(item) => converters?.formatPathToValue?.(item) || defaultFormatPathToValue(item)}
           onChange={handleSelectorChange}
         />

package/src/components/variables/VariableInput.tsx

@@ -192,7 +192,7 @@ const VariableInputComponent: React.FC<VariableInputProps> = ({
     };
 
     restoreFromValue();
-  }, [resolvedMetaTree, innerValue, resolvePathFromValue, currentMetaTreeNode]);
+  }, [resolvedMetaTree, innerValue, resolvePathFromValue, currentMetaTreeNode, value]);
 
   const ValueComponent = useMemo(() => {
     const Component = renderInputComponent?.(resolvedMetaTreeNode);
@@ -356,6 +356,7 @@ const VariableInputComponent: React.FC<VariableInputProps> = ({
       <FlowContextSelector
         metaTree={resolvedMetaTree}
         value={innerValue}
+        active={isVariableValue(innerValue)}
         onChange={handleVariableSelect}
         parseValueToPath={resolvePathFromValue}
         formatPathToValue={resolveValueFromPath}

package/src/components/variables/__tests__/FlowContextSelector.test.tsx

@@ -67,6 +67,23 @@ describe('FlowContextSelector', () => {
     });
   });
 
+  it('uses explicit active=false to keep the default trigger unhighlighted even when value parses to a path', async () => {
+    const flowContext = createTestFlowContext();
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <FlowContextSelector
+          metaTree={() => flowContext.getPropertyMetaTree()}
+          value="{{ ctx.user.name }}"
+          active={false}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    const button = await screen.findByRole('button');
+    expect(button.className).not.toContain('ant-btn-primary');
+  });
+
   it('should support function metaTree loading', async () => {
     const flowContext = createTestFlowContext();
     const metaTreeFn = vi.fn(() => flowContext.getPropertyMetaTree());
@@ -405,10 +422,13 @@ describe('FlowContextSelector', () => {
 
     const clearIcon = document.querySelector('.ant-input-clear-icon') as HTMLElement | null;
     expect(clearIcon).toBeInTheDocument();
+    if (!clearIcon) {
+      throw new Error('Expected inline clear icon to be present');
+    }
 
-    fireEvent.mouseDown(clearIcon!);
-    fireEvent.mouseUp(clearIcon!);
-    fireEvent.click(clearIcon!);
+    fireEvent.mouseDown(clearIcon);
+    fireEvent.mouseUp(clearIcon);
+    fireEvent.click(clearIcon);
 
     await waitFor(() => {
       expect(onChange).toHaveBeenCalledWith('', undefined);

package/src/components/variables/__tests__/VariableHybridInput.test.tsx

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+
+/**
+ * Pins how a `{{ … }}` reference renders as its label when the label lives below a lazily-loaded meta-tree level (e.g. a workflow node's output fields under `$jobsMapByNodeKey.<nodeKey>`). `buildLabelMap` only pre-walks already-loaded (array) children into a memoized map, so the two real user flows each need their own resolution path, both pinned here:
+ *   - after reload  — the value is already a deep reference at mount, its level still an unresolved thunk → the preload effect resolves it.
+ *   - after picking — the user drills into a lazy level (cascader resolves it IN PLACE, no tree-ref change) then picks a leaf → the live walk of the tree's current contents resolves it on the same render.
+ * Plus the top-level (already-loaded) and not-in-tree (raw-token fallback) cases.
+ */
+
+import { render, waitFor } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { VariableHybridInput, type VariableHybridInputConverters } from '../VariableHybridInput';
+import type { MetaTreeNode } from '../../../flowContext';
+import { createTestFlowContext, TestFlowContextWrapper } from './test-utils';
+
+// Workflow-style converters: `{{$root.a.b}}` (dotted path, no inner spaces).
+const VARIABLE_REGEXP = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const workflowConverters: VariableHybridInputConverters = {
+  formatPathToValue: (item?: MetaTreeNode) => {
+    const path = item?.paths ?? [];
+    return path.length ? `{{${path.join('.')}}}` : '';
+  },
+  parseValueToPath: (value?: string) => {
+    if (typeof value !== 'string') return undefined;
+    const match = value.trim().match(/^\{\{\s*(.+?)\s*\}\}$/);
+    return match ? match[1].split('.') : undefined;
+  },
+  variableRegExp: VARIABLE_REGEXP,
+};
+
+const TAG_SELECTOR = '.nb-variable-tag';
+
+describe('VariableHybridInput — saved reference labels', () => {
+  it('renders a top-level (already-loaded) reference as its label, not the raw token', async () => {
+    const flowContext = createTestFlowContext();
+    const metaTree: MetaTreeNode[] = [
+      {
+        name: '$user',
+        title: 'User',
+        type: '',
+        paths: ['$user'],
+        children: [{ name: 'name', title: 'Name', type: 'string', paths: ['$user', 'name'] }],
+      },
+    ];
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableHybridInput value="{{$user.name}}" metaTree={metaTree} converters={workflowConverters} />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(() => {
+      const tag = document.querySelector(TAG_SELECTOR);
+      expect(tag).toBeTruthy();
+      expect(tag?.textContent).toBe('User/Name');
+    });
+  });
+
+  it('shows the label after reload: a deep reference present at mount preloads its lazy level', async () => {
+    const flowContext = createTestFlowContext();
+    // The node's output fields are behind a lazy `children` thunk — exactly the `$jobsMapByNodeKey.<nodeKey>` shape produced by the workflow adapter.
+    const loadChildren = vi.fn(
+      async (): Promise<MetaTreeNode[]> => [
+        { name: 'name', title: 'Name', type: 'string', paths: ['$jobsMapByNodeKey', 'node1', 'name'] },
+      ],
+    );
+    const metaTree: MetaTreeNode[] = [
+      {
+        name: '$jobsMapByNodeKey',
+        title: 'Node result',
+        type: '',
+        paths: ['$jobsMapByNodeKey'],
+        children: [
+          {
+            name: 'node1',
+            title: 'Query',
+            type: '',
+            paths: ['$jobsMapByNodeKey', 'node1'],
+            children: loadChildren,
+          },
+        ],
+      },
+    ];
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableHybridInput
+          value="{{$jobsMapByNodeKey.node1.name}}"
+          metaTree={metaTree}
+          converters={workflowConverters}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    // The lazy thunk is invoked by the preload, and the deep label appears.
+    await waitFor(() => {
+      expect(loadChildren).toHaveBeenCalled();
+      const tag = document.querySelector(TAG_SELECTOR);
+      expect(tag?.textContent).toBe('Node result/Query/Name');
+    });
+    // It must NOT leave the raw token visible.
+    expect(document.body.textContent).not.toContain('{{$jobsMapByNodeKey.node1.name}}');
+  });
+
+  it('shows the label after picking: a level expanded in place then selected resolves live', async () => {
+    // Reproduces drilling into a lazy level in the cascader: that resolves the node's `children` onto the SAME meta-tree object in place — WITHOUT changing the tree reference — then the user picks a leaf, so `value` updates. The memoized `labelMap` (keyed on the tree reference) still misses the freshly loaded leaf; only a live walk of the tree's current contents resolves it.
+    const flowContext = createTestFlowContext();
+    const node1: MetaTreeNode = {
+      name: 'node1',
+      title: 'Query',
+      type: '',
+      paths: ['$jobsMapByNodeKey', 'node1'],
+      // Starts WITHOUT children (an unexpanded branch). No thunk — so the preload effect/`loadedFlag` path does not fire; the fix must come from the live walk.
+    };
+    const metaTree: MetaTreeNode[] = [
+      {
+        name: '$jobsMapByNodeKey',
+        title: 'Node result',
+        type: '',
+        paths: ['$jobsMapByNodeKey'],
+        children: [node1],
+      },
+    ];
+
+    // Mount with no reference yet — the deep level is not loaded.
+    const { rerender } = render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableHybridInput value="" metaTree={metaTree} converters={workflowConverters} />
+      </TestFlowContextWrapper>,
+    );
+
+    // Simulate the cascader's loadData: resolve node1's children in place on the SAME tree object (no new reference, no thunk).
+    node1.children = [
+      { name: 'name', title: 'Role name', type: 'string', paths: ['$jobsMapByNodeKey', 'node1', 'name'] },
+    ];
+
+    // The user picks the leaf → value updates to the deep reference.
+    rerender(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableHybridInput
+          value="{{$jobsMapByNodeKey.node1.name}}"
+          metaTree={metaTree}
+          converters={workflowConverters}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(() => {
+      const tag = document.querySelector(TAG_SELECTOR);
+      expect(tag?.textContent).toBe('Node result/Query/Role name');
+    });
+    expect(document.body.textContent).not.toContain('{{$jobsMapByNodeKey.node1.name}}');
+  });
+
+  it('falls back to the raw token when the reference is not in the tree', async () => {
+    const flowContext = createTestFlowContext();
+    const metaTree: MetaTreeNode[] = [{ name: '$user', title: 'User', type: '', paths: ['$user'], children: [] }];
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableHybridInput value="{{$missing.field}}" metaTree={metaTree} converters={workflowConverters} />
+      </TestFlowContextWrapper>,
+    );
+
+    await waitFor(() => {
+      const tag = document.querySelector(TAG_SELECTOR);
+      expect(tag?.textContent).toBe('{{$missing.field}}');
+    });
+  });
+});

package/src/components/variables/__tests__/VariableInput.test.tsx

@@ -8,6 +8,7 @@
  */
 
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { Input } from 'antd';
 import React from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import type { ContextSelectorItem } from '../types';
@@ -112,6 +113,50 @@ describe('VariableInput', () => {
     expect(selectorButton).toBeInTheDocument();
   });
 
+  it('should not highlight the selector button for synthetic constant/null paths', async () => {
+    const flowContext = createTestFlowContext();
+
+    render(
+      <TestFlowContextWrapper context={flowContext}>
+        <VariableInput
+          value=""
+          metaTree={[
+            { name: 'constant', title: 'Constant', type: 'string', paths: ['constant'] },
+            { name: 'null', title: 'Null', type: 'object', paths: ['null'] },
+            ...flowContext.getPropertyMetaTree(),
+          ]}
+          converters={{
+            renderInputComponent: (meta) => {
+              const first = meta?.paths?.[0];
+              if (first === 'constant') {
+                return (props: any) => <input aria-label="constant-value" {...props} />;
+              }
+              if (first === 'null') {
+                return () => <Input placeholder="<Null>" readOnly />;
+              }
+              return null;
+            },
+            resolveValueFromPath: (meta) => {
+              const first = meta?.paths?.[0];
+              if (first === 'constant') return '';
+              if (first === 'null') return null;
+              return undefined;
+            },
+            resolvePathFromValue: (currentValue) => {
+              if (currentValue === null) return ['null'];
+              const trimmed = typeof currentValue === 'string' ? currentValue.trim() : currentValue;
+              if (trimmed === '') return ['constant'];
+              return undefined;
+            },
+          }}
+        />
+      </TestFlowContextWrapper>,
+    );
+
+    const selectorButton = await screen.findByRole('button');
+    expect(selectorButton.className).not.toContain('ant-btn-primary');
+  });
+
   it('should handle onChange from Input', async () => {
     const onChange = vi.fn();
     const flowContext = createTestFlowContext();
@@ -195,20 +240,21 @@ describe('VariableInput', () => {
 
     const selectElement = container.querySelector('.ant-select');
     expect(selectElement).toBeInTheDocument();
+    if (!selectElement) {
+      throw new Error('Expected variable tag select wrapper to be present');
+    }
 
     // 触发鼠标悬停以显示清除按钮
-    fireEvent.mouseEnter(selectElement!);
+    fireEvent.mouseEnter(selectElement);
 
     // 尝试触发清除功能
     // 方法1: 直接触发 Select 组件的 onClear 事件
-    const selectInstance = selectElement as any;
-
     // 尝试通过键盘事件触发清除
-    fireEvent.keyDown(selectElement!, { key: 'Backspace', code: 'Backspace' });
+    fireEvent.keyDown(selectElement, { key: 'Backspace', code: 'Backspace' });
 
     // 或者尝试触发自定义的清除逻辑
     const clearEvents = new CustomEvent('clear');
-    selectElement!.dispatchEvent(clearEvents);
+    selectElement.dispatchEvent(clearEvents);
 
     // 检查是否调用了清除功能（可能需要调整期望）
     // 如果清除按钮不能直接测试，我们验证组件支持清除功能

package/src/components/variables/types.ts

@@ -16,12 +16,30 @@ export interface FlowContextSelectorProps
   value?: string;
   onChange?: (value: string, metaTreeNode?: MetaTreeNode) => void;
   children?: CascaderProps<ContextSelectorItem>['children'];
+  /**
+   * Controls whether the default `x` trigger button is rendered as active
+   * (`type="primary"`). When omitted, the selector falls back to its parsed
+   * `value` path (`true` iff a valid variable path is currently selected).
+   *
+   * Use this when callers intentionally feed synthetic paths such as
+   * `['constant']` / `['null']` into the cascader to keep menu state aligned,
+   * but only want real variable references to show the blue active button.
+   */
+  active?: boolean;
   metaTree?: MetaTreeNode[] | (() => MetaTreeNode[] | Promise<MetaTreeNode[]>);
   parseValueToPath?: (value: string) => string[] | undefined;
   formatPathToValue?: (item: MetaTreeNode) => string;
   open?: boolean;
   onlyLeafSelectable?: boolean;
   ignoreFieldNames?: string[];
+  /**
+   * Footer rendered at the bottom of the dropdown. Defaults to a muted
+   * "Double click to choose entire object" hint when non-leaf selection is
+   * allowed (`onlyLeafSelectable` is false) — since double-clicking a non-leaf
+   * node selects the whole object. Pass an explicit node to override, or `null`
+   * to hide it.
+   */
+  dropdownFooter?: React.ReactNode;
 }
 
 export interface ContextSelectorItem {