ezux 1.1.13 → 1.1.18

package/dist/components/EzTable/hooks/useTableHistory.d.ts

@@ -0,0 +1,87 @@
+import { SetStateAction } from 'react';
+/**
+ * Supported action types for table history tracking.
+ */
+export type TableActionType = 'ADD_ROW' | 'DELETE_ROW' | 'EDIT_CELL';
+/**
+ * Represents a single action in the table history.
+ * @group Models
+ */
+export interface TableAction<TData> {
+    /** Type of action performed. @group Properties */
+    type: TableActionType;
+    /** Metadata about the action (row, column, values). @group Properties */
+    payload: {
+        rowIndex?: number;
+        rowId?: string | number;
+        columnId?: string;
+        oldValue?: any;
+        newValue?: any;
+        row?: TData;
+    };
+    /** Execution timestamp. @group Properties */
+    timestamp: number;
+}
+/**
+ * State container for undo/redo history.
+ * @group Models
+ */
+export interface HistoryState<TData> {
+    /** List of past actions (undo stack). @group Properties */
+    past: TableAction<TData>[];
+    /** List of future actions (redo stack). @group Properties */
+    future: TableAction<TData>[];
+}
+/**
+ * Internal state structure for the history hook.
+ * @group Models
+ */
+export interface TableHistoryState<TData> {
+    /** Current table data. @group Properties */
+    data: TData[];
+    /** History stacks. @group Properties */
+    history: HistoryState<TData>;
+}
+/**
+ * Optimized hook for managing table data with undo/redo capabilities.
+ * Tracks added, edited, and deleted rows relative to the initial dataset.
+ *
+ * @param initialData - The baseline data for the table
+ * @param idField - Field name used as a unique identifier (default: 'id')
+ * @returns State and methods for data manipulation and history tracking
+ * @group Hooks
+ */
+export declare const useTableHistory: <TData extends object>(initialData: TData[], idField?: string) => {
+    /** Current table data including uncommitted changes. @group State */
+    data: TData[];
+    /** Programmatically set the table data. @group Methods */
+    setData: (action: SetStateAction<TData[]>) => void;
+    /** Perform a cell edit at a specific coordinate. @group Methods */
+    performEdit: (rowIndex: number, columnId: string, newValue: any) => void;
+    /** Add a new row to the data. @group Methods */
+    addRow: (newRow: TData, index?: number) => void;
+    /** Delete one or more rows by index. @group Methods */
+    deleteRows: (rowIndices: number[]) => void;
+    /** Undo the last recorded action. @group Methods */
+    undo: () => void;
+    /** Redo the last undone action. @group Methods */
+    redo: () => void;
+    /** Whether undo is currently available. @group State */
+    canUndo: boolean;
+    /** Whether redo is currently available. @group State */
+    canRedo: boolean;
+    /** Dictionary of change counts (added, edited, deleted) relative to initialData. @group State */
+    changes: {
+        added: number;
+        edited: number;
+        deleted: number;
+    };
+    /** Detailed lists of added, changed, and deleted records. @group State */
+    batchChanges: {
+        addedRecords: TData[];
+        changedRecords: TData[];
+        deletedRecords: TData[];
+    };
+    /** Reset all changes back to the initial state. @group Methods */
+    resetData: () => void;
+};

package/dist/components/EzTable/hooks/useTableImperative.d.ts

