@nocobase/client 2.0.0-beta.9 → 2.0.1

package/es/flow/models/blocks/filter-manager/flow-actions/defaultOperator.d.ts

@@ -6,6 +6,4 @@
  * 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 { FlowContext } from '@nocobase/flow-engine';
-import { FilterFormFieldModel } from '../../filter-form/fields';
-export declare const defaultOperator: import("@nocobase/flow-engine").ActionDefinition<FilterFormFieldModel, FlowContext>;
+export declare const defaultOperator: any;

package/es/flow/models/blocks/form/CreateFormModel.d.ts

@@ -15,6 +15,7 @@ export declare class CreateFormModel extends FormBlockModel {
     private actionExtraToolbarItems;
     createResource(ctx: any, params: any): SingleRecordResource<unknown>;
     getAclActionName(): string;
-    submit(params?: any): Promise<void>;
+    submitHandler(ctx: any, params: any, cb?: (values?: any, filterByTk?: any) => void): Promise<void>;
+    submit(params?: any, cb?: (values?: any, filterByTk?: any) => void): Promise<void>;
     renderComponent(): React.JSX.Element;
 }

package/es/flow/models/blocks/form/EditFormModel.d.ts

@@ -18,6 +18,7 @@ export declare class EditFormModel extends FormBlockModel {
     getCurrentRecord(): any;
     getAclActionName(): string;
     handlePageChange: (page: number) => Promise<void>;
-    submit(params?: any): Promise<void>;
+    submitHandler(ctx: any, params: any, cb?: (values?: any, filterByTk?: any) => void): Promise<void>;
+    submit(params?: any, cb?: (values?: any, filterByTk?: any) => void): Promise<void>;
     renderComponent(): React.JSX.Element;
 }

package/es/flow/models/blocks/form/FormAssociationFieldGroupModel.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 { AssociationFieldGroupModel } from '../../base';
+export declare class FormAssociationFieldGroupModel extends AssociationFieldGroupModel {
+    static itemModelName: string;
+}

package/es/flow/models/blocks/form/FormAssociationItemModel.d.ts

@@ -0,0 +1,39 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import { DisplayItemModel, FlowModelContext } from '@nocobase/flow-engine';
+import React from 'react';
+export declare class FormAssociationItemModel extends DisplayItemModel {
+    static defineChildren(ctx: FlowModelContext): {
+        key: any;
+        label: string;
+        refreshTargets: string[];
+        toggleable: (subModel: any) => boolean;
+        useModel: string;
+        createModelOptions: () => {
+            use: string;
+            stepParams: {
+                fieldSettings: {
+                    init: {
+                        dataSourceKey: any;
+                        collectionName: any;
+                        fieldPath: any;
+                    };
+                };
+            };
+            subModels: {
+                field: {
+                    use: string;
+                    props: any;
+                };
+            };
+        };
+    }[];
+    onInit(options: any): void;
+    renderItem(): React.JSX.Element;
+}

package/es/flow/models/blocks/form/FormBlockModel.d.ts

@@ -13,6 +13,7 @@ import { BlockGridModel } from '../../base/BlockGridModel';
 import { CollectionBlockModel } from '../../base/CollectionBlockModel';
 import { FormActionModel } from './FormActionModel';
 import { FormGridModel } from './FormGridModel';
