@nocobase/client-v2 2.1.0-beta.41 → 2.1.0-beta.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/client-v2",
-  "version": "2.1.0-beta.41",
+  "version": "2.1.0-beta.43",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.mjs",
@@ -27,11 +27,11 @@
     "@formily/antd-v5": "1.2.3",
     "@formily/react": "^2.2.27",
     "@formily/shared": "^2.2.27",
-    "@nocobase/evaluators": "2.1.0-beta.41",
-    "@nocobase/flow-engine": "2.1.0-beta.41",
-    "@nocobase/sdk": "2.1.0-beta.41",
-    "@nocobase/shared": "2.1.0-beta.41",
-    "@nocobase/utils": "2.1.0-beta.41",
+    "@nocobase/evaluators": "2.1.0-beta.43",
+    "@nocobase/flow-engine": "2.1.0-beta.43",
+    "@nocobase/sdk": "2.1.0-beta.43",
+    "@nocobase/shared": "2.1.0-beta.43",
+    "@nocobase/utils": "2.1.0-beta.43",
     "ahooks": "^3.7.2",
     "antd": "5.24.2",
     "antd-style": "3.7.1",
@@ -45,5 +45,5 @@
     "react-i18next": "^11.15.1",
     "react-router-dom": "^6.30.1"
   },
-  "gitHead": "ea3f966811146edb13c9e8016bf4cdc81597a003"
+  "gitHead": "6d7750e2373bf2451d246de88cc1f62491685e18"
 }

package/src/components/README.md

@@ -169,6 +169,54 @@ Key props:
 
 Under the hood `VariableInput` wraps `VariableHybridInput` (inline pills), `VariableTextArea` wraps `TextAreaWithContextSelector` (textarea + variable button). Both share the same MetaTree.
 
+#### TypedVariableInput
+
+Typed-constant + variable hybrid input. Ported from v1 `Variable.Input`'s `useTypedConstant` pattern: an italic `x` button on the right triggers a Cascader switcher `[Null | Constant<types> | Variable<…namespaces>]`; the left side renders the matching editor (`Input` / `InputNumber` / `Select(True/False)` / `DatePicker`) or a pill carrying the variable path.
+
+Reach for this when a field **accepts both** a typed literal **and** a variable reference. The canonical example is `plugin-notification-email`'s SMTP `port` and `secure` fields: users can type a numeric port / boolean flag, or pass `{{ $env.SMTP_PORT }}` to read from environment variables.
+
+```tsx
+import { TypedVariableInput } from '@nocobase/client-v2';
+
+// Port — numeric constant + $env variable
+<Form.Item name={['options', 'port']} label={t('Port')} initialValue={465}>
+  <TypedVariableInput
+    types={[['number', { min: 1, max: 65535, step: 1 }]]}
+    namespaces={['$env']}
+  />
+</Form.Item>
+
+// Secure mode — boolean constant + $env variable
+<Form.Item name={['options', 'secure']} label={t('Secure')} initialValue={true}>
+  <TypedVariableInput types={['boolean']} namespaces={['$env']} />
+</Form.Item>
+```
+
+Key props:
+
+- `types`: allowed constant types. Shape mirrors v1 `useTypedConstant` — pass bare type names (`['number', 'boolean']`) or `[type, editorProps]` tuples (`[['number', { min, max, step }]]`) to forward props to the underlying antd editor. Defaults to `['string', 'number', 'boolean', 'date']`. **Even when only one type is allowed, the `Constant` entry still expands into a typed submenu** (Number / Boolean / Date / String) — matches v1 so users can see what type the constant is
+- `namespaces`: restrict the variable picker to specific top-level namespaces (e.g. `['$env']`). Omit to expose every namespace registered on `flowEngine.context`
+- `extraNodes`: static leaves appended after the namespace-filtered nodes
+- `nullable`: whether to expose the `Null` switcher entry. Default `true`. Combined with `Form.Item.rules={[{ required: true }]}`, the user can explicitly clear the field but submission is still blocked by validation — mirrors v1's "Null + required" pairing
+- `delimiters`: variable-token delimiters, default `['{{', '}}']` — same as `VariableInput`
+- `value` / `onChange` / `placeholder` / `disabled` / `style` / `className`: standard controlled-input props
+
+Value shape:
+
+- Constant: stored as the native type (`number` / `boolean` / `Date` / `string`)
+- Variable: a string like `'{{ $env.SMTP_PORT }}'`
+- Null: `null`
+
+When **not** to use it:
+
+- **Pure literal fields** (users will never pass a variable) → use the antd primitive directly (`InputNumber` / `Select` / `DatePicker` / `Input`) and skip the Cascader column overhead
+- **Pure variable fields** (users will never pass a literal) → use `EnvVariableInput` (`$env`-only, with optional password masking) or `VariableInput` (general-purpose)
+
+Capabilities skipped (present in v1, not yet ported to v2):
+
+- `object` constant type (JSON editor) — v2 has no inline "JSON editor + Cascader switcher" yet; add when there's a concrete caller
+- Async `loadChildren` cascading — most MetaTree namespaces are already eagerly resolved by `useFilteredMetaTree`, so this hasn't been needed
+
 #### FileSizeInput
 
 A byte-valued size input paired with a unit selector (Byte / KB / MB / GB). The persisted value is always in bytes; the displayed number is derived from the picked unit.

