npm package: @globalicons/enterprise-tools
Description: A highly customizable and performant data table component for React and Next.js applications. It provides an intuitive and powerful UI for handling complex tabular data with ease.
Author: gia
Latest version: 3.3.0

# Enterprise Tools

A comprehensive collection of modern, feature-rich React components built with TypeScript and Tailwind CSS. This library provides flexible and customizable solutions for enterprise applications, starting with our flagship DataTable component and expanding to include charts and other enterprise-grade UI tools.

## Components

### DataTable

Our flagship component for displaying and managing tabular data with advanced features:

- 📊 **Pagination**: Server-side and client-side pagination support
- 🔄 **Loading States**: Skeleton loading with dynamic column support
- 📦 **Export Options**: CSV and PDF export with customizable formatting
- 🎯 **Column Management**: Show/hide columns with persistent visibility
- 📊 **Data Formatting**: Built-in support for various data types and formats
- 🔄 **State Management**: Efficient state handling with React hooks
- 🎯 **Accessibility**: ARIA attributes and keyboard navigation support
- 📏 **Column Resizing**: Drag to resize columns
- ✅ **Row Selection**: Single and multi-row selection support

### Coming Soon

- 📈 **Charts**: Interactive data visualization components
- 📊 **Dashboards**: Customizable dashboard layouts
- 🔔 **Notifications**: Toast and alert components
- 🗓️ **Date Pickers**: Advanced date selection tools
- 🔍 **Advanced Filters**: Complex data filtering components

## Installation

```bash
npm install @globalicons/enterprise-tools
# or
yarn add @globalicons/enterprise-tools
```

## Usage

### TypeScript Usage

```tsx
import { DataTable } from '@globalicons/enterprise-tools'

interface User {
	id: number
	name: string
	email: string
	role: string
	age: number
	joinDate: string
}

const columns = [
	{
		id: 'id',
		accessorKey: 'id',
		header: 'ID',
		size: 80,
		enableResizing: true,
		filterType: 'number-range',
	},
	{
		id: 'name',
		accessorKey: 'name',
		header: 'Name',
		size: 200,
		enableResizing: true,
		filterType: 'select',
	},
	{
		id: 'email',
		accessorKey: 'email',
		header: 'Email',
		size: 250,
		enableResizing: true,
	},
	{
		id: 'role',
		accessorKey: 'role',
		header: 'Role',
		size: 150,
		enableResizing: true,
		filterType: 'select',
	},
	{
		id: 'age',
		accessorKey: 'age',
		header: 'Age',
		size: 100,
		enableResizing: true,
		filterType: 'number-range',
	},
	{
		id: 'joinDate',
		accessorKey: 'joinDate',
		header: 'Join Date',
		size: 150,
		enableResizing: true,
		filterType: 'date-range',
		cell: (info) => new Date(info.getValue()).toLocaleDateString(),
	},
]

const data = [
	{ id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin', age: 30, joinDate: '2023-01-15' },
	{ id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User', age: 25, joinDate: '2023-02-20' },
]

function App() {
	return (
		<DataTable<User>
			data={data}
			columns={columns}
			enablePagination
			enableFilters
			enableColumnVisibility
			enableColumnResizing
			enableRowSelection
			enableMultiRowSelection
			theme='default'
			pageSize={10}
			onRowSelectionChange={(selection) => console.log('Selected rows:', selection)}
			onRowClick={(row) => console.log('Clicked row:', row)}
		/>
	)
}
```

### JavaScript Usage

```jsx
import { DataTable } from '@globalicons/enterprise-tools'

const columns = [
	{
		id: 'id',
		accessorKey: 'id',
		header: 'ID',
		size: 80,
		enableResizing: true,
		filterType: 'number-range',
	},
	{
		id: 'name',
		accessorKey: 'name',
		header: 'Name',
		size: 200,
		enableResizing: true,
		filterType: 'select',
	},
	{
		id: 'email',
		accessorKey: 'email',
		header: 'Email',
		size: 250,
		enableResizing: true,
	},
	{
		id: 'role',
		accessorKey: 'role',
		header: 'Role',
		size: 150,
		enableResizing: true,
		filterType: 'select',
	},
]

const data = [
	{ id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin' },
	{ id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User' },
]

function App() {
	return (
		<DataTable
			data={data}
			columns={columns}
			enablePagination
			enableFilters
			enableColumnVisibility
			enableColumnResizing
			enableRowSelection
			enableMultiRowSelection
			theme='nss'
			pageSize={10}
			onRowSelectionChange={(selection) => console.log('Selected rows:', selection)}
			onRowClick={(row) => console.log('Clicked row:', row)}
		/>
	)
}
```

