react-kd-grid 5.0.1

package/dist/types.d.ts

@@ -0,0 +1,592 @@
+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;
+    /** 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[];
+    placeholder?: string;
+    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 | Array<string | number | boolean> | 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 | null;
+}
+/** @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. A number sets the flex-grow weight.
+     */
+    flex?: boolean | number;
+    /** Minimum width in pixels. */
+    minWidth?: number;
+    /** Maximum width in pixels. */
+    maxWidth?: number;
+    /** Allow the user to drag-resize this column. */
+    resizable?: boolean;
+    /** Whether the column header is clickable to sort. Default `true`. */
+    sortable?: boolean;
+    /**
+     * Enable or configure the column filter.
+     * `true`  → text filter with defaults
+     * `false` → no filter (overrides the grid-level `filterable` prop)
+     * object  → full configuration
+     */
+    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;
+    /**
+     * 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);
+    /** Formatter for the group-footer aggregate value. Falls back to `formatter`. */
+    aggregateFormatter?: (value: any) => string;
+    /**
+     * 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. */
+    align?: "left" | "center" | "right";
+    /** Horizontal alignment for the header cell. */
+    headerAlign?: "left" | "center" | "right";
+    /** CSS class for body cells — static string or derived from value + row. */
+    className?: string | ((value: any, row: GridRow) => string);
+    /** Inline style for body cells — static or derived. */
+    cellStyle?: CSSProperties | ((value: any, row: GridRow) => CSSProperties);
+    /** CSS class for the header cell. */
+    headerClassName?: string;
+    /** Remove default padding from the cell container. */
+    noPadding?: boolean;
+    /** Set to `false` to opt out of the default truncation wrapper. */
+    wrapCellContent?: boolean;
+    /**
+     * Tooltip shown on hover of body cells.
+     * - `string` — static tooltip text
+     * - Function — derived from the cell value and its row
+     *
+     * When omitted, the grid falls back to the native browser `title` attribute
+     * (which shows the `displayValue` of the cell).
+     */
+    tooltip?: string | ((value: any, row: GridRow) => string);
+    /**
+     * Tooltip shown on hover of the column header cell.
+     * Useful for describing long or abbreviated column names.
+     */
+    headerTooltip?: string;
+    /**
+     * Enable inline cell editing for this column.
+     * - `true`  → all rows editable
+     * - Function → called per-row; return `false` to make that row read-only.
+     */
+    editable?: boolean | ((row: GridRow) => boolean);
+    /**
+     * Input type to use for the built-in editor.
+     * - `"text"`    (default) → `<input type="text">`
+     * - `"number"`  → `<input type="number">`
+     * - `"date"`    → `<input type="date">`
+     * - `"select"`  → `<select>` (requires `editorOptions`)
+     * - `"textarea"` → `<textarea>` (expands the row)
+     */
+    editorType?: "text" | "number" | "date" | "select" | "textarea";
+    /** Options for the built-in `"select"` editor. */
+    editorOptions?: Array<{
+        label: string;
+        value: any;
+    }>;
+    /**
+     * Fully custom editor renderer. When provided it replaces the built-in
+     * input. Receives the current draft value, the full row, and callbacks
+     * to commit or cancel the edit.
+     */
+    editor?: (value: any, row: GridRow, onCommit: (newValue: any) => void, onCancel: () => void) => ReactNode;
+}
+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 built from the sequence
+     * of grouping values, e.g. `"City=SF|Status=Open"`.
+     */
+    expanded: Set<string>;
+}
+export interface SortConfig {
+    key: string | null;
+    direction: SortDirection;
+}
+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;
+}
+/** Supported export file formats. */
+export type ExportFormat = "csv" | "json" | "xlsx";
+/** Export configuration for the grid toolbar. */
+export interface ExportOptions {
+    /** Allowed export formats. Defaults to `["xlsx"]`. */
+    formats?: ExportFormat[];
+    /** 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;
+}
+/**
+ * Configuration for infinite-scroll mode.
+ *
+ * When enabled, `pagination` is ignored and `PaginationControls` are hidden.
+ * The grid renders all rows currently in `data`; when the user scrolls near
+ * the bottom, `onLoadMore` is called so the parent can append more rows.
+ *
+ * @example
+ * ```tsx
+ * <KDGrid
+ *   data={rows}
+ *   columns={columns}
+ *   infiniteScroll={{
+ *     enabled: true,
+ *     hasMore: page < totalPages,
+ *     isLoading: isFetching,
+ *     onLoadMore: () => setPage((p) => p + 1),
+ *   }}
+ * />
+ * ```
+ */
+export interface InfiniteScrollOptions {
+    /** Must be `true` to activate infinite scroll mode. */
+    enabled: boolean;
+    /**
+     * Set to `false` when there are no more rows to fetch.
+     * The sentinel is disconnected immediately to prevent spurious calls.
+     */
+    hasMore: boolean;
+    /**
+     * Set to `true` while rows are being fetched.
+     * Prevents `onLoadMore` being called again before the current fetch resolves.
+     */
+    isLoading: boolean;
+    /**
+     * Called when the user scrolls near the bottom and `hasMore` is `true`.
+     * Append new rows to the `data` prop to display them.
+     */
+    onLoadMore: () => void;
+    /**
+     * Pixels of root margin below the viewport that trigger `onLoadMore`.
+     * Higher values pre-fetch earlier. Default `250`.
+     */
+    threshold?: number;
+    /**
+     * Custom renderer for the loading indicator shown at the bottom while
+     * `isLoading` is `true`. Defaults to a pulsing spinner row.
+     */
+    loadingRenderer?: () => React.ReactNode;
+}
+export interface ContextMenuItem {
+    id: string;
+    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 {
+    /**
+     * 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 CellEditParams {
+    /** The row object being edited. */
+    row: GridRow;
+    /** The column being edited. */
+    column: GridColumn;
+    /** The previous (pre-edit) value. */
+    oldValue: any;
+    /** The committed new value. */
+    newValue: any;
+    /** Row id derived from `getRowId` or `row.id`. */
+    rowId: string | 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 {
+    /**
+     * License key for the grid. The component will not render without a
+     * valid key. E.g. "kd_team_v3_xyz"
+     */
+    licenseKey?: string;
+    data: GridRow[];
+    columns: GridColumn[];
+    /**
+     * Derive a unique row identifier from a row object.
+     *
+     * 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;
+    /** Show a density toggle in the toolbar. */
+    showDensityControl?: boolean;
+    /** Override the header row height in pixels. Takes precedence over `headerDensity`. */
+    headerHeight?: number;
+    /** Independent density for the header row. */
+    headerDensity?: Density;
+    /**
+     * Minimum column width enforced during drag-resize.
+     * Prevents columns from being resized to an unusably narrow state.
+     * Default: `80` (px).
+     */
+    minResizeWidth?: number;
+    rowHeight?: number;
+    overscan?: number;
+    /**
+     * When total post-filter rows ≤ this number, virtualization is disabled for
+     * simpler DOM. Default `300`.
+     */
+    virtualizationThreshold?: number;
+    selectable?: boolean;
+    sortable?: boolean;
+    filterable?: boolean;
+    groupable?: boolean;
+    virtualized?: boolean;
+    /** 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;
+    /** 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;
+    /**
+     * Enable infinite-scroll mode. Mutually exclusive with `pagination`.
+     * When enabled, `PaginationControls` are hidden and `onLoadMore` is
+     * called automatically when the user scrolls near the bottom.
+     */
+    infiniteScroll?: InfiniteScrollOptions;
+    /**
+     * Controls how the global search bar matches text.
+     * Default `"contains"`.
+     */
+    searchMode?: SearchMode;
+    /**
+     * @deprecated Not implemented. Will be removed in a future major version.
+     * Use `onFilterChange` + your own state to build a saved-filter UI.
+     */
+    savedFilters?: SavedFilter[];
+    /**
+     * @deprecated Not implemented. Will be removed in a future major version.
+     */
+    onSaveFilter?: (filter: Omit<SavedFilter, "id">) => void;
+    /**
+     * @deprecated Not implemented. Will be removed in a future major version.
+     */
+    onLoadFilter?: (filter: SavedFilter) => void;
+    /**
+     * @deprecated Not implemented. Will be removed in a future major version.
+     */
+    onDeleteFilter?: (filterId: string) => void;
+    /** Fired on every filter change — useful for server-side filtering. */
+    onFilterChange?: (payload: ServerFilterChangePayload) => void;
+    /**
+     * 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";
+    groupFooterVariant?: "chips" | "columns";
+    showGroupExpandControls?: boolean;
+    renderGroupActions?: (groupInfo: {
+        groupKey: string;
+        columnKey: string;
+        groupValue: any;
+        rows: GridRow[];
+        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;
+    /**
+     * Called when the user copies cells with Ctrl/⌘+C while cell focus or
+     * rectangular selection is active.
+     */
+    onCopyCells?: (payload: CopyCellsPayload) => void;
+    /**
+     * Fired after the user commits an edit (Enter / Tab / blur).
+     * Update your `data` prop here to reflect the change.
+     */
+    onCellEdit?: (params: CellEditParams) => void;
+    /**
+     * Fired the moment an edit session opens (double-click or F2).
+     * Return `false` to veto the edit.
+     */
+    onCellEditStart?: (params: {
+        row: GridRow;
+        column: GridColumn;
+        value: any;
+    }) => boolean | void;
+    onAutosizeColumn?: (columnKey: string) => void;
+    onAutosizeAllColumns?: () => void;
+    onResetColumns?: () => void;
+    onColumnConfigChange?: (config: ColumnConfig) => void;
+    initialColumnConfig?: Partial<ColumnConfig>;
+    performanceConfig?: PerformanceConfig;
+    /**
+     * When `true`, enables inline editing for **all** columns that do not
+     * explicitly set `editable: false`. Individual columns can still opt out
+     * by setting `editable: false` on their column definition.
+     *
+     * Columns that already have their own `editable` setting are unaffected.
+     *
+     * Pair with `onCellEdit` to receive the committed values.
+     */
+    editable?: boolean;
+}
+export interface KDGridRef {
+    /** Replace the entire ordered grouping key list. */
+    setGroupKeys: (keys: string[]) => void;
+    /** Append a grouping key if not already present. */
+    addGroupKey: (key: string) => void;
+    /** Remove a specific grouping key. */
+    removeGroupKey: (key: string) => void;
+    /** Expand every group for the current grouping keys. */
+    expandAllGroups: () => void;
+    /** Collapse all groups. */
+    collapseAllGroups: () => void;
+    /** Toggle a specific group path, e.g. `"City=SF|Status=Open"`. */
+    toggleGroupExpansion: (groupPath: string) => void;
+    /** Read the current grouping configuration. */
+    getGroupConfig: () => GroupConfig;
+    /** 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 active filters (global + column). */
+    clearAllFilters: () => void;
+    /** Set the global search text. */
+    setGlobalFilter: (value: string) => void;
+    /**
+     * Scroll the grid body so that the row with the given id is visible.
+     * Falls back silently if the row is not found in the current view.
+     */
+    scrollToRow: (rowId: string | number) => void;
+    /**
+     * Scroll the grid body so that the column with the given key is visible.
+     * Falls back silently if the column is not found.
+     */
+    scrollToColumn: (columnKey: string) => void;
+}

package/dist/utils/dateUtils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal inline date utilities — replaces the date-fns dependency so
+ * consumers don't need to install date-fns to use KDGrid.
+ *
+ * We only use two operations from date-fns across the entire library:
+ *   format(date, "yyyy-MM-dd")  → toYMD(date)
+ *   parse(str,  "yyyy-MM-dd", referenceDate)  → fromYMD(str)
+ *
+ * These ~20 lines are far cheaper than shipping a 30 KB peer dependency.
+ */
+/** Format a Date to "yyyy-MM-dd" (ISO date portion only). */
+export declare const toYMD: (d: Date) => string;
+/** Parse a "yyyy-MM-dd" string into a Date (local midnight). Returns Invalid Date on failure. */
+export declare const fromYMD: (s: string) => Date;
+/** Format a Date to human-readable "dd-MM-yyyy" for display. */
+export declare const toDMY: (d: Date) => string;

package/dist/utils/highlightText.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+/**
+ * Highlights matching text within a string based on a search query
+ * @param text - The text to highlight
+ * @param searchQuery - The search query to match against
+ * @returns JSX element with highlighted matches
+ */
+export declare const highlightText: (text: string, searchQuery: string) => React.ReactNode;
+/**
+ * Checks if a value contains the search query (case-insensitive)
+ * @param value - The value to check
+ * @param searchQuery - The search query
+ * @returns true if the value contains the search query
+ */
+export declare const containsSearchQuery: (value: any, searchQuery: string) => boolean;

package/dist/utils/license.d.ts

@@ -0,0 +1,3 @@
+export declare function setLicenseKey(key: string): void;
+export declare function getLicenseKey(): string | undefined;
+export declare function validateLicense(key?: string): boolean;