package/src/components/README.zh-CN.md

@@ -169,6 +169,54 @@ import { VariableInput, VariableTextArea } from '@nocobase/client-v2';
 
 底层共用 `VariableHybridInput`（`VariableInput`）和 `TextAreaWithContextSelector`（`VariableTextArea`），用同一套 MetaTree 数据。
 
+#### TypedVariableInput
+
+类型化常量 + 变量混合输入器。移植 v1 `Variable.Input` 的 `useTypedConstant` 形态：右侧斜体 `x` 按钮触发 Cascader 切换 `[空值 | 常量<types> | 变量和密钥<…namespaces>]`，左侧根据当前模式渲染对应编辑器（`Input` / `InputNumber` / `Select(True/False)` / `DatePicker`）或一颗带变量路径的 pill。
+
+用于字段**同时接受**字面量**和**变量引用的场景。最典型的就是 `plugin-notification-email` 的 SMTP `port` 和 `secure`：可以填具体数字 / 布尔值，也可以填 `{{ $env.SMTP_PORT }}` 走环境变量。
+
+```tsx
+import { TypedVariableInput } from '@nocobase/client-v2';
+
+// 端口：数字常量 + $env 变量
+<Form.Item name={['options', 'port']} label={t('端口')} initialValue={465}>
+  <TypedVariableInput
+    types={[['number', { min: 1, max: 65535, step: 1 }]]}
+    namespaces={['$env']}
+  />
+</Form.Item>
+
+// 安全模式：布尔常量 + $env 变量
+<Form.Item name={['options', 'secure']} label={t('安全模式')} initialValue={true}>
+  <TypedVariableInput types={['boolean']} namespaces={['$env']} />
+</Form.Item>
+```
+
+主要属性：
+
+- `types`：允许的常量类型。形态对齐 v1 `useTypedConstant`，可以传裸类型名 `['number', 'boolean']`，也可以传 `[type, editorProps]` 元组 `[['number', { min, max, step }]]` 把 props 透传给底层 antd 编辑器。默认 `['string', 'number', 'boolean', 'date']`。**即使只允许一种类型，「常量」入口也会展开二级菜单**（数字 / 逻辑值 / 日期 / 字符串）——跟 v1 一致，让用户能直观看到当前常量是什么类型
+- `namespaces`：限定变量 picker 可选的顶层命名空间（如 `['$env']`）。不传就用 `flowEngine.context` 里所有已注册命名空间
+- `extraNodes`：在命名空间过滤后追加几条静态变量节点
+- `nullable`：是否暴露「空值」入口，默认 `true`。配合 `Form.Item.rules={[{ required: true }]}` 可以让用户能手动清空、但提交时会被校验拦截——跟 v1 的「空值 + required」组合一致
+- `delimiters`：变量 token 开闭分隔符，默认 `['{{', '}}']`，跟 `VariableInput` 一致
+- `value` / `onChange` / `placeholder` / `disabled` / `style` / `className`：标准受控字段属性
+
+值的形态：
+
+- 常量：原生类型直接存（`number` / `boolean` / `Date` / `string`）
+- 变量：字符串 `'{{ $env.SMTP_PORT }}'`
+- 空值：`null`
+
+什么时候**不该用**：
+
+- **纯字面量字段**（用户不会想填变量）→ 直接用 antd `InputNumber` / `Select` / `DatePicker` / `Input`，省掉 Cascader 那一格的视觉开销
+- **纯变量字段**（用户不会想填字面量）→ 用 `EnvVariableInput`（`$env` 专用，带 password mask）或 `VariableInput`（更通用）
+
+跳过的能力（v1 有但 v2 还没补）：
+
+- `object` 类型（JSON 编辑器）——v2 还没对应的「内联 JSON 编辑器 + Cascader 切换」组件，等真有需求再补
+- 异步 `loadChildren` 分支——大多数命名空间的 MetaTree 已经由 `useFilteredMetaTree` 提前展平，没遇到刚需
+
 #### FileSizeInput
 
 文件大小输入器。值统一存字节数，UI 上配一个单位选择器（Byte / KB / MB / GB）。

