@nocobase/flow-engine 2.2.0-beta.8 → 2.2.0

package/lib/components/variables/VariableHybridInput.js

@@ -42,6 +42,7 @@ __export(VariableHybridInput_exports, {
 module.exports = __toCommonJS(VariableHybridInput_exports);
 var import_css = require("@emotion/css");
 var import_antd = require("antd");
+var import_context = require("antd/es/form/context");
 var import_react = __toESM(require("react"));
 var import_FlowContextProvider = require("../../FlowContextProvider");
 var import_FlowContextSelector = require("../FlowContextSelector");
@@ -83,14 +84,28 @@ function normalizeVariableKey(value) {
   return value.replace(/^\{\{\s*/, "").replace(/\s*\}\}$/, "").trim();
 }
 __name(normalizeVariableKey, "normalizeVariableKey");
-function renderHTML(value, labelMap, regExp) {
+function renderHTML(value, regExp, resolveLabel) {
   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);
   });
 }
 __name(renderHTML, "renderHTML");
+function resolveTitlesByPath(roots, path, ctxT) {
+  if (!roots || !path || !path.length) return void 0;
+  const titles = [];
+  let nodes = roots;
+  for (const segment of path) {
+    if (!nodes) return void 0;
+    const matched = nodes.find((node) => node.name === segment);
+    if (!matched) return void 0;
+    titles.push(reactNodeToPlainText(matched.title || matched.name));
+    nodes = Array.isArray(matched.children) ? matched.children : void 0;
+  }
+  return titles.map(ctxT).join("/");
+}
+__name(resolveTitlesByPath, "resolveTitlesByPath");
 function buildLabelMap(nodes, ctxT, converters) {
   const map = /* @__PURE__ */ new Map();
   function walk(items = [], parentTitles = []) {
@@ -112,6 +127,34 @@ function buildLabelMap(nodes, ctxT, converters) {
   return map;
 }
 __name(buildLabelMap, "buildLabelMap");
+function collectReferencePaths(value, regExp, parseValueToPath) {
+  const re = new RegExp(regExp.source, regExp.flags.includes("g") ? regExp.flags : `${regExp.flags}g`);
+  const paths = [];
+  for (const matched of value.match(re) ?? []) {
+    const path = parseValueToPath(matched);
+    if (path && path.length) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+__name(collectReferencePaths, "collectReferencePaths");
+async function preloadReferencePath(path, roots) {
+  let nodes = roots;
+  let didLoad = false;
+  for (const segment of path) {
+    if (!nodes) break;
+    const matched = nodes.find((node) => node.name === segment);
+    if (!matched) break;
+    if (typeof matched.children === "function") {
+      matched.children = await (0, import_utils.loadMetaTreeChildren)(matched);
+      didLoad = true;
+    }
+    nodes = Array.isArray(matched.children) ? matched.children : void 0;
+  }
+  return didLoad;
+}
+__name(preloadReferencePath, "preloadReferencePath");
 function pasteHTML(container, html, indexes) {
   var _a;
   const selection = (_a = window.getSelection) == null ? void 0 : _a.call(window);
@@ -213,21 +256,64 @@ function getCurrentRange(element) {
 }
 __name(getCurrentRange, "getCurrentRange");
 const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
-  const { addonBefore, className, converters, disabled, metaTree, onChange, placeholder, style } = props;
+  var _a;
+  const { addonBefore, className, converters, disabled, metaTree, onChange, placeholder, readOnly, style } = props;
   const { token } = import_antd.theme.useToken();
   const ctx = (0, import_FlowContextProvider.useFlowContext)();
   const { resolvedMetaTree } = (0, import_useResolvedMetaTree.useResolvedMetaTree)(metaTree);
+  const formItemStatus = (_a = (0, import_react.useContext)(import_context.FormItemInputContext)) == null ? void 0 : _a.status;
+  const effectiveStatus = props.status ?? formItemStatus;
   const inputRef = (0, import_react.useRef)(null);
   const [isComposing, setIsComposing] = (0, import_react.useState)(false);
   const [changed, setChanged] = (0, import_react.useState)(false);
   const [range, setRange] = (0, import_react.useState)([-1, 0, -1, 0]);
   const value = typeof props.value === "string" ? props.value : props.value == null ? "" : String(props.value);
   const variableRegExp = (converters == null ? void 0 : converters.variableRegExp) ?? DEFAULT_VARIABLE_REGEXP;
+  const parseValueToPath = (converters == null ? void 0 : converters.parseValueToPath) ?? import_utils.parseValueToPath;
+  const [loadedFlag, setLoadedFlag] = (0, import_react.useState)(0);
+  (0, import_react.useEffect)(() => {
+    if (!value || !Array.isArray(resolvedMetaTree) || !resolvedMetaTree.length) {
+      return;
+    }
+    const paths = collectReferencePaths(value, variableRegExp, parseValueToPath);
+    if (!paths.length) {
+      return;
+    }
+    let cancelled = false;
+    const run = /* @__PURE__ */ __name(async () => {
+      let didLoad = false;
+      for (const path of paths) {
+        const loaded = await preloadReferencePath(path, resolvedMetaTree);
+        if (cancelled) return;
+        didLoad = didLoad || loaded;
+      }
+      if (didLoad && !cancelled) {
+        setLoadedFlag((prev) => prev + 1);
+      }
+    }, "run");
+    run();
+    return () => {
+      cancelled = true;
+    };
+  }, [value, resolvedMetaTree, variableRegExp, parseValueToPath]);
   const labelMap = (0, import_react.useMemo)(
     () => buildLabelMap(resolvedMetaTree, 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]
   );
-  const [html, setHtml] = (0, import_react.useState)(() => renderHTML(value, labelMap, variableRegExp));
+  const resolveLabel = (0, import_react.useCallback)(
+    (matched) => {
+      const mapped = labelMap.get(normalizeVariableKey(matched));
+      if (mapped) return mapped;
+      const path = parseValueToPath(matched);
+      return resolveTitlesByPath(resolvedMetaTree, 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] = (0, import_react.useState)(() => renderHTML(value, variableRegExp, resolveLabel));
   const emitChange = (0, import_react.useCallback)(
     (target) => {
       onChange == null ? void 0 : onChange(getDomValue(target).trim());
@@ -235,20 +321,20 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
     [onChange]
   );
   (0, import_react.useEffect)(() => {
-    setHtml(renderHTML(value, labelMap, variableRegExp));
+    setHtml(renderHTML(value, variableRegExp, resolveLabel));
     if (!changed) {
       setRange([-1, 0, -1, 0]);
     }
-  }, [value, labelMap]);
+  }, [value, resolveLabel]);
   (0, import_react.useEffect)(() => {
-    var _a;
+    var _a2;
     const element = inputRef.current;
     if (!element) return;
     if (document.activeElement !== element) return;
     const nextRange = new Range();
     if (changed) {
       if (range.join() === "-1,0,-1,0") return;
-      const selection = (_a = window.getSelection) == null ? void 0 : _a.call(window);
+      const selection = (_a2 = window.getSelection) == null ? void 0 : _a2.call(window);
       if (!selection) return;
       try {
         const children = Array.from(element.childNodes);
@@ -304,12 +390,13 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
   );
   const handleInput = (0, import_react.useCallback)(
     ({ currentTarget }) => {
+      if (readOnly) return;
       if (isComposing) return;
       setChanged(true);
       setRange(getCurrentRange(currentTarget));
       emitChange(currentTarget);
     },
-    [emitChange, isComposing]
+    [emitChange, isComposing, readOnly]
   );
   const handleBlur = (0, import_react.useCallback)(({ currentTarget }) => {
     setRange(getCurrentRange(currentTarget));
@@ -322,6 +409,7 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
   const handlePaste = (0, import_react.useCallback)(
     (event) => {
       event.preventDefault();
+      if (readOnly) return;
       const text = event.clipboardData.getData("text/plain").replace(/\n/g, " ");
       if (!text) return;
       setChanged(true);
@@ -329,17 +417,18 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
       setRange(getCurrentRange(event.currentTarget));
       emitChange(event.currentTarget);
     },
-    [emitChange]
+    [emitChange, readOnly]
   );
   const handleCompositionStart = (0, import_react.useCallback)(() => setIsComposing(true), []);
   const handleCompositionEnd = (0, import_react.useCallback)(
     ({ currentTarget }) => {
       setIsComposing(false);
+      if (readOnly) return;
       setChanged(true);
       setRange(getCurrentRange(currentTarget));
       emitChange(currentTarget);
     },
-    [emitChange]
+    [emitChange, readOnly]
   );
   const wrapperClassName = (0, import_react.useMemo)(
     () => import_css.css`
@@ -457,6 +546,42 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
           border-color: ${token.colorBorder};
         }
       }
+
+      &.is-readonly {
+        cursor: default;
+
+        &:hover {
+          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]);
   return /* @__PURE__ */ import_react.default.createElement(import_react.default.Fragment, null, /* @__PURE__ */ import_react.default.createElement(import_antd.Space.Compact, { className: (0, import_css.cx)("nb-variable-hybrid-input", wrapperClassName, className), style }, addonBefore != null && /* @__PURE__ */ import_react.default.createElement("span", { className: addonClassName }, addonBefore), /* @__PURE__ */ import_react.default.createElement(
@@ -466,9 +591,13 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
       role: "textbox",
       "aria-label": "textbox",
       className: (0, import_css.cx)(editorClassName, {
-        "is-disabled": disabled
+        "is-disabled": disabled,
+        "is-readonly": readOnly,
+        "is-error": effectiveStatus === "error",
+        "is-warning": effectiveStatus === "warning"
       }),
-      contentEditable: !disabled,
+      contentEditable: !disabled && !readOnly,
+      "aria-readonly": readOnly,
       "data-placeholder": placeholder,
       onInput: handleInput,
       onBlur: handleBlur,
@@ -483,10 +612,10 @@ const VariableHybridInputComponent = /* @__PURE__ */ __name((props) => {
     {
       metaTree,
       disabled,
-      parseValueToPath: (converters == null ? void 0 : converters.parseValueToPath) ?? import_utils.parseValueToPath,
+      parseValueToPath,
       formatPathToValue: (item) => {
-        var _a;
-        return ((_a = converters == null ? void 0 : converters.formatPathToValue) == null ? void 0 : _a.call(converters, item)) || (0, import_utils.formatPathToValue)(item);
+        var _a2;
+        return ((_a2 = converters == null ? void 0 : converters.formatPathToValue) == null ? void 0 : _a2.call(converters, item)) || (0, import_utils.formatPathToValue)(item);
       },
       onChange: handleSelectorChange
     }

package/lib/components/variables/VariableInput.js

@@ -132,16 +132,18 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
     },
     [onChange]
   );
+  const resolvedPath = (0, import_react.useMemo)(() => {
+    return resolvePathFromValue == null ? void 0 : resolvePathFromValue(innerValue);
+  }, [innerValue, resolvePathFromValue]);
   const resolvedMetaTreeNode = (0, import_react.useMemo)(() => {
     if (currentMetaTreeNode) return currentMetaTreeNode;
     if (Array.isArray(resolvedMetaTree)) {
-      const path = resolvePathFromValue == null ? void 0 : resolvePathFromValue(innerValue);
-      if (path) {
-        return findMetaTreeNodeByPath(resolvedMetaTree, path);
+      if (resolvedPath) {
+        return findMetaTreeNodeByPath(resolvedMetaTree, resolvedPath);
       }
     }
     return null;
-  }, [currentMetaTreeNode, innerValue, resolvedMetaTree, resolvePathFromValue]);
+  }, [currentMetaTreeNode, resolvedMetaTree, resolvedPath]);
   (0, import_react.useEffect)(() => {
     const restoreFromValue = /* @__PURE__ */ __name(async () => {
       if (!Array.isArray(resolvedMetaTree) || value == null) return;
@@ -188,13 +190,17 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
       }
     }, "restoreFromValue");
     restoreFromValue();
-  }, [resolvedMetaTree, innerValue, resolvePathFromValue, currentMetaTreeNode]);
+  }, [resolvedMetaTree, innerValue, resolvePathFromValue, currentMetaTreeNode, value]);
   const ValueComponent = (0, import_react.useMemo)(() => {
     const Component = renderInputComponent == null ? void 0 : renderInputComponent(resolvedMetaTreeNode);
     const CustomComponent = resolvedMetaTreeNode == null ? void 0 : resolvedMetaTreeNode.render;
-    const finalComponent = (0, import_utils.isVariableValue)(innerValue) ? import_VariableTag.VariableTag : Component || CustomComponent || import_antd.Input;
+    const shouldRenderVariableTag = (0, import_utils.isVariableValue)(innerValue) || Array.isArray(resolvedPath) && resolvedPath.length > 0 && !Component && !CustomComponent;
+    const finalComponent = shouldRenderVariableTag ? import_VariableTag.VariableTag : Component || CustomComponent || import_antd.Input;
     return finalComponent;
-  }, [renderInputComponent, resolvedMetaTreeNode, innerValue]);
+  }, [renderInputComponent, resolvedMetaTreeNode, innerValue, resolvedPath]);
+  const isVariableActive = (0, import_react.useMemo)(() => {
+    return (0, import_utils.isVariableValue)(innerValue) || Array.isArray(resolvedPath) && resolvedPath.length > 0 && !(renderInputComponent == null ? void 0 : renderInputComponent(resolvedMetaTreeNode)) && !(resolvedMetaTreeNode == null ? void 0 : resolvedMetaTreeNode.render);
+  }, [innerValue, renderInputComponent, resolvedMetaTreeNode, resolvedPath]);
   (0, import_react.useEffect)(() => {
     if (!resolvedMetaTreeNode) return;
     if (!Array.isArray(resolvedMetaTree) || innerValue == null) return;
@@ -278,8 +284,11 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
       return {
         ...baseProps,
         onClear: handleClear,
+        disabled,
+        allowCustomTagInput: false,
         metaTreeNode: resolvedMetaTreeNode,
         metaTree,
+        resolvedPath,
         style: stableProps.style
       };
     }
@@ -300,6 +309,7 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
     disabled,
     handleClear,
     resolvedMetaTreeNode,
+    resolvedPath,
     metaTree,
     ValueComponent,
     stableProps
@@ -325,6 +335,8 @@ const VariableInputComponent = /* @__PURE__ */ __name(({
     {
       metaTree: resolvedMetaTree,
       value: innerValue,
+      active: isVariableActive,
+      disabled,
       onChange: handleVariableSelect,
       parseValueToPath: resolvePathFromValue,
       formatPathToValue: resolveValueFromPath,

package/lib/components/variables/VariableTag.js

@@ -47,35 +47,37 @@ var import_utils = require("./utils");
 var import_useResolvedMetaTree = require("./useResolvedMetaTree");
 var import_ahooks = require("ahooks");
 var import_FlowContextProvider = require("../../FlowContextProvider");
+const VARIABLE_PARSING_FAILED_TEXT = "Variable parsing failed";
 const VariableTagComponent = /* @__PURE__ */ __name(({
   value,
   onClear,
+  disabled = false,
+  allowCustomTagInput = true,
   className,
   style,
   metaTreeNode,
-  metaTree
+  metaTree,
+  resolvedPath
 }) => {
   const { resolvedMetaTree } = (0, import_useResolvedMetaTree.useResolvedMetaTree)(metaTree);
   const ctx = (0, import_FlowContextProvider.useFlowContext)();
-  const { data: displayedValue } = (0, import_ahooks.useRequest)(
+  const { data: displayState } = (0, import_ahooks.useRequest)(
     async () => {
       const resolveLabelFromPath = /* @__PURE__ */ __name(async (rawPath2) => {
-        if (!rawPath2) return null;
-        if (!Array.isArray(rawPath2)) return null;
-        if (!Array.isArray(resolvedMetaTree)) return null;
+        if (!rawPath2) return { label: null, resolved: false, attempted: false };
+        if (!Array.isArray(rawPath2)) return { label: null, resolved: false, attempted: false };
+        if (!Array.isArray(resolvedMetaTree)) return { label: null, resolved: false, attempted: false };
         const topNames = new Set((resolvedMetaTree || []).map((n) => String(n == null ? void 0 : n.name)));
         const path = !topNames.has(String(rawPath2[0])) ? rawPath2.slice(1) : rawPath2;
-        if (!path.length) return "";
+        if (!path.length) return { label: "", resolved: true, attempted: true };
         let nodes = resolvedMetaTree;
         const titleChain = [];
-        let matchedCount = 0;
         for (let i = 0; i < path.length; i++) {
-          if (!nodes) break;
+          if (!nodes) return { label: null, resolved: false, attempted: true };
           const seg = String(path[i]);
           const node = nodes.find((n) => String(n == null ? void 0 : n.name) === seg);
-          if (!node) break;
+          if (!node) return { label: null, resolved: false, attempted: true };
           titleChain.push(String(node.title ?? node.name ?? seg));
-          matchedCount = i + 1;
           if (i < path.length - 1) {
             if (Array.isArray(node.children)) {
               nodes = node.children;
@@ -92,29 +94,37 @@ const VariableTagComponent = /* @__PURE__ */ __name(({
             }
           }
         }
-        if (matchedCount === 0) return null;
-        let label2 = titleChain.map(ctx.t).join("/");
-        if (matchedCount < path.length) {
-          const tail = path.slice(matchedCount).join("/");
-          label2 = tail ? `${label2}/${tail}` : label2;
-        }
-        return label2;
+        return { label: titleChain.map(ctx.t).join("/"), resolved: true, attempted: true };
       }, "resolveLabelFromPath");
       if (metaTreeNode == null ? void 0 : metaTreeNode.parentTitles) {
-        return [...metaTreeNode.parentTitles, metaTreeNode.title].map(ctx.t).join("/");
+        return {
+          text: [...metaTreeNode.parentTitles, metaTreeNode.title].map(ctx.t).join("/"),
+          invalid: false
+        };
       }
       if (metaTreeNode) {
-        const rawPath2 = (0, import_utils.parseValueToPath)(value) || metaTreeNode.paths;
-        const label2 = await resolveLabelFromPath(rawPath2);
-        return label2 ?? ctx.t(metaTreeNode.title) ?? "";
+        const rawPath2 = resolvedPath || (0, import_utils.parseValueToPath)(value) || metaTreeNode.paths;
+        const result2 = await resolveLabelFromPath(rawPath2);
+        if (result2.resolved && result2.label != null) {
+          return { text: result2.label, invalid: false };
+        }
+        if (result2.attempted) {
+          return { text: VARIABLE_PARSING_FAILED_TEXT, invalid: true, rawValue: String(value ?? "") };
+        }
+        return { text: ctx.t(metaTreeNode.title) ?? "", invalid: false };
+      }
+      if (!value) return { text: String(value), invalid: false };
+      const rawPath = resolvedPath || (0, import_utils.parseValueToPath)(value);
+      const result = await resolveLabelFromPath(rawPath);
+      if (result.resolved && result.label != null) {
+        return { text: result.label, invalid: false };
+      }
+      if (result.attempted) {
+        return { text: VARIABLE_PARSING_FAILED_TEXT, invalid: true, rawValue: String(value ?? "") };
       }
-      if (!value) return String(value);
-      const rawPath = (0, import_utils.parseValueToPath)(value);
-      const label = await resolveLabelFromPath(rawPath);
-      if (label != null) return label;
-      return Array.isArray(rawPath) ? rawPath.join("/") : String(value);
+      return { text: Array.isArray(rawPath) ? rawPath.join("/") : String(value), invalid: false };
     },
-    { refreshDeps: [resolvedMetaTree, value, metaTreeNode] }
+    { refreshDeps: [resolvedMetaTree, resolvedPath, value, metaTreeNode] }
   );
   const { token } = import_antd.theme.useToken();
   const shrinkableOverflowItem = import_css.css`
@@ -129,12 +139,12 @@ const VariableTagComponent = /* @__PURE__ */ __name(({
     }
   `;
   const customTagRender = /* @__PURE__ */ __name((props) => {
-    const { label } = props;
-    const fullText = typeof label === "string" ? label : String(label);
-    return /* @__PURE__ */ import_react.default.createElement(import_antd.Tooltip, { title: fullText, placement: "top", getPopupContainer: () => document.body }, /* @__PURE__ */ import_react.default.createElement(
+    const fullText = (displayState == null ? void 0 : displayState.text) || (typeof props.label === "string" ? props.label : String(props.label));
+    const tooltipText = (displayState == null ? void 0 : displayState.invalid) ? displayState.rawValue || fullText : fullText;
+    return /* @__PURE__ */ import_react.default.createElement(import_antd.Tooltip, { title: tooltipText, placement: "top", getPopupContainer: () => document.body }, /* @__PURE__ */ import_react.default.createElement(
       import_antd.Tag,
       {
-        color: "blue",
+        color: (displayState == null ? void 0 : displayState.invalid) ? "error" : "blue",
         style: {
           margin: `0 ${token.marginXXS || token.marginXS}px`,
           borderRadius: token.borderRadiusSM,
@@ -175,12 +185,14 @@ const VariableTagComponent = /* @__PURE__ */ __name(({
         flex: "1 1 auto",
         ...style
       },
-      value: displayedValue ? [displayedValue] : [],
-      mode: "tags",
+      value: (displayState == null ? void 0 : displayState.text) ? [displayState.text] : [],
+      mode: allowCustomTagInput ? "tags" : "multiple",
       open: false,
-      allowClear: !!onClear,
-      onClear,
-      disabled: !onClear,
+      showSearch: allowCustomTagInput,
+      searchValue: allowCustomTagInput ? void 0 : "",
+      allowClear: !disabled && !!onClear,
+      onClear: disabled ? void 0 : onClear,
+      disabled: disabled || !onClear,
       variant: "outlined",
       suffixIcon: null,
       tagRender: customTagRender,

package/lib/components/variables/types.d.ts

@@ -13,12 +13,30 @@ export interface FlowContextSelectorProps extends Omit<CascaderProps<ContextSele
     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 {
     label: React.ReactNode;
@@ -68,7 +86,10 @@ export interface VariableInputProps {
 }
 export interface VariableTagProps {
     value?: string;
+    resolvedPath?: Array<string | number>;
     onClear?: () => void;
+    disabled?: boolean;
+    allowCustomTagInput?: boolean;
     className?: string;
     style?: React.CSSProperties;
     metaTreeNode?: MetaTreeNode | null;

package/lib/flowContext.d.ts

@@ -24,9 +24,13 @@ import { FlowResource, FlowSQLRepository } from './resources';
 import type { ActionDefinition, EventDefinition, ResourceType } from './types';
 import { JSONValue } from './utils/params-resolvers';
 import type { RecordRef } from './utils/serverContextParams';
+import { PREPARE_CONTEXT_RESOURCE_ACTION_PARAMS } from './utils/dirtyAwareApiClient';
 import { FlowView, FlowViewer } from './views/FlowView';
 import { type RunJSVersion } from './runjs-context/registry';
 type Getter<T = any> = (ctx: FlowContext) => T | Promise<T>;
+export type ResolveJsonTemplateOptions = {
+    contractModelUid?: string | number | null;
+};
 export type FlowContextDocRef = string | {
     url: string;
     title?: string;
@@ -77,6 +81,7 @@ export interface MetaTreeNode {
     hidden?: boolean | (() => boolean);
     disabled?: boolean | (() => boolean);
     disabledReason?: string | (() => string | undefined);
+    selectable?: boolean;
     children?: MetaTreeNode[] | (() => Promise<MetaTreeNode[]>);
 }
 export interface PropertyMeta {
@@ -343,7 +348,7 @@ declare class BaseFlowEngineContext extends FlowContext {
      * @deprecated use `resolveJsonTemplate` instead
      */
     renderJson: (template: JSONValue) => Promise<any>;
-    resolveJsonTemplate: (template: JSONValue) => Promise<any>;
+    resolveJsonTemplate: (template: JSONValue, options?: ResolveJsonTemplateOptions) => Promise<any>;
     getVar: (path: string) => Promise<any>;
     request: (options: RequestOptions) => Promise<any>;
     runjs: (code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<any>;
@@ -469,6 +474,12 @@ export declare function createRunJSDeprecationProxy(ctx: any, options?: {
     doc?: RunJSDocMeta;
 }): any;
 export declare class FlowRunJSContext extends FlowContext {
+    [PREPARE_CONTEXT_RESOURCE_ACTION_PARAMS](action: {
+        actionName: string;
+        dataSourceKey?: string;
+        resourceName: string;
+        resourceOf?: unknown;
+    }, params: Record<string, unknown> | undefined): Record<string, unknown>;
     constructor(delegate: FlowContext);
     exit(): void;
     exitAll(): void;