npm package: @litforge/data-table
Description: A comprehensive data table component with sorting, pagination, search, and selection, built with Lit.
Latest version: 0.1.22

# @litforge/data-table

A comprehensive data table component with sorting, pagination, search, and selection, built with Lit.

## Overview

The `DataTable` component provides a full-featured table with:
- Column sorting
- Pagination
- Search/filtering
- Row selection
- Loading states
- Empty states
- Customizable toolbar

## Installation

```bash
npm install @litforge/data-table
# or
pnpm add @litforge/data-table
# or
yarn add @litforge/data-table
```

## Basic Usage

```html
<script type="module">
  import '@litforge/data-table';
</script>

<data-table
  columns="${columns}"
  rows="${rows}"
  sortable
  pagination
  @table-sort="${handleSort}"
></data-table>
```

## Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `columns` | `TableColumn[]` | `undefined` | Column definitions |
| `rows` | `TableRowData[]` | `undefined` | Table row data |
| `selectable` | `boolean` | `false` | Enables row selection |
| `sortBy` | `string` | `undefined` | Currently sorted column |
| `sortDirection` | `'asc' \| 'desc'` | `undefined` | Sort direction |
| `loading` | `boolean` | `false` | Shows loading state |
| `emptyMessage` | `string` | `undefined` | Message when no data |
| `showToolbar` | `boolean` | `false` | Shows toolbar |
| `showPagination` | `boolean` | `false` | Shows pagination |
| `searchable` | `boolean` | `false` | Enables search |
| `toolbarTitle` | `string` | `undefined` | Toolbar title |
| `toolbarDescription` | `string` | `undefined` | Toolbar description |
| `page` | `number` | `undefined` | Current page number |
| `pageSize` | `number` | `undefined` | Items per page |
| `totalItems` | `number` | `undefined` | Total items count |
| `pageSizeOptions` | `number[]` | `undefined` | Page size options |
| `selected` | `Set<string>` | `undefined` | Selected row IDs |

## Events

### `table-sort`

Fired when a column is sorted.

```typescript
interface TableSortDetail {
  column: string;
  direction: 'asc' | 'desc';
}
```

### `table-row-select`

Fired when a row is selected/deselected.

```typescript
interface TableRowSelectDetail {
  rowId: string;
  selected: boolean;
}
```

### `table-page-change`

Fired when page changes.

```typescript
interface TablePageChangeDetail {
  page: number;
}
```

### `table-page-size-change`

Fired when page size changes.

```typescript
interface TablePageSizeChangeDetail {
  pageSize: number;
}
```

### `table-search`

Fired when search query changes.

```typescript
interface TableSearchDetail {
  query: string;
}
```

## Examples

### Basic Table

```html
<data-table
  columns="${columns}"
  rows="${rows}"
></data-table>
```

### With Sorting and Pagination

```html
<data-table
  columns="${columns}"
  rows="${rows}"
  sortable
  showPagination
  page="${currentPage}"
  pageSize="${pageSize}"
  totalItems="${total}"
  @table-sort="${handleSort}"
  @table-page-change="${handlePageChange}"
></data-table>
```

### With Search and Selection

```html
<data-table
  columns="${columns}"
  rows="${rows}"
  selectable
  searchable
  showToolbar
  toolbarTitle="Users"
  @table-search="${handleSearch}"
  @table-row-select="${handleRowSelect}"
></data-table>
```

## TypeScript

```typescript
import { DataTable } from '@litforge/data-table';
import type {
  TableColumn,
  TableRowData,
  TableSortDetail,
  TableSortDirection
} from '@litforge/data-table';

const columns: TableColumn[] = [
  { id: 'name', label: 'Name', sortable: true },
  { id: 'email', label: 'Email', sortable: true }
];
```

## Styling

The component uses CSS variables for theming:

```css
data-table {
  --lf-data-table-font-family: 'Inter', sans-serif;
  --lf-data-table-border-color: #e2e8f0;
  --lf-data-table-header-background: #f8fafc;
  /* ... more variables */
}
```

## License

Part of the LitForge component library.