@flowgram.ai/form 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,655 @@
+import * as React from 'react';
+import React__default from 'react';
+import * as _flowgram_ai_utils from '@flowgram.ai/utils';
+import { MaybePromise, Disposable, Emitter, DisposableCollection } from '@flowgram.ai/utils';
+import { ReactiveState } from '@flowgram.ai/reactive';
+
+type Context = any;
+
+declare enum FeedbackLevel {
+    Error = "error",
+    Warning = "warning"
+}
+interface Feedback<FeedbackLevel> {
+    /**
+     * The data path (or field path) that generate this feedback
+     */
+    name: string;
+    /**
+     * The type of the feedback
+     */
+    type?: string;
+    /**
+     * Feedback level
+     */
+    level: FeedbackLevel;
+    /**
+     * Feedback message
+     */
+    message: string;
+}
+type FieldError = Feedback<FeedbackLevel.Error>;
+type FieldWarning = Feedback<FeedbackLevel.Warning>;
+type FormErrorOptions = Omit<FieldError, 'name'>;
+type FormWarningOptions = Omit<FieldWarning, 'name'>;
+type Validate<TFieldValue = any, TFormValues = any> = (props: {
+    /**
+     * Value of the data to validate
+     */
+    value: TFieldValue;
+    /**
+     * Complete form values
+     */
+    formValues: TFormValues;
+    /**
+     * The path of the data we are validating
+     */
+    name: FieldName;
+    /**
+     * The custom context set when init form
+     */
+    context: Context;
+}) => MaybePromise<string> | MaybePromise<FormErrorOptions> | MaybePromise<FormWarningOptions> | MaybePromise<undefined>;
+type Errors = Record<FieldName, FieldError[]>;
+type Warnings = Record<FieldName, FieldWarning[]>;
+declare enum ValidateTrigger {
+    onChange = "onChange",
+    onBlur = "onBlur"
+}
+type FormValidateReturn = (FieldError | FieldWarning)[];
+
+declare class Path {
+    protected _path: string[];
+    constructor(path: string | string[]);
+    get parent(): Path | undefined;
+    toString(): string;
+    get value(): string[];
+    /**
+     * 仅计直系child
+     * @param path
+     */
+    isChild(path: string): boolean;
+    /**
+     * 比较两个数组path大小
+     * 返回小于0则path1<path2, 大于0 则path1>path2, 等于0则相等
+     * @param path1
+     * @param path2
+     */
+    static compareArrayPath(path1: Path, path2: Path): number | void;
+    isChildOrGrandChild(path: string): boolean;
+    getArrayIndex(parent: Path): number;
+    concat(name: number | string): Path;
+    replaceParent(parent: Path, newParent: Path): Path;
+}
+
+declare class Store<TValues = FieldValue> {
+    protected _values: TValues;
+    get values(): TValues;
+    setInitialValues<TValue = FieldValue>(values: TValues): void;
+    setIn<TValue = FieldValue>(path: Path, value: TValue): void;
+    getIn<TValue = FieldValue>(path: Path): TValue;
+    dispose(): void;
+}
+
+interface OnValueChangePayload<TValue> {
+    value: TValue | undefined;
+    prevValue: TValue | undefined;
+    formValues: any;
+    prevFormValues: any;
+}
+declare class FieldModel<TValue extends FieldValue = FieldValue> implements Disposable {
+    readonly onValueChangeEmitter: Emitter<OnValueChangePayload<TValue>>;
+    readonly form: FormModel;
+    readonly id: string;
+    readonly onValueChange: _flowgram_ai_utils.Event<OnValueChangePayload<TValue>>;
+    protected toDispose: DisposableCollection;
+    protected _ref?: Ref;
+    protected _path: Path;
+    protected _state: ReactiveState<FieldModelState>;
+    /**
+     * @deprecated
+     * 原用于直接给field 设置validate 逻辑，现将该逻辑放到form._options.validate 中设置，该字段暂时弃用
+     */
+    originalValidate?: Validate;
+    protected _renderCount: number;
+    constructor(path: Path, form: FormModel);
+    protected _mount: boolean;
+    get renderCount(): number;
+    set renderCount(n: number);
+    private initState;
+    get path(): Path;
+    get name(): FieldName;
+    set name(name: FieldName);
+    get ref(): Ref | undefined;
+    set ref(ref: Ref | undefined);
+    get state(): FieldModelState;
+    get reactiveState(): ReactiveState<FieldModelState>;
+    get value(): TValue | undefined;
+    set value(value: TValue | undefined);
+    updateNameForLeafState(newName: string): void;
+    /**
+     * @deprecated
+     * @param validate
+     * @param from
+     */
+    updateValidate(validate: Validate | undefined, from?: 'ui'): void;
+    bubbleState(): void;
+    clearState(): void;
+    get children(): FieldModel[];
+    get parent(): FieldModel | undefined;
+    clear(): void;
+    validate(): Promise<void>;
+    validateSelf(): Promise<void>;
+    protected _runAsyncValidate(): Promise<{
+        errors?: FieldError[];
+        warnings?: FieldWarning[];
+    }>;
+    updateState(s: Partial<FieldModel>): void;
+    dispose(): void;
+    onDispose(fn: () => void): void;
+}
+
+declare class FieldArrayModel<TValue = FieldValue> extends FieldModel<Array<TValue>> {
+    protected onAppendEmitter: Emitter<{
+        index: number;
+        value: TValue | undefined;
+        arrayValue: Array<TValue>;
+    }>;
+    readonly onAppend: _flowgram_ai_utils.Event<{
+        index: number;
+        value: TValue | undefined;
+        arrayValue: Array<TValue>;
+    }>;
+    protected onDeleteEmitter: Emitter<{
+        arrayValue: Array<TValue> | undefined;
+        index: number;
+    }>;
+    readonly onDelete: _flowgram_ai_utils.Event<{
+        arrayValue: Array<TValue> | undefined;
+        index: number;
+    }>;
+    get children(): FieldModel<any>[];
+    map<T>(cb: (f: FieldModel, index: number, arr: FieldModel[]) => T): T[];
+    append(value?: TValue): FieldModel<any>;
+    /**
+     * 删除数组项，该操作会删除数组项的值并销毁数组项的Field模型
+     * @param index
+     */
+    delete(index: number): void;
+    _splice(start: number, deleteCount?: number): void;
+    swap(from: number, to: number): void;
+    move(from: number, to: number): void;
+}
+
+declare class FormModel<TValues = any> implements Disposable {
+    protected _fieldMap: Map<string, FieldModel>;
+    readonly store: Store<any>;
+    protected _options: FormOptions;
+    protected onFieldModelCreateEmitter: Emitter<FieldModel<any>>;
+    readonly onFieldModelCreate: _flowgram_ai_utils.Event<FieldModel<any>>;
+    readonly onFormValuesChangeEmitter: Emitter<OnFormValuesChangePayload>;
+    readonly onFormValuesChange: _flowgram_ai_utils.Event<OnFormValuesChangePayload>;
+    readonly onFormValuesInitEmitter: Emitter<OnFormValuesInitPayload>;
+    readonly onFormValuesInit: _flowgram_ai_utils.Event<OnFormValuesInitPayload>;
+    readonly onFormValuesUpdatedEmitter: Emitter<OnFormValuesUpdatedPayload>;
+    readonly onFormValuesUpdated: _flowgram_ai_utils.Event<OnFormValuesUpdatedPayload>;
+    readonly onValidateEmitter: Emitter<FormModelState>;
+    readonly onValidate: _flowgram_ai_utils.Event<FormModelState>;
+    protected _state: ReactiveState<FormModelState>;
+    protected _initialized: boolean;
+    set fieldMap(map: Map<string, FieldModel<any>>);
+    /**
+     * 表单初始值，初始化设置后不可修改
+     * @protected
+     */
+    get fieldMap(): Map<string, FieldModel<any>>;
+    get context(): any;
+    get initialValues(): any;
+    get values(): any;
+    get validationTrigger(): ValidateTrigger | undefined;
+    get state(): FormModelState;
+    get reactiveState(): ReactiveState<FormModelState>;
+    get fields(): FieldModel[];
+    updateState(state: Partial<FormState>): void;
+    get initialized(): boolean;
+    fireOnFormValuesChange(payload: OnFormValuesChangePayload): void;
+    fireOnFormValuesInit(payload: OnFormValuesInitPayload): void;
+    init(options: FormOptions<TValues>): void;
+    createField<TValue = FieldValue>(name: FieldName, isArray?: boolean): FieldModel<TValue>;
+    createFieldArray<TValue = FieldValue>(name: FieldName, value?: Array<TValue>): FieldArrayModel<TValue>;
+    /**
+     * 销毁Field 模型和子模型,但不会删除field的值
+     * @param name
+     */
+    disposeField(name: string): void;
+    /**
+     * 删除field, 会删除值和 Field 模型， 以及对应的子模型
+     * @param name
+     */
+    deleteField(name: string): void;
+    getField<TFieldModel extends FieldModel | FieldArrayModel = FieldModel>(name: FieldName): TFieldModel | undefined;
+    getValueIn<TValue>(name: FieldName): TValue;
+    setValueIn<TValue>(name: FieldName, value: TValue): void;
+    setInitValueIn<TValue = any>(name: FieldName, value: TValue): void;
+    clearValueIn(name: FieldName): void;
+    validateIn(name: FieldName): Promise<string | FormErrorOptions | FormWarningOptions | undefined>;
+    validate(): Promise<FormValidateReturn>;
+    dispose(): void;
+}
+
+interface FormState {
+    /**
+     * If the form data is valid
+     */
+    invalid: boolean;
+    /**
+     * If the form data is different from the intialValues
+     */
+    isDirty: boolean;
+    /**
+     * If the form fields have been touched
+     */
+    isTouched: boolean;
+    /**
+     * If the form is during validation
+     */
+    isValidating: boolean;
+    /**
+     * Form errors
+     */
+    errors?: Errors;
+    /**
+     * Form warnings
+     */
+    warnings?: Warnings;
+}
+interface FormModelState extends Omit<FormState, 'errors' | 'warnings'> {
+    errors?: Errors;
+    warnings?: Warnings;
+}
+interface FormOptions<TValues = any> {
+    /**
+     * InitialValues of the form.
+     */
+    initialValues?: TValues;
+    /**
+     * When should the validation trigger, for example onChange or onBlur.
+     */
+    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<string, Validate>;
+    /**
+     * Custom context. It will be accessible via form instance or in validate function.
+     */
+    context?: Context;
+}
+interface Form$1<TValues = any> {
+    /**
+     * 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;
+}
+interface FormRenderProps<TValues> {
+    /**
+     * Form instance.
+     */
+    form: Form$1<TValues>;
+}
+interface FormControl<TValues> {
+    _formModel: FormModel<TValues>;
+    getField: <TValue = FieldValue, TField extends Field$1<TValue> | FieldArray$1<TValue> = Field$1<TValue>>(name: FieldName) => Field$1<TValue> | FieldArray$1<TValue> | undefined;
+    /** 手动初始化form */
+    init: () => void;
+}
+interface CreateFormReturn<TValues> {
+    form: Form$1<TValues>;
+    control: FormControl<TValues>;
+}
+interface OnFormValuesChangeOptions {
+    action?: 'array-append' | 'array-splice';
+    indexes?: number[];
+}
+interface OnFormValuesChangePayload {
+    values: FieldValue;
+    prevValues: FieldValue;
+    name: FieldName;
+    options?: OnFormValuesChangeOptions;
+}
+interface OnFormValuesInitPayload {
+    values: FieldValue;
+    prevValues: FieldValue;
+    name: FieldName;
+}
+interface OnFormValuesUpdatedPayload {
+    values: FieldValue;
+    prevValues: FieldValue;
+    name: FieldName;
+    options?: OnFormValuesChangeOptions;
+}
+
+type FieldValue = any;
+type FieldName = string;
+type CustomElement = Partial<HTMLElement> & {
+    name: FieldName;
+    type?: string;
+    value?: any;
+    disabled?: boolean;
+    checked?: boolean;
+    options?: HTMLOptionsCollection;
+    files?: FileList | null;
+    focus?: () => void;
+};
+type FieldElement = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | CustomElement;
+type Ref = FieldElement;
+/**
+ * Field render model, it's only available when Field is rendered
+ */
+interface Field$1<TFieldValue extends FieldValue = FieldValue, E = React__default.ChangeEvent<any> | TFieldValue> {
+    /**
+     * Uniq key for the Field, you can use it for the child react component's uniq key.
+     */
+    key: string;
+    /**
+     * A function which sends the input's value to Field.
+     * It should be assigned to the onChange prop of the input component
+     * @param e It can be the new value of the field or the event sent by original dom input or checkbox component.
+     */
+    onChange: (e: E) => void;
+    /**
+     * The current value of Field
+     */
+    value: TFieldValue;
+    /**
+     * Field's name (path)
+     */
+    name: FieldName;
+    /**
+     * A function which sends the input's onFocus event to Field. It should be assigned to the input's onFocus prop.
+     */
+    onFocus?: () => void;
+    /**
+     * A function which sends the input's onBlur event to Field. It should be assigned to the input's onBlur prop.
+     */
+    onBlur?: () => void;
+}
+/**
+ * FieldArray render model, it's only available when FieldArray is rendered
+ */
+interface FieldArray$1<TFieldValue extends FieldValue = FieldValue> extends Field$1<Array<TFieldValue> | undefined, Array<TFieldValue> | undefined> {
+    /**
+     * Same as native Array.map, the first param of the callback function is the child field of this FieldArray.
+     * @param cb callback function
+     */
+    map: <T = any>(cb: (f: Field$1, index: number) => T) => T[];
+    /**
+     * Append a value at the end of the array, it will create a new Field for this value as well.
+     * @param value the value to append
+     */
+    append: (value: TFieldValue) => Field$1<TFieldValue>;
+    /**
+     * Delete the value and the related field at certain index of the array.
+     * @param index the index of the element to delete
+     */
+    delete: (index: number) => void;
+    /**
+     * Move an array element from one position to another.
+     * @param from from position
+     * @param to to position
+     */
+    move: (from: number, to: number) => void;
+    /**
+     * Swap the position of two elements of the array.
+     * @param from
+     * @param to
+     */
+    swap: (from: number, to: number) => void;
+}
+interface FieldOptions<TValue, TFormValues = any> {
+    /**
+     * Field's name(path), it should be uniq within a form instance.
+     * Two Fields Rendered with the same name will link to the same part of data and field status such as errors is shared.
+     */
+    name: FieldName;
+    /**
+     * Default value of the field. Please notice that Field is a render model, so this default value will only be set when
+     * the field is rendered. If you want to give a default value before field rendering, please set it in the Form's defaultValue.
+     */
+    defaultValue?: TValue;
+    /**
+     * This is a render prop. A function that returns a React element and provides the ability to attach events and value into the component.
+     * This simplifies integrating with external controlled components with non-standard prop names. Provides field、fieldState and formState, to the child component.
+     * @param props
+     */
+    render?: (props: FieldRenderProps<TValue>) => React__default.ReactElement;
+}
+interface FieldRenderProps<TValue> {
+    field: Field$1<TValue>;
+    fieldState?: Readonly<FieldState>;
+    formState?: Readonly<FormState>;
+}
+interface FieldArrayOptions<TValue> {
+    /**
+     * Field's name(path), it should be uniq within a form instance.
+     * Two Fields Rendered with the same name will link to the same part of data and field status such as errors is shared.
+     */
+    name: FieldName;
+    /**
+     * Default value of the field. Please notice that Field is a render model, so this default value will only be set when
+     * the field is rendered. If you want to give a default value before field rendering, please set it in the Form's initialValues.
+     */
+    defaultValue?: TValue[];
+    /**
+     * This is a render prop. A function that returns a React element and provides the ability to attach events and value into the component.
+     * This simplifies integrating with external controlled components with non-standard prop names. Provides field、fieldState and formState, to the child component.
+     * @param props
+     */
+    render?: (props: FieldArrayRenderProps<TValue>) => React__default.ReactElement;
+}
+interface FieldArrayRenderProps<TValue> {
+    field: FieldArray$1<TValue>;
+    fieldState?: Readonly<FieldState>;
+    formState?: Readonly<FormState>;
+}
+interface FieldState {
+    /**
+     * If field value is invalid
+     */
+    invalid: boolean;
+    /**
+     * If field input component is touched by user
+     */
+    isTouched: boolean;
+    /**
+     * If field current value is different from the initialValue.
+     */
+    isDirty: boolean;
+    /**
+     * If field is validating.
+     */
+    isValidating: boolean;
+    /**
+     * Field errors, empty array means there is no errors.
+     */
+    errors?: FieldError[];
+    /**
+     * Field warnings, empty array means there is no warnings.
+     */
+    warnings?: FieldWarning[];
+}
+interface FieldModelState extends Omit<FieldState, 'errors' | 'warnings'> {
+    errors?: Errors;
+    warnings?: Warnings;
+}
+
+type FieldProps<TValue> = FieldOptions<TValue> & {
+    /**
+     * A React element or a render prop
+     */
+    children?: ((props: FieldRenderProps<TValue>) => React.ReactElement) | React.ReactElement;
+    /**
+     * Dependencies of the current field. If a field name is given in deps, current field will re-render if the given field name data is updated
+     */
+    deps?: FieldName[];
+};
+/**
+ * HOC That declare a field, an Field model will be created it's rendered. Multiple Field rendering with a same name will link to the same model, which means they shared data、 status and methods
+ */
+declare function Field<TValue>({ name, defaultValue, render, children, deps, }: FieldProps<TValue>): React.ReactElement;
+
+type FormProps<TValues> = FormOptions & {
+    /**
+     * React children or child render prop
+     */
+    children?: ((props: FormRenderProps<TValues>) => React__default.ReactNode) | React__default.ReactNode;
+    /**
+     * If this prop is set to true, Form instance will be kept event thought<Form /> is destroyed.
+     * This means you can still use some form's api such as Form.validate and Form.setValueIn to handle pure data logic.
+     * @default false
+     */
+    keepModelOnUnMount?: boolean;
+    /**
+     * provide form instance from outside. if control is given Form will use the form instance in the control instead of creating one.
+     */
+    control?: FormControl<TValues>;
+};
+/**
+ * Hoc That init and provide Form instance. You can also provide form instance from outside by using control prop
+ * @param props
+ */
+declare function Form<TValues>(props: FormProps<TValues>): React__default.JSX.Element;
+
+/**
+ * Get Form instance. It should be use in a child component of  <Form />
+ */
+declare function useForm(): Form$1;
+
+/**
+ * Listen to the field data change and refresh the React component.
+ * @param name the field's uniq name (path)
+ */
+declare function useWatch<TValue = FieldValue>(name: FieldName): TValue;
+
+type FieldArrayProps<TValue> = FieldArrayOptions<TValue> & {
+    /**
+     * A React element or a render prop
+     */
+    children?: ((props: FieldArrayRenderProps<TValue>) => React.ReactElement) | React.ReactElement;
+    /**
+     * Dependencies of the current field. If a field name is given in deps, current field will re-render if the given field name data is updated
+     */
+    deps?: FieldName[];
+};
+/**
+ * HOC That declare an array field, an FieldArray model will be created when it's rendered. Multiple FieldArray rendering with a same name will link to the same model, which means they shared data、 status and methods
+ */
+declare function FieldArray<TValue extends FieldValue>({ name, defaultValue, deps, render, children, }: FieldArrayProps<TValue>): React.ReactElement;
+
+/**
+ * @deprecated
+ * `useField` is deprecated because its return relies on React render. if the Field is not rendered, the return would be
+ * undefined. If you simply want to monitor the change of the value of a certain path, please use `useWatch(fieldName)`
+ * @param name
+ */
+declare function useField<TFieldValue = FieldValue, TField extends Field$1<TFieldValue> | FieldArray$1<TFieldValue> = Field$1<TFieldValue>>(name?: FieldName): TField | undefined;
+
+declare function useFormState(control?: FormControl<any> | Form$1): FormState;
+declare function useFormErrors(control?: FormControl<any> | Form$1): Errors | undefined;
+declare function useFormWarnings(control?: FormControl<any> | Form$1): Warnings | undefined;
+
+/**
+ * Get validate method of a field with given name. the returned function could possibly do nothing if the field is not found.
+ * The reason could be that the field is not rendered yet or the name given is wrong.
+ * @param name
+ */
+declare function useFieldValidate(name?: FieldName): () => void;
+
+/**
+ * Get the current Field. It should be used in a child component of <Field />, otherwise it throws an error
+ */
+declare function useCurrentField<TFieldValue = FieldValue, TField extends Field$1<TFieldValue> | FieldArray$1<TFieldValue> = Field$1<TFieldValue>>(): Field$1<TFieldValue> | FieldArray$1<TFieldValue>;
+
+/**
+ * Get the current field state. It should be used in a child component of <Field />, otherwise it throws an error
+ */
+declare function useCurrentFieldState(): FieldState;
+
+type CreateFormOptions = FormOptions & {
+    /**
+     * 为 true 时，createForm 不会对form 初始化， 用户需要手动调用 control.init()
+     * 该配置主要为了解决，用户需要去监听一些form 的初始化事件，那么他需要再配置完监听后再初始化。
+     * 该配置默认为 false
+     **/
+    disableAutoInit?: boolean;
+};
+declare function createForm<TValues>(options?: CreateFormOptions): CreateFormReturn<TValues>;
+
+declare namespace Glob {
+    const DIVIDER = ".";
+    const ALL = "*";
+    function isMatch(pattern: string, path: string): boolean;
+    /**
+     * 判断pattern 是否match pattern 或其parent
+     * @param pattern
+     * @param path
+     */
+    function isMatchOrParent(pattern: string, path: string): boolean;
+    /**
+     * 从 path 中提取出匹配pattern 的 parent path，包括是 path 自身
+     * 该方法默认 isMatchOrParent(pattern, path) 为 true, 不做为false 的错误处理。
+     * @param pattern
+     * @param path
+     */
+    function getParentPathByPattern(pattern: string, path: string): string;
+    /**
+     * 找到 obj 在给与 paths 下所有子path
+     * @param paths
+     * @param obj
+     * @private
+     */
+    function getSubPaths(paths: string[], obj: any): string[];
+    /**
+     * 将带有通配符的 path pattern 分割。如 a.b.*.c.*.d, 会被分割成['a.b','*','c','*','d']
+     * @param pattern
+     * @private
+     */
+    function splitPattern(pattern: string): string[];
+    function findMatchPaths(obj: any, pattern: string): string[];
+}
+
+declare function toField<TValue>(model: FieldModel): Field$1<TValue>;
+declare function toFieldState(modelState: FieldModelState): {
+    readonly isTouched: boolean;
+    readonly invalid: boolean;
+    readonly isDirty: boolean;
+    readonly isValidating: boolean;
+    readonly errors: FieldError[] | undefined;
+    readonly warnings: FieldWarning[] | undefined;
+};
+
+declare function toFieldArray<TValue>(model: FieldArrayModel<TValue>): FieldArray$1<TValue>;
+
+declare function toForm<TValue>(model: FormModel): Form$1<TValue>;
+declare function toFormState(modelState: FormModelState): FormState;
+
+export { Field, FieldArray, FieldArrayModel, type FieldArrayProps, type FieldArrayRenderProps, type FieldError, FieldModel, type FieldName, type FieldProps, type FieldRenderProps, type FieldState, type FieldValue, type FieldWarning, Form, type FormControl, FormModel, type FormProps, type FormRenderProps, type FormState, type FormValidateReturn, Glob, type Field$1 as IField, type FieldArray$1 as IFieldArray, Path, type Validate, ValidateTrigger, createForm, toField, toFieldArray, toFieldState, toForm, toFormState, useCurrentField, useCurrentFieldState, useField, useFieldValidate, useForm, useFormErrors, useFormState, useFormWarnings, useWatch };