@flowgram.ai/node 0.1.0-alpha.10

package/dist/index.d.ts

@@ -0,0 +1,366 @@
+import * as React from 'react';
+import React__default from 'react';
+import { FormModel, OnFormValuesChangePayload, FormModelValid, FormFeedback, FormManager, IFormItem, FormItem, NodeFormContext, IFormMeta } from '@flowgram.ai/form-core';
+import { FieldName as FieldName$1, FieldValue as FieldValue$1, Errors, Warnings } from '@flowgram.ai/form/src/types';
+import { FormValidateReturn, FormControl, FormModel as FormModel$1, FieldValue, IFieldArray, IField, FieldName, Validate as Validate$1, IForm, FormRenderProps, ValidateTrigger, FormState } from '@flowgram.ai/form';
+import * as _flowgram_ai_document from '@flowgram.ai/document';
+import { FlowNodeEntity } from '@flowgram.ai/document';
+import * as _flowgram_ai_utils from '@flowgram.ai/utils';
+import { Disposable, Emitter, DisposableCollection, Event } from '@flowgram.ai/utils';
+
+declare class FormModelV2 extends FormModel implements Disposable {
+    protected effectMap: Record<string, EffectOptions[]>;
+    protected effectReturnMap: Map<DataEvent, Record<string, EffectReturn>>;
+    protected plugins: FormPlugin[];
+    protected node: FlowNodeEntity;
+    protected formFeedbacks: FormValidateReturn | undefined;
+    protected onInitializedEmitter: Emitter<FormModel>;
+    protected onValidateEmitter: Emitter<FormModel>;
+    readonly onValidate: _flowgram_ai_utils.Event<FormModel>;
+    readonly onInitialized: _flowgram_ai_utils.Event<FormModel>;
+    protected onDisposeEmitter: Emitter<void>;
+    readonly onDispose: _flowgram_ai_utils.Event<void>;
+    protected toDispose: DisposableCollection;
+    protected onFormValuesChangeEmitter: Emitter<OnFormValuesChangePayload>;
+    readonly onFormValuesChange: _flowgram_ai_utils.Event<OnFormValuesChangePayload>;
+    protected onValidChangeEmitter: Emitter<FormModelValid>;
+    readonly onValidChange: _flowgram_ai_utils.Event<FormModelValid>;
+    protected onFeedbacksChangeEmitter: Emitter<FormFeedback[]>;
+    readonly onFeedbacksChange: _flowgram_ai_utils.Event<FormFeedback[]>;
+    constructor(node: FlowNodeEntity);
+    protected _valid: FormModelValid;
+    get valid(): FormModelValid;
+    private set valid(value);
+    get flowNodeEntity(): FlowNodeEntity;
+    get formManager(): FormManager;
+    protected _formControl?: FormControl<any>;
+    get formControl(): FormControl<any> | undefined;
+    protected _formMeta: FormMeta;
+    get formMeta(): FormMeta;
+    get values(): any;
+    protected _feedbacks: FormFeedback[];
+    get feedbacks(): FormFeedback[];
+    updateFormValues(value: any): void;
+    private set feedbacks(value);
+    get formItemPathMap(): Map<string, IFormItem>;
+    protected _initialized: boolean;
+    get initialized(): boolean;
+    get nodeContext(): {
+        node: FlowNodeEntity;
+        playgroundContext: unknown;
+        clientContext: unknown;
+    };
+    get nativeFormModel(): FormModel$1 | undefined;
+    render(): React.JSX.Element;
+    initPlugins(plugins: FormPlugin[]): void;
+    init(formMeta: FormMeta, rawInitialValues?: any): void;
+    toJSON(): any;
+    clearValid(): void;
+    validate(): Promise<boolean>;
+    getValues<T = any>(): T | undefined;
+    getField<TValue = FieldValue, TField extends IFieldArray<TValue> | IField<TValue> = IField<TValue>>(name: FieldName): TField | undefined;
+    getValueIn<TValue>(name: FieldName): TValue | undefined;
+    setValueIn(name: FieldName, value: any): void;
+    /**
+     * 监听表单某个路径下的值变化
+     * @param name 路径
+     * @param callback 回调函数
+     */
+    onFormValueChangeIn<TValue = FieldValue, TFormValue = FieldValue>(name: FieldName, callback: (payload: onFormValueChangeInPayload<TValue, TFormValue>) => void): Disposable;
+    /**
+     * @deprecated 该方法用于兼容 V1 版本 FormModel接口，如果确定是FormModelV2 请使用 FormModel.getValueIn
+     * @param path glob path
+     */
+    getFormItemValueByPath(globPath: string): any;
+    validateWithFeedbacks(): Promise<FormFeedback[]>;
+    /**
+     * @deprecated 该方法用于兼容 V1 版本 FormModel接口，如果确定是FormModelV2, 请使用FormModel.getValueIn 和 FormModel.setValueIn
+     * @param path glob path
+     */
+    getFormItemByPath(path: string): FormItem | undefined;
+    dispose(): void;
+}
+
+interface FormPluginConfig<Opts = any> {
+    /**
+     * form plugin name, for debug use
+     */
+    name?: string;
+    /**
+     * setup formMeta
+     * @param ctx
+     * @returns
+     */
+    onSetupFormMeta?: (ctx: FormPluginSetupMetaCtx, opts: Opts) => void;
+    /**
+     * FormModel 初始化时执行
+     * @param ctx
+     */
+    onInit?: (ctx: FormPluginCtx, opts: Opts) => void;
+    /**
+     * FormModel 销毁时执行
+     */
+    onDispose?: (ctx: FormPluginCtx, opts: Opts) => void;
+}
+declare class FormPlugin<Opts = any> implements Disposable {
+    readonly name: string;
+    readonly pluginId: string;
+    readonly config: FormPluginConfig;
+    readonly opts?: Opts;
+    protected _formModel: FormModelV2;
+    constructor(config: FormPluginConfig, opts?: Opts);
+    get formModel(): FormModelV2;
+    get ctx(): {
+        formModel: FormModelV2;
+        node: _flowgram_ai_document.FlowNodeEntity;
+        playgroundContext: unknown;
+    };
+    setupFormMeta(formMeta: FormMeta, nodeContext: NodeFormContext): FormMeta;
+    init(formModel: FormModelV2): void;
+    dispose(): void;
+}
+type FormPluginCreator<Opts> = (opts: Opts) => FormPlugin<Opts>;
+declare function defineFormPluginCreator<Opts>(config: FormPluginConfig): FormPluginCreator<Opts>;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface Node {
+}
+interface Flow {
+}
+/**
+ * NodeContext contains
+ * - node: the Editor's node entity.
+ * - playgroundContext: the Editor's playgroundContext injected when initiate the Editor.
+ */
+type NodeContext = NodeFormContext;
+type Validate<TFieldValue = any, TFormValues = any> = (props: {
+    value: TFieldValue;
+    formValues: TFormValues;
+    context: NodeContext;
+    name: FieldName$1;
+}) => ReturnType<Validate$1<TFieldValue, TFormValues>>;
+declare enum DataEvent {
+    onValueChange = "onValueChange",
+    /**
+     * When value Init，it triggers when
+     * - defaultValue is configured in formMeta, it will trigger when form is initializing.
+     * - defaultValue is configured in Field, it will trigger when this Field is initializing if no initial value is set to this field.
+     */
+    onValueInit = "onValueInit",
+    /**
+     * When Value Init or change
+     */
+    onValueInitOrChange = "onValueInitOrChange",
+    onArrayAppend = "onArrayAppend",
+    onArrayDelete = "onArrayDelete"
+}
+type EffectReturn = () => void;
+interface EffectFuncProps<TFieldValue = any, TFormValues = any> {
+    name: FieldName$1;
+    value: TFieldValue;
+    prevValue?: TFieldValue;
+    formValues: TFormValues;
+    form: IForm;
+    context: NodeContext;
+}
+type Effect<TFieldValue = any, TFormValues = any> = (props: EffectFuncProps<TFieldValue, TFormValues>) => void | EffectReturn;
+type ArrayAppendEffect<TFieldValue = any, TFormValues = any> = (props: {
+    index: number;
+    value: TFieldValue;
+    arrayValues: Array<TFieldValue>;
+    formValues: TFormValues;
+    form: IForm;
+    context: NodeContext;
+}) => void | EffectReturn;
+type ArrayDeleteEffect<TFieldValue = any, TFormValues = any> = (props: {
+    index: number;
+    arrayValue: Array<TFieldValue>;
+    formValues: TFormValues;
+    form: IForm;
+    context: NodeContext;
+}) => void | EffectReturn;
+type EffectOptions = {
+    effect: Effect;
+    event: DataEvent;
+} | {
+    effect: ArrayAppendEffect;
+    event: DataEvent;
+} | {
+    effect: ArrayDeleteEffect;
+    event: DataEvent;
+};
+interface FormMeta<TValues = any> {
+    /**
+     * The render method of the node form content. <Form /> is already integrated, so you don't need to wrap your components with <Form />
+     * @param props
+     */
+    render: (props: FormRenderProps<any>) => React.ReactElement;
+    /**
+     * When to trigger the validation.
+     */
+    validateTrigger?: ValidateTrigger;
+    /**
+     * Form data's validation rules. It's a key value map, where the key is a pattern of data's path (or field name), the value is a validate function.
+     */
+    validate?: Record<FieldName$1, Validate>;
+    /**
+     * Form data's effects. It's a key value map, where the key is a pattern of data's path (or field name), the value is an array of effect configuration.
+     */
+    effect?: Record<FieldName$1, EffectOptions[]>;
+    /**
+     * Form data's complete default value. it will not be sent to formatOnInit, but used directly as form's value when needed.
+     */
+    defaultValues?: TValues | ((context: NodeContext) => TValues);
+    /**
+     * This function is to format the value when initiate the form, the returned value will be used as the initial value of the form.
+     * @param value value input to node as initialValue.
+     * @param context
+     */
+    formatOnInit?: (value: any, context: NodeContext) => any;
+    /**
+     * This function is to format the value when FormModel.toJSON is called, the returned value will be used as the final value to be saved .
+     * @param value value sent by form before format.
+     * @param context
+     */
+    formatOnSubmit?: (value: any, context: NodeContext) => any;
+    /**
+     * Form's plugins
+     */
+    plugins?: FormPlugin[];
+}
+declare function isFormModelV2(fm: FormModel | FormModelV2): fm is FormModelV2;
+declare function isFormMetaV2(formMeta: IFormMeta | FormMeta): boolean;
+type FormPluginCtx = {
+    formModel: FormModelV2;
+} & NodeContext;
+type FormPluginSetupMetaCtx = {
+    mergeEffect: (effect: Record<string, EffectOptions[]>) => void;
+    mergeValidate: (validate: Record<FieldName$1, Validate>) => void;
+    addFormatOnInit: (formatOnInit: FormMeta['formatOnInit']) => void;
+    addFormatOnSubmit: (formatOnSubmit: FormMeta['formatOnSubmit']) => void;
+} & NodeContext;
+interface onFormValueChangeInPayload<TValue = FieldValue$1, TFormValues = FieldValue$1> {
+    value: TValue;
+    prevValue: TValue;
+    formValues: TFormValues;
+    prevFormValues: TFormValues;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare function isFormV2(node: FlowNodeEntity): boolean;
+declare function createEffectOptions<T>(event: DataEvent, effect: T): {
+    effect: T;
+    event: DataEvent;
+};
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Listen to Form's values and refresh the React component.
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+declare function useWatchFormValues<T = any>(node: FlowNodeEntity): T | undefined;
+/**
+ * Listen to Form's value in a certain path and refresh the React component.
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+declare function useWatchFormValueIn<T = any>(node: FlowNodeEntity, name: string): T | undefined;
+/**
+ * Listen to FormModel's initialization and refresh React component.
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+declare function useInitializedFormModel(node: FlowNodeEntity): FormModelV2;
+/**
+ * Get Form's state, Form State is a proxy, it will refresh the React component when the value you accessed changed
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+declare function useWatchFormState(node: FlowNodeEntity): FormState | undefined;
+/**
+ * Get Form's errors, Form errors is a proxy, it will refresh the React component when the value you accessed changed
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+declare function useWatchFormErrors(node: FlowNodeEntity): Errors | undefined;
+/**
+ * Get Form's warnings, Form warnings is a proxy, it will refresh the React component when the value you accessed changed
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+declare function useWatchFormWarnings(node: FlowNodeEntity): Warnings | undefined;
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+interface NodeFormProps<TValues> {
+    /**
+     * The initialValues of the form.
+     */
+    initialValues: TValues;
+    /**
+     * Form values. Returns a deep copy of the data in the store.
+     */
+    values: TValues;
+    /**
+     * Form state
+     */
+    state: FormState;
+    /**
+     * Get value in certain path
+     * @param name path
+     */
+    getValueIn<TValue = FieldValue>(name: FieldName): TValue;
+    /**
+     * Set value in certain path.
+     * It will trigger the re-rendering of the Field Component if a Field is related to this path
+     * @param name path
+     */
+    setValueIn<TValue>(name: FieldName, value: TValue): void;
+    /**
+     * set form values
+     */
+    updateFormValues(values: any): void;
+    /**
+     * Render form
+     */
+    render: () => React__default.ReactNode;
+    /**
+     * Form value change event
+     */
+    onFormValuesChange: Event<OnFormValuesChangePayload>;
+    /**
+     * Trigger form validate
+     */
+    validate: () => Promise<boolean>;
+    /**
+     * Form validate event
+     */
+    onValidate: Event<FormState>;
+    /**
+     * Form field value change event
+     */
+    onFormValueChangeIn<TValue = FieldValue, TFormValue = FieldValue>(name: FieldName, callback: (payload: onFormValueChangeInPayload<TValue, TFormValue>) => void): Disposable;
+}
+/**
+ * Only support FormModelV2
+ * @param node
+ */
+declare function getNodeForm<TValues = FieldValue>(node: FlowNodeEntity): NodeFormProps<TValues> | undefined;
+
+export { type ArrayAppendEffect, type ArrayDeleteEffect, DataEvent, type Effect, type EffectFuncProps, type EffectOptions, type EffectReturn, type Flow, type FormMeta, FormModelV2, FormPlugin, type FormPluginConfig, type FormPluginCreator, type FormPluginCtx, type FormPluginSetupMetaCtx, type Node, type NodeFormProps, type Validate, createEffectOptions, defineFormPluginCreator, getNodeForm, isFormMetaV2, isFormModelV2, isFormV2, type onFormValueChangeInPayload, useInitializedFormModel, useWatchFormErrors, useWatchFormState, useWatchFormValueIn, useWatchFormValues, useWatchFormWarnings };