## Props

### Core Props

| Prop        | Type                   | Required | Default   | Description                           |
| ----------- | ---------------------- | -------- | --------- | ------------------------------------- |
| `data`      | `T[]`                  | Yes      | -         | Array of data to display in the table |
| `columns`   | `CustomColumnDef<T>[]` | Yes      | -         | Array of column definitions           |
| `theme`     | `'default' \| 'nss'`   | No       | 'default' | Theme to apply to the table           |
| `isLoading` | `boolean`              | No       | false     | Show loading state with skeleton      |

### Pagination Props

| Prop                 | Type                                                            | Required | Default | Description                                      |
| -------------------- | --------------------------------------------------------------- | -------- | ------- | ------------------------------------------------ |
| `enablePagination`   | `boolean`                                                       | No       | false   | Enable pagination functionality                  |
| `pageSize`           | `number`                                                        | No       | 10      | Number of rows per page                          |
| `manualPagination`   | `boolean`                                                       | No       | false   | Enable server-side pagination                    |
| `pageCount`          | `number`                                                        | No       | -       | Total number of pages for server-side pagination |
| `rowCount`           | `number`                                                        | No       | -       | Total number of rows for server-side pagination  |
| `onPaginationChange` | `(pagination: { pageIndex: number; pageSize: number }) => void` | No       | -       | Callback for pagination changes                  |

### Column Management Props

| Prop                     | Type      | Required | Default | Description                          |
| ------------------------ | --------- | -------- | ------- | ------------------------------------ |
| `enableColumnVisibility` | `boolean` | No       | false   | Enable column visibility toggle      |
| `enableColumnResizing`   | `boolean` | No       | false   | Enable column resizing functionality |

### Filtering Props

| Prop             | Type             | Required | Default | Description                           |
| ---------------- | ---------------- | -------- | ------- | ------------------------------------- |
| `enableFilters`  | `boolean`        | No       | false   | Enable column filtering functionality |
| `defaultFilters` | `DefaultFilter[]` | No       | []      | Array of default filters to apply     |

### Row Selection Props

| Prop                      | Type                                           | Required | Default | Description                        |
| ------------------------- | ---------------------------------------------- | -------- | ------- | ---------------------------------- |
| `enableRowSelection`      | `boolean \| ((row: Row<T>) => boolean)`        | No       | false   | Enable row selection               |
| `enableMultiRowSelection` | `boolean \| ((row: Row<T>) => boolean)`        | No       | true    | Enable multi-row selection         |
| `onRowSelectionChange`    | `(selection: Record<string, boolean>) => void` | No       | -       | Callback for row selection changes |
| `onRowClick`              | `(row: T) => void`                             | No       | -       | Callback for row click events      |

### Sorting Props

| Prop              | Type                              | Required | Default | Description                  |
| ----------------- | --------------------------------- | -------- | ------- | ---------------------------- |
| `enableSorting`   | `boolean`                         | No       | true    | Enable column sorting        |
| `manualSorting`   | `boolean`                         | No       | false   | Enable server-side sorting   |
| `defaultSorting`  | `SortingState`                    | No       | []      | Default sorting state        |
| `onSortingChange` | `(sorting: SortingState) => void` | No       | -       | Callback for sorting changes |

### Export Props

| Prop             | Type                              | Required | Default | Description                |
| ---------------- | --------------------------------- | -------- | ------- | -------------------------- |
| `isDownloadable` | `{ formats: ('csv' \| 'pdf')[] }` | No       | -       | Enable data export options |

## Column Definition

```tsx
interface CustomColumnDef<T> {
	// Required properties
	id: string
	accessorKey: keyof T
	header: string

	// Optional properties
	cell?: (info: { getValue: () => any }) => React.ReactNode
	size?: number
	enableResizing?: boolean
	enableSorting?: boolean
	enableHiding?: boolean
	hidden?: boolean
	filterType?: 'select' | 'number-range' | 'date-range'
}
```

### Filter Types

1. **Select Filter**

   - For categorical data
   - Shows a dropdown with unique values
   - Supports multiple selection
   - Example: `filterType: 'select'`

2. **Number Range Filter**

   - For numerical data
   - Supports range and comparison operators
   - Options:
     - Range: min/max values
     - Greater than
     - Greater than or equal
     - Less than
     - Less than or equal
     - Equals
   - Example: `filterType: 'number-range'`

3. **Date Range Filter**
   - For date data
   - Supports range and comparison operators
   - Options:
     - Range: from/to dates
     - Before
     - After
     - Equals
   - Example: `filterType: 'date-range'`

