@flowgram.ai/form-core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,677 @@
+import React from 'react';
+import { FlowNodeEntity } from '@flowgram.ai/document';
+import { EntityData, PlaygroundContext, EntityDataRegistry } from '@flowgram.ai/core';
+import * as inversify from 'inversify';
+import { ContainerModule } from 'inversify';
+import * as _flowgram_ai_utils from '@flowgram.ai/utils';
+import { Emitter, MaybePromise, Event, DisposableCollection } from '@flowgram.ai/utils';
+
+interface ErrorData {
+    error: Error | null;
+}
+declare class FlowNodeErrorData extends EntityData {
+    static type: string;
+    getDefaultData(): ErrorData;
+    setError(e: ErrorData['error']): void;
+    getError(): Error;
+}
+
+interface NodeErrorRenderProps {
+    error: Error;
+    context: NodeContext;
+}
+type NodeErrorRender = Render<NodeErrorRenderProps>;
+
+declare const ErrorContainerModule: ContainerModule;
+
+declare function getNodeError(node: FlowNodeEntity): Error;
+
+interface NodeContext {
+    node: FlowNodeEntity;
+    playgroundContext: PlaygroundContext;
+}
+type Render<T = any> = (props: T) => any;
+type NodePluginRender = Render<NodeContext>;
+type NodePlaceholderRender = Render<NodeContext>;
+interface NodeRenderProps {
+    node: FlowNodeEntity;
+}
+type NodeRenderHoc = (Component: React.JSXElementConstructor<NodeRenderProps>) => React.JSXElementConstructor<NodeRenderProps>;
+
+declare enum MaterialRenderKey {
+    CustomNodeError = "Material_CustomNodeError"
+}
+declare class NodeManager {
+    readonly materialRenderRegistry: Map<string, Render>;
+    readonly pluginRenderRegistry: Map<string, Render>;
+    readonly nodeRenderHocs: NodeRenderHoc[];
+    protected nodeContributions: NodeContribution[];
+    registerMaterialRender(key: string, render: Render): void;
+    getMaterialRender(key: string): Render | undefined;
+    registerPluginRender(key: string, render: NodePluginRender): void;
+    getPluginRender(key: string): NodePluginRender | undefined;
+    registerNodeErrorRender(render: Render<NodeErrorRenderProps>): void;
+    get nodeRenderHoc(): (...args: any[]) => any;
+    registerNodeRenderHoc(hoc: NodeRenderHoc): void;
+    get nodeErrorRender(): Render | undefined;
+    protected init(): void;
+}
+
+declare const NodeContribution: unique symbol;
+interface NodeContribution {
+    onRegister?(nodeManager: NodeManager): void;
+}
+
+declare const NodeContainerModule: ContainerModule;
+
+declare const PLUGIN_KEY: {
+    FORM: string;
+    ERROR: string;
+};
+
+declare const MATERIAL_KEY: {
+    NODE_ERROR_RENDER: string;
+    NODE_PLACEHOLDER_RENDER: string;
+};
+
+interface INodeEngineContext {
+    readonly: boolean;
+}
+/**
+ * NodeEngineContext 在 Node Engine 中为全局单例, 它的作用是让Node之间共享数据。
+ * context 分为内置context(如 readonly) 和 自定义context(业务可以按需注入)
+ */
+declare class NodeEngineContext {
+    static DEFAULT_READONLY: boolean;
+    static DEFAULT_JSON: {
+        readonly: boolean;
+    };
+    readonly onChangeEmitter: Emitter<NodeEngineContext>;
+    readonly onChange: _flowgram_ai_utils.Event<NodeEngineContext>;
+    private _readonly;
+    private _json;
+    get json(): INodeEngineContext;
+    get readonly(): boolean;
+    set readonly(value: boolean);
+    private fireChange;
+    private updateJSON;
+}
+
+declare class NodeEngine {
+    nodeManager: NodeManager;
+    context: NodeEngineContext;
+}
+
+declare const FormCoreContainerModule: ContainerModule;
+
+interface FormItemAbility {
+    type: string;
+    /**
+     * 注册到formManager时钩子时调用
+     */
+    onAbilityRegister?: () => void;
+}
+interface AbilityClass {
+    type: string;
+    new (): FormItemAbility;
+}
+
+interface IFormItem<T = any> {
+    value: T;
+}
+declare enum FormItemEventName {
+    onFormValueChange = "onFormValueChange",
+    onFormItemInit = "onFormItemInit"
+}
+type FormModelValid = boolean | null;
+type FeedbackStatus = 'error' | 'warning' | 'pending';
+type FeedbackText = string;
+interface FormItemFeedback {
+    feedbackStatus?: FeedbackStatus;
+    feedbackText?: FeedbackText;
+}
+interface FormFeedback {
+    feedbackStatus?: FeedbackStatus;
+    feedbackText?: FeedbackText;
+    path: string;
+}
+interface FormItemDomRef {
+    current: HTMLElement | null;
+}
+
+interface FormItemAbilityMeta<Options = any> {
+    type: string;
+    options: Options;
+}
+/**
+ * @deprecated
+ */
+interface FormItemContext {
+    /**
+     * @deprecated Use context.node instead
+     */
+    formItemMeta: IFormItemMeta;
+    /**
+     * @deprecated
+     */
+    formItem: IFormItem;
+    /**
+     * @deprecated Use context.node instead
+     */
+    flowNodeEntity: FlowNodeEntity;
+    /**
+     * @deprecated Use context.playgroundContext instead
+     */
+    playgroundContext: PlaygroundContext;
+}
+interface FormItemHookParams extends FormItemContext {
+    formItem: IFormItem;
+}
+interface FormItemHooks<T> {
+    /**
+     * FormItem初始化钩子
+     */
+    onInit?: (params: FormItemHookParams & T) => void;
+    /**
+     * FormItem提交时钩子
+     */
+    onSubmit?: (params: FormItemHookParams & T) => void;
+    /**
+     * FormItem克隆时钩子
+     */
+    onClone?: (params: FormItemHookParams & T) => MaybePromise<void>;
+    /**
+     * 克隆后执行的逻辑
+     */
+    afterClone?: (params: FormItemHookParams & T) => void;
+    /**
+     * FormItem全局校验时钩子
+     */
+    onValidate?: (params: FormItemHookParams & T) => void;
+}
+
+type FormDataTypeName = 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+type FormDataType = string | number | boolean | FormDataObject | DataArray | null;
+interface FormDataObject {
+    [key: string]: FormDataType;
+}
+type DataArray = Array<FormDataType>;
+declare const FORM_VOID: "form-void";
+interface TreeNode<T> {
+    name: string;
+    children?: TreeNode<T>[];
+}
+interface IFormItemMeta extends TreeNode<IFormItemMeta> {
+    /**
+     * 表单项名称
+     */
+    name: string;
+    /**
+     * 数据类型
+     */
+    type: FormDataTypeName | typeof FORM_VOID;
+    /**
+     * 枚举值
+     */
+    enum?: FormDataType[];
+    /**
+     * 数组类型item的数据类型描述
+     */
+    items?: IFormItemMeta;
+    /**
+     * 表单项标题
+     */
+    title?: string;
+    /**
+     * 表单项描述
+     */
+    description?: string;
+    /**
+     * 表单项默认值
+     */
+    default?: FormDataType;
+    /**
+     * 是否必填
+     */
+    required?: boolean;
+    /**
+     * 扩展能力
+     */
+    abilities?: FormItemAbilityMeta[];
+    /**
+     * 子表单项
+     */
+    children?: IFormItemMeta[];
+}
+interface IFormMeta {
+    /**
+     * 表单树结构root
+     */
+    root: IFormItemMeta;
+    /**
+     * 表单全局配置
+     */
+    options?: IFormMetaOptions;
+}
+interface NodeFormContext {
+    node: FlowNodeEntity;
+    playgroundContext: PlaygroundContext;
+}
+interface IFormMetaOptions {
+    formatOnInit?: (value: any, context: NodeFormContext) => any;
+    formatOnSubmit?: (value: any, context: NodeFormContext) => any;
+    [key: string]: any;
+}
+interface FormMetaGeneratorParams<PlaygroundContext, FormValue = any> {
+    node: FlowNodeEntity;
+    playgroundContext: PlaygroundContext;
+    initialValue?: FormValue;
+}
+type FormMetaGenerator<PlaygroundContext = any, FormValue = any> = (params: FormMetaGeneratorParams<FormValue, FormValue>) => MaybePromise<IFormMeta>;
+type FormMetaOrFormMetaGenerator = FormMetaGenerator | IFormMeta;
+
+type FormModelFactory = (entity: FlowNodeEntity) => FormModel;
+declare const FormModelFactory: unique symbol;
+declare const FormModelEntity: unique symbol;
+declare abstract class FormModel {
+    readonly onValidate: Event<FormModel>;
+    readonly onValidChange: Event<FormModelValid>;
+    readonly onFeedbacksChange: Event<FormFeedback[]>;
+    readonly onInitialized: Event<FormModel>;
+    protected toDispose: DisposableCollection;
+    /**
+     * @deprecated
+     * use `formModel.node` instead in FormModelV2
+     */
+    abstract get flowNodeEntity(): FlowNodeEntity;
+    /**
+     * @deprecated
+     */
+    abstract get formManager(): FormManager;
+    abstract get formMeta(): IFormMeta;
+    abstract get initialized(): boolean;
+    abstract get valid(): FormModelValid;
+    /**
+     * @deprecated
+     * use `formModel.getFieldIn` instead in FormModelV2 to get the model of a form field
+     * do not use this in FormModelV2 since  it only return an empty Map.
+     */
+    abstract get formItemPathMap(): Map<string, IFormItem>;
+    /**
+     * @deprecated
+     */
+    abstract clearValid(): void;
+    abstract validate(): Promise<boolean>;
+    abstract validateWithFeedbacks(): Promise<FormFeedback[]>;
+    abstract init(formMetaOrFormMetaGenerator: any, initialValue?: any): MaybePromise<void>;
+    abstract toJSON(): any;
+    /**
+     * @deprecated
+     * use `formModel.getField` instead in FormModelV2
+     */
+    abstract getFormItemByPath(path: string): FormItem | undefined;
+    /**
+     * @deprecated
+     * use `formModel.getFieldValue` instead in FormModelV2 to get the model of a form field by path
+     */
+    abstract getFormItemValueByPath<T = any>(path: string): any | undefined;
+    abstract render(): any;
+    abstract dispose(): void;
+}
+
+declare abstract class FormItem {
+    readonly meta: IFormItemMeta;
+    readonly path: string;
+    readonly formModel: FormModel;
+    readonly onInitEventEmitter: Emitter<FormItem>;
+    readonly onInit: _flowgram_ai_utils.Event<FormItem>;
+    protected toDispose: DisposableCollection;
+    readonly onDispose: _flowgram_ai_utils.Event<void>;
+    private _domRef;
+    protected constructor(meta: IFormItemMeta, path: string, formModel: FormModel);
+    abstract get value(): any;
+    abstract set value(value: any);
+    abstract validate(): void;
+    set domRef(domRef: FormItemDomRef);
+    get domRef(): FormItemDomRef;
+    dispose(): void;
+}
+
+interface FormMetaTraverseParams {
+    formItemMeta: IFormItemMeta;
+    parentPath?: string;
+    handle: (params: {
+        formItemMeta: IFormItemMeta;
+        path: string;
+    }) => any;
+}
+declare class FormMeta implements IFormMeta {
+    constructor(root: IFormItemMeta, options: IFormMetaOptions);
+    protected _root: IFormItemMeta;
+    get root(): IFormItemMeta;
+    protected _options: IFormMetaOptions;
+    get options(): IFormMetaOptions;
+    static traverse({ formItemMeta, parentPath, handle }: FormMetaTraverseParams): void;
+}
+
+interface Extension {
+    key: string;
+}
+declare class FormAbilityExtensionRegistry {
+    protected registry: Map<string, Extension>;
+    register(extension: Extension): void;
+    get<T extends Extension>(key: string): T | undefined;
+    get objectMap(): Record<string, Extension>;
+    get collection(): Extension[];
+}
+
+interface FormItemMaterialContext {
+    /**
+     * 当前表单项的meta
+     */
+    meta: IFormItemMeta;
+    /**
+     * 当前表单项的路径
+     */
+    path: string;
+    /**
+     * 节点引擎全局readonly
+     */
+    readonly: boolean;
+    /**
+     * 通过路径获取表单项的值
+     * @param path 表单项在当前表单中的绝对路径，路径协议遵循glob
+     */
+    getFormItemValueByPath: <T>(path: string) => T;
+    /**
+     * 节点表单校验回调函数注册
+     */
+    onFormValidate: FormModel['onValidate'];
+    /**
+     * 获取Node模型
+     */
+    node: FlowNodeEntity;
+    /**
+     * 获取FormModel原始模型
+     */
+    form: FormModel;
+    /**
+     * 业务注入的全局context
+     */
+    playgroundContext: PlaygroundContext;
+    /**
+     * 数组场景下当前项的index
+     */
+    index?: number | undefined;
+}
+
+declare class SetterAbility implements FormItemAbility {
+    static readonly type = "setter";
+    get type(): string;
+}
+
+declare class ValidationAbility implements FormItemAbility {
+    static readonly type = "validation";
+    get type(): string;
+}
+
+interface IValidateResult {
+    type: 'error' | 'warning';
+    message: string;
+}
+type ValidatorFunctionResponse = null | void | undefined | string | boolean | IValidateResult;
+interface ValidationAbilityOptions {
+    /**
+     * 已注册的validator唯一标识
+     */
+    key?: string;
+    /**
+     * 不使用已注册的validator 也支持在options中直接写validator
+     */
+    validator?: ValidatorFunction;
+}
+interface ValidatorProps<T = any, CustomOptions = any> {
+    value: T;
+    options: ValidationAbilityOptions & CustomOptions;
+    context: FormItemMaterialContext;
+}
+type ValidatorFunction = (props: ValidatorProps) => ValidatorFunctionResponse;
+interface ValidationExtension {
+    key: string;
+    validator: ValidatorFunction;
+}
+
+interface SetterAbilityOptions {
+    /**
+     * 已注册的setter的唯一标识
+     */
+    key: string;
+}
+/**
+ * Setter context 是 FormItemMaterialContext 的外观
+ * 基于外观设计模式设计，屏蔽了FormItemMaterialContext中一些setter不可见的接口
+ * readonly: 对于setter 已经放在props 根级别，所以在这里屏蔽，防止干扰
+ * getFormItemValueByPath: setter需通过表单联动方式获取其他表单项的值，不推荐是用这个方法，所以屏蔽
+ */
+type SetterOrDecoratorContext = Omit<FormItemMaterialContext, 'getFormItemValueByPath' | 'readonly'>;
+interface SetterComponentProps<T = any, CustomOptions = any> extends FormItemFeedback, FormItemContext {
+    value: T;
+    onChange: (v: T) => void;
+    /**
+     * 节点引擎全局readonly
+     */
+    readonly: boolean;
+    children?: any;
+    options: SetterAbilityOptions & CustomOptions;
+    context: SetterOrDecoratorContext;
+}
+interface SetterExtension {
+    key: string;
+    component: (props: SetterComponentProps) => any;
+    validator?: ValidatorFunction;
+}
+type SetterHoc = (Component: React.JSXElementConstructor<SetterComponentProps>) => React.JSXElementConstructor<SetterComponentProps>;
+
+declare class DecoratorAbility implements FormItemAbility {
+    static readonly type = "decorator";
+    get type(): string;
+}
+
+interface DecoratorAbilityOptions {
+    /**
+     * 已注册的decorator的唯一标识
+     */
+    key: string;
+}
+interface DecoratorComponentProps<CustomOptions = any> extends FormItemFeedback, FormItemContext {
+    readonly: boolean;
+    children?: any;
+    options: DecoratorAbilityOptions & CustomOptions;
+    context: SetterOrDecoratorContext;
+}
+interface DecoratorExtension {
+    key: string;
+    component: (props: DecoratorComponentProps) => any;
+}
+
+interface VisibilityAbilityOptions {
+    /**
+     * 是否隐藏
+     */
+    hidden: string | boolean;
+    /**
+     * 隐藏是否要清空表单值, 默认为false
+     */
+    clearWhenHidden?: boolean;
+}
+declare class VisibilityAbility implements FormItemAbility {
+    static readonly type = "visibility";
+    get type(): string;
+}
+
+declare class EffectAbility implements FormItemAbility {
+    static readonly type = "effect";
+    get type(): string;
+}
+
+interface EffectAbilityOptions {
+    /**
+     * 已注册的effect 唯一标识
+     */
+    key?: string;
+    /**
+     * 触发 effect 的事件
+     */
+    event?: FormItemEventName;
+    /**
+     * 如果不使用已经注册的effect, 也支持直接写effect函数
+     */
+    effect?: EffectFunction;
+}
+interface EffectEvent {
+    target: any & {
+        value: any;
+    };
+    currentTarget: any;
+    type: FormItemEventName;
+}
+interface EffectProps<CustomOptions = any, Event = EffectEvent> extends FormItemContext {
+    event: Event;
+    options: EffectAbilityOptions & CustomOptions;
+    context: FormItemMaterialContext;
+}
+type EffectFunction = (props: EffectProps) => void;
+interface EffectExtension {
+    key: string;
+    effect: EffectFunction;
+}
+
+declare class DefaultAbility implements FormItemAbility {
+    static readonly type = "default";
+    get type(): string;
+}
+
+interface GetDefaultValueProps extends FormItemContext {
+    options: DefaultAbilityOptions;
+    context: FormItemMaterialContext;
+}
+interface DefaultAbilityOptions<T = any> {
+    getDefaultValue: (params: GetDefaultValueProps) => T;
+}
+
+declare class FormPathService {
+    static readonly ROOT = "/";
+    static readonly DIVIDER = "/";
+    static readonly RELATIVE_PARENT = "..";
+    static readonly RELATIVE_CURRENT = ".";
+    static readonly ARRAY = "[]";
+    static normalize(path: string): string;
+    static join(paths: string[]): string;
+    static toArrayPath(path: string): string;
+    static parseArrayItemPath(path: string): {
+        itemIndex: number;
+        arrayPath: string;
+        itemMetaPath: string;
+    } | null;
+    simplify(path: string): string;
+}
+
+declare class FormContextMaker {
+    readonly nodeEngineContext: NodeEngineContext;
+    readonly playgroundContext: PlaygroundContext;
+    makeFormItemMaterialContext(formItem: FormItem, options?: {
+        getIndex: () => number | undefined;
+    }): FormItemMaterialContext;
+}
+
+declare class FormManager {
+    readonly abilityRegistry: Map<string, FormItemAbility>;
+    readonly setterHocs: SetterHoc[];
+    readonly extensionRegistryMap: Map<string, FormAbilityExtensionRegistry>;
+    readonly pathManager: FormPathService;
+    readonly formContextMaker: FormContextMaker;
+    readonly playgroundContext: PlaygroundContext;
+    protected formContributions: FormContribution[];
+    get components(): Record<string, any>;
+    get decorators(): Record<string, any>;
+    registerAbilityExtension(type: string, extension: any): void;
+    getAbilityExtension(abilityType: string, extensionKey: string): any;
+    registerAbility(Ability: AbilityClass): void;
+    registerAbilities(Abilities: AbilityClass[]): void;
+    getAbility<ExtendAbility>(type: string): (FormItemAbility & ExtendAbility) | undefined;
+    /**
+     * @deprecated
+     * Setter Hoc and setter are no longer supported in NodeEngineV2
+     * @param hoc
+     */
+    registerSetterHoc(hoc: SetterHoc): void;
+    protected init(): void;
+}
+
+declare const FormContribution: unique symbol;
+interface FormContribution {
+    onRegister?(formManager: FormManager): void;
+}
+
+interface Options {
+    formModelFactory: FormModelFactory;
+}
+interface DetailChangeEvent {
+    path: string;
+    oldValue: any;
+    value: any;
+    initialized: boolean;
+}
+interface OnFormValuesChangePayload {
+    values: any;
+    prevValues: any;
+    name: string;
+}
+declare class FlowNodeFormData extends EntityData {
+    static type: string;
+    readonly formModel: FormModel;
+    protected flowNodeEntity: FlowNodeEntity;
+    /**
+     * @deprecated rehaje 版表单form Values change 事件
+     * @protected
+     */
+    protected onDetailChangeEmitter: Emitter<DetailChangeEvent>;
+    /**
+     * @deprecated 该方法为旧版引擎（rehaje）表单数据变更事件, 新版节点引擎请使用
+     * this.getFormModel<FormModelV2>().onFormValuesChange.
+     * @protected
+     */
+    readonly onDetailChange: _flowgram_ai_utils.Event<DetailChangeEvent>;
+    constructor(entity: FlowNodeEntity, opts: Options);
+    getFormModel<TFormModel>(): TFormModel;
+    getDefaultData(): any;
+    createForm(formMetaOrFormMetaGenerator: any, initialValue?: any): void;
+    recreateForm(formMetaOrFormMetaGenerator: FormMetaOrFormMetaGenerator, initialValue?: any): void;
+    toJSON(): any;
+    dispose(): void;
+    /**
+     * @deprecated rehaje 版表单form Values change 事件触发函数
+     * @protected
+     */
+    fireDetaiChange(detailChangeEvent: DetailChangeEvent): void;
+}
+
+declare function isNodeFormReady(node: FlowNodeEntity): boolean;
+declare function getFormModel(node: FlowNodeEntity): FormModel;
+
+declare function createNodeContainerModules(): inversify.ContainerModule[];
+
+declare const NodeRender: React.MemoExoticComponent<({ node }: NodeRenderProps) => React.JSX.Element>;
+
+declare function registerNodeErrorRender(nodeManager: NodeManager, render: Render): void;
+declare function registerNodePlaceholderRender(nodeManager: NodeManager, render: NodePlaceholderRender): void;
+
+declare function createNodeEntityDatas(): EntityDataRegistry[];
+
+declare function useNodeEngineContext(): NodeEngineContext;
+
+declare function useFormItem(path: string): IFormItem | undefined;
+
+declare const NodeEngineReactContext: React.Context<INodeEngineContext>;
+
+export { type AbilityClass, type DataArray, DecoratorAbility, type DecoratorAbilityOptions, type DecoratorComponentProps, type DecoratorExtension, DefaultAbility, type DefaultAbilityOptions, type DetailChangeEvent, EffectAbility, type EffectAbilityOptions, type EffectEvent, type EffectExtension, type EffectFunction, type EffectProps, ErrorContainerModule, type ErrorData, type Extension, FORM_VOID, type FeedbackStatus, type FeedbackText, FlowNodeErrorData, FlowNodeFormData, FormAbilityExtensionRegistry, FormContextMaker, FormContribution, FormCoreContainerModule, type FormDataObject, type FormDataType, type FormDataTypeName, type FormFeedback, FormItem, type FormItemAbility, type FormItemAbilityMeta, type FormItemContext, type FormItemDomRef, FormItemEventName, type FormItemFeedback, type FormItemHookParams, type FormItemHooks, type FormItemMaterialContext, FormManager, FormMeta, type FormMetaGenerator, type FormMetaGeneratorParams, type FormMetaOrFormMetaGenerator, type FormMetaTraverseParams, FormModel, FormModelEntity, FormModelFactory, type FormModelValid, FormPathService, type GetDefaultValueProps, type IFormItem, type IFormItemMeta, type IFormMeta, type IFormMetaOptions, type INodeEngineContext, type IValidateResult, MATERIAL_KEY, MaterialRenderKey, NodeContainerModule, type NodeContext, NodeContribution, NodeEngine, NodeEngineContext, NodeEngineReactContext, type NodeErrorRender, type NodeErrorRenderProps, type NodeFormContext, NodeManager, type NodePlaceholderRender, type NodePluginRender, NodeRender, type NodeRenderHoc, type NodeRenderProps, type OnFormValuesChangePayload, PLUGIN_KEY, type Render, SetterAbility, type SetterAbilityOptions, type SetterComponentProps, type SetterExtension, type SetterHoc, type SetterOrDecoratorContext, type TreeNode, ValidationAbility, type ValidationAbilityOptions, type ValidationExtension, type ValidatorFunction, type ValidatorFunctionResponse, type ValidatorProps, VisibilityAbility, type VisibilityAbilityOptions, createNodeContainerModules, createNodeEntityDatas, getFormModel, getNodeError, isNodeFormReady, registerNodeErrorRender, registerNodePlaceholderRender, useFormItem, useNodeEngineContext };