@progress/kendo-react-data-tools 11.0.0-develop.9 → 11.0.0

package/index.d.mts

@@ -16,6 +16,7 @@ import { GroupDescriptor } from '@progress/kendo-data-query';
 import { JSX } from 'react/jsx-runtime';
 import * as React_2 from 'react';
 import { SortDescriptor } from '@progress/kendo-data-query';
+import { State } from '@progress/kendo-data-query';
 import { SVGIcon } from '@progress/kendo-react-common';
 
 /**
@@ -726,6 +727,181 @@ declare interface DataItemWrapper {
     levelCount: number;
 }
 
+/**
+ * Represents a data source with data presentation operations (filtering, sorting, paging, grouping).
+ *
+ * @template T - The type of data items in the data source. Defaults to any.
+ */
+export declare type DataSource<T extends object = any> = {
+    /** The array of data items. */
+    data: T[];
+    /**
+     * Sets the data items in the data source.
+     *
+     * @param value - The array of new data items.
+     */
+    setData: (value: T[]) => void;
+    /** The total number of data items. */
+    total: number;
+    /** The schema used for data validation and transformation. */
+    schema: DataSourceProps<T>['schema'];
+    /** The current sort descriptors applied to the data. */
+    sort: SortDescriptor[] | undefined;
+    /**
+     * Sets the sort descriptors for the data.
+     *
+     * @param value - The new sort descriptors.
+     */
+    setSort: (value: SortDescriptor[] | undefined) => void;
+    /** The current filter descriptor applied to the data. */
+    filter: CompositeFilterDescriptor | undefined;
+    /**
+     * Sets the filter descriptor for the data.
+     *
+     * @param value - The new filter descriptor.
+     */
+    setFilter: (value: CompositeFilterDescriptor | undefined) => void;
+    /** The current skip value for pagination. */
+    skip: number | undefined;
+    /**
+     * Sets the skip value for pagination.
+     *
+     * @param value - The new skip value.
+     */
+    setSkip: (value: number | undefined) => void;
+    /** The current take value for pagination. */
+    take: number | undefined;
+    /**
+     * Sets the take value for pagination.
+     *
+     * @param value - The new take value.
+     */
+    setTake: (value: number | undefined) => void;
+    /** The current group descriptors applied to the data. */
+    group: GroupDescriptor[] | undefined;
+    /**
+     * Sets the group descriptors for the data.
+     *
+     * @param value - The new group descriptors.
+     */
+    setGroup: (value: GroupDescriptor[] | undefined) => void;
+    /** The current data state, including sorting, filtering, and pagination. */
+    dataState: Partial<DataSourceProps<T>>;
+    /**
+     * Sets the data state, including sorting, filtering, and pagination.
+     *
+     * @param dataState - The new data state.
+     */
+    setDataState: (dataState: Partial<DataSourceProps<T>>) => void;
+    /**
+     * Sets the total number of data items.
+     *
+     * @param value - The new total value.
+     */
+    setTotal: (value: number | undefined) => void;
+};
+
+/**
+ * Describes the options for configuring the useDataSource hook.
+ *
+ * @template T - The type of data items in the data source. Defaults to any.
+ */
+export declare type DataSourceProps<T extends object = any> = {
+    /**
+     * The total number of records in the data source.
+     */
+    total?: number;
+    /**
+     * The initial total number of records in the data source.
+     */
+    defaultTotal?: number;
+    /**
+     * The current data array to be managed by the hook.
+     * This represents the data items that are currently available in the data source.
+     * If not provided, the `defaultData` will be used as the initial value.
+     */
+    data?: T[];
+    /**
+     * The initial data array to be managed by the hook.
+     */
+    defaultData?: T[];
+    /**
+     * The current sorting configuration.
+     */
+    sort?: SortDescriptor[];
+    /**
+     * The initial sorting configuration.
+     */
+    defaultSort?: SortDescriptor[];
+    /**
+     * The current filter configuration.
+     */
+    filter?: CompositeFilterDescriptor;
+    /**
+     * The initial filter configuration.
+     */
+    defaultFilter?: CompositeFilterDescriptor;
+    /**
+     * The current number of records to skip (for paging).
+     */
+    skip?: number;
+    /**
+     * The initial number of records to skip (for paging).
+     */
+    defaultSkip?: number;
+    /**
+     * The current number of records to take per page.
+     */
+    take?: number;
+    /**
+     * The initial number of records to take per page.
+     */
+    defaultTake?: number;
+    /**
+     * The current grouping configuration.
+     */
+    group?: GroupDescriptor[];
+    /**
+     * The initial grouping configuration.
+     */
+    defaultGroup?: GroupDescriptor[];
+    /**
+     * Specifies whether filtering is enabled.
+     *
+     * @default true
+     */
+    filterable?: boolean;
+    /**
+     * Specifies whether sorting is enabled.
+     *
+     * @default true
+     */
+    sortable?: boolean;
+    /**
+     * Specifies whether paging is enabled.
+     *
+     * @default true
+     */
+    pageable?: boolean;
+    /**
+     * Specifies whether grouping is enabled.
+     *
+     * @default true
+     */
+    groupable?: boolean;
+    /**
+     * Configuration for the data schema, including model definition.
+     */
+    schema: {
+        model: {
+            /**
+             * The field that serves as the unique identifier for records.
+             */
+            id: string;
+        };
+    };
+};
+
 /**
  * The DateFilter component used for editing date value of FilterDescriptor object.
  */