4. **Equality Filter**
   - For exact value matching
   - Performs string equality comparison
   - Useful for status fields, IDs, or any exact match scenarios
   - Example: `filterType: 'eq'`

## Default Filters

The DataTable supports applying default filters when the component first renders. This is useful for pre-filtering data and showing the filters in the UI automatically.

### Usage

```tsx
import { DataTable, DefaultFilter } from '@globalicons/enterprise-tools'

const defaultFilters: DefaultFilter[] = [
  {
    columnId: 'status',
    filterType: 'eq',
    value: 'active'
  },
  {
    columnId: 'department', 
    filterType: 'select',
    value: ['Engineering', 'Marketing']
  },
  {
    columnId: 'salary',
    filterType: 'number-range',
    value: {
      type: 'gte',
      value: 50000
    }
  }
]

<DataTable
  data={data}
  columns={columns}
  enableFilters
  defaultFilters={defaultFilters}
/>
```

### Default Filter Interface

```tsx
interface DefaultFilter {
  columnId: string                                    // ID of the column to filter
  filterType: 'eq' | 'select' | 'number-range' | 'date-range'  // Type of filter
  value: any                                          // Filter value (varies by type)
}
```

### Filter Value Types

- **Equality (`eq`)**: String or number value
  ```tsx
  { columnId: 'status', filterType: 'eq', value: 'active' }
  ```

- **Select**: Array of values
  ```tsx
  { columnId: 'category', filterType: 'select', value: ['tech', 'science'] }
  ```

- **Number Range**: Range object or comparison object
  ```tsx
  // Range
  { columnId: 'price', filterType: 'number-range', value: { min: 100, max: 500 } }
  // Comparison
  { columnId: 'age', filterType: 'number-range', value: { type: 'gte', value: 18 } }
  ```

- **Date Range**: Range object or comparison object
  ```tsx
  // Range
  { columnId: 'createdAt', filterType: 'date-range', value: { from: new Date('2024-01-01'), to: new Date('2024-12-31') } }
  // Comparison
  { columnId: 'updatedAt', filterType: 'date-range', value: { type: 'after', value: new Date('2024-01-01') } }
  ```

### Features

- ✅ **Visual Indicators**: Filter icons show as active for columns with default filters
- ✅ **User Interaction**: Users can modify or clear default filters through the UI
- ✅ **Multiple Types**: Supports all filter types including the new equality filter
- ✅ **Persistent State**: Filters persist until manually changed by the user
- ✅ **Priority System**: Column `filterType` takes priority over `defaultFilter` `filterType`
- ✅ **Fallback Support**: Columns without `filterType` can use `defaultFilter` `filterType`

### Filter Type Priority

The DataTable uses a priority system to determine which filter type to use for each column:

1. **Column `filterType`** (Highest Priority): If a column has a `filterType` defined, it will always use that filter type, regardless of any `defaultFilter` settings.

2. **DefaultFilter `filterType`** (Fallback): If a column doesn't have a `filterType` defined, but has a corresponding `defaultFilter`, it will use the `defaultFilter`'s `filterType`.

3. **No Filter** (Default): Columns without either a `filterType` or matching `defaultFilter` will not be filterable.

**Example:**
```tsx
const columns = [
  { id: 'status', header: 'Status', filterType: 'select' }, // Will use 'select' filter
  { id: 'description', header: 'Description' } // Will use 'eq' filter from defaultFilter
]

const defaultFilters = [
  { columnId: 'status', filterType: 'eq', value: 'active' }, // filterType ignored, uses 'select'
  { columnId: 'description', filterType: 'eq', value: 'test' } // filterType used
]
```

## Pagination Modes

### Client-Side Pagination

```tsx
<DataTable data={data} columns={columns} enablePagination pageSize={10} />
```

### Server-Side Pagination

```tsx
<DataTable
	data={data}
	columns={columns}
	enablePagination
	manualPagination
	pageCount={totalPages}
	rowCount={totalRows}
	onPaginationChange={(pagination) => {
		// Fetch new data based on pagination.pageIndex and pagination.pageSize
	}}
/>
```

## Export Options

### CSV Export

- Includes all visible columns
- Properly formatted data with headers
- Handles special characters and line breaks
- Filename format: `file_YYYY_MM_DD.csv`

### PDF Export

- A0 size in landscape orientation for maximum space
- Full content display without truncation
- Theme-based styling
- Proper margins and spacing
- Filename format: `file_YYYY_MM_DD.pdf`