@@ -0,0 +1,42 @@
+import { Table } from '@tanstack/react-table';
+import { EzTableProps, EzTableRef } from '../EzTable.types';
+/**
+ * Consolidates the massive imperative API for EzTable using shared factory utilities.
+ * Reduces boilerplate and ensures consistent naming conventions.
+ */
+export declare const useTableImperative: <TData extends object>(props: EzTableProps<TData>, table: Table<TData>, data: TData[], methods: {
+    refresh: () => void;
+    setData: React.Dispatch<React.SetStateAction<TData[]>>;
+    performEdit: (rowIndex: number, columnId: string, value: unknown) => void;
+    showSpinner: () => void;
+    hideSpinner: () => void;
+    scrollToIndex: (index: number) => void;
+    toggleRowEditing: (rowIndex: number, editing?: boolean) => void;
+    forceUpdate: () => void;
+    resetData: () => void;
+    setPagerMessage: (msg: string | undefined) => void;
+    batchChanges: {
+        addedRecords: TData[];
+        changedRecords: TData[];
+        deletedRecords: TData[];
+    };
+    changes: {
+        added: number;
+        edited: number;
+        deleted: number;
+    };
+    addRow: (row: TData, index?: number) => void;
+    deleteRows: (indices: number[]) => void;
+    setFocusedCell: (cell: {
+        r: number;
+        c: number;
+    } | null) => void;
+    autoFitColumn: (columnId: string, options?: {
+        onlyVisible?: boolean;
+        maxWidth?: number;
+    }) => void;
+    addMutation?: any;
+    updateMutation?: any;
+    deleteMutation?: any;
+    service?: any;
+}, ref: React.Ref<EzTableRef<TData>>, extraApi?: any) => EzTableRef<TData>;

package/dist/components/EzTable/hooks/useTableSelection.d.ts

@@ -0,0 +1,32 @@
+import { Table } from '@tanstack/react-table';
+import { EzTableProps } from '../EzTable.types';
+/**
+ * Handles selection logic for EzTable, including range selection.
+ * Integrates with TanStack table's selection state for row selection.
+ *
+ * @param props - Table properties of type {@link EzTableProps}
+ * @param table - The TanStack Table instance
+ * @returns Selection state and event handlers
+ * @group Hooks
+ */
+export declare const useTableSelection: <TData extends object>(props: EzTableProps<TData>, table: Table<TData>) => {
+    /** Cell-based range selection state. @group State */
+    rangeSelection: {
+        start: {
+            r: number;
+            c: number;
+        };
+        end: {
+            r: number;
+            c: number;
+        };
+    } | null;
+    /** Handler for mouse down event on a cell. @group Events */
+    onCellMouseDown: (rowIndex: number, colIndex: number) => void;
+    /** Handler for mouse enter event on a cell. @group Events */
+    onCellMouseEnter: (rowIndex: number, colIndex: number) => void;
+    /** Imperatively select a range of rows. @group Methods */
+    selectRowByRange: (startIndex: number, endIndex: number) => void;
+    /** Whether a selection operation is currently active. @group State */
+    isSelecting: boolean;
+};

package/dist/components/EzTable/hooks/useTableState.d.ts

@@ -0,0 +1,33 @@
+import { SortingState, ColumnFiltersState, PaginationState, RowSelectionState, GroupingState, ExpandedState, RowPinningState, ColumnPinningState, Table } from '@tanstack/react-table';
+import { EzTableProps, EzGlobalFilterState } from '../EzTable.types';
+/**
+ * Core state and TanStack table instance initialization for EzTable.
+ * Handles persistence and basic state synchronization via unified useComponentState.
+ */
+export declare const useTableState: <TData extends object>(props: EzTableProps<TData>, currentData: TData[]) => {
+    table: Table<TData>;
+    states: {
+        sorting: SortingState;
+        setSorting: (updater: any) => void;
+        columnFilters: ColumnFiltersState;
+        setColumnFilters: (updater: any) => void;
+        globalFilter: EzGlobalFilterState;
+        setGlobalFilter: (updater: any) => void;
+        rowSelection: RowSelectionState;
+        setRowSelection: (updater: any) => void;
+        paginationState: PaginationState;
+        setPaginationState: (updater: any) => void;
+        grouping: GroupingState;
+        setGrouping: (updater: any) => void;
+        expanded: ExpandedState;
+        setExpanded: (updater: any) => void;
+        rowPinning: RowPinningState;
+        setRowPinning: (updater: any) => void;
+        columnPinning: ColumnPinningState;
+        setColumnPinning: (updater: any) => void;
+        columnVisibility: Record<string, boolean>;
+        setColumnVisibility: (updater: any) => void;
+        columnOrder: string[];
+        setColumnOrder: (updater: any) => void;
+    };
+};

package/dist/components/EzTable/hooks/useTableVirtualization.d.ts

