@progress/kendo-react-grid/utils/handleAIResponse.d.ts

React Data Grid (Table) provides 100+ ready-to-use data grid features. KendoReact Grid package

/**
 * @license
 *-------------------------------------------------------------------------------------------
 * Copyright © 2026 Progress Software Corporation. All rights reserved.
 * Licensed under commercial license. See LICENSE.md in the package root for more information
 *-------------------------------------------------------------------------------------------
 */
import { AxiosResponse } from 'axios';
import { CompositeFilterDescriptor, GroupDescriptor, SortDescriptor } from '@progress/kendo-data-query';
import { GridColumnState, GridHandle } from '../interfaces/index.js';
/**
 * Represents the grid state that can be controlled externally.
 * This interface contains all the stateful properties that can be modified through AI commands.
 *
 * @example
 * ```tsx
 * const [gridState, setGridState] = useState<GridAIState>({
 *   sort: [],
 *   filter: undefined,
 *   group: [],
 *   columnsState: initialColumns,
 *   skip: 0,
 *   take: 20
 * });
 * ```
 */
export interface GridAIState {
    /**
     * The current sort descriptors applied to the grid.
     * Array of sort objects defining field and direction.
     */
    sort?: SortDescriptor[];
    /**
     * The current filter descriptor applied to the grid.
     * Composite filter defining logic and filter array.
     */
    filter?: CompositeFilterDescriptor;
    /**
     * The current group descriptors applied to the grid.
     * Array of group objects defining field and aggregates.
     */
    group?: GroupDescriptor[];
    /**
     * The current column state including visibility, width, order, and lock status.
     * Array of column state objects.
     */
    columnsState?: GridColumnState[];
    /**
     * The number of items to skip for pagination.
     * Zero-based index for the first item to display.
     */
    skip?: number;
    /**
     * The number of items to take (page size) for pagination.
     * Number of items to display per page.
     */
    take?: number;
    /**
     * The highlight descriptor for highlighting cells/rows in the grid.
     * Object with dataItemKey as keys, values can be boolean (whole row) or number array (specific cells).
     *
     * @example
     * ```tsx
     * highlight: {
     *   '1': true,           // Highlight entire row with dataItemKey = 1
     *   '2': [0, 1, 2]       // Highlight cells at column indices 0, 1, 2 in row with dataItemKey = 2
     * }
     * ```
     */
    highlight?: any;
    /**
     * The select descriptor for selecting cells/rows in the grid.
     * Object with dataItemKey as keys, values can be boolean (whole row) or number array (specific cells).
     *
     * @example
     * ```tsx
     * select: {
     *   '1': true,           // Select entire row with dataItemKey = 1
     *   '2': [0, 1]          // Select cells at column indices 0 and 1 in row with dataItemKey = 2
     * }
     * ```
     */
    select?: any;
}
/**
 * Represents the result of processing an AI response.
 * Contains the updated grid state and any messages to display.
 */
