# BlkBoxTable

BlkBoxTable is a flexible and feature-rich React table component built to handle large datasets with high performance. This component offers features like row selection, column and row dragging, pagination, sticky columns, and advanced filtering with search functionality. It's designed for a seamless and customizable table experience.

This library is maintained and supported by [BlkBox](https://blkbox.ai/), ensuring regular updates and improvements.

## Features

- **Sticky Columns**: Keep important columns visible during horizontal scrolling.
- **Expandable Rows**: Show additional details for rows with nested content.
- **Virtualized Rows**: Efficient rendering for large datasets by only displaying visible rows.
- **Column and Row Dragging**: Reorder columns and rows interactively.
- **Row Selection**: Select rows individually or in bulk.
- **Pagination**: Simplify navigation with paginated views.
- **Search Functionality**: Filter rows based on a search query.
- **Customizable Settings**: Adjust row counts, appearance, and behaviors.
- **Loading State**: Built-in loading placeholders for smooth data fetching.

## Installation

Install the package using npm or yarn:

```bash
npm install blkbox-data-grid
```

or

```bash
yarn add blkbox-data-grid
```

## Basic Usage

Here is an example to get started:

```jsx
import React, { useRef } from 'react';
import BlkBoxTable from 'blkbox-data-grid';

const columns = [
  { field: 'id', headerName: 'ID', width: 100 },
  { field: 'name', headerName: 'Name', sorting: true },
  { field: 'age', headerName: 'Age', sorting: true },
];

const rows = [
  { id: 1, name: 'John Doe', age: 30 },
  { id: 2, name: 'Jane Doe', age: 25 },
];

const App = () => {
  const tableRef = useRef(null);

  const handleRowExpanded = (data) => {
    console.log('Row expanded:', data);
  };

  return (
    <BlkBoxTable
      tableRef={tableRef}
      columns={columns}
      rows={rows}
      isColumnDraggable={true}
      isRowExpandable={true}
      isPaginatorVisible={true}
      filterText="John"
      isLoading={false}
      defaultRowsPerPage={5}
      rowsPerPageOptions={[5, 10, 15]}
      onRowExpanded={handleRowExpanded}
    />
  );
};

export default App;
```

## Props

| Prop Name                  | Type                            | Default Value    | Description                                                                 |
|----------------------------|---------------------------------|------------------|-----------------------------------------------------------------------------|
| `columns`                  | `Column[]`                     | -                | Defines the table's column structure, including field, header, width, etc. |
| `rows`                     | `Row[]`                        | []               | Array of row objects. Supports nested children for expandable rows.        |
| `isColumnDraggable`        | `boolean`                      | `false`          | Enables dragging and reordering of columns.                                |
| `isRowDraggable`           | `boolean`                      | `false`          | Enables dragging and reordering of rows.                                   |
| `isRowExpandable`          | `boolean`                      | `false`          | Allows rows to be expandable to show nested content.                       |
| `isLoading`                | `boolean`                      | `false`          | Displays loading skeletons while data is being fetched.                    |
| `isPaginatorVisible`       | `boolean`                      | `true`           | Toggles pagination controls for the table.                                 |
| `defaultRowsPerPage`       | `number`                       | `5`              | Number of rows to display per page.                                        |
| `rowsPerPageOptions`       | `number[]`                     | `[5, 10, 15]`    | Options for rows per page in the pagination dropdown.                      |
| `onRowExpanded`            | `(data: Row) => void`          | -                | Callback triggered when a row is expanded.                                 |
| `emptyStateComponent`      | `ReactNode`                    | "No Data"        | Custom empty state component when there are no rows.                       |
| `virtualizationSettings`   | `Partial<VirtualizationSettingsProps>` | -          | Settings for virtualizing the table content.                               |
| `rowKey`                   | `string | number`              | `'id'`           | Key used to uniquely identify rows in the table.                           |
| `tableContainerClassName`  | `string`                       | -                | Custom CSS class for the main grid container.                              |
| `filterText`               | `string`                       | `""`             | Text to filter rows based on column values.                                |
| `tableRef`                 | `MutableRefObject`             | -                | Ref object to expose table methods to the parent.                          |

### Column Type

The `columns` prop is an array of objects with the following structure:

```typescript
type Column = {
  field: string; // Unique identifier for the column
  headerName: string; // Display name for the column header
  width?: number; // Optional width of the column
  sorting?: boolean; // Whether sorting is enabled for this column
  sticky?: 'left' | 'right'; // Optional sticky positioning
  alignItem?: 'left' | 'center' | 'right'; // Alignment of content
  body?: (row: any, field: string, level: number) => React.ReactNode; // Custom renderer for the cell
  showExpansionIcon?: boolean; // Show expansion icon for expandable rows
};
```

### Row Type

The `rows` prop is an array of objects with the following structure:

```typescript
type Row = {
  id?: string | number; // Unique identifier for the row
  [key: string]: any; // Additional fields corresponding to column keys
  children?: Row[]; // Nested rows for expandable rows
};
```

### VirtualizationSettingsProps Type

The `virtualizationSettings` prop allows you to customize table virtualization. Here's the structure:

```typescript
type VirtualizationSettingsProps = {
  rowHeight: number; // Height of each row in pixels
  bufferRowCount: number; // Number of rows rendered beyond the visible area
  initialRowIndex: number; // Initial index of the visible row
  initialScrollPosition?: number; // Initial scroll position of the table
};
```

## Advanced Features

### Row Selection

Enable row selection for better interactivity:

```jsx
<BlkBoxTable
  columns={columns}
  rows={rows}
  isRowSelectable={true}
  rowKey="id"
/>
```

### Column Dragging

Reorder columns easily:

```jsx
<BlkBoxTable
  columns={columns}
  rows={rows}
  isColumnDraggable={true}
/>
```

### Row Expansion

Expand rows to display additional details:

```jsx
<BlkBoxTable
  columns={columns}
  rows={rows}
  isRowExpandable={true}
  onRowExpanded={(row) => console.log('Expanded row:', row)}
/>
```

### Search Functionality

Filter rows based on a search query:

```jsx
<BlkBoxTable
  columns={columns}
  rows={rows}
  filterText="Jane"
/>
```

## Customization

### Styling

Override default styles using the `tableContainerClassName` prop or by modifying the accompanying CSS files.

### Custom Empty State

Provide a custom empty state component:

```jsx
<BlkBoxTable
  columns={columns}
  rows={[]}
  emptyStateComponent={<div>No Records Found</div>}
/>
```

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch: `git checkout -b my-feature`
3. Commit your changes: `git commit -m 'Add new feature'`
4. Push to the branch: `git push origin my-feature`
5. Open a pull request.

## License

This project is licensed under the MIT License. See the `LICENSE` file for details.