@nocobase/client-v2 2.1.0-beta.9 → 2.2.0-beta.1

package/es/components/form/DialogFormLayout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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';
+export interface DialogFormLayoutProps {
+    /** Header title rendered in the dialog's title slot. */
+    title: React.ReactNode;
+    /** Form body — typically a `<Form>` wrapping `<Form.Item>` fields. */
+    children: React.ReactNode;
+    /** Called before the dialog is closed by the Cancel button or the top-right close (X) icon. Use for "discard changes" confirmations. */
+    onCancel?: () => void | Promise<void>;
+    /** Called when the Submit button is clicked. Caller owns validation + the actual API call; the dialog is closed automatically when `onSubmit` resolves. Throw from `onSubmit` to keep the dialog open (e.g. on a validation error). */
+    onSubmit?: () => void | Promise<void>;
+    /** Drives the Submit button's loading state. */
+    submitting?: boolean;
+    /** Override the Submit button label. Defaults to "Submit". */
+    submitText?: React.ReactNode;
+    /** Override the Cancel button label. Defaults to "Cancel". */
+    cancelText?: React.ReactNode;
+    /** Full override of the footer content. When provided, the default Cancel + Submit buttons are replaced. Useful for forms that need extra actions (e.g. Preview, Save draft). */
+    footer?: React.ReactNode;
+}
+/**
+ * Standard layout for dialog-hosted forms — the dialog counterpart of `DrawerFormLayout`. Title sits left-aligned in the dialog's native header, the form body fills the middle, and a Cancel + Submit footer sits at the bottom. Neither this layout nor `DrawerFormLayout` renders a close icon — both rely on the caller passing `closable: true` at the `viewer.dialog` / `viewer.drawer` call site to surface antd Modal's native top-right X (Dialog) or antd Drawer's native left-side X (Drawer).
+ *
+ * Callers own the `<Form>` instance, validation, and the actual API call. This component only handles the chrome and close behaviour.
+ *
+ * Example:
+ *
+ * ```tsx
+ * ctx.viewer.dialog({
+ *   closable: true,                       // native top-right X
+ *   content: () => (
+ *     <DialogFormLayout
+ *       title={t('Bind verifier')}
+ *       onSubmit={handleSubmit}
+ *       submitting={submitting}
+ *       submitText={t('Bind')}
+ *     >
+ *       <Form form={form} layout="vertical">...</Form>
+ *     </DialogFormLayout>
+ *   ),
+ * });
+ * ```
+ */
+export declare function DialogFormLayout(props: DialogFormLayoutProps): React.JSX.Element;

package/es/components/form/DrawerFormLayout.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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';
+export interface DrawerFormLayoutProps {
+    /** Header title rendered next to antd Drawer's native close (X) icon. */
+    title: React.ReactNode;
+    /** Form body — typically a `<Form>` wrapping `<Form.Item>` fields. */
+    children: React.ReactNode;
+    /**
+     * Called when the Submit button is clicked. Caller owns validation + the
+     * actual API call; the drawer is closed automatically when `onSubmit`
+     * resolves. Throw from `onSubmit` to keep the drawer open (e.g. on a
+     * validation error).
+     */
+    onSubmit?: () => void | Promise<void>;
+    /** Drives the Submit button's loading state. */
+    submitting?: boolean;
+    /** Override the Submit button label. Defaults to "Submit". */
+    submitText?: React.ReactNode;
+    /** Override the Cancel button label. Defaults to "Cancel". */
+    cancelText?: React.ReactNode;
+    /**
+     * Full override of the footer content. When provided, the default
+     * Cancel + Submit buttons are replaced. Useful for forms that need
+     * extra actions (e.g. Preview, Save draft).
+     */
+    footer?: React.ReactNode;
+}
+/**
+ * Standard layout for drawer-hosted forms: a title-only header on top
+ * (caller must open the drawer with `viewer.drawer({ closable: true })`
+ * so antd Drawer renders its native left-side X next to the title),
+ * the caller-provided form body in the middle, and a Cancel + Submit
+ * footer at the bottom. Wraps `useFlowView()`'s `Header` / `Footer`
+ * slots so the drawer chrome stays consistent across plugins.
+ *
+ * To intercept close (e.g. dirty-form confirmation), use the lower-level
+ * `viewer.drawer({ preventClose, beforeClose, ... })` hooks — this
+ * layout no longer wraps a custom close handler.
+ *
+ * Callers own the `<Form>` instance, validation, and the actual API call.
+ */
+export declare function DrawerFormLayout(props: DrawerFormLayoutProps): React.JSX.Element;

