@insticc/react-datagrid-2 1.1.11 → 1.1.13

package/README.md

@@ -0,0 +1,1051 @@
+# DataGrid Component
+
+A powerful and flexible React data grid component built on top of Material React Table, providing advanced features for data visualization, filtering, sorting, pagination, and row selection.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Props Reference](#props-reference)
+  - [Core Props](#core-props)
+  - [Column Configuration](#column-configuration)
+  - [Actions & Toolbar](#actions--toolbar)
+  - [Export Options](#export-options)
+  - [Selection & Interaction](#selection--interaction)
+  - [Pagination & Display](#pagination--display)
+  - [Styling & Layout](#styling--layout)
+  - [Advanced Features](#advanced-features)
+- [Column Types](#column-types)
+- [Examples](#examples)
+- [API Reference](#api-reference)
+
+---
+
+## Installation
+
+```bash
+npm install @insticc/react-datagrid-2
+```
+
+### Required Dependencies
+
+```bash
+npm install react prop-types material-react-table semantic-ui-react @mui/material bootstrap
+```
+
+---
+
+## Basic Usage
+
+```jsx
+import React, { useState } from 'react';
+import DataGrid from '@insticc/react-datagrid-2';
+
+function MyComponent() {
+  const [selectedRows, setSelectedRows] = useState([]);
+
+  const columns = [
+    { accessorKey: 'id', header: 'ID', type: 'text' },
+    { accessorKey: 'name', header: 'Name', type: 'text' },
+    { accessorKey: 'email', header: 'Email', type: 'email' },
+    { accessorKey: 'createdAt', header: 'Created', type: 'date', isDateColumn: true },
+  ];
+
+  const data = [
+    { id: '1', name: 'John Doe', email: 'john@example.com', createdAt: '2025-01-15' },
+    { id: '2', name: 'Jane Smith', email: 'jane@example.com', createdAt: '2025-02-20' },
+  ];
+
+  return (
+    <DataGrid
+      columns={columns}
+      createRows={data}
+      rowKey="id"
+      selectData={setSelectedRows}
+      hasExcelExport={true}
+      hasPdfExport={true}
+    />
+  );
+}
+```
+
+---
+
+## Props Reference
+
+### Core Props
+
+#### `columns` (required)
+- **Type:** `Array`
+- **Description:** Array of column definitions that determine how data is displayed
+- **Example:**
+```jsx
+const columns = [
+  {
+    accessorKey: 'name',        // Key to access data
+    header: 'Full Name',        // Column header text
+    type: 'text',               // Cell type - formatter applied automatically
+    enableSorting: true,        // Enable/disable sorting
+    enableColumnFilter: true,   // Enable/disable filtering
+    filterFn: 'contains',       // Filter function type
+    isDateColumn: false,        // Special handling for dates
+    cellClass: 'custom-class',  // CSS class wrapping cell content
+    Cell: CustomComponent,      // Optional: Custom cell renderer (receives typeValue)
+  }
+];
+```
+
+**Column Rendering Modes:**
+- `type` only: Formatter applied automatically
+- `type` + `cellClass`: Formatted content wrapped in div
+- `type` + `Cell`: Custom component receives `typeValue` (formatted content)
+- `Cell` only: Full custom rendering without type formatter
+
+#### `createRows` (required)
+- **Type:** `Array`
+- **Description:** Array of data objects to display in the grid
+- **Example:**
+```jsx
+const data = [
+  { id: 1, name: 'John', email: 'john@example.com' },
+  { id: 2, name: 'Jane', email: 'jane@example.com' }
+];
+```
+
+#### `rowKey` (required)
+- **Type:** `string`
+- **Description:** Property name used as unique identifier for each row
+- **Default:** `'id'`
+- **Example:** `rowKey="id"` or `rowKey="uuid"`
+
+#### `selectData` (required)
+- **Type:** `function`
+- **Description:** Callback function that receives selected rows whenever selection changes
+- **Signature:** `(selectedRows: Array) => void`
+- **Example:**
+```jsx
+const handleSelection = (rows) => {
+  console.log('Selected rows:', rows);
+};
+
+<DataGrid selectData={handleSelection} />
+```
+
+---
+
+### Column Configuration
+
+#### `columnVisibilityState`
+- **Type:** `object`
+- **Default:** `{}`
+- **Description:** Controls which columns are visible/hidden
+- **Example:**
+```jsx
+columnVisibilityState={{
+  email: false,    // Hide email column
+  phone: true      // Show phone column
+}}
+```
+
+#### `columnOrder`
+- **Type:** `Array<string>`
+- **Default:** `[]`
+- **Description:** Defines the order of columns by their accessorKey
+- **Example:**
+```jsx
+columnOrder={['name', 'email', 'id']}
+```
+
+---
+
+### Actions & Toolbar
+
+#### `actions`
+- **Type:** `Array<ActionObject>`
+- **Default:** `null`
+- **Description:** Array of custom action buttons displayed in the toolbar
+- **Action Object Properties:**
+  - `name` (string): Button label
+  - `function` (function, required): Callback when button is clicked
+  - `tooltip` (string): Tooltip text on hover
+  - `color` (string): Button color - one of: `'blue'`, `'red'`, `'green'`, `'yellow'`, `'orange'`, `'black'`, `'grey'`, `'teal'`, `'brown'`, `'violet'`, `'purple'`, `'olive'`, `'pink'`
+  - `icon` (string|element): Icon name or React element
+  - `selectionMode` (string): When button is enabled - `'single'`, `'multi'`, `'always'`
+  - `confirmMessage` (string|element): Confirmation message before action
+  - `hasConfirmMessage` (boolean): Whether to show confirmation dialog
+  - `disabled` (boolean): Disable the button
+  - `visible` (boolean): Show/hide the button
+  - `toggle` (boolean): Toggle button style
+  - `active` (boolean): Toggle button active state
+- **Example:**
+```jsx
+actions={[
+  {
+    name: 'Delete',
+    function: (selectedRows) => handleDelete(selectedRows),
+    tooltip: 'Delete selected rows',
+    color: 'red',
+    icon: 'trash',
+    selectionMode: 'multi',
+    hasConfirmMessage: true,
+    confirmMessage: 'Are you sure you want to delete these rows?'
+  },
+  {
+    name: 'Edit',
+    function: (selectedRows) => handleEdit(selectedRows),
+    tooltip: 'Edit selected row',
+    color: 'blue',
+    icon: 'edit',
+    selectionMode: 'single'
+  },
+  {
+    name: 'Add New',
+    function: () => handleAdd(),
+    tooltip: 'Add new record',
+    color: 'green',
+    icon: 'plus',
+    selectionMode: 'always'
+  }
+]}
+```
+
+#### `enableTopToolbar`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Show/hide the top toolbar containing actions and pagination
+
+#### `enableBottomToolbar`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Show/hide the bottom toolbar
+
+#### `hasClearFiltersBtn`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Show/hide the "Clear Filters" button in toolbar
+
+#### `gridHelper`
+- **Type:** `object | null`
+- **Default:** `null`
+- **Description:** Adds a help button with custom content
+- **Required Properties (if defined):**
+  - `title` (string|element, required): Help dialog title
+  - `content` (string|element, required): Help dialog content
+- **Example:**
+```jsx
+gridHelper={{
+  title: 'Grid Instructions',
+  content: (
+    <div>
+      <p>Use the filters to search data</p>
+      <p>Click rows to select them</p>
+    </div>
+  )
+}}
+```
+
+---
+
+### Export Options
+
+#### `hasExcelExport`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enable Excel export button
+
+#### `excelOption`
+- **Type:** `string`
+- **Default:** `'selectedRows'`
+- **Options:** `'all'`, `'allRows'`, `'pageRows'`, `'selectedRows'`
+- **Description:** Determines which rows to export to Excel
+
+#### `hasPdfExport`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enable PDF export button
+
+#### `pdfOption`
+- **Type:** `string`
+- **Default:** `'selectedRows'`
+- **Options:** `'all'`, `'allRows'`, `'pageRows'`, `'selectedRows'`
+- **Description:** Determines which rows to export to PDF
+
+**Export Options Explained:**
+- `'all'` - Export all data including hidden columns
+- `'allRows'` - Export all rows (respects filters)
+- `'pageRows'` - Export only current page rows
+- `'selectedRows'` - Export only selected rows
+
+---
+
+### Selection & Interaction
+
+#### `disableSelect`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Disable row selection checkboxes and click-to-select behavior completely
+
+#### `enableMultiRowSelection`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Allow selecting multiple rows at once
+
+#### `selectAllMode`
+- **Type:** `string`
+- **Default:** `'page'`
+- **Options:** `'page'`, `'all'`
+- **Description:** 
+  - `'page'` - "Select All" checkbox selects only current page
+  - `'all'` - "Select All" checkbox selects all filtered rows
+
+#### `selectedIds`
+- **Type:** `Array`
+- **Default:** `[]`
+- **Description:** Array of row IDs that should be pre-selected
+- **Example:**
+```jsx
+selectedIds={[1, 5, 10]}  // Pre-select rows with these IDs
+```
+
+#### `disableRows`
+- **Type:** `Array`
+- **Default:** `[]`
+- **Description:** Array of row IDs that should be disabled (cannot be selected)
+- **Example:**
+```jsx
+disableRows={[3, 7]}  // Disable selection for these rows
+```
+
+#### `hasSubRows`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enable support for hierarchical/nested rows
+- **Note:** Requires data with `subRows` property
+
+#### `enableExpanding`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Show expand/collapse icons for rows with subRows
+
+---
+
+### Pagination & Display
+
+#### `enablePagination`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Enable/disable pagination
+
+#### `pagination`
+- **Type:** `string`
+- **Default:** `'both'`
+- **Options:** `'top'`, `'bottom'`, `'both'`
+- **Description:** Position of pagination controls
+
+#### `pageSize`
+- **Type:** `number`
+- **Default:** `150`
+- **Description:** Number of rows per page initially
+
+#### `itemsPerPage`
+- **Type:** `Array<number>`
+- **Default:** `[50, 100, 150]`
+- **Description:** Options for rows per page dropdown
+- **Example:**
+```jsx
+itemsPerPage={[10, 25, 50, 100]}
+```
+
+---
+
+### Styling & Layout
+
+#### `rowHeight`
+- **Type:** `number`
+- **Default:** `75`
+- **Description:** Minimum height of each row in pixels
+
+#### `fontSize`
+- **Type:** `number`
+- **Default:** `14`
+- **Description:** Base font size for grid content in pixels
+
+#### `gridHeight`
+- **Type:** `number | string`
+- **Default:** `600`
+- **Description:** Maximum height of the grid container
+- **Examples:**
+```jsx
+gridHeight={600}              // 600px
+gridHeight="80vh"             // 80% of viewport height
+gridHeight="fit-content"      // Auto height
+```
+
+#### `enableCompactStyleMode`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enable compact styling with reduced padding and responsive font sizes
+- **Features:**
+  - Smaller cell padding (2px vs auto)
+  - Responsive font sizing using clamp()
+  - Optimized for dense data display
+
+#### `getRowStyle`
+- **Type:** `function`
+- **Description:** Custom function to apply styles to rows based on data
+- **Signature:** `({ row }) => object`
+- **Example:**
+```jsx
+getRowStyle={({ row }) => ({
+  backgroundColor: row.original.status === 'active' ? '#e8f5e9' : 'white',
+  color: row.original.priority === 'high' ? 'red' : 'inherit'
+})}
+```
+
+#### `enableFixedHeader`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Pin headers to top when scrolling
+
+#### `enableFixedActions`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Pin action toolbar to top when scrolling (requires enableFixedHeader)
+
+---
+
+### Advanced Features
+
+#### `enableGlobalFilter`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Show global search input that filters all columns
+
+#### `globalFilterFn`
+- **Type:** `string`
+- **Default:** `'contains'`
+- **Options:** `'contains'`, `'fuzzy'`, `'between'`, `'equals'`, `'greaterThan'`, `'lessThan'`, `'notEquals'`, `'lessThanOrEqualTo'`, `'greaterThanOrEqualTo'`, `'empty'`, `'notEmpty'`, `'startsWith'`, `'endsWith'`, `'betweenInclusive'`
+- **Description:** Filter function for global search
+
+#### `enableColumnFilterModes`
+- **Type:** `boolean`
+- **Default:** `true`
+- **Description:** Allow users to change filter type per column (contains, equals, etc.)
+
+#### `enableVirtualization`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Enable row and column virtualization for large datasets (improves performance)
+- **Recommended for:** 1000+ rows
+
+#### `enableFullScreenToggle`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Show fullscreen toggle button
+
+#### `enableDensityToggle`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Show density toggle button (compact/comfortable/spacious)
+
+---
+
+### Cache & Updates
+
+#### `updateCache`
+- **Type:** `function`
+- **Default:** `undefined`
+- **Description:** Callback function triggered when cache update button is clicked
+- **Example:**
+```jsx
+updateCache={() => {
+  fetchLatestData();
+}}
+```
+
+#### `cacheUpdateText`
+- **Type:** `string`
+- **Default:** `undefined`
+- **Description:** Tooltip text for cache update button
+- **Example:** `"Refresh data from server"`
+
+#### `cacheUpdating`
+- **Type:** `boolean`
+- **Default:** `false`
+- **Description:** Shows loading state on cache update button
+
+---
+
+### Callbacks
+
+#### `onVisibleRowsChange`
+- **Type:** `function`
+- **Description:** Called whenever visible rows change (filtering, sorting, pagination)
+- **Signature:** `(visibleRows: Array) => void`
+- **Example:**
+```jsx
+onVisibleRowsChange={(rows) => {
+  console.log('Currently visible:', rows.length);
+}}
+```
+
+---
+
+## Column Types
+
+The DataGrid supports various pre-built cell types via the `type` property in column definitions:
+
+### Text Types
+- `text` - Plain text
+- `textTitle` - Bold text
+- `textDescription` - Gray text (#666)
+- `textSmall` - Small font text
+
+### Date Types
+- `date` - Date only (no time)
+- `datetime` - Date with time
+
+### Number Types
+- `number` - Raw number
+- `integer` - Rounded integer
+- `currency` - EUR currency format (€1,234.56)
+- `percentage` - Percentage format (12.34%)
+
+### Link Types
+- `email` - Clickable mailto link
+- `phone` - Clickable tel link
+- `link` - External link (opens in new tab)
+
+### Complex Types
+- `array` - Comma-separated array values
+- `json` - Formatted JSON display
+- `countryFlag` - Country flag image (requires ISO2 code)
+- `persons` - List of persons with "et al." notation
+
+### Example with Types
+
+```jsx
+const columns = [
+  { accessorKey: 'name', header: 'Name', type: 'textTitle' },
+  { accessorKey: 'description', header: 'Description', type: 'textDescription' },
+  { accessorKey: 'email', header: 'Email', type: 'email' },
+  { accessorKey: 'salary', header: 'Salary', type: 'currency' },
+  { accessorKey: 'completion', header: 'Progress', type: 'percentage' },
+  { accessorKey: 'createdAt', header: 'Created', type: 'date', isDateColumn: true },
+  { accessorKey: 'country', header: 'Country', type: 'countryFlag' },
+  { accessorKey: 'tags', header: 'Tags', type: 'array' },
+];
+```
+
+### Custom Cell Renderers with Type Support
+
+You have multiple options for cell rendering:
+
+#### Option 1: Using Type Alone (Simplest)
+```jsx
+const columns = [
+  {
+    accessorKey: 'price',
+    header: 'Price',
+    type: 'currency'  // Automatically formatted as currency
+  }
+];
+// No custom Cell needed - formatter is applied automatically
+```
+
+#### Option 2: Type + cellClass
+```jsx
+const columns = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    type: 'text',
+    cellClass: 'custom-status'  // Formatted text wrapped in <div class="custom-status">
+  }
+];
+```
+
+#### Option 3: Type + Custom Cell (Advanced)
+When you need both formatting AND custom logic:
+
+```jsx
+// Custom cell that uses the type formatter and adds custom styling
+const CustomStatusCell = ({ typeValue, cell, row }) => {
+  const value = cell.getValue();
+  
+  return (
+    <div style={{ 
+      color: value === 'active' ? 'green' : 'red',
+      fontWeight: 'bold' 
+    }}>
+      {typeValue || value}  {/* Use typeValue (formatted) or fallback to raw value */}
+    </div>
+  );
+};
+
+const columns = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    type: 'text',              // Formatter is applied first
+    Cell: CustomStatusCell,    // Custom component receives typeValue prop
+  }
+];
+```
+
+#### Option 4: Custom Cell Only (No Type)
+```jsx
+const CustomCell = ({ cell }) => {
+  return <strong>{cell.getValue()}</strong>;
+};
+
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    Cell: CustomCell  // No type - full control over rendering
+  }
+];
+```
+
+**How Cell Rendering Works:**
+1. If `type` is specified, `DEFAULT_CELL_TYPES[type]` formatter is applied automatically
+2. If `Cell` component is also provided, it receives all props including `typeValue` (the formatted result)
+3. If `cellClass` is specified, content is wrapped in `<div className={cellClass}>`
+4. Priority: Custom Cell (with typeValue) > Type formatter > Raw value
+
+**Note:** You can use `type` alone without a custom `Cell` component - the formatter will be applied automatically.
+
+---
+
+## Examples
+
+### Example 1: Basic Grid with Selection
+
+```jsx
+import React, { useState } from 'react';
+import DataGrid from '@insticc/react-datagrid-2';
+
+function UserGrid() {
+  const [selected, setSelected] = useState([]);
+
+  const columns = [
+    { accessorKey: 'id', header: 'ID', type: 'integer' },
+    { accessorKey: 'name', header: 'Name', type: 'textTitle' },
+    { accessorKey: 'email', header: 'Email', type: 'email' },
+    { accessorKey: 'role', header: 'Role', type: 'text' },
+  ];
+
+  const users = [
+    { id: 1, name: 'John Doe', email: 'john@company.com', role: 'Admin' },
+    { id: 2, name: 'Jane Smith', email: 'jane@company.com', role: 'User' },
+  ];
+
+  return (
+    <DataGrid
+      columns={columns}
+      createRows={users}
+      rowKey="id"
+      selectData={setSelected}
+      pageSize={50}
+      itemsPerPage={[25, 50, 100]}
+    />
+  );
+}
+```
+
+### Example 2: Grid with Actions and Exports
+
+```jsx
+function ProductGrid() {
+  const handleDelete = (rows) => {
+    const ids = rows.map(r => r.id);
+    console.log('Deleting:', ids);
+  };
+
+  const handleEdit = (rows) => {
+    if (rows.length === 1) {
+      console.log('Editing:', rows[0]);
+    }
+  };
+
+  const actions = [
+    {
+      name: 'Delete',
+      function: handleDelete,
+      tooltip: 'Delete selected products',
+      color: 'red',
+      icon: 'trash',
+      selectionMode: 'multi',
+      hasConfirmMessage: true,
+      confirmMessage: 'Are you sure you want to delete these products?'
+    },
+    {
+      name: 'Edit',
+      function: handleEdit,
+      tooltip: 'Edit product',
+      color: 'blue',
+      icon: 'edit',
+      selectionMode: 'single'
+    }
+  ];
+
+  return (
+    <DataGrid
+      columns={productColumns}
+      createRows={products}
+      rowKey="productId"
+      selectData={setSelected}
+      actions={actions}
+      hasExcelExport={true}
+      hasPdfExport={true}
+      excelOption="selectedRows"
+      pdfOption="allRows"
+    />
+  );
+}
+```
+
+### Example 3: Hierarchical Data with SubRows
+
+```jsx
+function ProjectGrid() {
+  const data = [
+    {
+      id: 1,
+      name: 'Project Alpha',
+      status: 'Active',
+      subRows: [
+        { id: '1.1', name: 'Task 1', status: 'Complete' },
+        { id: '1.2', name: 'Task 2', status: 'In Progress' }
+      ]
+    },
+    {
+      id: 2,
+      name: 'Project Beta',
+      status: 'Planning',
+      subRows: [
+        { id: '2.1', name: 'Task 1', status: 'Not Started' }
+      ]
+    }
+  ];
+
+  return (
+    <DataGrid
+      columns={projectColumns}
+      createRows={data}
+      rowKey="id"
+      selectData={setSelected}
+      hasSubRows={true}
+      enableExpanding={true}
+    />
+  );
+}
+```
+
+### Example 4: Custom Styling and Virtualization
+
+```jsx
+function LargeDataGrid() {
+  // Custom cell with type support
+  const StatusCell = ({ typeValue, cell }) => {
+    const value = cell.getValue();
+    const color = value === 'active' ? 'green' : 'red';
+    
+    return (
+      <span style={{ color, fontWeight: 'bold' }}>
+        {typeValue || value}
+      </span>
+    );
+  };
+
+  const getRowStyle = ({ row }) => {
+    if (row.original.status === 'error') {
+      return { backgroundColor: '#ffebee' };
+    }
+    if (row.original.priority === 'high') {
+      return { backgroundColor: '#fff3e0' };
+    }
+    return {};
+  };
+
+  const columns = [
+    { accessorKey: 'id', header: 'ID', type: 'integer' },
+    { 
+      accessorKey: 'status', 
+      header: 'Status', 
+      type: 'text',        // Formatter applied
+      Cell: StatusCell     // Custom cell receives typeValue
+    },
+    { accessorKey: 'name', header: 'Name', type: 'text' },
+  ];
+
+  return (
+    <DataGrid
+      columns={columns}
+      createRows={largeDataset}  // 10000+ rows
+      rowKey="id"
+      selectData={setSelected}
+      enableVirtualization={true}
+      enableCompactStyleMode={true}
+      rowHeight={40}
+      fontSize={12}
+      gridHeight="calc(100vh - 200px)"
+      getRowStyle={getRowStyle}
+      pageSize={100}
+    />
+  );
+}
+```
+
+### Example 5: Advanced Features
+
+```jsx
+function AdvancedGrid() {
+  const [cacheLoading, setCacheLoading] = useState(false);
+
+  const refreshData = async () => {
+    setCacheLoading(true);
+    await fetchLatestData();
+    setCacheLoading(false);
+  };
+
+  const handleVisibleRowsChange = (rows) => {
+    console.log('Visible rows count:', rows.length);
+  };
+
+  return (
+    <DataGrid
+      columns={columns}
+      createRows={data}
+      rowKey="id"
+      selectData={setSelected}
+      
+      // Advanced features
+      enableGlobalFilter={true}
+      globalFilterFn="fuzzy"
+      enableColumnFilterModes={true}
+      enableFixedHeader={true}
+      enableFixedActions={true}
+      
+      // Cache management
+      updateCache={refreshData}
+      cacheUpdateText="Refresh data from server"
+      cacheUpdating={cacheLoading}
+      
+      // Callbacks
+      onVisibleRowsChange={handleVisibleRowsChange}
+      
+      // Help
+      gridHelper={{
+        title: 'Data Grid Help',
+        content: (
+          <div>
+            <h3>Features</h3>
+            <ul>
+              <li>Click rows to select</li>
+              <li>Use column filters for search</li>
+              <li>Export to Excel or PDF</li>
+            </ul>
+          </div>
+        )
+      }}
+    />
+  );
+}
+```
+
+---
+
+## API Reference
+
+### Column Definition Object
+
+```typescript
+{
+  accessorKey: string;              // Required: Key to access data
+  header: string;                   // Required: Column header text
+  type?: string;                    // Cell type (see Column Types)
+  enableSorting?: boolean;          // Default: true
+  enableColumnFilter?: boolean;     // Default: true
+  enableColumnFilterModes?: boolean;// Default: true
+  filterFn?: string;                // Default: 'contains'
+  enableResizing?: boolean;         // Default: true
+  grow?: boolean;                   // Default: true
+  enableClickToCopy?: boolean;      // Default: false
+  enableColumnActions?: boolean;    // Default: false
+  isDateColumn?: boolean;           // Special date handling
+  sortingFn?: function;             // Custom sorting function
+  Cell?: Component;                 // Custom cell renderer (receives typeValue prop)
+  cellClass?: string;               // CSS class wrapping cell content
+  locale?: string;                  // Locale for date/number formatting
+  onlyFlag?: boolean;               // For countryFlag type
+  columnDef?: object;               // Additional metadata
+}
+```
+
+**Cell Rendering Priority:**
+1. If `type` is defined: `DEFAULT_CELL_TYPES[type]` formatter is applied first (becomes `content`)
+2. If `Cell` is also defined: Custom component receives `typeValue` (the formatted result) and can override `content`
+3. If only `Cell` is defined (no `type`): Custom component has full control
+4. If `cellClass` is defined: Final content is wrapped in `<div className={cellClass}>`
+
+**Rendering Flow:**
+```
+Raw Value → [type formatter] → content → [Custom Cell] → content → [cellClass wrapper] → Final Output
+```
+
+### Action Object
+
+```typescript
+{
+  name: string;                     // Button label
+  function: (selectedRows) => void; // Required: Click handler
+  tooltip?: string;                 // Hover tooltip
+  color?: string;                   // Button color
+  icon?: string | element;          // Button icon
+  selectionMode?: 'single' | 'multi' | 'always';
+  confirmMessage?: string | element;
+  hasConfirmMessage?: boolean;
+  disabled?: boolean;
+  visible?: boolean;
+  toggle?: boolean;
+  active?: boolean;
+  key?: string;                     // Unique key for React
+}
+```
+
+---
+
+## Performance Tips
+
+1. **Use Virtualization for Large Datasets**
+   ```jsx
+   enableVirtualization={true}  // For 1000+ rows
+   ```
+
+2. **Optimize Row Height**
+   ```jsx
+   rowHeight={40}  // Smaller = more rows visible
+   ```
+
+3. **Disable Unused Features**
+   ```jsx
+   enableDensityToggle={false}
+   enableFullScreenToggle={false}
+   enableGlobalFilter={false}
+   ```
+
+4. **Use Compact Mode**
+   ```jsx
+   enableCompactStyleMode={true}
+   fontSize={12}
+   ```
+
+5. **Limit Initial Page Size**
+   ```jsx
+   pageSize={50}  // Don't render too many rows initially
+   ```
+
+6. **Pre-select Rows Carefully**
+   ```jsx
+   // Only include necessary IDs
+   selectedIds={criticalIds}  // vs selecting all rows
+   ```
+
+7. **Optimize Custom Cell Renderers**
+   ```jsx
+   // Use typeValue when available to avoid re-computing
+   const MyCell = ({ typeValue, cell }) => {
+     return typeValue || cell.getValue(); // Prefer typeValue
+   };
+   ```
+
+---
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+---
+
+## Important Notes
+
+### Row Selection Behavior
+- **Click-to-select:** When `disableSelect={false}`, clicking anywhere on a row will toggle its selection
+- **Single selection mode:** Clicking a row deselects all other rows and selects only the clicked row
+- **Checkbox behavior:** For multi-row selection, use the checkboxes in combination with `enableMultiRowSelection={true}`
+- The selection state is controlled by `rowSelection` and updates through the `selectData` callback
+
+### Fixed Header and Actions
+- `enableFixedHeader` pins the column headers when scrolling
+- `enableFixedActions` (requires `enableFixedHeader={true}`) also pins the action toolbar
+- Both features use CSS positioning and may require adjustments based on your page layout
+
+### Date Columns
+- Columns with `isDateColumn={true}` get automatic date-aware sorting
+- Use the `type` prop (`'date'` or `'datetime'`) to format date display
+- The `locale` prop on columns controls date formatting (default: 'pt-PT')
+
+### LocalizationProvider
+The DataGrid component is wrapped with MUI's `LocalizationProvider` using `AdapterDateFns`. This is required for any date-related functionality and doesn't need to be added by the consumer.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Rows not selecting when clicked**
+- Check that `disableSelect={false}` (default)
+- Verify `selectData` callback is provided
+- Ensure `rowKey` matches your data's unique identifier
+
+**Issue: Date columns not sorting correctly**
+- Set `isDateColumn={true}` on date columns
+- Ensure date values are in a valid format (ISO 8601 recommended)
+
+**Issue: Fixed headers not working**
+- Set `enableFixedHeader={true}`
+- Check that `gridHeight` is set to a specific value (not 'fit-content')
+- For fixed actions, also set `enableFixedActions={true}`
+
+**Issue: Selection state not syncing with parent component**
+- Use the `selectedIds` prop to control selection from parent
+- The component will auto-sync when `selectedIds` changes
+
+**Issue: Export buttons not appearing**
+- Set `hasExcelExport={true}` and/or `hasPdfExport={true}`
+- Check that action buttons have enough space in the toolbar
+
+**Issue: Type formatter not working**
+- Verify column has `type` property defined
+- Check that `type` value matches a key in `DEFAULT_CELL_TYPES` (e.g., 'text', 'date', 'currency')
+- The formatter is applied automatically - no `Cell` component needed
+- If using a custom `Cell`, the formatted value is in `typeValue` prop
+
+**Issue: Custom Cell component not receiving typeValue**
+- Verify the column has a `type` property defined
+- Check that `type` matches a key in `DEFAULT_CELL_TYPES`
+- Remember: `typeValue` is only passed when both `type` and `Cell` are defined
+
+---
+
+## Dependencies
+
+This component is built on top of:
+- [Material React Table](https://www.material-react-table.com/) - Core table functionality
+- [MUI (Material-UI)](https://mui.com/) - UI components and styling
+- [Semantic UI React](https://react.semantic-ui.com/) - Additional UI components
+- [Bootstrap](https://getbootstrap.com/) - Base CSS framework
+- [date-fns](https://date-fns.org/) - Date manipulation and formatting
+
+---
+
+## License
+
+ISC
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insticc/react-datagrid-2",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "",
   "main": "build/index.js",
   "scripts": {