@@ -0,0 +1,35 @@
+import { Table } from '@tanstack/react-table';
+import { EzTableProps } from '../EzTable.types';
+/**
+ * Handles table virtualization using the shared useVirtualization hook.
+ * Maps table density and column sizes to virtualization parameters.
+ *
+ * @param props - Table properties of type {@link EzTableProps}
+ * @param table - The TanStack Table instance
+ * @returns Virtualization state and scroll methods
+ * @group Hooks
+ */
+export declare const useTableVirtualization: <TData extends object>(props: EzTableProps<TData>, table: Table<TData>, dir?: "ltr" | "rtl") => {
+    /** Reference to the scrollable container. @group Properties */
+    parentRef: import('react').RefObject<HTMLDivElement | null>;
+    /** Row virtualizer instance. @group Properties */
+    rowVirtualizer: import('@tanstack/virtual-core').Virtualizer<HTMLDivElement, Element>;
+    /** Column virtualizer instance (if enabled). @group Properties */
+    columnVirtualizer: import('@tanstack/virtual-core').Virtualizer<HTMLDivElement, Element> | undefined;
+    /** Scroll to a specific item index. @group Methods */
+    scrollToIndex: (index: number, options?: {
+        align?: "start" | "center" | "end" | "auto";
+    }) => void;
+    /** Scroll to a specific row. @group Methods */
+    scrollToRow: (index: number, options?: {
+        align?: "start" | "center" | "end" | "auto";
+    }) => void;
+    /** Scroll to a specific column. @group Methods */
+    scrollToColumn: ((index: number, options?: {
+        align?: "start" | "center" | "end" | "auto";
+    }) => void) | undefined;
+    /** Calculated row height based on density or props. @group Properties */
+    effectiveRowHeight: number;
+    /** Whether rows are measured from rendered content. @group Properties */
+    dynamicRowSizing: boolean;
+};

package/dist/components/EzTable/index.d.ts

@@ -0,0 +1,54 @@
+import { default as React } from 'react';
+import { EzTableProps, EzTableRef } from './EzTable.types';
+export declare const EzTablePrimitive: <TData extends object>({ ref, ...props }: EzTableProps<TData> & {
+    ref?: React.Ref<EzTableRef<TData>>;
+}) => React.JSX.Element;
+/**
+ * EzTable is a high-performance, enterprise-grade data grid engine.
+ * Built on TanStack Table v8, it combines lightweight core logic with powerful
+ * features like virtualization, advanced filtering, and modular editing.
+ *
+
+ * ### Core Capabilities
+ * - **Superior Performance**: Row and column virtualization for smooth handling of 100k+ records.
+ * - **Smart Data Fetching**: Support for infinite scroll, server-side pagination, and caching via React Query.
+ * - **Flexible Editing**: Choose between `Normal` (inline), `Dialog` (form-based), or `Batch` editing modes.
+ * - **Advanced Interactivity**: Range selection, drag-and-drop column reordering, and context menus.
+ * - **Data Intelligence**: Built-in export (Excel/CSV/PDF), column pinning, and grouping.
+ *
+ * ### Minimal Example
+ * ```tsx
+ * <EzTable
+ *   data={employees}
+ *   columns={[
+ *     { accessorKey: 'name', header: 'Name' },
+ *     { accessorKey: 'role', header: 'Role' }
+ *   ]}
+ *   pagination
+ *   enableFiltering
+ * />
+ * ```
+ *
+ * ### Advanced Config: Editing & Persistence
+ * ```tsx
+ * <EzTable
+ *   data={data}
+ *   columns={columns}
+ *   editSettings={{
+ *     allowEditing: true,
+ *     mode: 'Batch',
+ *     primaryKey: 'id'
+ *   }}
+ *   enablePersistence
+ *   persistenceKey="user-table-grid"
+ *   onBatchSave={(changes) => saveToDatabase(changes)}
+ * />
+ * ```
+ *
+ * @group Core Components
+ */
+export declare function EzTable<TData extends object>({ ref, ...props }: EzTableProps<TData> & {
+    ref?: React.Ref<EzTableRef<TData>>;
+}): React.JSX.Element;
+export * from './context/EzTableContext';
+export * from './utils/SizingUtils';

package/dist/components/EzTable/renderers/index.d.ts