package/es/components/form/EnvVariableInput.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { MetaTreeNode } from '@nocobase/flow-engine';
+import React from 'react';
+/**
+ * Convert a stored value like `"{{ $env.foo.bar }}"` back into the
+ * `[$env, foo, bar]` path used by the variable picker.
+ */
+export declare function parseEnvPath(value?: string): string[] | undefined;
+/**
+ * Format a meta tree node back into a `"{{ $env.x.y }}"` server-compatible
+ * expression. Used as the `formatPathToValue` converter so the picker output
+ * survives a round trip through the API.
+ */
+export declare function formatEnvPath(meta?: MetaTreeNode): string;
+export interface EnvVariableInputProps {
+    value?: string;
+    onChange?: (value: string) => void;
+    addonBefore?: React.ReactNode;
+    disabled?: boolean;
+    /**
+     * When true, plain (non-variable) values are masked via `Input.Password`
+     * so secret credentials are not displayed verbatim. Variable expressions
+     * remain editable through the variable picker even in password mode.
+     */
+    password?: boolean;
+    placeholder?: string;
+}
+/**
+ * Convenience wrapper around `VariableInput` constrained to the `$env`
+ * namespace, with optional password-input masking for plain values. Use for
+ * fields that accept either a literal credential or a `{{ $env.X }}`
+ * reference (S3 access keys, OAuth secrets, etc.). The `$env` tree is
+ * provided by the environment-variables plugin's
+ * `flowEngine.context.defineProperty('$env', ...)`; this component degrades
+ * gracefully to an empty picker when no env variables are defined.
+ */
+export declare function EnvVariableInput(props: EnvVariableInputProps): React.JSX.Element;

package/es/components/form/FileSizeInput.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 React from 'react';
+export interface FileSizeInputProps {
+    value?: number;
+    onChange?: (value?: number) => void;
+    disabled?: boolean;
+    /** Minimum byte size. Empty / below-min input snaps to this on blur. Defaults to 1. */
+    min?: number;
+    /** Maximum byte size. Defaults to `Number.POSITIVE_INFINITY`. */
+    max?: number;
+    /** Default byte size used to derive the initial unit shown when the field is empty. Defaults to 20 MB. */
+    defaultValue?: number;
+}
+/**
+ * Byte-valued size input paired with a unit selector (Byte / KB / MB / GB).
+ * The persisted value is always normalized to bytes; the displayed number is
+ * derived from the picked unit. Useful for fields like file-size limits or
+ * memory quotas where the natural input unit varies by magnitude.
+ */
+export declare function FileSizeInput(props: FileSizeInputProps): React.JSX.Element;

package/es/components/form/JsonTextArea.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';
+export interface JsonTextAreaProps extends Omit<TextAreaProps, 'value' | 'onChange'> {
+    value?: unknown;
+    onChange?: (value: unknown) => void;
+    space?: number;
+    json5?: boolean;
+    showError?: boolean;
+}
+export declare const JsonTextArea: React.MemoExoticComponent<(props: JsonTextAreaProps) => React.JSX.Element>;

package/es/components/form/PasswordInput.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { PasswordProps as AntdPasswordProps } from 'antd/es/input';
+import React from 'react';
+export interface PasswordInputProps extends AntdPasswordProps {
+    /**
+     * Render a visual strength bar beneath the input. Defaults to `false`. The
+     * score is computed locally — opting in does NOT add any form validation;
+     * use a separate `Form.Item.rules` entry for that (or wire the entry up to
+     * a cross-plugin password-validator extension point if your project
+     * provides one).
+     */
+    checkStrength?: boolean;
+}
+/**
+ * `Input.Password` plus an optional strength meter, ported from the v1
+ * `Password` component. The strength scoring and bar UI are identical to v1,
+ * so users who switch from a v1 page to a v2 page see the same visual signal.
+ *
+ * The component is value-shape compatible with antd `Input.Password` — drop
+ * it into any existing `Form.Item<password>` and toggle the meter with
+ * `checkStrength`.
+ *
+ * Caveats:
+ *
+ * - Strength scoring is purely a UX hint, not validation. Submitting a weak
+ *   password is still allowed unless the server (or a separately installed
+ *   password-policy plugin) rejects it.
+ * - The meter swallows the gap between `<Input.Password>` and the next form
+ *   element. If your `Form.Item` already adds vertical rhythm, the meter
+ *   inherits it; no extra spacing is added.
+ */
+export declare function PasswordInput(props: PasswordInputProps): React.JSX.Element;
+export default PasswordInput;

