react-kd-grid 2.2.4 → 3.0.0

package/dist/types.d.ts

@@ -1,10 +1,21 @@
 import { CSSProperties, MouseEvent, ReactNode } from "react";
+/** Used internally by useVirtualization and GridRows. Not part of the public API. */
+export interface VirtualizedRange {
+    startIndex: number;
+    endIndex: number;
+    offsetY: number;
+}
 export type FilterType = "text" | "multiselect" | "number" | "date" | "boolean";
 export type Density = "sm" | "md" | "lg";
+export type SortDirection = "asc" | "desc" | null;
+export type PaginationMode = "client" | "server";
+export type SearchMode = "contains" | "exact" | "startsWith" | "endsWith" | "regex";
 export interface FilterOption {
     label: string;
-    value: any;
+    /** Tightened from `any` — filter values must be scalar. */
+    value: string | number | boolean;
 }
+/** Inline column filter configuration (used as `filterable: { type, ... }`). */
 export interface ColumnFilter {
     type: FilterType;
     options?: FilterOption[];
@@ -12,251 +23,342 @@ export interface ColumnFilter {
     min?: number;
     max?: number;
 }
+export interface ColumnFilterValue {
+    type: FilterType;
+    /**
+     * The filter value.
+     * - Text/boolean: `string | boolean`
+     * - Number: `number | string`
+     * - Date: `Date | string`
+     * - Multiselect: `any[]` (array of selected option values)
+     */
+    value: string | number | boolean | Date | any[] | null;
+    operator?: "equals" | "contains" | "startsWith" | "endsWith" | "gt" | "lt" | "gte" | "lte" | "between";
+    /** Secondary value for the `between` operator. */
+    secondValue?: string | number | boolean | Date | null;
+}
+export interface ActiveFilters {
+    [columnKey: string]: ColumnFilterValue;
+}
+/** @internal Used by FilterPopup component. */
+export interface FilterPopupProps {
+    column: GridColumn;
+    data: GridRow[];
+    currentFilter?: ColumnFilterValue;
+    onApplyFilter: (filter: ColumnFilterValue | null) => void;
+    onClose: () => void;
+    position: {
+        top: number;
+        left: number;
+    };
+    autoApply?: boolean;
+}
 export interface GridColumn {
     key: string;
     header: string;
     width?: number;
     /**
-     * Flexible sizing. When true or a positive number, the column can expand to fill
-     * available horizontal space. If a number is provided, it represents the flex grow weight.
-     * Note: runtime support may require renderer updates; currently a type hint.
+     * Flexible sizing. When `true` or a positive number the column can expand to
+     * fill available horizontal space. A number sets the flex-grow weight.
      */
     flex?: boolean | number;
-    /** Minimum width in pixels for this column */
+    /** Minimum width in pixels. */
     minWidth?: number;
-    /** Maximum width in pixels for this column */
+    /** Maximum width in pixels. */
     maxWidth?: number;
-    /** Allows column to be resizable via UI (if the header implements it) */
+    /** Allow the user to drag-resize this column. */
     resizable?: boolean;
+    /** Whether the column header is clickable to sort. Default `true`. */
+    sortable?: boolean;
     /**
-     * Whether the column is sortable. Defaults to true; set explicitly to false to disable.
+     * Enable or configure the column filter.
+     * `true`  → text filter with defaults
+     * `false` → no filter (overrides the grid-level `filterable` prop)
+     * object  → full configuration
      */
-    sortable?: boolean;
     filterable?: boolean | ColumnFilter;
+    /** Format the raw cell value to a display string. */
     formatter?: (value: any) => string;
+    /** Fully custom cell renderer; takes precedence over `formatter`. */
     cellRenderer?: (value: any, row: GridRow) => ReactNode;
+    /** Whether the column is visible. Default `true`. */
     visible?: boolean;
     /**
-     * Group aggregate to compute for this column when grouping is enabled.
-     * If a function is provided, it will receive the array of raw cell values and should return the aggregate value.
+     * Aggregate function applied to this column's values inside group footers.
+     * Built-ins: `"sum" | "avg" | "min" | "max"`.
+     * Custom: `(values: any[]) => any`.
      */
     aggregate?: "sum" | "avg" | "min" | "max" | ((values: any[]) => any);
-    /**
-     * Optional formatter for the aggregate value displayed in group footers.
-     * Falls back to the column's formatter if not provided.
-     */
+    /** Formatter for the group-footer aggregate value. Falls back to `formatter`. */
     aggregateFormatter?: (value: any) => string;
     /**
-     * Footer aggregate to compute for this column and display at the bottom of all rows.
-     * If a function is provided, it will receive the array of raw cell values and should return the aggregate value.
-     */
-    footer_aggregate?: "count" | "sum" | "avg" | "min" | "max" | ((values: any[]) => any);
-    /**
-     * Optional formatter for the footer aggregate value.
-     * Falls back to the column's formatter if not provided.
+     * Aggregate function for the global footer row at the bottom of all rows.
+     * Built-ins: `"count" | "sum" | "avg" | "min" | "max"`.
+     *
+     * @renamed Was `footer_aggregate` (snake_case) in v2. Now `footerAggregate`.
      */
+    footerAggregate?: "count" | "sum" | "avg" | "min" | "max" | ((values: any[]) => any);
+    /** Formatter for the global footer aggregate value. Falls back to `formatter`. */
     footerAggregateFormatter?: (value: any) => string;
-    /**
-     * Horizontal alignment for cell content: left | center | right
-     */
+    /** Horizontal alignment for cell content. */
     align?: "left" | "center" | "right";
-    /**
-     * Horizontal alignment for header content: left | center | right
-     */
+    /** Horizontal alignment for the header cell. */
     headerAlign?: "left" | "center" | "right";
-    /** Optional CSS class for body cells of this column */
+    /** CSS class for body cells — static string or derived from value + row. */
     className?: string | ((value: any, row: GridRow) => string);
-    /** Optional inline style for body cells of this column */
+    /** Inline style for body cells — static or derived. */
     cellStyle?: CSSProperties | ((value: any, row: GridRow) => CSSProperties);
-    /** Optional CSS class for the header cell of this column */
+    /** CSS class for the header cell. */
     headerClassName?: string;
-    /** If true, removes default padding from the cell container for this column */
+    /** Remove default padding from the cell container. */
     noPadding?: boolean;
-    /** If false, do not wrap renderer output with the default truncation div */
+    /** Set to `false` to opt out of the default truncation wrapper. */
     wrapCellContent?: boolean;
 }
 export interface GridRow {
+    /** Optional unique identifier. Provide `getRowId` on the grid for custom keys. */
     id?: string | number;
     [key: string]: any;
 }
+/** Runtime multi-level grouping state. */
 export interface GroupConfig {
     /** Ordered list of column keys to group by (multi-level). */
     columnKeys: string[];
     /**
-     * Expanded group paths. Each path is a stable string key built from the sequence of
-     * grouping values, e.g. "City=SF|Status=Open". Root groups are single segment.
+     * Expanded group paths. Each path is a stable string built from the sequence
+     * of grouping values, e.g. `"City=SF|Status=Open"`.
      */
     expanded: Set<string>;
 }
-export interface GroupedData {
-    [groupValue: string]: {
-        rows: GridRow[];
-        count: number;
-    };
+export interface SortConfig {
+    key: string | null;
+    direction: SortDirection;
 }
-export type SearchMode = "contains" | "exact" | "startsWith" | "endsWith" | "regex";
-export type BulkAction = "delete" | "archive" | "copy" | "edit" | "export";
-export interface SavedFilter {
+export interface PaginationConfig {
+    enabled: boolean;
+    pageSize: number;
+    currentPage: number;
+    totalPages: number;
+    totalRows: number;
+    showPageSizeSelector?: boolean;
+    pageSizeOptions?: number[];
+}
+export interface ServerPaginationConfig {
+    enabled: boolean;
+    onPageChange: (page: number, pageSize: number) => Promise<void> | void;
+    onPageSizeChange?: (pageSize: number) => Promise<void> | void;
+    loading?: boolean;
+    totalRows: number;
+}
+/** Export configuration for the grid toolbar. */
+export interface ExportOptions {
+    /** Allowed export formats. Defaults to `["xlsx"]`. */
+    formats?: Array<"csv" | "json" | "xlsx">;
+    /** Default filename without extension. Defaults to `"grid-data"`. */
+    filename?: string;
+    /** When `false`, export is disabled even if `showExport` is `true`. */
+    enabled?: boolean;
+    /** `"client"` processes data in the browser; `"server"` calls `onServerExport`. */
+    exportMode?: "client" | "server";
+    /**
+     * Called when `exportMode === "server"`.
+     * @param format            Requested file format.
+     * @param exportSelected    Whether only selected rows should be exported.
+     * @param selectedRowIds    IDs of selected rows when `exportSelected` is `true`.
+     */
+    onServerExport?: (format: "csv" | "json" | "xlsx", exportSelected: boolean, selectedRowIds?: Array<string | number>) => void;
+}
+/** Client/server pagination options passed to the `pagination` prop. */
+export interface PaginationOptions {
+    enabled?: boolean;
+    mode?: PaginationMode;
+    pageSize?: number;
+    showPageSizeSelector?: boolean;
+    pageSizeOptions?: number[];
+    serverConfig?: ServerPaginationConfig;
+}
+/** Performance tuning knobs for large datasets. */
+export interface PerformanceConfig {
+    /** Enable horizontal (column) virtualization. Default `true`. */
+    enableHorizontalVirtualization?: boolean;
+    /** Column count above which horizontal virtualization activates. Default `50`. */
+    horizontalVirtualizationThreshold?: number;
+    /** Row count above which sorting is offloaded to a Web Worker. Default `5000`. Set to `0` to disable. */
+    sortWorkerThreshold?: number;
+    /** Maximum search-cache size for global filtering. Default `5000`. */
+    maxFilterCacheSize?: number;
+    /** Enable aggressive memoization for large datasets. Default `true`. */
+    enableAggressiveMemoization?: boolean;
+}
+export interface ContextMenuItem {
     id: string;
-    name: string;
-    globalFilter: string;
-    columnFilters: Record<string, any>;
-    searchMode: SearchMode;
+    label: string;
+    icon?: ReactNode;
+    onClick: (row: GridRow) => void;
+    disabled?: boolean;
+    /** Renders as a horizontal divider; `label` and `onClick` are ignored. */
+    separator?: boolean;
 }
 export interface BulkActionOption {
-    id: BulkAction;
+    /**
+     * Unique identifier for this action.
+     * Open string type — add any custom id (e.g. `"approve"`, `"flag"`).
+     */
+    id: string;
     label: string;
     icon: ReactNode;
     onClick: (selectedRows: Set<string | number>) => void;
     disabled?: boolean;
     destructive?: boolean;
 }
+export interface SavedFilter {
+    id: string;
+    name: string;
+    globalFilter: string;
+    columnFilters: Record<string, ColumnFilterValue>;
+    searchMode: SearchMode;
+}
+export interface ServerFilterChangePayload {
+    globalFilter: string;
+    columnFilters: ActiveFilters;
+    filterableKeys: string[];
+    searchMode?: SearchMode;
+}
+export interface ColumnConfig {
+    columnWidths: Record<string, number>;
+    columnVisibility: Record<string, boolean>;
+    pinnedColumns: string[];
+    sortConfig: SortConfig;
+    /** Multi-level grouping state persisted to storage. */
+    groupConfig?: {
+        columnKeys?: string[];
+    };
+    filters: {
+        globalFilter: string;
+        columnFilters: ActiveFilters;
+    };
+    columnOrder?: string[];
+    density?: Density;
+}
+export interface RowEventParams {
+    row: GridRow;
+    event: MouseEvent;
+}
+export interface CellClickParams {
+    row: GridRow;
+    column: GridColumn;
+    value: any;
+    event: MouseEvent;
+}
+export interface CellContextMenuParams {
+    row: GridRow;
+    column: GridColumn;
+    value: any;
+    displayValue: string;
+    event: MouseEvent;
+}
+export interface CellFocusParams {
+    row: GridRow;
+    column: GridColumn;
+    value: any;
+    rowIndex: number;
+    colIndex: number;
+}
+export interface CellSelectionPayload {
+    bounds: {
+        rowStart: number;
+        rowEnd: number;
+        colStart: number;
+        colEnd: number;
+    } | null;
+    cells: Array<CellFocusParams>;
+}
+export interface CopyCellsPayload {
+    text: string;
+    bounds?: {
+        rowStart: number;
+        rowEnd: number;
+        colStart: number;
+        colEnd: number;
+    } | null;
+    cells: Array<CellFocusParams>;
+    isRectangular: boolean;
+    isFocusedCell: boolean;
+}
 export interface KDGridProps {
     data: GridRow[];
     columns: GridColumn[];
     /**
-     * Optional function to derive unique row identifier from a row object.
-     * Priority order:
-     *   1. If getRowId is provided, use it to extract the ID from the row
-     *   2. Else if row.id exists, use it
-     *   3. Else use the row's index as fallback (may cause issues with pagination/filtering)
+     * Derive a unique row identifier from a row object.
      *
-     * Examples:
-     *   - (row) => row.employeeId
-     *   - (row) => `${row.dept}_${row.name}` (composite key)
-     *   - (row) => row.uuid
-     *
-     * Recommendation: Always provide either row.id or getRowId prop for best results.
+     * Priority:
+     * 1. `getRowId(row)` if provided
+     * 2. `row.id` if present
+     * 3. Row index (⚠️ may cause issues with pagination / filtering)
      */
     getRowId?: (row: GridRow) => string | number;
+    /** Fixed height of the grid container in pixels. */
     height?: number;
+    /** Row density. Default `"md"`. */
     density?: Density;
     onDensityChange?: (density: Density) => void;
-    /**
-     * Optional header size controls (independent of row density).
-     * - If headerHeight is provided, it takes precedence (fixed pixel height).
-     * - Else if headerDensity is provided, it maps to the density sizing (sm|md|lg).
-     * - Else defaults to medium (md).
-     */
-    headerDensity?: Density;
-    headerHeight?: number;
+    /** Show a density toggle in the toolbar. */
     showDensityControl?: boolean;
-    onRowSelect?: (row: GridRow) => void;
-    onSelectedRowsChange?: (selectedRows: Set<string | number>) => void;
-    selectable?: boolean;
-    isRowSelectable?: (row: GridRow) => boolean;
-    showToolbar?: boolean;
-    showExport?: boolean;
+    /** Override the header row height in pixels. Takes precedence over `headerDensity`. */
+    headerHeight?: number;
+    /** Independent density for the header row. */
+    headerDensity?: Density;
+    rowHeight?: number;
+    overscan?: number;
     /**
-     * Optional export options to control which formats are allowed and default filename.
-     * If not provided, only Excel ("xlsx") will be allowed by default.
+     * When total post-filter rows ≤ this number, virtualization is disabled for
+     * simpler DOM. Default `300`.
      */
-    exportOptions?: {
-        /** Allowed export formats (defaults to ["xlsx"]) */
-        formats?: Array<"csv" | "json" | "xlsx">;
-        /** Default exported filename without extension (defaults to "grid-data") */
-        filename?: string;
-        /** Enable/disable export action (defaults to true; combined with showExport) */
-        enabled?: boolean;
-        /** Export execution mode. Default: 'client'. */
-        exportMode?: "client" | "server";
-        /**
-         * Optional handler to perform server-side export when exportMode === 'server'.
-         * If exportSelected is true, selectedRowIds will contain the ids that are currently selected in the grid.
-         */
-        onServerExport?: (format: "csv" | "json" | "xlsx", exportSelected: boolean, selectedRowIds?: Array<string | number>) => void;
-    };
+    virtualizationThreshold?: number;
+    selectable?: boolean;
     sortable?: boolean;
     filterable?: boolean;
     groupable?: boolean;
     virtualized?: boolean;
-    rowHeight?: number;
-    overscan?: number;
-    rowStyle?: (row: GridRow) => CSSProperties | undefined;
-    onContextMenu?: (row: GridRow, event: MouseEvent) => void;
-    onRowDoubleClick?: (row: GridRow, event: MouseEvent) => void;
-    onRowClick?: (row: GridRow, event: MouseEvent) => void;
-    onCellClick?: (args: {
-        row: GridRow;
-        column: GridColumn;
-        value: any;
-        event: MouseEvent;
-    }) => void;
-    onCellContextMenu?: (args: {
-        row: GridRow;
-        column: GridColumn;
-        value: any;
-        displayValue: string;
-        event: MouseEvent;
-    }) => void;
-    cellFocusEnabled?: boolean;
-    onCellFocusChange?: (args: {
-        row: GridRow;
-        column: GridColumn;
-        value: any;
-        rowIndex: number;
-        colIndex: number;
-    }) => void;
-    cellSelectionEnabled?: boolean;
-    canSelectCell?: (row: GridRow, column: GridColumn) => boolean;
-    onCellSelectionChange?: (payload: {
-        bounds: {
-            rowStart: number;
-            rowEnd: number;
-            colStart: number;
-            colEnd: number;
-        } | null;
-        cells: Array<{
-            row: GridRow;
-            column: GridColumn;
-            value: any;
-            rowIndex: number;
-            colIndex: number;
-        }>;
-    }) => void;
-    onAutosizeColumn?: (columnKey: string) => void;
-    onAutosizeAllColumns?: () => void;
-    onResetColumns?: () => void;
-    pagination?: {
-        enabled?: boolean;
-        mode?: PaginationMode;
-        pageSize?: number;
-        showPageSizeSelector?: boolean;
-        pageSizeOptions?: number[];
-        serverConfig?: ServerPaginationConfig;
-    };
-    /** If provided, when total (post-filter) rows <= threshold virtualization is auto-disabled for simpler DOM (default: 300). */
-    virtualizationThreshold?: number;
+    /** Show a loading overlay / skeleton. Replaces `isLoading` from v2. */
+    loading?: boolean;
+    /** Text to show when there are no rows to display. */
+    noDataMessage?: string;
+    /** Fully custom empty-state renderer; overrides `noDataMessage`. */
+    noDataRenderer?: () => ReactNode;
+    showToolbar?: boolean;
+    showExport?: boolean;
+    exportOptions?: ExportOptions;
+    toolbarLeft?: ReactNode;
+    toolbarRight?: ReactNode;
     onRefresh?: () => void;
-    isLoading?: boolean;
+    /** Externally controlled selection ids (controlled mode). */
+    selectedRowIds?: Iterable<string | number> | null;
+    onRowSelect?: (row: GridRow) => void;
+    onSelectedRowsChange?: (selectedRows: Set<string | number>) => void;
+    /** Predicate; return `false` to make a specific row non-selectable. */
+    isRowSelectable?: (row: GridRow) => boolean;
     bulkActions?: BulkActionOption[];
+    pagination?: PaginationOptions;
+    /**
+     * Controls how the global search bar matches text.
+     * Default `"contains"`.
+     */
+    searchMode?: SearchMode;
     savedFilters?: SavedFilter[];
     onSaveFilter?: (filter: Omit<SavedFilter, "id">) => void;
     onLoadFilter?: (filter: SavedFilter) => void;
     onDeleteFilter?: (filterId: string) => void;
+    /** Fired on every filter change — useful for server-side filtering. */
     onFilterChange?: (payload: ServerFilterChangePayload) => void;
-    onSort?: (columnKey: string, direction: "asc" | "desc") => void;
-    onColumnConfigChange?: (config: ColumnConfig) => void;
-    initialColumnConfig?: Partial<ColumnConfig>;
-    toolbarLeft?: ReactNode;
-    toolbarRight?: ReactNode;
     /**
-     * Controls the visibility of the Group Bar (the area where you can drop headers to group).
-     * - 'hidden': never show the bar
-     * - 'auto': show only when there are active grouped columns
-     * - 'visible': always show when groupable is true
+     * Called when the user sorts a column.
+     * `direction` is `null` when the sort is cleared.
      */
+    onSort?: (columnKey: string, direction: "asc" | "desc" | null) => void;
     groupBarVisibility?: "hidden" | "auto" | "visible";
-    /**
-     * How to render group aggregation footer rows when grouping is enabled.
-     * - 'chips': render a colored summary bar with chips (default)
-     * - 'columns': render a full-width colored row placing aggregate values under their respective columns
-     */
     groupFooterVariant?: "chips" | "columns";
-    /**
-     * Optional custom renderer for actions on grouped rows.
-     * Receives information about the group and its rows.
-     */
+    showGroupExpandControls?: boolean;
     renderGroupActions?: (groupInfo: {
         groupKey: string;
         columnKey: string;
@@ -265,160 +367,58 @@ export interface KDGridProps {
         count: number;
         level: number;
     }) => ReactNode;
+    /** CSS class applied to each row — static string or derived from row + index. */
+    rowClassName?: string | ((row: GridRow, index: number) => string);
+    rowStyle?: (row: GridRow) => CSSProperties | undefined;
+    onRowClick?: (params: RowEventParams) => void;
+    onRowDoubleClick?: (params: RowEventParams) => void;
+    /** Right-click on a row (before the built-in context menu opens). */
+    onContextMenu?: (params: RowEventParams) => void;
+    /** Custom items for the row right-click context menu. */
+    contextMenuItems?: ContextMenuItem[];
+    onCellClick?: (params: CellClickParams) => void;
+    onCellContextMenu?: (params: CellContextMenuParams) => void;
+    /** Enable single-cell focus with arrow-key navigation. */
+    cellFocusEnabled?: boolean;
+    onCellFocusChange?: (params: CellFocusParams) => void;
+    /** Enable rectangular cell selection (disables browser text selection). */
+    cellSelectionEnabled?: boolean;
+    /** Return `false` to prevent a specific cell from being selected. */
+    canSelectCell?: (row: GridRow, column: GridColumn) => boolean;
+    onCellSelectionChange?: (payload: CellSelectionPayload) => void;
     /**
-     * Show expand/collapse all group buttons in the toolbar when grouping is enabled.
-     * Defaults to true.
-     */
-    showGroupExpandControls?: boolean;
-    /**
-     * Callback invoked when user copies cells (Ctrl/Cmd + C) while cell focus or rectangular selection is active.
-     * Provides the plain text that was written to the clipboard (tab/newline delimited) and metadata.
-     */
-    onCopyCells?: (payload: {
-        text: string;
-        /** Present only for rectangular selections */
-        bounds?: {
-            rowStart: number;
-            rowEnd: number;
-            colStart: number;
-            colEnd: number;
-        } | null;
-        cells: Array<{
-            row: GridRow;
-            column: GridColumn;
-            value: any;
-            rowIndex: number;
-            colIndex: number;
-        }>;
-        isRectangular: boolean;
-        isFocusedCell: boolean;
-    }) => void;
-    /** Optional controlled selection ids */
-    selectedRowIds?: Iterable<string | number> | null;
-    /** Performance optimization settings for large datasets */
-    performanceConfig?: {
-        /** Enable horizontal virtualization for large column sets (default: true) */
-        enableHorizontalVirtualization?: boolean;
-        /** Column count threshold to enable horizontal virtualization (default: 50) */
-        horizontalVirtualizationThreshold?: number;
-        /** Row count threshold to offload sorting to a Web Worker (default: 5000). Set to 0 to always sort inline. */
-        sortWorkerThreshold?: number;
-        /** Maximum cache size for filtering operations (default: 5000) */
-        maxFilterCacheSize?: number;
-        /** Enable aggressive memoization for large datasets (default: true) */
-        enableAggressiveMemoization?: boolean;
-    };
-}
-export interface ContextMenuItem {
-    id: string;
-    label: string;
-    icon?: ReactNode;
-    onClick: (row: GridRow) => void;
-    disabled?: boolean;
-    separator?: boolean;
-}
-export type SortDirection = "asc" | "desc" | null;
-export interface SortConfig {
-    key: string | null;
-    direction: SortDirection;
-}
-export interface VirtualizedRange {
-    startIndex: number;
-    endIndex: number;
-    offsetY: number;
-}
-export interface ColumnFilterValue {
-    type: FilterType;
-    value: any;
-    operator?: "equals" | "contains" | "startsWith" | "endsWith" | "gt" | "lt" | "gte" | "lte" | "between";
-    secondValue?: any;
-}
-export interface ActiveFilters {
-    [columnKey: string]: ColumnFilterValue;
-}
-export interface ColumnConfig {
-    columnWidths: Record<string, number>;
-    columnVisibility: Record<string, boolean>;
-    pinnedColumns: string[];
-    sortConfig: SortConfig;
-    /**
-     * Persisted grouping configuration. New multi-level shape uses columnKeys.
-     * The legacy single-key field (columnKey) is retained for backward compatibility.
+     * Called when the user copies cells with Ctrl/⌘+C while cell focus or
+     * rectangular selection is active.
      */
-    groupConfig?: {
-        columnKeys?: string[];
-        columnKey?: string | null;
-    };
-    filters: {
-        globalFilter: string;
-        columnFilters: ActiveFilters;
-    };
-    columnOrder?: string[];
-    density?: Density;
-}
-export interface PaginationConfig {
-    enabled: boolean;
-    pageSize: number;
-    currentPage: number;
-    totalPages: number;
-    totalRows: number;
-    showPageSizeSelector?: boolean;
-    pageSizeOptions?: number[];
-}
-export interface ServerPaginationConfig {
-    enabled: boolean;
-    onPageChange: (page: number, pageSize: number) => Promise<void> | void;
-    onPageSizeChange?: (pageSize: number) => Promise<void> | void;
-    loading?: boolean;
-    totalRows: number;
-}
-export type PaginationMode = "client" | "server";
-export interface FilterPopupProps {
-    column: GridColumn;
-    data: GridRow[];
-    currentFilter?: ColumnFilterValue;
-    onApplyFilter: (filter: ColumnFilterValue | null) => void;
-    onClose: () => void;
-    position: {
-        top: number;
-        left: number;
-    };
-    autoApply?: boolean;
-}
-export interface ServerFilterChangePayload {
-    globalFilter: string;
-    columnFilters: ActiveFilters;
-    filterableKeys: string[];
-    searchMode?: SearchMode;
+    onCopyCells?: (payload: CopyCellsPayload) => void;
+    onAutosizeColumn?: (columnKey: string) => void;
+    onAutosizeAllColumns?: () => void;
+    onResetColumns?: () => void;
+    onColumnConfigChange?: (config: ColumnConfig) => void;
+    initialColumnConfig?: Partial<ColumnConfig>;
+    performanceConfig?: PerformanceConfig;
 }
-/**
- * Imperative handle for KDGrid to allow external control of grouping.
- * Use with React.forwardRef and useImperativeHandle in the grid component.
- */
 export interface KDGridRef {
-    /** Replace the entire ordered grouping keys */
+    /** Replace the entire ordered grouping key list. */
     setGroupKeys: (keys: string[]) => void;
-    /** Add a grouping key at the end if not already present */
+    /** Append a grouping key if not already present. */
     addGroupKey: (key: string) => void;
-    /** Remove a specific grouping key */
+    /** Remove a specific grouping key. */
     removeGroupKey: (key: string) => void;
-    /** Expand all group paths for the current grouping keys */
+    /** Expand every group for the current grouping keys. */
     expandAllGroups: () => void;
-    /** Collapse all group paths */
+    /** Collapse all groups. */
     collapseAllGroups: () => void;
-    /** Toggle a specific group path, e.g. "City=SF|Status=Open" */
+    /** Toggle a specific group path, e.g. `"City=SF|Status=Open"`. */
     toggleGroupExpansion: (groupPath: string) => void;
-    /** Read the current in-grid grouping configuration */
+    /** Read the current grouping configuration. */
     getGroupConfig: () => GroupConfig;
-    /** Set a column filter programmatically */
-    setColumnFilter: (columnKey: string, filter: any) => void;
-    /** Clear a specific column filter */
+    /** Apply a column filter programmatically. Pass `null` to clear. */
+    setColumnFilter: (columnKey: string, filter: ColumnFilterValue | null) => void;
+    /** Clear a single column filter. */
     clearColumnFilter: (columnKey: string) => void;
-    /** Clear all column filters */
+    /** Clear all active filters (global + column). */
     clearAllFilters: () => void;
-    /** Set global filter */
+    /** Set the global search text. */
     setGlobalFilter: (value: string) => void;
 }
-export interface CustomDataGridProps extends KDGridProps {
-}
-export type CustomDataGridRef = KDGridRef;