@@ -0,0 +1,6 @@
+export * from '../../../shared/components/BaseCell';
+export * from '../../../shared/components/PrimitiveRenderer';
+export * from '../../../shared/components/BooleanRenderer';
+export * from '../../../shared/components/SelectRenderer';
+export * from '../../../shared/components/ChartRenderer';
+export * from '../../../shared/components/SearchableSelect';

package/dist/components/EzTable/services/TableService.d.ts

@@ -0,0 +1,29 @@
+import { ITableService, TableParams } from '../EzTable.types';
+/**
+ * TableService implementation following the ServiceRegistry pattern.
+ * Provides mock server-side operations like sorting, filtering, and pagination.
+ */
+export declare class TableService<T extends Record<string, unknown>> implements ITableService<T> {
+    name: string;
+    init(): Promise<void>;
+    cleanup(): Promise<void>;
+    /**
+     * Seeds the mock database with initial data.
+     */
+    initializeWithData(data: T[]): void;
+    /**
+     * Simulates fetching data from a server with support for sorting, filtering, and pagination.
+     */
+    getData(params: TableParams<T>): Promise<{
+        data: T[];
+        totalCount: number;
+    }>;
+    fetchData(query: unknown): Promise<{
+        data: T[];
+        rowCount?: number;
+    }>;
+    createRow(row: Partial<T>): Promise<T>;
+    updateRow(id: string | number, updates: Partial<T>): Promise<T>;
+    deleteRow(id: string | number): Promise<void>;
+    private simulateLatency;
+}

package/dist/components/EzTable/types/EzTableColumn.types.d.ts