package/es/components/form/RemoteSelect.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 SelectProps } from 'antd';
+import React from 'react';
+export interface RemoteSelectFieldNames {
+    label?: string;
+    value?: string;
+}
+export interface RemoteSelectProps<RawItem = any, Resp = RawItem[], V = any> extends Omit<SelectProps<V>, 'options' | 'loading'> {
+    /**
+     * Fetch the option source. Receives no arguments; caller closes over the
+     * `ctx.api.resource(...)` (or any other source) it needs. May resolve
+     * with either an array of raw items (the common case) or an arbitrary
+     * envelope object — in the latter case, supply `selectItems` to pluck
+     * the array out.
+     */
+    request: () => Promise<Resp | undefined>;
+    /**
+     * When `request` returns an envelope (object with metadata around the
+     * list), use this to extract the array of items that drives the
+     * dropdown. Defaults to identity, i.e. `request` itself returns the
+     * array.
+     */
+    selectItems?: (response: Resp) => RawItem[] | undefined;
+    /**
+     * Names of the raw item properties that hold the display label and the
+     * persisted value. Defaults to `{ label: 'label', value: 'value' }`.
+     * Ignored when `mapOptions` is supplied.
+     */
+    fieldNames?: RemoteSelectFieldNames;
+    /**
+     * Full custom mapping from a raw item to an antd `OptionType`. When
+     * provided, overrides `fieldNames`.
+     */
+    mapOptions?: (item: RawItem, index: number) => {
+        label: React.ReactNode;
+        value: any;
+    };
+    /**
+     * Stable cache key for ahooks `useRequest` so the dropdown doesn't re-fetch
+     * on every re-mount. Pass a value tied to the request's effective inputs.
+     */
+    cacheKey?: string;
+    /**
+     * Re-run the request when any of these values changes. Forwarded to
+     * `useRequest`'s `refreshDeps`.
+     */
+    refreshDeps?: unknown[];
+    /**
+     * Skip the auto-fetch on mount when `false`. Defaults to `true`.
+     */
+    ready?: boolean;
+    /**
+     * Notified once the request resolves. Receives both the mapped item
+     * array and the raw response envelope — useful when callers need to
+     * read sibling metadata (counts, availability hints, etc.) without
+     * issuing a second request.
+     */
+    onLoaded?: (items: RawItem[], response: Resp) => void;
+}
+/**
+ * Generic settings-page Select bound to an async option source. The
+ * component itself stays framework-agnostic — it knows nothing about
+ * NocoBase resources, data sources, or Formily. Pass any async `request`
+ * that resolves with an array, and supply `fieldNames` (or `mapOptions`)
+ * to map raw items to antd option shape.
+ *
+ * Search is local-only (antd's default `optionFilterProp="label"`). For
+ * server-side search, drive `request` from external state and pass the
+ * search input via `refreshDeps`.
+ */
+export declare function RemoteSelect<RawItem = any, Resp = RawItem[], V = any>(props: RemoteSelectProps<RawItem, Resp, V>): React.JSX.Element;
+export default RemoteSelect;

package/es/components/form/ScanInput/CodeScanner.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 React from 'react';
+import type { CodeFormatsToSupport } from './types';
+type CodeScannerProps = {
+    visible: boolean;
+    formatsToSupport?: CodeFormatsToSupport;
+    onClose: () => void;
+    onScanSuccess: (result: string) => void;
+};
+export declare function CodeScanner(props: CodeScannerProps): React.ReactPortal;
+export {};

package/es/components/form/ScanInput/ScanBox.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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';
+export declare function ScanBox({ style }: {
+    style?: React.CSSProperties;
+}): React.JSX.Element;

