@manikantsharma/react-table/README.md

A powerful, accessible React table component built with MUI Joy

# React Table

A powerful, accessible React table component built with MUI Joy. Features sorting, pagination, row selection, column visibility, and loading states.

## Features

- 🔥 **Full-featured**: Sorting, pagination, row selection, column filtering
- ♿ **Accessible**: ARIA labels, keyboard navigation, screen reader support
- 🎨 **Customizable**: Extensive theming and styling options
- ⚡ **Performance**: Optimized with React.memo and useMemo
- 📱 **Responsive**: Mobile-friendly design
- 🦴 **Loading States**: Skeleton loading for better UX
- 🔧 **TypeScript**: Full type safety out of the box
- 🎯 **MUI Joy**: Built on top of Material-UI's Joy design system

## Installation

```bash
npm install @manikantsharma/react-table
# or
yarn add @manikantsharma/react-table
# or
pnpm add @manikantsharma/react-table
```

### Peer Dependencies

Make sure you have these peer dependencies installed:

```bash
npm install react react-dom @mui/joy @mui/icons-material @mui/utils
```

## Quick Start

```tsx
import React from "react";
import { CustomTable, CustomTableColumn } from "@manikantsharma/react-table";

interface Person {
  id: number;
  name: string;
  age: number;
  email: string;
}

const columns: CustomTableColumn<Person>[] = [
  {
    key: "name",
    dataIndex: "name",
    title: "Name",
    sortable: true,
  },
  {
    key: "age",
    dataIndex: "age",
    title: "Age",
    sortable: true,
    align: "center",
  },
  {
    key: "email",
    dataIndex: "email",
    title: "Email",
  },
];

const data: Person[] = [
  { id: 1, name: "John Doe", age: 30, email: "john@example.com" },
  { id: 2, name: "Jane Smith", age: 25, email: "jane@example.com" },
];

function App() {
  return (
    <CustomTable
      columns={columns}
      dataSource={data}
      rowKey="id"
      toolbar={{
        title: "Users",
        showColumnFilter: true,
      }}
      pagination={{
        pageSize: 10,
        showSizeChanger: true,
      }}
    />
  );
}
```

## API Reference

### CustomTable Props

| Property       | Type                                                | Default | Description                 |
| -------------- | --------------------------------------------------- | ------- | --------------------------- |
| `columns`      | `CustomTableColumn<T>[]`                            | -       | Column configuration        |
| `dataSource`   | `T[]`                                               | -       | Data to display             |
| `rowKey`       | `string \| (record: T) => string`                   | `'id'`  | Unique key for each row     |
| `loading`      | `boolean`                                           | `false` | Loading state               |
| `pagination`   | `TablePagination \| false`                          | -       | Pagination configuration    |
| `rowSelection` | `TableRowSelection<T>`                              | -       | Row selection configuration |
| `toolbar`      | `TableToolbar`                                      | -       | Toolbar configuration       |
| `size`         | `'sm' \| 'md' \| 'lg'`                              | `'md'`  | Table size                  |
| `bordered`     | `boolean`                                           | `true`  | Show border                 |
| `onSortChange` | `(field: string, order: SortOrder \| null) => void` | -       | Sort change callback        |

### Column Configuration

```tsx
interface CustomTableColumn<T> {
  key: string;
  dataIndex: keyof T;
  title: string;
  width?: string | number;
  align?: "left" | "center" | "right";
  sortable?: boolean;
  render?: (value: any, record: T, index: number) => React.ReactNode;
  ellipsis?: boolean;
  hidden?: boolean;
}
```

### Row Selection

```tsx
const rowSelection = {
  type: "checkbox", // or 'radio'
  selectedRowKeys: selectedKeys,
  onChange: (keys, rows) => {
    setSelectedKeys(keys);
  },
  getCheckboxProps: (record) => ({
    disabled: record.disabled,
  }),
};
```

### Custom Rendering

```tsx
const columns = [
  {
    key: "status",
    dataIndex: "status",
    title: "Status",
    render: (value, record) => (
      <Chip color={value === "active" ? "success" : "neutral"}>{value}</Chip>
    ),
  },
];
```

## Advanced Usage

### Using Individual Components

```tsx
import {
  EnhancedTableHead,
  EnhancedTableToolbar,
  useTableSelection,
  useTableSorting,
} from "@manikantsharma/react-table";

// Build your own custom table using the building blocks
```

### Custom Hooks

```tsx
import {
  useTableSelection,
  useTableSorting,
  useColumnVisibility,
} from "@manikantsharma/react-table";

function MyCustomTable() {
  const { selected, handleClick, handleSelectAllClick } = useTableSelection(
    data,
    rowSelection
  );

  const { order, orderBy, handleRequestSort } = useTableSorting(onSortChange);

  const { visibleColumns, handleVisibilityChange } =
    useColumnVisibility(columns);

  // Your custom table implementation
}
```

## Examples

### With Loading State

```tsx
<CustomTable
  columns={columns}
  dataSource={data}
  loading={isLoading}
  rowKey="id"
/>
```

### With Custom Actions

```tsx
<CustomTable
  columns={columns}
  dataSource={data}
  toolbar={{
    title: "Users",
    actions: <Button startDecorator={<AddIcon />}>Add User</Button>,
    onDelete: (selectedKeys) => {
      // Handle bulk delete
    },
  }}
  rowSelection={{
    type: "checkbox",
    onChange: (keys, rows) => setSelected(rows),
  }}
/>
```

### With Custom Cell Rendering

```tsx
const columns = [
  {
    key: "avatar",
    dataIndex: "avatar",
    title: "Avatar",
    render: (avatar, record) => <Avatar src={avatar} alt={record.name} />,
  },
  {
    key: "actions",
    dataIndex: "id",
    title: "Actions",
    render: (id) => (
      <Box sx={{ display: "flex", gap: 1 }}>
        <IconButton size="sm" onClick={() => edit(id)}>
          <EditIcon />
        </IconButton>
        <IconButton size="sm" color="danger" onClick={() => delete id}>
          <DeleteIcon />
        </IconButton>
      </Box>
    ),
  },
];
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT © Mani Kant Sharma

## Changelog

### v1.0.0

- Initial release
- Full table functionality with sorting, pagination, selection
- TypeScript support
- MUI Joy integration
- Accessibility features