@@ -2072,9 +2248,7 @@ export declare interface PopulateClipboardArgs {
     /**
      * Represents the current selected state of the data.
      */
-    selectedState: {
-        [key: string | number]: boolean | number[];
-    };
+    selectedState: SelectDescriptor;
     /**
      * Passes the data currently displayed.
      */
@@ -2109,6 +2283,401 @@ export declare function readColumns<C = CellProps, H = HeaderCellProps, F = Filt
 /** @hidden */
 export declare const relativeContextElement: (element: any) => any;
 
+/**
+ * Represents a remote data source with CRUD operations (Create, Read, Update, Delete).
+ *
+ * @template T - The type of data items in the data source. Defaults to any.
+ */
+export declare type RemoteDataSource<T extends object = any> = DataSource<T> & {
+    /** Set of original data items read from the remote source, indexed by ID */
+    reads: Map<string | number | symbol | null, T>;
+    /** Map of created items that need to be synced */
+    creates: Map<string | number | symbol | null, T>;
+    /** Map of updated items that need to be synced */
+    updates: Map<string | number | symbol | null, T>;
+    /** Map of items marked for deletion that need to be synced */
+    deletes: Map<string | number | symbol | null, T>;
+    /** Map of dirty fields for each item */
+    dirty: Map<string | number | symbol | null, Set<string>>;
+    /** Map of errors for each item */
+    errors: Map<string | number | symbol | null, any[]>;
+    /** Adds an error to an item */
+    addError: (params: {
+        error: any;
+        data?: T;
+    }) => void;
+    /** Removes an error from an item */
+    removeError: (params: {
+        error: any;
+    }) => void;
+    /** Removes all errors for an item */
+    removeErrors: (params: {
+        data: T;
+    }) => void;
+    /** Removes all errors */
+    removeAllErrors: () => void;
+    /** Reads data from the remote source */
+    read: (state?: State) => Promise<T[]>;
+    /** Creates a new item */
+    create: (params: {
+        data: T;
+    }) => void;
+    /** Updates an existing item */
+    update: (params: {
+        data: T;
+        field?: string;
+    }) => void;
+    /** Deletes an item */
+    delete: (params: {
+        data: T;
+    }) => void;
+    /** Syncs all pending changes with the remote source */
+    sync: () => Promise<void>;
+    /** Syncs a single item with the remote source */
+    syncItem: (params: {
+        data: T;
+    }) => Promise<void>;
+    /** Removes an item from creates */
+    removeCreate: (params: {
+        data: T;
+    }) => void;
+    /** Removes an item from updates */
+    removeUpdate: (params: {
+        data: T;
+    }) => void;
+    /** Removes an item from deletes */
+    removeDelete: (params: {
+        data: T;
+    }) => void;
+    /** Adds an item to reads */
+    pushCreate: (params: {
+        data: T;
+    }) => void;
+    /** Updates an item in reads */
+    pushUpdate: (params: {
+        data: T;
+    }) => void;
+    /** Removes an item from reads */
+    pushDelete: (params: {
+        data: T;
+    }) => void;
+    /** Discards all pending changes */
+    discard: () => void;
+};
+
+/**
+ * Configuration properties for the remote data source.
+ * Extends the basic DataSourceProps with remote data operations capabilities.
+ *
+ * @template T - The type of data items in the data source. Defaults to any object.
+ */
+export declare interface RemoteDataSourceProps<T extends object = any> extends DataSourceProps<T> {
+    /**
+     * Map of original data items read from the remote source, indexed by ID.
+     */
+    reads?: Map<string | number | symbol | null, T>;
+    /**
+     * Map of created items that need to be synced with the remote source.
+     */
+    creates?: Map<string | number | symbol | null, T>;
+    /**
+     * Map of updated items that need to be synced with the remote source.
+     */
+    updates?: Map<string | number | symbol | null, T>;
+    /**
+     * Map of items marked for deletion that need to be synced with the remote source.
+     */
+    deletes?: Map<string | number | symbol | null, T>;
+    /**
+     * Determines if filtering operations should be performed on the server.
+     * When true, filter parameters are sent to the server during read operations.
+     *
+     * @default true
+     */
+    serverFiltering?: boolean;
+    /**
+     * Determines if sorting operations should be performed on the server.
+     * When true, sort parameters are sent to the server during read operations.
+     *
+     * @default true
+     */
+    serverSorting?: boolean;
+    /**
+     * Determines if paging operations should be performed on the server.
+     * When true, skip and take parameters are sent to the server during read operations.
+     *
+     * @default true
+     */
+    serverPaging?: boolean;
+    /**
+     * Determines if grouping operations should be performed on the server.
+     * When true, group parameters are sent to the server during read operations.
+     *
+     * @default true
+     */
+    serverGrouping?: boolean;
+    /**
+     * Configuration for CRUD operations transport.
+     * Defines how data is sent to and received from the server.
+     */
+    transport?: {
+        /**
+         * Configuration for create operations.
+         * Can be either an object specifying the endpoint configuration or a function for custom implementation.
+         */
+        create?: {
+            /**
+             * URL for the create operation. Can be a string or a function that returns a string based on the data item.
+             */
+            url: string | ((dataItem: T) => string);
+            /**
+             * HTTP method to use for the create operation.
+             *
+             * @default "POST"
+             */
+            method?: string;
+            /**
+             * Content-Type header to use for the request.
+             *
+             * @default "application/json"
+             */
+            contentType?: string;
+            /**
+             * Additional data to include in the request.
+             */
+            data?: {
+                [key: string]: any;
+            };
+            /**
+             * Function that transforms the request data before sending it to the server.
+             *
+             * @param data - The data item to transform
+             * @returns Transformed data
+             */
+            parameterMap?: (data: T) => any;
+            /**
+             * Callback executed when the create operation is successful.
+             *
+             * @param data - The created data item
+             */
+            onSuccess?: (data: T) => void;
+            /**
+             * Function to process the server response.
+             *
+             * @param response - The server response
+             * @returns Processed data item or null
+             */
+            onResponse?: (response: any) => T | null;
+            /**
+             * Callback executed when the create operation fails.
+             *
+             * @param error - The error from the server
+             */
+            onError?: (error: any) => void;
+        } | ((options: {
+            data: T;
+        }) => Promise<T>);
+        /**
+         * Configuration for read operations.
+         * Can be either an object specifying the endpoint configuration or a function for custom implementation.
+         */
+        read?: {
+            /**
+             * URL for the read operation. Can be a string or a function that returns a string.
+             */
+            url: string | (() => string);
+            /**
+             * HTTP method to use for the read operation.
+             *
+             * @default "GET"
+             */
+            method?: string;
+            /**
+             * Content-Type header to use for the request.
+             */
+            contentType?: string;
+            /**
+             * Additional data to include in the request.
+             */
+            data?: {
+                [key: string]: any;
+            };
+            /**
+             * Function that transforms the request data before sending it to the server.
+             *
+             * @param data - The request parameters including filter, paging, sorting, and grouping info
+             * @returns Transformed request parameters
+             */
+            parameterMap?: (data: {
+                filter?: CompositeFilterDescriptor;
+                skip?: number;
+                take?: number;
+                sort?: SortDescriptor[];
+                group?: GroupDescriptor[];
+            }) => any;
+            /**
+             * Callback executed when the read operation is successful.
+             *
+             * @param data - The retrieved data items
+             */
+            onSuccess?: (data: T[]) => void;
+            /**
+             * Function to process the server response.
+             *
+             * @param response - The server response
+             * @returns Processed data item or null
+             */
+            onResponse?: (response: any) => T | null;
+            /**
+             * Callback executed when the read operation fails.
+             *
+             * @param error - The error from the server
+             */
+            onError?: (error: any) => void;
+        } | ((options: {
+            filter?: CompositeFilterDescriptor;
+            skip?: number;
+            take?: number;
+            sort?: SortDescriptor[];
+            group?: GroupDescriptor[];
+            onSuccess?: (data: T[]) => void;
+            onResponse?: (response: any) => T | null;
+            onError?: (error: any) => void;
+        }) => Promise<T[]>);
+        /**
+         * Configuration for update operations.
+         * Can be either an object specifying the endpoint configuration or a function for custom implementation.
+         */
+        update?: {
+            /**
+             * URL for the update operation. Can be a string or a function that returns a string based on the data item.
+             */
+            url: string | ((dataItem: T) => string);
+            /**
+             * HTTP method to use for the update operation.
+             *
+             * @default "PUT"
+             */
+            method?: string;
+            /**
+             * Content-Type header to use for the request.
+             *
+             * @default "application/json"
+             */
+            contentType?: string;
+            /**
+             * Additional data to include in the request.
+             */
+            data?: {
+                [key: string]: any;
+            };
+            /**
+             * Function that transforms the request data before sending it to the server.
+             *
+             * @param data - The data item to transform
+             * @returns Transformed data
+             */
+            parameterMap?: (data: T) => any;
+            /**
+             * Callback executed when the update operation is successful.
+             *
+             * @param data - The updated data item
+             */
+            onSuccess?: (data: T) => void;
+            /**
+             * Function to process the server response.
+             *
+             * @param response - The server response
+             * @returns Processed data item or null
+             */
+            onResponse?: (response: any) => T | null;
+            /**
+             * Callback executed when the update operation fails.
+             *
+             * @param error - The error from the server
+             */
+            onError?: (error: any) => void;
+        } | ((options: {
+            data: T;
+        }) => Promise<T>);
+        /**
+         * Configuration for delete operations.
+         * Can be either an object specifying the endpoint configuration or a function for custom implementation.
+         */
+        delete?: {
+            /**
+             * URL for the delete operation. Can be a string or a function that returns a string based on the data item.
+             */
+            url: string | ((dataItem: T) => string);
+            /**
+             * HTTP method to use for the delete operation.
+             *
+             * @default "DELETE"
+             */
+            method?: string;
+            /**
+             * Content-Type header to use for the request.
+             */
+            contentType?: string;
+            /**
+             * Additional data to include in the request.
+             */
+            data?: {
+                [key: string]: any;
+            };
+            /**
+             * Function that transforms the request data before sending it to the server.
+             *
+             * @param data - The data item to transform
+             * @returns Transformed data
+             */
+            parameterMap?: (data: T) => any;
+            /**
+             * Callback executed when the delete operation is successful.
+             *
+             * @param data - The deleted data item
+             */
+            onSuccess?: (data: T) => void;
+            /**
+             * Function to process the server response.
+             *
+             * @param response - The server response
+             * @returns Processed data item or null
+             */
+            onResponse?: (response: any) => T | null;
+            /**
+             * Callback executed when the delete operation fails.
+             *
+             * @param error - The error from the server
+             */
+            onError?: (error: any) => void;
+        } | ((options: {
+            data: T;
+        }) => Promise<T>);
+    };
+    /**
+     * Schema configuration for parsing and mapping server responses.
+     * Extends the base DataSourceProps schema with additional properties for remote data.
+     */
+    schema: DataSourceProps['schema'] & {
+        /**
+         * Specifies the field in the response that contains the data items,
+         * or a function that extracts the data items from the response.
+         */
+        data?: string | ((data: any) => T[]);
+        /**
+         * Specifies the field in the response that contains the total count,
+         * or a function that extracts the total count from the response.
+         */
+        total?: string | ((data: any) => number);
+        /**
+         * Specifies the field in the response that contains error information,
+         * or a function that extracts error information from the response.
+         */
+        errors?: string | ((data: any) => any);
+    };
+}
+
 /**
  * Removes the items from the passed `data` which match the passed `condition`.
  *
@@ -2758,6 +3327,94 @@ export declare function updateRight(columnsMap: number[][], columns: Array<{
     ariaColumnIndex: number;
 }>, generateRight?: boolean): void;
 
+/**
+ * A hook that provides functionality for managing local data with built-in support for filtering, sorting, paging, and grouping.
+ *
+ * @template T - The type of data items in the data source. Defaults to any.
+ * @param {DataSourceProps<T>} props - The configuration options for the data source.
+ * @returns {DataSource<T>} An object containing data management methods and properties.
+ *
+ * @example
+ * ```tsx
+ * interface Product {
+ *   ProductID: number;
+ *   ProductName: string;
+ *   UnitPrice: number;
+ * }
+ *
+ * const dataSource = useDataSource<Product>({
+ *   defaultData: products,
+ *   defaultSort: [{ field: 'UnitPrice', dir: 'desc' }],
+ *   defaultSkip: 0,
+ *   take: 10,
+ *   schema: {
+ *     model: {
+ *       id: 'ProductID'
+ *     }
+ *   }
+ * });
+ *
+ * return (
+ *   <Grid
+ *     data={dataSource.data}
+ *     total={dataSource.total}
+ *     {...dataSource.dataState}
+ *     onDataStateChange={(event) => {
+ *       dataSource.setDataState(event.dataState);
+ *     }}
+ *   >
+ *     <GridColumn field="ProductID" title="ID" />
+ *     <GridColumn field="ProductName" title="Product Name" />
+ *   </Grid>
+ * );
+ * ```
+ */
+export declare const useDataSource: <T extends object = any>(props: DataSourceProps<T>) => DataSource<T>;
+
+/**
+ * A specialized version of useRemoteDataSource tailored for working with OData services.
+ * It automatically handles the construction of OData queries and the processing of OData responses.
+ *
+ * @template T - The type of data items in the data source. Defaults to any.
+ * @param {RemoteDataSourceProps<T>} props - The configuration options for the OData data source.
+ * @returns {RemoteDataSource<T>} An object containing all the properties and methods from useRemoteDataSource with OData-specific defaults for transport and schema configurations.
+ *
+ * @example
+ * ```tsx
+ * interface Product {
+ *   ProductID: number;
+ *   ProductName: string;
+ *   UnitPrice: number;
+ * }
+ *
+ * const dataSource = useODataDataSource<Product>({
+ *   take: 10,
+ *   skip: 0,
+ *   transport: {
+ *     read: {
+ *       url: 'https://demos.telerik.com/kendo-ui/service-v4/odata/Products'
+ *     }
+ *   },
+ *   schema: {
+ *     model: {
+ *       id: 'ProductID'
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare const useODataDataSource: <T extends object = any>(props: RemoteDataSourceProps<T>) => RemoteDataSource<T>;
+
+/**
+ * A hook that extends the functionality of useDataSource by adding support for remote data operations.
+ * It enables you to connect to remote endpoints and perform CRUD operations while managing the data state locally.
+ *
+ * @template T - The type of data items in the data source
+ * @param {RemoteDataSourceProps<T>} props - The configuration options for the remote data source.
+ * @returns {RemoteDataSource<T>} An object containing all the properties and methods from useDataSource plus additional methods for interacting with remote data.
+ */
+export declare const useRemoteDataSource: <T extends object = any>(props: RemoteDataSourceProps<T>) => RemoteDataSource<T>;
+
 /**
  * @hidden
  */