package/es/components/form/ScanInput/ScanInput.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 { InputProps } from 'antd';
+import React from 'react';
+import type { CodeFormatsToSupport } from './types';
+export type ScanInputProps = Omit<InputProps, 'onChange'> & {
+    disableManualInput?: boolean;
+    enableScan?: boolean;
+    formatsToSupport?: CodeFormatsToSupport;
+    onChange?: (value: string | React.ChangeEvent<HTMLInputElement>) => void;
+};
+export declare function ScanInput({ value, onChange, disabled, disableManualInput, enableScan, formatsToSupport, onFocus, suffix, ...rest }: ScanInputProps): React.JSX.Element;

package/es/components/form/ScanInput/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export * from './CodeScanner';
+export * from './ScanInput';
+export * from './types';

package/es/components/form/ScanInput/types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { Html5QrcodeSupportedFormats } from 'html5-qrcode';
+export type CodeFormatsToSupport = Html5QrcodeSupportedFormats[];

package/es/components/form/ScanInput/useCodeScanner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { CodeFormatsToSupport } from './types';
+type ScannerSize = {
+    width: number;
+    height: number;
+};
+type UseCodeScannerOptions = {
+    enabled: boolean;
+    elementId: string;
+    formatsToSupport?: CodeFormatsToSupport;
+    scanBoxSize?: ScannerSize;
+    onScannerSizeChanged?: (size: ScannerSize) => void;
+    onScanSuccess: (text: string) => void;
+    onScanFailure?: () => void;
+};
+export declare const DEFAULT_CODE_FORMATS: CodeFormatsToSupport;
+export declare function getCodeScanBoxSize(width: number, height: number): {
+    width: number;
+    height: number;
+};
+export declare function useCodeScanner({ enabled, elementId, formatsToSupport, scanBoxSize, onScannerSizeChanged, onScanSuccess, onScanFailure, }: UseCodeScannerOptions): {
+    startScanFile: (file: File) => Promise<void>;
+};
+export {};

