@progress/kendo-react-form 7.2.4-develop.3 → 7.3.0-develop.1

package/index.d.mts

@@ -1,5 +1,724 @@
-/**-----------------------------------------------------------------------------------------
-* Copyright © 2024 Progress Software Corporation. All rights reserved.
-* Licensed under commercial license. See LICENSE.md in the package root for more information
-*-------------------------------------------------------------------------------------------*/
-export * from './index';
+/**
+ * @license
+ *-------------------------------------------------------------------------------------------
+ * Copyright © 2024 Progress Software Corporation. All rights reserved.
+ * Licensed under commercial license. See LICENSE.md in the package root for more information
+ *-------------------------------------------------------------------------------------------
+ */
+import { FieldRenderPropsBase } from '@progress/kendo-react-common';
+import { ForwardRefExoticComponent } from 'react';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import PropTypes from 'prop-types';
+import * as React_2 from 'react';
+import { RefAttributes } from 'react';
+
+/**
+ * Represents the Field component that is used inside the KendoReact Form component.
+ * It uses `name` property to access field value and meta information from Form state.
+ */
+export declare const Field: {
+    (props: FieldProps): React_2.ReactElement<any, string | React_2.JSXElementConstructor<any>> | null;
+    displayName: string;
+};
+
+/**
+ * Represents the FieldArray component that is used inside the KendoReact Form component.
+ * It provides methods via render props for common array manipulations.
+ */
+export declare const FieldArray: React_2.FunctionComponent<FieldArrayProps>;
+
+/**
+ * Represents the props of the FieldArray component that is used inside the KendoReact Form component.
+ */
+export declare interface FieldArrayProps {
+    /**
+     * The name of the field in the Form state.
+     */
+    name: string;
+    /**
+     * Can be set to a React component.
+     * [`FieldArrayRenderProps`]({% slug api_form_fieldarrayrenderprops %}).
+     */
+    component: React.ComponentType<any>;
+    /**
+     * The validation functions for the FieldArray level.
+     * Currently, `validator` supports only synchronous functions.
+     */
+    validator?: FieldValidatorType | FieldValidatorType[];
+    /**
+     * The React elements that are passed as children to the rendered component.
+     */
+    children?: any;
+    /**
+     * @hidden
+     */
+    [customProp: string]: any;
+}
+
+/**
+ * Represents the props that are passed to the component which is rendered by FieldArray.
+ */
+export declare interface FieldArrayRenderProps {
+    /**
+     * Represents the current value of the FieldArray
+     * ([see example]({% slug custom_components_form %}#toc-using-basic-properties)).
+     */
+    value: any;
+    /**
+     * Represents the error message that is returned by the validator.
+     * The FieldArray is considered valid if the `validationMessage` field is empty.
+     */
+    validationMessage: string | null;
+    /**
+     * Indicates if the field is touched.
+     * The touched state is set to `true` when the `onBlur` callback is called.
+     */
+    touched: boolean;
+    /**
+     * Indicates if the field is modified.
+     * The modified state is set to `true` when the `onChange` callback for the current field is called for first time.
+     */
+    modified: boolean;
+    /**
+     * Indicates if the field is visited.
+     * The visited state is set to `true` when the `onFocus` callback is called.
+     */
+    visited: boolean;
+    /**
+     * A calculated property based on whether `validationMessage` is present and the `touched` state is set to `true`.
+     */
+    valid: boolean;
+    /**
+     * Represents the children that are passed to the FieldArray.
+     */
+    children: any;
+    /**
+     * The name of the field in the Form state.
+     */
+    name: string;
+    /**
+     * A callback to add a value to the beginning of the array.
+     */
+    onUnshift: (options: {
+        value: any;
+    }) => number;
+    /**
+     * A callback to add a value to the end of the array.
+     */
+    onPush: (options: {
+        value: any;
+    }) => void;
+    /**
+     * A callback to insert value at given index of the array.
+     */
+    onInsert: (options: {
+        value: any;
+        index: number;
+    }) => void;
+    /**
+     * A callback to remove a value from the end of the array. The value is returned.
+     */
+    onPop: () => any;
+    /**
+     * A callback to remove a value from given index of the array.
+     */
+    onRemove: (options: {
+        index: number;
+    }) => any;
+    /**
+     * A callback to replace value at given index of the array.
+     */
+    onReplace: (options: {
+        value: any;
+        index: number;
+    }) => void;
+    /**
+     * A callback to move a value from one index to another. Useful for drag and drop reordering.
+     */
+    onMove: (options: {
+        prevIndex: number;
+        nextIndex: number;
+    }) => void;
+    /**
+     * @hidden
+     */
+    [customProp: string]: any;
+}
+
+/**
+ * Represents the props of the Field component that is used inside the KendoReact Form component.
+ */
+export declare interface FieldProps {
+    /**
+     * The name of the field in the Form state.
+     * Supports nested fields in the `user.age` and `users[index].name` formats.
+     */
+    name: string;
+    /**
+     * Can be set to a React component or to the name of an HTML element,
+     * for example, `input`, `select`, and `textarea`.
+     * The props that are passed to component are the
+     * [`FieldRenderProps`]({% slug api_form_fieldrenderprops %}).
+     */
+    component: string | React.ComponentType<any>;
+    /**
+     * The validation functions for the Field level.
+     * Currently, `validator` supports only synchronous functions.
+     * Using the array overload with inline array will cause an infinite loop - in this case use a `useMemo` hook to memoize the array.
+     */
+    validator?: FieldValidatorType | FieldValidatorType[];
+    /**
+     * The React elements that are passed as children to the rendered component.
+     */
+    children?: any;
+    /**
+     * Called when underlying editor triggers it's `onChange` event and the Form update it's internal state.
+     * Useful for updating related fields.
+     * > The `Form` listens to this editor event and automatically keeps it's internal state up to date.
+     * That why this event should be used only for executing custom logic.
+     */
+    onChange?: (event: any) => void;
+    /**
+     * @hidden
+     */
+    [customProp: string]: any;
+}
+
+/**
+ * Represents the props that are passed to the component which is rendered by Field.
+ */
+export declare interface FieldRenderProps extends FieldRenderPropsBase {
+}
+
+/**
+ * The validator function for the Field component. The function arguments are:
+ *
+ * * value - The current value of the field.
+ * * valueGetter - Function which can be used to get other fields value.
+ * Usable when validator depends on more than one field. Supports field paths.
+ * * fieldProps - Props of the Field component. Currently contains only the `name` prop.
+ * Usable when one validator is used across multiple fields.
+ *
+ * Returns `string` to signify error or `undefined` to signify validation success.
+ */
+export declare type FieldValidatorType = (value: any, valueGetter: (name: string) => any, fieldProps: {
+    name: string;
+}) => string | undefined;
+
+/**
+ * Represents the KendoReact FieldWrapper component.
+ * It's designed to wrap the field editor, Label, Hint and Error components.
+ * The FieldWrapper supports only single editor inside it.
+ */
+export declare const FieldWrapper: React_2.FunctionComponent<FieldWrapperProps>;
+
+/**
+ * Represents the props of the KendoReact FieldWrapper component.
+ */
+export declare interface FieldWrapperProps {
+    /**
+     * @hidden
+     */
+    children: any;
+    /**
+     * The styles that are applied to the FieldWrapper.
+     */
+    style?: React_2.CSSProperties;
+    /**
+     * Sets a class of the FieldWrapper DOM element.
+     */
+    className?: string;
+    /**
+     * Specifies the direction of the content.
+     */
+    dir?: string;
+}
+
+/** @hidden */
+export declare const Form: ForwardRefExoticComponent<FormProps & RefAttributes<any>>;
+
+/**
+ * Represents the [KendoReact Form component]({% slug overview_form %}).
+ *
+ * @example
+ * ```jsx
+ * export const FormInput = (fieldRenderProps) => {
+ *     const onValueChange = React.useCallback(
+ *         (event) => fieldRenderProps.onChange(event.target.value),
+ *         [fieldRenderProps.onChange]
+ *     );
+ *     return (
+ *         <input
+ *             className={'k-input'}
+ *             value={fieldRenderProps.value}
+ *             onChange={onValueChange}
+ *         />
+ *     );
+ * };
+ *
+ * export const App = () => {
+ *     const handleSubmit = (dataItem) => alert(JSON.stringify(dataItem));
+ *     return (
+ *         <Form
+ *             initialValues={{title: ''}}
+ *             onSubmit={handleSubmit}
+ *             render={(formRenderProps) => (
+ *                 <div>
+ *                     <Field name={'title'} component={FormInput} />
+ *                     <button
+ *                         className="k-button"
+ *                         disabled={!formRenderProps.allowSubmit}
+ *                         onClick={formRenderProps.onSubmit}
+ *                     >
+ *                         Submit
+ *                     </button>
+ *                 </div>
+ *             )}
+ *         />
+ *     );
+ * };
+ *
+ * ReactDOM.render(<App />, document.querySelector('my-app'));
+ * ```
+ */
+export declare class FormClassComponent extends React_2.Component<FormProps, {}> {
+    /**
+     * @hidden
+     */
+    static displayName: string;
+    /**
+     * @hidden
+     */
+    static propTypes: {
+        initialValues: PropTypes.Requireable<any>;
+        onSubmit: PropTypes.Requireable<(...args: any[]) => any>;
+        onSubmitClick: PropTypes.Requireable<(...args: any[]) => any>;
+        render: PropTypes.Validator<(...args: any[]) => any>;
+        id: PropTypes.Requireable<string>;
+    };
+    private _key?;
+    private _touched;
+    private _visited;
+    private _modified;
+    private _validatorsByField;
+    private _values;
+    private _fields;
+    private _unmounted;
+    private _submitted;
+    /**
+     * @hidden
+     */
+    private _accumulatorTimeout;
+    /**
+     * @hidden
+     */
+    get touched(): KeyValue<boolean>;
+    /**
+     * @hidden
+     */
+    set touched(value: KeyValue<boolean>);
+    /**
+     * @hidden
+     */
+    get visited(): KeyValue<boolean>;
+    /**
+     * @hidden
+     */
+    set visited(value: KeyValue<boolean>);
+    /**
+     * @hidden
+     */
+    get modified(): KeyValue<boolean>;
+    /**
+     * @hidden
+     */
+    set modified(value: KeyValue<boolean>);
+    /**
+     * @hidden
+     */
+    get validatorsByField(): KeyValue<(FieldValidatorType | FieldValidatorType[] | undefined)[]>;
+    /**
+     * @hidden
+     */
+    set validatorsByField(value: KeyValue<(FieldValidatorType | FieldValidatorType[] | undefined)[]>);
+    /**
+     * @hidden
+     */
+    get values(): KeyValue<any>;
+    /**
+     * @hidden
+     */
+    set values(value: KeyValue<any>);
+    /**
+     * @hidden
+     */
+    get fields(): string[];
+    /**
+     * @hidden
+     */
+    get formErrors(): KeyValue<string> | undefined;
+    /**
+     * @hidden
+     */
+    get errors(): KeyValue<string>;
+    /**
+     * @hidden
+     */
+    constructor(props: FormProps);
+    /**
+     * @hidden
+     */
+    componentWillUnmount(): void;
+    /**
+     * @hidden
+     */
+    isValid: () => boolean;
+    /**
+     * @hidden
+     */
+    accumulatedForceUpdate: () => void;
+    /**
+     * @hidden
+     */
+    resetForm: () => void;
+    /**
+     * Method for resetting the form state outside the form component.
+     *
+     * > Use `onReset` only if you cannot achieve the desired behavior through the Field component or by FormRenderProps.
+     */
+    onReset: () => void;
+    /**
+     * @hidden
+     */
+    addField: (field: string) => void;
+    /**
+     * @hidden
+     */
+    onSubmit: (event: React_2.SyntheticEvent<any>) => void;
+    /**
+     * Method for emiting changes to a specific field outside the form component.
+     *
+     * > Use `onChange` only if you cannot achieve the desired behavior through the Field component by FormRenderProps.
+     */
+    onChange: (name: string, options: {
+        value: any;
+    }) => void;
+    /**
+     * @hidden
+     */
+    onFocus: (name: string, skipForceUpdate?: boolean) => void;
+    /**
+     * @hidden
+     */
+    onBlur: (name: string, skipForceUpdate?: boolean) => void;
+    /**
+     * @hidden
+     */
+    onFieldRegister: (name: string, validator: FieldValidatorType | FieldValidatorType[] | undefined) => () => void;
+    /**
+     * @hidden
+     */
+    isFormValid: (errors: KeyValue<any>) => boolean;
+    /**
+     * @hidden
+     */
+    isFormModified: (modified: KeyValue<boolean>, fields: string[]) => boolean;
+    /**
+     * @hidden
+     */
+    isFormHasNotTouched: (touched: KeyValue<boolean>, fields: string[]) => boolean;
+    /**
+     * @hidden
+     */
+    isFormTouched: (touched: KeyValue<boolean>, fields: string[]) => boolean;
+    /**
+     * @hidden
+     */
+    isFormVisited: (visited: KeyValue<boolean>, fields: string[]) => boolean;
+    /**
+     * @hidden
+     */
+    valueGetter: (fieldName: string) => any;
+    /**
+     * @hidden
+     */
+    valueSetter: (fieldName: string, value: any) => any;
+    /**
+     * @hidden
+     */
+    onArrayAction: (name: string) => void;
+    /**
+     * @hidden
+     */
+    onInsert: (name: string, options: {
+        value: any;
+        index: number;
+    }) => void;
+    /**
+     * @hidden
+     */
+    onUnshift: (name: string, options: {
+        value: any;
+    }) => void;
+    /**
+     * @hidden
+     */
+    onPush: (name: string, options: {
+        value: any;
+    }) => void;
+    /**
+     * @hidden
+     */
+    onPop: (name: string) => any;
+    /**
+     * @hidden
+     */
+    onRemove: (name: string, options: {
+        index: number;
+    }) => any;
+    /**
+     * @hidden
+     */
+    onReplace: (name: string, options: {
+        value: any;
+        index: number;
+    }) => void;
+    /**
+     * @hidden
+     */
+    onMove: (name: string, options: {
+        prevIndex: number;
+        nextIndex: number;
+    }) => void;
+    /**
+     * @hidden
+     */
+    render(): JSX_2.Element;
+}
+
+/**
+ * Represents the KendoReact FormElement component.
+ * It's small wrapper around HTML form element which automatically attach the
+ * Form component's `onSubmit` render prop and Kendo CSS classes.
+ * Other props are passed to the DOM node.
+ */
+export declare const FormElement: React_2.FunctionComponent<FormElementProps>;
+
+/**
+ * Represent the `ref` of the FormElement component.
+ */
+export declare interface FormElementHandle {
+    props: FormElementProps;
+    element: HTMLFormElement | null;
+}
+
+/**
+ * Represents the props of the KendoReact FormElement component.
+ */
+export declare interface FormElementProps {
+    /**
+     * @hidden
+     */
+    children: any;
+    /**
+     * The styles that are applied to the form DOM element.
+     */
+    style?: React_2.CSSProperties;
+    /**
+     * Sets a class of the form DOM element.
+     */
+    className?: string;
+    /**
+     * If set to `true` enable the horizontal layout of the form editors.
+     */
+    horizontal?: boolean;
+    /**
+     * @hidden
+     */
+    [customProp: string]: any;
+    /**
+     * Configures the `size` of the Form.
+     *
+     * The available options are:
+     * - small
+     * - medium
+     * - large
+     * - null&mdash;Does not set a size `className`.
+     *
+     * @default `medium`
+     */
+    size?: null | 'small' | 'medium' | 'large';
+}
+
+/**
+ * Represent the `ref` of the Form component.
+ */
+export declare interface FormHandle extends Pick<FormClassComponent, keyof FormClassComponent> {
+}
+
+/**
+ * Represents the props of the KendoReact Form component.
+ */
+export declare interface FormProps {
+    /**
+     * The initial field values of the Form.
+     *
+     * > When you initialize the Form felds, set initial values to them. Otherwise, some
+     * components might throw errors related to switching from uncontrolled to controlled mode.
+     */
+    initialValues?: {
+        [name: string]: any;
+    };
+    /**
+     * The validation function for the Form level.
+     * Should return key-value pair where the key is the field path and the value is the error message.
+     * Nested fields are supported, e.g.: 'users[0].name'.
+     * You can use the same field path to access the value from the
+     * values object using the `getter` function from the `kendo-react-common` package.
+     * Currently, `validator` supports only synchronous functions.
+     */
+    validator?: FormValidatorType;
+    /**
+     * The submission handler for the Form.
+     * Called when at least one field has been modified, the user pressed the **Submit** button,  and the form validation was successful.
+     */
+    onSubmit?: (values: {
+        [name: string]: any;
+    }, event?: React.SyntheticEvent<any>) => void;
+    /**
+     * Called every time the user presses the **Submit** button.
+     * Useful in advanced scenarios when you need to handle every submit event, even when the form is invalid or not modified state.
+     */
+    onSubmitClick?: (event: FormSubmitClickEvent) => void;
+    /**
+     * The Form content that will be rendered.
+     */
+    render: (props: FormRenderProps) => any;
+    /**
+     * Set this to `true` to allow the form submit without modifed fields.
+     */
+    ignoreModified?: boolean;
+    /**
+     * @hidden
+     * This prop comes from the `withId` HOC and is used internally by the Form.
+     * It replaces the previously used guid() function and generates an `id` of the Form.
+     */
+    id?: string;
+}
+
+/**
+ * Represents the props that are passed to the `render` option component of the Form.
+ */
+export declare interface FormRenderProps {
+    /**
+     * A callback for submitting the Form.
+     * Can be passed to the `onClick` property of the **Submit** button.
+     */
+    onSubmit: (event: React.SyntheticEvent<any>) => void;
+    /**
+     * A callback for emiting changes to a specific field without using the Field component
+     * ([see example]({% slug common_scenarios_form %}#toc-changing-the-field-value)).
+     *
+     * > Use `onChange` only if you cannot achieve the desired behavior through the Field component.
+     */
+    onChange: (name: string, options: {
+        value: any;
+    }) => void;
+    /**
+     * A callback for resetting the Form.
+     */
+    onFormReset: () => void;
+    /**
+     * The key-value pair containing the current errors by field path, combined from both field and form level validators.
+     */
+    errors: KeyValue<string>;
+    /**
+     * Indicates if the Form is valid.
+     * If any field is invalid, `valid` is set to `false`.
+     */
+    valid: boolean;
+    /**
+     * Indicates if the Form is touched.
+     * If any field is touched, `touched` is set to `true`.
+     * The touched state of field is set to `true` when the `onBlur`
+     * callback of the Field component is called or when the user tries to submit the form.
+     */
+    touched: boolean;
+    /**
+     * Indicates if the Form is visited.
+     * If any field is visited, `visited` is set to `true`.
+     * The visited state of field is set to `true` when the `onFocus`
+     * callback of the Field component is called or when the user tries to submit the form.
+     */
+    visited: boolean;
+    /**
+     * Indicates if the Form is modified.
+     * If any field is modified, `modified` is set to `true`.
+     * The modified state of field is set to `true` when the `onChange`
+     * callback of the Field component is called for first time.
+     */
+    modified: boolean;
+    /**
+     * Indicates if the Form is successfuly submitted.
+     * Useful for detecting if user is leaving the form before saving changes.
+     */
+    submitted: boolean;
+    /**
+     * Indicates if the Form is ready to be submitted.
+     * * If `allowSubmit` is set to `true` and the Form is valid, the user will be able to submit the form.
+     * * If `allowSubmit` is set to `true` and the Form is not valid, the user will be able to set the `touched` and `visited` state of all fields to `true`.
+     * `touched` and `visited` state to true.
+     *
+     * Useful for toggling the disabled state of the **Submit** button.
+     */
+    allowSubmit: boolean;
+    /**
+     * A callback for getting the value of a field without using the Field component
+     * ([see example]({% slug common_scenarios_form %}#toc-reading-the-field-state)).
+     * Useful for creating and modifying the UI based on the field values.
+     */
+    valueGetter: (name: string) => any;
+}
+
+/**
+ * The FormSubmitClick event.
+ */
+export declare interface FormSubmitClickEvent {
+    /**
+     * Contains the current values of the form.
+     */
+    values: {
+        [name: string]: any;
+    };
+    /**
+     * The native event.
+     */
+    event?: React.SyntheticEvent<any>;
+    /**
+     * Represents the validity state of the form.
+     */
+    isValid: boolean;
+    /**
+     * Represents the modified state of the form.
+     */
+    isModified: boolean;
+}
+
+/**
+ * The validator function for the Form component.
+ *
+ * * values - The current values of the form.
+ * * valueGetter - Function which can be used to get field value. Supports field paths.
+ *
+ * Returns key-value pair with errors if such are present. The key is the field path, where the value is the error message.
+ */
+export declare type FormValidatorType = (values: any, valueGetter: (name: string) => any) => KeyValue<string> | undefined;
+
+/**
+ *
+ */
+export declare interface KeyValue<ValueType> {
+    [name: string]: ValueType;
+}
+
+export { }