@@ -0,0 +1,146 @@
+import { default as React } from 'react';
+import { Row, Column, Table, RowData, ColumnDef as TanStackColumnDef } from '@tanstack/react-table';
+import { FilterSettings, SearchSettings, SortSettings, TextWrapSettings } from './EzTableFilter.types';
+import { SelectionSettings, EditSettings } from './EzTableEdit.types';
+import { EzTableClassNames, EzTableIcons, EzTableSlots, EzTableLocalization } from './EzTableProps';
+/**
+ * Props passed to custom cell renderers.
+ * @group Models
+ */
+export interface EzTableCellProps<TData = Record<string, unknown>, TValue = unknown> {
+    /** Returns the current cell value. @group Properties */
+    getValue: () => TValue;
+    /** The TanStack Row instance. @group Properties */
+    row: Row<TData>;
+    /** The TanStack Column instance. @group Properties */
+    column: Column<TData, TValue>;
+    /** The TanStack Table instance. @group Properties */
+    table: Table<TData>;
+}
+/**
+ * Props passed to custom editor components.
+ * @group Models
+ */
+export interface EzTableEditorProps<TData = Record<string, unknown>, TValue = unknown> extends EzTableCellProps<TData, TValue> {
+    /** Current value in the editor. @group Properties */
+    value: TValue;
+    /** Callback to update the value. @group Events */
+    onChange: (value: TValue) => void;
+    /** Callback when the editor loses focus. @group Events */
+    onBlur: () => void;
+}
+/**
+ * Extended metadata for EzTable columns, supporting rich features
+ * like editor types, chart options, and formatting.
+ * @group Models
+ */
+export type EzColumnMeta = {
+    /** Custom cell component. @group Components */
+    Cell?: React.ComponentType<EzTableCellProps<Record<string, unknown>, unknown>>;
+    /** Custom editor component. @group Components */
+    Editor?: React.ComponentType<EzTableEditorProps<Record<string, unknown>, unknown>>;
+    /** Custom filter component. @group Components */
+    Filter?: React.ComponentType<unknown>;
+    /** Filter UI variant. @group Properties */
+    filterVariant?: 'text' | 'range' | 'select';
+    /** Column content alignment. @group Properties */
+    align?: 'left' | 'center' | 'right';
+    /** Column header icon. @group Properties */
+    icon?: React.ReactNode;
+    /** Whether to wrap text in cells. @group Properties */
+    wrapText?: boolean;
+    /** Text clipping mode. @group Properties */
+    clipMode?: 'clip' | 'ellipsis' | 'ellipsis-tooltip';
+    /** Whether to automatically fit column width to content. @group Properties */
+    autoFit?: boolean;
+    /** Predefined column type for automatic formatting/editing. @group Properties */
+    columnType?: 'text' | 'longtext' | 'number' | 'boolean' | 'date' | 'datetime' | 'select' | 'multiselect' | 'chart' | 'sparkline' | 'progress';
+    /** Options for boolean columns. @group Properties */
+    booleanOptions?: {
+        trueLabel?: string;
+        falseLabel?: string;
+        nullLabel?: string;
+        showIcon?: boolean;
+        showLabel?: boolean;
+        variant?: 'checkbox' | 'switch';
+    };
+    /** Options for chart/progress columns. @group Properties */
+    chartOptions?: {
+        color?: 'default' | 'success' | 'warning' | 'danger' | 'info';
+        size?: 'sm' | 'md' | 'lg';
+        showLabel?: boolean;
+        height?: number;
+        width?: number;
+        showDots?: boolean;
+    };
+    /** Options for long text columns. @group Properties */
+    longTextOptions?: {
+        previewLength?: number;
+    };
+    /** Options for numeric columns. @group Properties */
+    numberOptions?: {
+        format?: 'integer' | 'float' | 'currency' | 'percentage';
+        decimals?: number;
+        currency?: string;
+        locale?: string;
+    };
+    /** Options for date columns. @group Properties */
+    dateOptions?: {
+        format?: 'short' | 'medium' | 'long' | 'full';
+        locale?: string;
+    };
+    /** Options for date-time columns. @group Properties */
+    dateTimeOptions?: {
+        format?: 'short' | 'medium' | 'long' | 'full' | 'relative';
+        showIcon?: boolean;
+        locale?: string;
+    };
+    /** Options for select/dropdown columns. @group Properties */
+    selectOptions?: {
+        options?: {
+            value: unknown;
+            label: string;
+            color?: string;
+            icon?: React.ReactNode;
+        }[];
+        multiSelect?: boolean;
+        variant?: 'dropdown' | 'radio' | 'combobox';
+    };
+    /** Grid lines configuration for this column. @group Properties */
+    gridLines?: 'Both' | 'Horizontal' | 'Vertical' | 'None';
+};
+declare module '@tanstack/react-table' {
+    interface TableMeta<TData extends RowData> {
+        updateData?: (rowIndex: number, columnId: string, value: unknown) => void;
+        editingRows?: Record<string, boolean>;
+        toggleRowEditing?: (rowIndex: number, editing?: boolean) => void;
+        focusedCell?: {
+            r: number;
+            c: number;
+        } | null;
+        setFocusedCell?: (cell: {
+            r: number;
+            c: number;
+        } | null) => void;
+        navigateFocus?: (dr: number, dc: number) => void;
+        enableEditing?: boolean;
+        isRowEditable?: (row: TData) => boolean;
+        isCellEditable?: (row: TData, columnId: string) => boolean;
+        enableSearchHighlighting?: boolean;
+        selectionSettings?: SelectionSettings;
+        editSettings?: EditSettings;
+        filterSettings?: FilterSettings;
+        searchSettings?: SearchSettings;
+        sortSettings?: SortSettings;
+        textWrapSettings?: TextWrapSettings;
+        classNames?: EzTableClassNames<TData>;
+        icons?: EzTableIcons;
+        slots?: EzTableSlots<TData>;
+        slotProps?: Record<string, unknown>;
+        localization?: EzTableLocalization;
+        gridLines?: 'Both' | 'Horizontal' | 'Vertical' | 'None';
+    }
+    interface ColumnMeta<TData extends RowData, TValue> extends EzColumnMeta {
+    }
+}
+export type ColumnDef<TData, TValue = unknown> = TanStackColumnDef<TData, TValue>;

package/dist/components/EzTable/types/EzTableEdit.types.d.ts

