npm package: @shadowfax-tech/table
Description: Data table component (TanStack Table) for SFX UI
Latest version: 0.3.0

# @shadowfax-tech/table

A powerful, feature-rich data table component built with TanStack Table v8 and styled with the SFX UI theme system.

## Features

- 📊 Column sorting with visual indicators
- ✅ Row selection with checkboxes
- 🎨 Custom cell and header rendering
- 📱 Fully responsive design
- 🎭 Smooth animations
- 🎯 Sticky headers
- 📏 Compact and striped variants
- All colors/spacing from theme (no hard-coded values)

## Installation

```bash
npm install @shadowfax-tech/table
# or
yarn add @shadowfax-tech/table
```

**Note:** `@tanstack/react-table` is bundled as a dependency.

## Quick Start

```tsx
import { Table } from '@shadowfax-tech/table';
import '@shadowfax-tech/table/styles';

interface User {
  id: string;
  name: string;
  email: string;
  role: string;
}

const columns = [
  { id: 'name', name: 'Name', sortable: true },
  { id: 'email', name: 'Email', sortable: true },
  { id: 'role', name: 'Role' },
];

function MyTable() {
  return (
    <Table
      columns={columns}
      data={users}
      idSelector={(row) => row.id}
    />
  );
}
```

## Custom Cell Rendering

```tsx
const columns = [
  {
    id: 'status',
    name: 'Status',
    renderCell: ({ value }) => (
      <span className={`status-${value.toLowerCase()}`}>
        {value}
      </span>
    ),
  },
];
```

## Custom Header Rendering

```tsx
const columns = [
  {
    id: 'name',
    name: 'Name',
    sortable: true,
    renderHeader: ({ column, sortDirection, toggleSort }) => (
      <div onClick={toggleSort}>
        {column.name}
        {sortDirection && <span>{sortDirection === 'asc' ? '↑' : '↓'}</span>}
      </div>
    ),
  },
];
```

## Row Selection

```tsx
<Table
  columns={columns}
  data={users}
  idSelector={(row) => row.id}
  selectableRows
  onSelectionChange={({ selectedRows }) => {
    console.log('Selected:', selectedRows);
  }}
/>
```

## Column Widths

```tsx
const columns = [
  { 
    id: 'name', 
    name: 'Name', 
    width: '200px',
    minWidth: '150px',
    maxWidth: '300px'
  },
  { id: 'email', name: 'Email', width: '40%' },
];
```

## Props

### TableProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `TableColumn[]` | **required** | Column definitions |
| `data` | `TData[]` | **required** | Table data |
| `idSelector` | `(row, index) => string` | **required** | Extract unique ID |
| `selectableRows` | `boolean` | `false` | Enable row selection |
| `onSelectionChange` | `(params) => void` | - | Selection callback |
| `renderEmptyTable` | `() => ReactNode` | - | Custom empty state |
| `loading` | `boolean` | `false` | Loading state |
| `className` | `string` | - | Additional CSS class |
| `maxHeight` | `string` | - | Max height with scroll |
| `stickyHeader` | `boolean` | `true` | Sticky header on scroll |
| `striped` | `boolean` | `false` | Alternating row colors |
| `compact` | `boolean` | `false` | Reduced padding |
| `onRowClick` | `(row, index) => void` | - | Row click handler |

### TableColumn

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | **required** | Unique column ID |
| `name` | `string` | **required** | Column header name |
| `accessor` | `string \| keyof TData` | `id` | Data accessor key |
| `sortable` | `boolean` | `false` | Enable sorting |
| `renderCell` | `(params) => ReactNode` | - | Custom cell renderer |
| `renderHeader` | `(params) => ReactNode` | - | Custom header renderer |
| `width` | `string` | - | Column width |
| `minWidth` | `string` | - | Minimum width |
| `maxWidth` | `string` | - | Maximum width |
| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment |

## Advanced Examples

See the [full documentation](https://github.com/shadowfax-tech/sfx-cargo-ui/tree/main/src/lib/components/table) for:
- HeaderRenderParams and CellRenderParams
- Search and filter in headers
- Loading and empty states
- Responsive tables
- Best practices

## License

MIT

## Links

- [GitHub](https://github.com/shadowfax-tech/sfx-cargo-ui)
- [Full Documentation](https://github.com/shadowfax-tech/sfx-cargo-ui/tree/main/src/lib/components/table)
- [npm](https://www.npmjs.com/package/@shadowfax-tech/table)