package/src/components/form/TypedVariableInput.tsx

@@ -0,0 +1,441 @@
+/**
+ * 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 { CloseCircleFilled } from '@ant-design/icons';
+import {
+  buildContextSelectorItems,
+  useFlowContext,
+  type ContextSelectorItem,
+  type MetaTreeNode,
+} from '@nocobase/flow-engine';
+import { Button, Cascader, DatePicker, Input, InputNumber, Select, Space, Tag, theme, type CascaderProps } from 'antd';
+import dayjs from 'dayjs';
+import React, { useCallback, useMemo } from 'react';
+import {
+  makeFormatVariablePath,
+  makeParseVariablePath,
+  useFilteredMetaTree,
+  type VariableDelimiters,
+} from './VariableInput';
+
+/**
+ * Constant types this input can edit. Subset of v1 `Variable.Input`
+ * `useTypedConstant` — drops `'object'` (no v2 JSON editor yet) and `'null'`
+ * (handled by the dedicated `nullable` prop).
+ */
+export type TypedConstantType = 'string' | 'number' | 'boolean' | 'date';
+
+/**
+ * One allowed constant type. Either a bare type name (`'number'`) or a
+ * `[type, editorProps]` pair (`['number', { min: 1, max: 65535 }]`) where
+ * `editorProps` is forwarded to the antd editor for that type — same
+ * shape as v1 `useTypedConstant`.
+ */
+export type TypedConstantSpec = TypedConstantType | [TypedConstantType, Record<string, unknown>];
+
+export interface TypedVariableInputProps {
+  /**
+   * Stored value. A `{{ ... }}` string is treated as a variable reference;
+   * anything else is a constant of the inferred type.
+   */
+  value?: unknown;
+  onChange?: (next: unknown) => void;
+  /**
+   * Allowed constant types. The `Constant` switcher entry always exposes a
+   * typed submenu (matching v1 `Variable.Input`) so users can see what type
+   * the constant is, even when only one type is permitted. Default: all four
+   * supported types.
+   */
+  types?: TypedConstantSpec[];
+  /**
+   * Restrict the variable picker to specific top-level meta-tree namespaces
+   * (e.g. `['$env']`). When omitted, every registered top-level property is
+   * exposed — matching `VariableInput`'s default behaviour.
+   */
+  namespaces?: string[];
+  /** Additional leaves appended to the picker after the namespace-filtered nodes. */
+  extraNodes?: MetaTreeNode[];
+  /**
+   * When true (default), the switcher exposes a `Null` option that resets the
+   * value to `null`. When false, the value is constrained to one of the
+   * allowed types or a variable reference.
+   */
+  nullable?: boolean;
+  /** Variable-token delimiters. Default `['{{', '}}']` — see `VariableInput`. */
+  delimiters?: VariableDelimiters;
+  disabled?: boolean;
+  placeholder?: string;
+  style?: React.CSSProperties;
+  className?: string;
+}
+
+const DEFAULT_TYPES: TypedConstantSpec[] = ['string', 'number', 'boolean', 'date'];
+
+const TYPE_LABEL_KEYS: Record<TypedConstantType, string> = {
+  string: 'String',
+  number: 'Number',
+  boolean: 'Boolean',
+  date: 'Date',
+};
+
+type NormalizedType = { type: TypedConstantType; props: Record<string, unknown> };
+
+function normalizeTypes(types: TypedConstantSpec[]): NormalizedType[] {
+  return types.map((spec) =>
+    Array.isArray(spec) ? { type: spec[0], props: spec[1] ?? {} } : { type: spec, props: {} },
+  );
+}
+
+function defaultValueFor(type: TypedConstantType): unknown {
+  switch (type) {
+    case 'string':
+      return '';
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    case 'date': {
+      const now = new Date();
+      return new Date(now.getFullYear(), now.getMonth(), now.getDate(), 0, 0, 0);
+    }
+    default:
+      return null;
+  }
+}
+
+type DetectedMode = { mode: 'null' | 'variable' | TypedConstantType; variablePath?: string[] };
+
+function detectMode(value: unknown, parseVariablePath: (v?: string) => string[] | undefined): DetectedMode {
+  if (value == null) return { mode: 'null' };
+  if (typeof value === 'string') {
+    const path = parseVariablePath(value);
+    if (path && path.length > 0) return { mode: 'variable', variablePath: path };
+    return { mode: 'string' };
+  }
+  if (typeof value === 'number') return { mode: 'number' };
+  if (typeof value === 'boolean') return { mode: 'boolean' };
+  if (value instanceof Date) return { mode: 'date' };
+  return { mode: 'string' };
+}
+
+const NULL_KEY = '__null__';
+const CONST_KEY = '__const__';
+
+interface SwitcherOption {
+  value: string;
+  label: React.ReactNode;
+  isLeaf?: boolean;
+  children?: SwitcherOption[];
+  meta?: MetaTreeNode;
+  paths?: string[];
+  disabled?: boolean;
+}
+
+function fromContextItem(item: ContextSelectorItem): SwitcherOption {
+  return {
+    value: item.value,
+    label: item.label,
+    isLeaf: item.isLeaf,
+    meta: item.meta,
+    paths: item.paths,
+    disabled: item.disabled,
+    children: item.children?.map(fromContextItem),
+  };
+}
+
+function resolveVariableLabels(path: string[], metaTree: MetaTreeNode[]): string[] {
+  const labels: string[] = [];
+  let nodes: MetaTreeNode[] | undefined = metaTree;
+  for (const segment of path) {
+    if (!nodes) break;
+    const matched: MetaTreeNode | undefined = nodes.find((node) => node.name === segment);
+    if (!matched) {
+      labels.push(segment);
+      nodes = undefined;
+      continue;
+    }
+    labels.push(typeof matched.title === 'string' && matched.title ? matched.title : matched.name);
+    nodes = Array.isArray(matched.children) ? matched.children : undefined;
+  }
+  return labels;
+}
+
+function renderConstantEditor(
+  type: TypedConstantType,
+  value: unknown,
+  onChange: ((next: unknown) => void) | undefined,
+  options: {
+    typedProps: Record<string, unknown>;
+    disabled?: boolean;
+    placeholder?: string;
+    t: (text: string) => string;
+  },
+): React.ReactNode {
+  const { typedProps, disabled, placeholder, t } = options;
+  switch (type) {
+    case 'string':
+      return (
+        <Input
+          value={typeof value === 'string' ? value : ''}
+          onChange={(ev) => onChange?.(ev.target.value)}
+          disabled={disabled}
+          placeholder={placeholder}
+          {...typedProps}
+        />
+      );
+    case 'number':
+      return (
+        <InputNumber
+          value={typeof value === 'number' ? value : null}
+          onChange={(next) => onChange?.(next)}
+          disabled={disabled}
+          placeholder={placeholder}
+          style={{ width: '100%' }}
+          {...typedProps}
+        />
+      );
+    case 'boolean':
+      return (
+        <Select
+          value={typeof value === 'boolean' ? value : undefined}
+          onChange={(next) => onChange?.(next)}
+          disabled={disabled}
+          placeholder={placeholder ?? t('Select')}
+          options={[
+            { value: true, label: t('True') },
+            { value: false, label: t('False') },
+          ]}
+          style={{ width: '100%' }}
+          {...typedProps}
+        />
+      );
+    case 'date': {
+      const parsed = value instanceof Date ? dayjs(value) : null;
+      return (
+        <DatePicker
+          value={parsed}
+          onChange={(next) => onChange?.(next ? next.toDate() : null)}
+          disabled={disabled}
+          showTime
+          allowClear={false}
+          style={{ width: '100%' }}
+          {...typedProps}
+        />
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * Constant-or-variable input. Port of v1 `Variable.Input` typed-constant
+ * Cascader pattern (the `[Null | Constant<type> | Variable<…namespaces>]`
+ * switcher). Use this when a field can accept either a typed literal
+ * (number, boolean, date, string) or a variable reference like
+ * `{{ $env.SMTP_PORT }}` — see `plugin-notification-email`'s port / secure
+ * fields for the canonical example.
+ *
+ * Pure literal fields should keep using the antd primitive
+ * (`InputNumber`, `Select`, `DatePicker`). Pure variable fields should keep
+ * using `EnvVariableInput` / `VariableInput`. This component carries the
+ * Cascader switcher overhead, so reach for it only when the field
+ * genuinely accepts both shapes.
+ */
+export function TypedVariableInput(props: TypedVariableInputProps) {
+  const {
+    value,
+    onChange,
+    types = DEFAULT_TYPES,
+    namespaces,
+    extraNodes,
+    nullable = true,
+    delimiters,
+    disabled,
+    placeholder,
+    style,
+    className,
+  } = props;
+  const ctx = useFlowContext();
+  const t = useCallback((text: string): string => (typeof ctx?.t === 'function' ? ctx.t(text) : text), [ctx]);
+  const { token } = theme.useToken();
+
+  const metaTree = useFilteredMetaTree({ namespaces, extraNodes });
+
+  const parseVariablePath = useMemo(() => makeParseVariablePath(delimiters), [delimiters]);
+  const formatVariablePath = useMemo(() => makeFormatVariablePath(delimiters), [delimiters]);
+
+  const normalizedTypes = useMemo(() => normalizeTypes(types), [types]);
+  const detected = useMemo(() => detectMode(value, parseVariablePath), [value, parseVariablePath]);
+  const variableItems = useMemo(() => buildContextSelectorItems(metaTree).map(fromContextItem), [metaTree]);
+
+  const switcherOptions = useMemo<SwitcherOption[]>(() => {
+    const items: SwitcherOption[] = [];
+    if (nullable) {
+      items.push({ value: NULL_KEY, label: t('Null'), isLeaf: true });
+    }
+    // Always render Constant with a typed submenu — even when only one type is
+    // allowed. Matches v1 `Variable.Input`, where clicking 常量 reveals 数字 /
+    // 逻辑值 / etc. so the user can see what type the constant actually is.
+    if (normalizedTypes.length > 0) {
+      items.push({
+        value: CONST_KEY,
+        label: t('Constant'),
+        children: normalizedTypes.map(({ type }) => ({
+          value: type,
+          label: t(TYPE_LABEL_KEYS[type]),
+          isLeaf: true,
+        })),
+      });
+    }
+    items.push(...variableItems);
+    return items;
+  }, [nullable, normalizedTypes, variableItems, t]);
+
+  const onSwitcherChange = useCallback<NonNullable<CascaderProps<SwitcherOption>['onChange']>>(
+    (path, selectedOptions) => {
+      const head = path?.[0];
+      if (head === NULL_KEY) {
+        onChange?.(null);
+        return;
+      }
+      if (head === CONST_KEY) {
+        // Cascader always emits the second segment now that we render typed
+        // children even for single-type configs. Fall back to the first
+        // allowed type so picking only the parent still does something
+        // sensible (`changeOnSelect` lets this fire).
+        const targetType = (path[1] as TypedConstantType | undefined) ?? normalizedTypes[0]?.type;
+        if (!targetType) return;
+        if (detected.mode === targetType) return;
+        onChange?.(defaultValueFor(targetType));
+        return;
+      }
+      const leaf = selectedOptions?.[selectedOptions.length - 1] as SwitcherOption | undefined;
+      const meta = leaf?.meta;
+      if (!meta) return;
+      const formatted = formatVariablePath(meta);
+      if (formatted != null) onChange?.(formatted);
+    },
+    [onChange, normalizedTypes, detected.mode, formatVariablePath],
+  );
+
+  const onClearVariable = useCallback(() => {
+    if (nullable) {
+      onChange?.(null);
+      return;
+    }
+    const first = normalizedTypes[0];
+    if (first) onChange?.(defaultValueFor(first.type));
+  }, [nullable, normalizedTypes, onChange]);
+
+  const constantTypeForRendering: TypedConstantType = useMemo(() => {
+    const m = detected.mode;
+    if (m === 'string' || m === 'number' || m === 'boolean' || m === 'date') return m;
+    return normalizedTypes[0]?.type ?? 'string';
+  }, [detected.mode, normalizedTypes]);
+
+  const typedProps = useMemo(
+    () => normalizedTypes.find((nt) => nt.type === constantTypeForRendering)?.props ?? {},
+    [normalizedTypes, constantTypeForRendering],
+  );
+
+  const isVariable = detected.mode === 'variable';
+  const isNull = detected.mode === 'null';
+
+  const variableLabels = useMemo(
+    () => (isVariable && detected.variablePath ? resolveVariableLabels(detected.variablePath, metaTree) : []),
+    [isVariable, detected.variablePath, metaTree],
+  );
+
+  return (
+    <Space.Compact style={{ display: 'flex', width: '100%', ...style }} className={className}>
+      <div style={{ flex: 1, minWidth: 0, overflow: 'hidden' }}>
+        {isVariable ? (
+          <div
+            role="button"
+            aria-label="variable-tag"
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: token.marginXXS,
+              padding: `0 ${token.paddingSM}px`,
+              minHeight: token.controlHeight,
+              border: `1px solid ${token.colorBorder}`,
+              borderRadius: token.borderRadius,
+              borderTopRightRadius: 0,
+              borderBottomRightRadius: 0,
+              background: disabled ? token.colorBgContainerDisabled : token.colorBgContainer,
+              overflow: 'hidden',
+            }}
+          >
+            <Tag
+              color="blue"
+              style={{
+                marginInlineEnd: 0,
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+              }}
+            >
+              {variableLabels.map((label, index) => (
+                <React.Fragment key={`${label}-${index}`}>
+                  {index ? ' / ' : ''}
+                  {label}
+                </React.Fragment>
+              ))}
+            </Tag>
+            {!disabled ? (
+              <Button
+                type="text"
+                size="small"
+                aria-label="icon-close"
+                onClick={onClearVariable}
+                icon={<CloseCircleFilled style={{ color: token.colorTextTertiary }} />}
+              />
+            ) : null}
+          </div>
+        ) : isNull ? (
+          // v1 used the `placeholder` slot (not `value`) so the antd default
+          // placeholder colour applies — keeps the field looking visibly
+          // empty/inactive rather than holding a real text value.
+          <Input placeholder={`<${t('Null')}>`} readOnly disabled={disabled} style={{ width: '100%' }} />
+        ) : (
+          renderConstantEditor(constantTypeForRendering, value, onChange, {
+            typedProps,
+            disabled,
+            placeholder,
+            t,
+          })
+        )}
+      </div>
+      <Cascader<SwitcherOption>
+        options={switcherOptions}
+        onChange={onSwitcherChange}
+        disabled={disabled}
+        changeOnSelect
+      >
+        <Button
+          aria-label="variable-switcher"
+          disabled={disabled}
+          type={isVariable ? 'primary' : 'default'}
+          style={{
+            flexShrink: 0,
+            fontStyle: 'italic',
+            fontFamily: '"New York", "Times New Roman", Times, serif',
+          }}
+        >
+          x
+        </Button>
+      </Cascader>
+    </Space.Compact>
+  );
+}
+
+export default TypedVariableInput;