export interface GridAIResponseResult {
    /**
     * The updated grid state after processing AI commands.
     * Spread this into your Grid component props.
     */
    state: GridAIState;
    /**
     * Array of user-friendly messages describing what changes were made.
     * Can be displayed to users as feedback.
     */
    messages: string[];
    /**
     * Indicates whether the AI triggered a PDF export.
     * Handle this separately as it's an action, not state.
     */
    shouldExportPdf: boolean;
}
/**
 * Processes an AI response and returns the updated grid state.
 * This is a pure function that takes the current state and AI response,
 * and returns a new state object with all the changes applied.
 *
 * @param response - The axios response from the AI service containing commands
 * @param currentState - The current grid state
 * @param gridRef - Reference to grid methods (getTotal, getLeafDataItems, exportAsPdf)
 * @returns Object containing the new state, messages, and export flag
 *
 * @example
 * ```tsx
 * const App = () => {
 *   const [gridState, setGridState] = useState<GridAIState>({
 *     sort: [],
 *     filter: undefined,
 *     group: [],
 *     columnsState: initialColumns,
 *     skip: 0,
 *     take: 20
 *   });
 *   const gridRef = useRef<GridHandle>(null);
 *
 *   const handleAIRequest = async (prompt: string) => {
 *     const response = await axios.post('/api/ai/grid', { prompt, columns: gridState.columnsState });
 *     const result = handleAIResponse(response, gridState, gridRef.current);
 *
 *     // Update state with AI changes
 *     setGridState(result.state);
 *
 *     // Handle PDF export if requested
 *     if (result.shouldExportPdf && gridRef.current) {
 *       gridRef.current.exportAsPdf();
 *     }
 *
 *     // Show messages to user
 *     console.log(result.messages);
 *   };
 *
 *   return (
 *     <Grid
 *       ref={gridRef}
 *       data={data}
 *       {...gridState}
 *       onSortChange={(e) => setGridState(prev => ({ ...prev, sort: e.sort }))}
 *       onFilterChange={(e) => setGridState(prev => ({ ...prev, filter: e.filter }))}
 *       onGroupChange={(e) => setGridState(prev => ({ ...prev, group: e.group }))}
 *       onColumnsStateChange={(e) => setGridState(prev => ({ ...prev, columnsState: e.columnsState }))}
 *       onPageChange={(e) => setGridState(prev => ({ ...prev, skip: e.page.skip, take: e.page.take }))}
 *     />
 *   );
 * };
 * ```
 */
export declare function handleAIResponse(response: AxiosResponse<any>, currentState: GridAIState, gridRef: Pick<GridHandle, 'getLeafDataItems' | 'getTotal' | 'exportAsPdf' | 'props'> | null): GridAIResponseResult;
/**
 * Handles sort command by merging new sort with existing sorts.
 *
 * @hidden
 */
declare const handleSortCommand: (commandSort: SortDescriptor | SortDescriptor[], currentSort?: SortDescriptor[]) => SortDescriptor[];
/**
 * Handles filter command by combining new filter with existing filters.
 *
 * @hidden
 */
declare const handleFilterCommand: (commandFilter: CompositeFilterDescriptor, currentFilter?: CompositeFilterDescriptor) => CompositeFilterDescriptor | undefined;
/**
 * Handles group command by merging new group with existing groups.
 *
 * @hidden
 */
declare const handleGroupCommand: (commandGroup: GroupDescriptor | GroupDescriptor[], currentGroup?: GroupDescriptor[]) => GroupDescriptor[];
/**
 * Handles column visibility change.
 *
 * @hidden
 */
declare const handleColumnVisibility: (columnId: string, hidden: boolean, columnsState: GridColumnState[]) => GridColumnState[];
/**
 * Handles column resize.
 *
 * @hidden
 */
declare const handleColumnResize: (columnId: string, newWidth: string, columnsState: GridColumnState[]) => GridColumnState[];
/**
 * Handles column reorder.
 *
 * @hidden
 */
declare const handleColumnReorder: (columnId: string, position: number, columnsState: GridColumnState[]) => GridColumnState[];
/**
 * Handles column lock/unlock.
 *
 * @hidden
 */
declare const handleColumnLock: (columnId: string, locked: boolean, columnsState: GridColumnState[]) => GridColumnState[];
/**
 * Handles page change by calculating new skip/take values.
 *
 * @hidden
 */
declare const handlePageChange: (gridRef: Pick<GridHandle, 'getLeafDataItems' | 'getTotal' | 'exportAsPdf' | 'props'>, targetPage: number, currentSkip?: number, currentTake?: number) => {
    skip: number;
    take: number;
};
/**
 * Handles page size change by recalculating skip/take values.
 *
 * @hidden
 */
declare const handlePageSizeChange: (pageSize: number, currentSkip?: number, currentTake?: number) => {
    skip: number;
    take: number;
};
export { handleSortCommand, handleFilterCommand, handleGroupCommand, handleColumnVisibility, handleColumnResize, handleColumnReorder, handleColumnLock, handlePageChange, handlePageSizeChange };