+import { FormValueRuntime } from './value-runtime';
 type DefaultCollectionBlockModelStructure = {
     parent?: BlockGridModel;
     subModels?: {
@@ -22,16 +23,33 @@ type DefaultCollectionBlockModelStructure = {
 };
 type CustomFormBlockModelClassesEnum = {};
 export declare class FormBlockModel<T extends DefaultCollectionBlockModelStructure = DefaultCollectionBlockModelStructure> extends CollectionBlockModel<T> {
+    formValueRuntime?: FormValueRuntime;
+    private userModifiedTopLevelFields;
     get form(): FormInstance<any>;
     _defaultCustomModelClasses: {
         FormActionGroupModel: string;
         FormItemModel: string;
-        FormCustomItemModel: string;
+        FormAssociationFieldGroupModel: string;
     };
     customModelClasses: CustomFormBlockModelClassesEnum;
     renderConfigureActions(): React.JSX.Element;
     setFieldsValue(values: any): void;
-    setFieldValue(fieldName: string, value: any): void;
+    setFieldValue(fieldName: any, value: any): void;
+    /**
+     * @internal
+     *
+     * 仅用于编辑表单刷新保护：只记录「用户交互」触发的改动（来自 antd Form.onValuesChange）。
+     * 程序化 setFieldValue/setFieldsValue 不会触发 onValuesChange（见 linkageRules 的手动 emit），因此不会污染该集合。
+     */
+    markUserModifiedFields(changedValues: any): void;
+    /**
+     * @internal
+     */
+    getUserModifiedFields(): Set<string>;
+    /**
+     * @internal
+     */
+    resetUserModifiedFields(): void;
     onDispatchEventStart(eventName: string, options?: any, inputArgs?: Record<string, any>): Promise<void>;
     getStepParams(flowKey: string, stepKey: string): any | undefined;
     getStepParams(flowKey: string): Record<string, any> | undefined;
@@ -44,6 +62,7 @@ export declare class FormBlockModel<T extends DefaultCollectionBlockModelStructu
     useHooksBeforeRender(): void;
     onInit(options: any): void;
     protected onMount(): void;
+    onUnmount(): void;
     getCurrentRecord(): {};
     renderComponent(): void;
 }
@@ -53,7 +72,20 @@ export declare function FormComponent({ model, children, layoutProps, initialVal
     layoutProps?: any;
     initialValues?: any;
     onFinish?: (values: any) => void;
+    [key: string]: any;
 }): React.JSX.Element;
+type FormBlockContentProps = {
+    model: FormBlockModel;
+    gridModel: FormGridModel;
+    layoutProps?: any;
+    onFinish?: (values: any) => void;
+    grid: React.ReactNode;
+    actions?: React.ReactNode;
+    footer?: React.ReactNode;
+    heightMode?: string;
+    height?: number;
+};
+export declare const FormBlockContent: ({ model, gridModel, layoutProps, onFinish, grid, actions, footer, heightMode, height, }: FormBlockContentProps) => React.JSX.Element;
 /**
  * 兼容旧版本
  * @deprecated use FormBlockModel instead

package/es/flow/models/blocks/form/FormGridModel.d.ts

@@ -30,4 +30,5 @@ export declare class FormGridModel<T extends DefaultFormGridStructure = DefaultF
     };
     dragOverlayConfig: DragOverlayConfig;
     renderAddSubModelButton(): React.JSX.Element;
+    render(): React.JSX.Element;
 }

package/es/flow/models/blocks/form/QuickEditFormModel.d.ts

@@ -16,6 +16,7 @@ export declare class QuickEditFormModel extends FlowModel {
     viewContainer: any;
     __onSubmitSuccess: any;
     _fieldProps: any;
+    _onOk: any;
     get form(): any;
     useHooksBeforeRender(): void;
     static open(options: {
@@ -24,10 +25,12 @@ export declare class QuickEditFormModel extends FlowModel {
         dataSourceKey: string;
         collectionName: string;
         fieldPath: string;
-        filterByTk: string;
         record: any;
+        filterByTk?: string;
         onSuccess?: (values: any) => void;
         fieldProps?: any;
+        sourceFieldModelUid?: string;
+        onOk?: (values: any) => void;
     }): Promise<void>;
     onInit(options: any): void;
     addAppends(fieldPath: string, refresh?: boolean): void;

package/es/flow/models/blocks/form/assignRulesUpdateAssociationValues.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.
+ */
+/**
+ * 从 assignRules 的 targetPath 推导需要注入到请求中的 updateAssociationValues。
+ *
+ * 规则：仅当 targetPath 穿过至少一段关联字段（association）时返回该关联路径：
+ * - user.name -> user
+ * - user.profile.name -> user.profile
+ */
+export declare function collectUpdateAssociationValuesFromAssignRules(items: Array<{
+    targetPath?: string;
+} | any>, rootCollection: any): string[];

package/es/flow/models/blocks/form/dynamicNamePath.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 type DynamicNamePart = string | number;
+/**
+ * Build a dynamic NamePath based on current subform list row index.
+ *
+ * fieldIndex is an array like: ["products:0", "products:2"] (nested lists allowed, including same-name lists).
+ *
+ * For example:
+ * - nameParts: ["products", "products"] + fieldIndex: ["products:0"] => [0, "products"]
+ * - nameParts: ["products", "products", "id"] + fieldIndex: ["products:1", "products:0"] => [0, "id"]
+ */
+export declare function buildDynamicNamePath(nameParts: DynamicNamePart[], fieldIndex?: string[]): DynamicNamePart[];

package/es/flow/models/blocks/form/index.d.ts

@@ -17,3 +17,5 @@ export * from './FormItemModel';
 export * from './FormJSFieldItemModel';
 export * from './JSFormActionModel';
 export * from './QuickEditFormModel';
+export * from './FormAssociationFieldGroupModel';
+export * from './FormAssociationItemModel';

package/es/flow/models/blocks/form/legacyDefaultValueMigration.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { mergeAssignRulesWithLegacyDefaults } from '../shared/legacyDefaultValueMigrationBase';
+import type { FieldAssignRuleItem } from '../../../components/FieldAssignRulesEditor';
+export declare function collectLegacyDefaultValueRulesFromFormModel(formModel: any): FieldAssignRuleItem[];
+export declare function clearLegacyDefaultValuesFromFormModel(formModel: any): any[];
+export { mergeAssignRulesWithLegacyDefaults };

package/es/flow/models/blocks/form/submitHandler.d.ts

@@ -6,4 +6,4 @@
  * 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 declare function submitHandler(ctx: any, params: any): Promise<void>;
+export declare function submitHandler(ctx: any, params: any, cb?: (values?: any, filterByTk?: any) => void): Promise<void>;

package/es/flow/models/blocks/form/submitValues.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { FormBlockModel } from './FormBlockModel';
+/**
+ * 提交前过滤：移除当前表单 block 中被「联动规则隐藏」的字段值（`model.hidden === true`）。
+ *
+ * 说明：
+ * - 仅对 “隐藏 / Hidden” 生效（对应 `model.hidden=true`）。
+ * - “隐藏并保留值 / Hidden (reserved value)” 在实现上是 `props.hidden=true` 但 `model.hidden=false`，
+ *   因此仍会提交（保持现有语义）。
+ * - 不会清空 antd Form 的内部 store，只影响本次提交 payload。
+ */
+export declare function omitHiddenModelValuesFromSubmit<T = any>(values: T, blockModel: FormBlockModel): T;

package/es/flow/models/blocks/form/value-runtime/conditions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function evaluateCondition(ctx: any, condition: any): boolean;

package/es/flow/models/blocks/form/value-runtime/deps.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 { NamePath } from './types';
+export type DepCollector = {
+    deps: Set<string>;
+    wildcard: boolean;
+};
+export declare function recordDep(namePath: NamePath, collector: DepCollector | undefined): void;
+export declare function createFormValuesProxy(options: {
+    valuesMirror: any;
+    basePath: NamePath;
+    collector?: DepCollector;
+    getFormValuesSnapshot: () => any;
+    getFormValueAtPath: (namePath: NamePath) => any;
+}): any;
+export declare function collectStaticDepsFromTemplateValue(value: any, collector: DepCollector): void;
+export declare function collectStaticDepsFromRunJSValue(value: any, collector: DepCollector): void;

package/es/flow/models/blocks/form/value-runtime/form-patch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 { FormInstance } from 'antd';
+import type { Patch, SetOptions } from './types';
+export type FormPatcher = {
+    patch: (form: FormInstance) => void;
+    restore: () => void;
+};
+export declare function createFormPatcher(options: {
+    isSuppressed: () => boolean;
+    getCallerContext: () => any;
+    setFormValues: (callerCtx: any, patch: Patch, options?: SetOptions) => Promise<void>;
+}): FormPatcher;

package/es/flow/models/blocks/form/value-runtime/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 './types';
+export { FormValueRuntime } from './runtime';
+export { isEmptyValue } from './utils';

package/es/flow/models/blocks/form/value-runtime/path.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { NamePath } from './types';
+export type PathSegment = string | number | {
+    placeholder: string;
+};
+export declare function parsePathString(path: string): PathSegment[];
+/**
+ * Resolve a dynamic NamePath using the current row index context (`fieldIndex`).
+ *
+ * - Supports placeholders: `users[placeholder].name`
+ * - Auto-fills to-many index when omitted: `users.name` -> `users[ctxIndex].name`
+ *
+ * Returns `null` when a placeholder can't be resolved in current context.
+ */
+export declare function resolveDynamicNamePath(path: string | NamePath, fieldIndex?: unknown): NamePath | null;
+export declare function namePathToPathKey(namePath: Array<string | number>): string;
+export declare function pathKeyToNamePath(pathKey: string): NamePath;
+export declare function buildAncestorKeys(namePath: NamePath): string[];

package/es/flow/models/blocks/form/value-runtime/rules.d.ts

@@ -0,0 +1,129 @@
+/**
+ * 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 { FlowModel } from '@nocobase/flow-engine';
+import { DepCollector } from './deps';
+import type { FormAssignRuleItem, FormValueWriteMeta, NamePath, Patch, SetOptions, ValueSource } from './types';
+type ObservableBinding = {
+    source: ValueSource;
+    dispose: () => void;
+};
+export type RuleEngineOptions = {
+    getBlockModelUid: () => string;
+    getActionName: () => string | undefined;
+    getBlockContext: () => any;
+    getEngine: () => any;
+    getEngineModel: (uid: string) => FlowModel | null;
+    isDisposed: () => boolean;
+    valuesMirror: any;
+    changeTick: {
+        value: number;
+    };
+    getWriteSeq: () => number;
+    txWriteCounts: Map<string, Map<string, number>>;
+    createTrackingFormValues: (collector: DepCollector) => any;
+    tryResolveNamePath: (callerCtx: any, path: string | NamePath) => NamePath | null;
+    getFormValueAtPath: (namePath: NamePath) => any;
+    setFormValues: (callerCtx: any, patch: Patch, options?: SetOptions) => Promise<void>;
+    findExplicitHit: (pathKey: string) => string | null;
+    lastDefaultValueByPathKey: Map<string, any>;
+    lastWriteMetaByPathKey: Map<string, FormValueWriteMeta>;
+    observableBindings: Map<string, ObservableBinding>;
+};
+export declare class RuleEngine {
+    private readonly options;
+    private readonly rules;
+    private readonly lastRuleWriteByTargetKey;
+    private readonly assignTemplatesByTargetPath;
+    /** 当前表单中“已配置到 UI 的字段（FormItemModel）”的 targetPath 集合，用于避免对 row grid 重复注册规则 */
+    private readonly formItemTargetPaths;
+    /** targetPath -> updateAssociation（SubForm/SubTable 等） */
+    private readonly updateAssociationByTargetPath;
+    private readonly pendingRuleIds;
+    private readonly ruleDebounceUntilById;
+    private readonly ruleDebounceTimersById;
+    private readonly defaultRuleIdsByMasterUid;
+    private readonly defaultRuleMasterDisposers;
+    private runningRules;
+    private rulesEnabled;
+    private currentRuleTxId;
+    constructor(options: RuleEngineOptions);
+    private getAssignRuleBlockId;
+    private removeAssignRuleBlockInstance;
+    private removeRowGridAssignRuleInstances;
+    private hasAnyNonBlockAssignRuleInstance;
+    private ensureBlockAssignRuleInstancesForTargetPath;
+    private getCollectionFromContext;
+    private getRootCollection;
+    private shouldCreateBlockLevelAssignRule;
+    /**
+     * 对关联字段嵌套属性（如 user.name / user.profile.name）：
+     * - 依赖应包含关联对象本身（user / user.profile），否则当关联对象从 null -> {id} 时，user.name 仍为 undefined，无法触发 rule re-run。
+     * - 写入前需校验关联对象已存在，避免隐式创建关联对象。
+     */
+    private collectAssociationPrefixPaths;
+    private shouldSkipToManyAssociationWriteWithoutIndex;
+    private shouldSkipAssociationNestedWrite;
+    private getAssociationTargetKeyFields;
+    private resolveAssociationFieldByPrefixPath;
+    private isAssociationTargetKeyWrite;
+    private collectUpdateAssociationInitPatches;
+    dispose(): void;
+    enable(): void;
+    syncAssignRules(items: FormAssignRuleItem[]): void;
+    onModelMounted(model: FlowModel): void;
+    onModelUnmounted(model: FlowModel): void;
+    private isModelInThisForm;
+    private cacheUpdateAssociationForModel;
+    private getUpdateAssociationForTargetPath;
+    private getDefaultRuleId;
+    private getModelTargetNamePath;
+    private tryRegisterDefaultRuleInstance;
+    private getModelTargetPath;
+    private getAssignRuleInstanceId;
+    private getDeepestFieldIndexKey;
+    private getDeepestToManyAssociationKey;
+    private isRowGridModel;
+    private tryRegisterAssignRuleInstancesForModel;
+    private tryUnregisterAssignRuleInstancesForModel;
+    private tryUnregisterDefaultRuleInstance;
+    private bindMasterInitialValue;
+    private removeRule;
+    private scheduleRule;
+    private flushRules;
+    private runRule;
+    private isTzAwareTargetInterface;
+    private normalizeDateOnlyToStartOfDayIso;
+    private normalizeResolvedValueForTarget;
+    private isPrimitiveAssociationTargetValue;
+    private extractAssociationIdentity;
+    private isAssociationTargetSemanticallyEqual;
+    private resolveCollectionFieldByNamePath;
+    private normalizeResolvedValueForAssociationTarget;
+    private prepareRuleContext;
+    private shouldApplyDefaultRuleInCurrentState;
+    private shouldRunRule;
+    private createRuleCollectorAndContext;
+    private evaluateRuleCondition;
+    private resolveRuleValue;
+    private resolveRunJSValue;
+    private resolveTemplateValue;
+    private commitRuleDeps;
+    /**
+     * Check if default rule value can be applied.
+     * Default value can overwrite when:
+     * 1. Current value is empty
+     * 2. Current value equals the last default value (user hasn't modified it)
+     */
+    private checkDefaultRuleCanApply;
+    private createRuleEvaluationContext;
+    private buildItemChainValue;
+    private getFieldIndexSignature;
+    private updateRuleDeps;
+}
+export {};

package/es/flow/models/blocks/form/value-runtime/runtime.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 { FormInstance } from 'antd';
+import type { FlowModel } from '@nocobase/flow-engine';
+import type { FormAssignRuleItem, NamePath, Patch, SetOptions } from './types';
+type FormBlockModel = FlowModel & {
+    getAclActionName?: () => string;
+};
+export declare class FormValueRuntime {
+    private readonly model;
+    private readonly getForm;
+    private readonly valuesMirror;
+    private readonly explicitSet;
+    private readonly lastDefaultValueByPathKey;
+    private readonly lastWriteMetaByPathKey;
+    private readonly observableBindings;
+    private readonly changeTick;
+    private readonly txWriteCounts;
+    private writeSeq;
+    private disposed;
+    private suppressFormCallbackDepth;
+    private lastObservedChangedPaths;
+    private lastObservedSource;
+    private lastObservedToken;
+    private readonly formValuesProxy;
+    private mountedListener?;
+    private unmountedListener?;
+    private readonly formPatcher;
+    private readonly ruleEngine;
+    constructor(options: {
+        model: FormBlockModel;
+        getForm: () => FormInstance;
+    });
+    /**
+     * 同步“表单赋值”配置到运行时规则引擎。
+     *
+     * - mode=default → source=default（遵循 explicit/空值覆盖语义）
+     * - mode=assign  → source=system（不受 explicit 影响，依赖变化时持续生效）
+     */
+    syncAssignRules(items: FormAssignRuleItem[]): void;
+    get formValues(): any;
+    getFormValuesSnapshot(): any;
+    private getFormValueAtPath;
+    mount(options?: {
+        sync?: boolean;
+    }): void;
+    dispose(): void;
+    isSuppressed(): boolean;
+    handleFormFieldsChange(changedFields: Array<{
+        name?: NamePath | string | number;
+        touched?: boolean;
+    }>): void;
+    handleFormValuesChange(changedValues: any, allValues: any): void;
+    private deriveExplicitPaths;
+    private collectExplicitDiffPaths;
+    private pushExplicitPath;
+    private isPlainObjectValue;
+    private isObjectCleared;
+    setFormValues(callerCtx: any, patch: Patch, options?: SetOptions): Promise<void>;
+    private applyBoundValue;
+    private resolveNamePath;
+    private tryResolveNamePath;
+    private bumpChangeTick;
+    private emitFormValuesChange;
+    private markExplicit;
+    private isExplicit;
+    private findExplicitHit;
+}
+export {};

package/es/flow/models/blocks/form/value-runtime/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type NamePath = Array<string | number>;
+export type ValueSource = 'default' | 'linkage' | 'user' | 'system';
+export type Patch = Record<string, any> | Array<{
+    path: string | NamePath;
+    value: any;
+    condition?: any;
+}>;
+export interface SetOptions {
+    source?: ValueSource;
+    triggerEvent?: boolean;
+    markExplicit?: boolean;
+    txId?: string;
+    /**
+     * linkage 规则定义所在层级，数值越大表示层级越内层。
+     * 仅在 source='linkage' 且 linkageTxId 有效时参与同事务冲突裁决。
+     */
+    linkageScopeDepth?: number;
+    /**
+     * linkage 链路事务 id（通常来自 formValuesChange payload 的 txId）。
+     * 仅在 source='linkage' 时使用。
+     */
+    linkageTxId?: string;
+}
+export interface FormValueWriteMeta {
+    source: ValueSource;
+    writeSeq: number;
+    linkageScopeDepth?: number;
+    linkageTxId?: string;
+}
+export interface FormValuesChangePayload {
+    source: ValueSource;
+    txId: string;
+    /**
+     * linkage 链路根事务 id。
+     * 用于跨事件继续沿用同一 linkage 冲突裁决边界。
+     */
+    linkageTxId?: string;
+    changedPaths: NamePath[];
+    changedValues?: any;
+    allValues?: any;
+    allValuesSnapshot?: any;
+}
+export type AssignMode = 'default' | 'assign';
+export type FormAssignRuleItem = {
+    key?: string;
+    enable?: boolean;
+    /** 赋值目标路径，例如 `title` / `users.nickname` / `user.name` */
+    targetPath?: string;
+    /** 规则级 title field 覆盖（仅当前规则生效，不影响 collection 全局） */
+    valueTitleField?: string;
+    mode?: AssignMode;
+    condition?: any;
+    value?: any;
+};

package/es/flow/models/blocks/form/value-runtime/utils.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.
+ */
+/** Maximum writes per path per transaction to prevent rule oscillation loops */
+export declare const MAX_WRITES_PER_PATH_PER_TX = 20;
+export declare function isEmptyValue(v: any): boolean;
+export declare function createTxId(): string;