package/es/components/form/TypedVariableInput.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 MetaTreeNode } from '@nocobase/flow-engine';
+import React from 'react';
+import { 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;
+}
+/**
+ * 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 declare function TypedVariableInput(props: TypedVariableInputProps): React.JSX.Element;
+export default TypedVariableInput;

package/es/components/form/VariableInput.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 MetaTreeNode, type VariableHybridInputConverters } from '@nocobase/flow-engine';
+import React from 'react';
+/**
+ * The flow-engine defaults emit `{{ ctx.$X.Y }}` and only parse the same
+ * shape back into a path — but NocoBase server templates (and v1 stored
+ * values) use the bare `{{$X.Y}}` form without the `ctx.` prefix. These
+ * converters keep the picker's output stable against v1 and let already-
+ * stored values round-trip to a labelled pill instead of falling back to a
+ * raw `{{…}}` literal.
+ */
+/**
+ * Variable delimiters: opening + closing tokens. Default `['{{', '}}']`
+ * matches NocoBase server template convention (Handlebars HTML-escaped
+ * output). Pass `['{{{', '}}}']` to switch to Handlebars' raw/unescaped
+ * form — required for fields whose content is rendered as HTML (e.g.
+ * in-app message body) so the variable expansion bypasses HTML escaping.
+ *
+ * Restrict to literal-token pairs, since the regex builder escapes them
+ * verbatim.
+ */
+export type VariableDelimiters = readonly [string, string];
+/**
+ * Factory: returns a `parseValueToPath` bound to the given delimiters.
+ * Anchored (`^…$`) — only treats the whole input as a single variable
+ * reference, matching the v1 single-line picker behaviour.
+ */
+export declare function makeParseVariablePath(delimiters?: VariableDelimiters): (value?: string) => string[] | undefined;
+/**
+ * Factory: returns a `formatPathToValue` bound to the given delimiters.
+ * No inner spaces — matches the v1 storage shape exactly so round-trips
+ * through the API stay byte-stable.
+ */
+export declare function makeFormatVariablePath(delimiters?: VariableDelimiters): (meta?: MetaTreeNode) => string | undefined;
+/**
+ * Factory: returns a global regex matching every occurrence of the
+ * variable token within a longer string. Used by `VariableHybridInput`
+ * to render embedded variables as pills.
+ */
+export declare function makeVariableRegExp(delimiters?: VariableDelimiters): RegExp;
+export declare const parseVariablePath: (value?: string) => string[] | undefined;
+export declare const formatVariablePath: (meta?: MetaTreeNode) => string | undefined;
+/**
+ * Resolve the meta tree the variable picker should expose. Filters the global
+ * meta tree by `namespaces` (top-level property names like `'$env'`,
+ * `'$user'`), appends `extraNodes`, and eagerly resolves any lazy `children`
+ * thunks so labels render on first paint.
+ *
+ * Returns `[]` while loading or when no nodes survive the filter, mirroring
+ * the existing EnvVariableInput behavior so the picker still opens but offers
+ * nothing.
+ */
+export declare function useFilteredMetaTree(options: {
+    namespaces?: string[];
+    extraNodes?: MetaTreeNode[];
+}): MetaTreeNode[];
+export interface VariableInputProps {
+    value?: string;
+    onChange?: (value: string) => void;
+    disabled?: boolean;
+    placeholder?: string;
+    addonBefore?: React.ReactNode;
+    /**
+     * Restrict the picker to specific top-level meta tree namespaces (e.g.
+     * `['$env', '$user']`). When omitted, every registered top-level property is
+     * exposed. Filter happens at the picker level — the underlying regex used
+     * for pill rendering still matches any `{{ ... }}` expression so pre-existing
+     * out-of-scope values stay legible.
+     */
+    namespaces?: string[];
+    /**
+     * Static leaves appended to the picker, after the namespace-filtered nodes.
+     * Use for ad-hoc local-only variables (e.g. `$resetLink`) that are not part
+     * of the global FlowContext registry.
+     */
+    extraNodes?: MetaTreeNode[];
+    /**
+     * Override the converters used by the underlying `VariableHybridInput`.
+     * Mostly useful when the caller wants to constrain `formatPathToValue` to a
+     * specific namespace (see `EnvVariableInput` for that pattern).
+     *
+     * Takes precedence over `delimiters` when both are set on the same field
+     * (an explicit converter wins over the delimiter-derived one).
+     */
+    converters?: VariableHybridInputConverters;
+    /**
+     * Token pair wrapping variable references in the stored string. Defaults
+     * to `['{{', '}}']` — the standard NocoBase server-template form,
+     * HTML-escaped by Handlebars. Pass `['{{{', '}}}']` for fields rendered
+     * as HTML where escaping would corrupt the variable value (e.g. the
+     * in-app message body).
+     *
+     * Ignored when `converters` is also supplied — caller-provided converters
+     * win.
+     */
+    delimiters?: VariableDelimiters;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Inline (single-line) variable input. Renders the literal text and any
+ * `{{ ... }}` references as styled pills via `VariableHybridInput`. Use for
+ * fields like form input titles, email subject lines, or any place a single
+ * line of mixed literal+variable content is appropriate.
+ */
+export declare function VariableInput(props: VariableInputProps): React.JSX.Element;
+export interface VariableTextAreaProps extends Omit<VariableInputProps, 'converters' | 'addonBefore'> {
+    rows?: number;
+    maxRows?: number;
+}
+/**
+ * Multi-line variable input. Variables are inserted as raw `{{ ... }}` text at
+ * the caret rather than rendered as pills — use for email body templates and
+ * other free-form long-form text where literal display of variable expressions
+ * is desirable (the server expands them at render time).
+ */
+export declare function VariableTextArea(props: VariableTextAreaProps): React.JSX.Element;

package/es/components/form/createFormRegistry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+export interface FormRegistryEntry {
+    name: string;
+}
+export interface FormRegistry<T extends FormRegistryEntry> {
+    readonly namespace: string;
+    register(entry: T): void;
+    unregister(name: string): boolean;
+    get(name: string): T | undefined;
+    has(name: string): boolean;
+    list(): T[];
+}
+/**
+ * Create an isolated, namespaced registry of form-like entries.
+ *
+ * Each call returns a fresh registry instance backed by its own closure-scoped
+ * `Map`, so plugins do not share state across namespaces. Plugins that need an
+ * extension point for form-shaped registrations (e.g. storage configuration
+ * forms, data-source connection forms) can build their own typed registry on
+ * top of this primitive instead of re-implementing the same boilerplate.
+ *
+ * Re-registering the same `name` overwrites the previous entry and emits a
+ * console warning. This is intentional so HMR / hot reload works without
+ * throwing, while still surfacing unintended duplicates during development.
+ */
+export declare function createFormRegistry<T extends FormRegistryEntry>(namespace: string): FormRegistry<T>;