@@ -0,0 +1,58 @@
+import { default as React } from 'react';
+/**
+ * Configuration for row/cell selection behavior.
+ * @group Models
+ */
+export interface SelectionSettings {
+    /** Selection mode. @group Properties */
+    mode?: 'Row' | 'Cell' | 'Both';
+    /** Selection type. @group Properties */
+    type?: 'Single' | 'Multiple';
+    /** Whether to allow selection only via checkbox. @group Properties */
+    checkboxOnly?: boolean;
+    /** Whether to persist selection across data updates. @group Properties */
+    persistSelection?: boolean;
+}
+/**
+ * Configuration for editing behavior.
+ * @group Models
+ */
+export interface EditSettings {
+    /** Whether to allow adding new rows. @group Properties */
+    allowAdding?: boolean;
+    /** Whether to allow editing existing rows. @group Properties */
+    allowEditing?: boolean;
+    /** Whether to allow deleting rows. @group Properties */
+    allowDeleting?: boolean;
+    /** Edit mode. @group Properties */
+    mode?: 'Normal' | 'Dialog' | 'Batch';
+    /** Position for newly added rows. @group Properties */
+    newRowPosition?: 'Top' | 'Bottom';
+    /** Whether to allow editing on double-click. @group Properties */
+    allowEditOnDblClick?: boolean;
+    /** Primary key field(s) for identification. @group Properties */
+    primaryKey?: string | string[];
+}
+export type ToolbarItemType = 'Search' | 'Print' | 'Export' | 'Add' | 'Edit' | 'Delete' | 'Update' | 'Cancel' | 'ColumnChooser' | string;
+/**
+ * Represents an item in the table toolbar.
+ * @group Models
+ */
+export interface ToolbarItem {
+    /** Display text for the item. @group Properties */
+    text?: string;
+    /** Tooltip text for the item. @group Properties */
+    tooltipText?: string;
+    /** Prefix icon for the item. @group Properties */
+    prefixIcon?: string | React.ReactNode;
+    /** Unique identifier for the item. @group Properties */
+    id?: string;
+    /** Alignment in the toolbar. @group Properties */
+    align?: 'Left' | 'Right' | 'Center';
+    /** Predefined or custom type. @group Properties */
+    type?: ToolbarItemType;
+    /** Custom template for rendering the item. @group Properties */
+    template?: React.ReactNode;
+    /** Callback when the item is clicked. @group Events */
+    onClick?: (e: React.MouseEvent) => void;
+}

package/dist/components/EzTable/types/EzTableFilter.types.d.ts

@@ -0,0 +1,50 @@
+import { FilterOperator as SharedFilterOperator, FilterRule as SharedFilterRule, FilterGroup as SharedFilterGroup } from '../../../shared/types/common';
+export type FilterOperator = SharedFilterOperator;
+export type FilterRule = SharedFilterRule;
+export type FilterGroup = SharedFilterGroup;
+/**
+ * Configuration for filtering behavior.
+ * @group Models
+ */
+export interface FilterSettings {
+    /** Filter UI type. @group Properties */
+    type?: 'Menu' | 'CheckBox' | 'Excel';
+    /** Whether to ignore accents during filtering. @group Properties */
+    ignoreAccent?: boolean;
+    /** Filter application mode. @group Properties */
+    mode?: 'Immediate' | 'OnEnter';
+    /** Whether to show the filter bar status. @group Properties */
+    showFilterBarStatus?: boolean;
+}
+/**
+ * Configuration for global search behavior.
+ * @group Models
+ */
+export interface SearchSettings {
+    /** Specific fields to search in. @group Properties */
+    fields?: string[];
+    /** Search operator. @group Properties */
+    operator?: 'contains' | 'startsWith' | 'endsWith' | 'equal';
+    /** Search key/term. @group Properties */
+    key?: string;
+    /** Whether to ignore case during search. @group Properties */
+    ignoreCase?: boolean;
+}
+/**
+ * Configuration for sorting behavior.
+ * @group Models
+ */
+export interface SortSettings {
+    /** Sort mode (single or multiple columns). @group Properties */
+    mode?: 'Single' | 'Multiple';
+    /** Whether to allow unsorting columns. @group Properties */
+    allowUnsort?: boolean;
+}
+/**
+ * Configuration for text wrapping.
+ * @group Models
+ */
+export interface TextWrapSettings {
+    /** Wrap mode for header, content or both. @group Properties */
+    wrapMode?: 'Both' | 'Header' | 'Content';
+}