npm package: @ms-kit/data-table-react
Description: React DataTable component with sorting, filtering, pagination, and more
Latest version: 0.1.7

# @ms-kit/data-table-react

Componente React DataTable con sorting, filtering, pagination y mas. Construido sobre TanStack Table + Radix UI + Tailwind CSS.

## Instalacion

```bash
npm install @ms-kit/data-table-react @tanstack/react-table lucide-react
```

> `@tanstack/react-table` y `lucide-react` son peer dependencies. npm 7+ las instala automaticamente, pero pnpm y algunas versiones de yarn requieren instalarlas de forma explicita.

### Dependencias opcionales

```bash
# Drag & drop de columnas
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

# Exportar a Excel
npm install xlsx
```

### CSS

Importa Tailwind y el tema en tu archivo CSS:

```css
@import "tailwindcss";
@import "@ms-kit/data-table-react/theme.css";
```

> Requiere Tailwind CSS v4 con el plugin `@tailwindcss/vite` (o equivalente). El tema incluye `@source` automaticamente para que Tailwind detecte las clases de los componentes.

## Uso basico

```tsx
import { DataTable } from "@ms-kit/data-table-react";
import { createColumnHelper } from "@tanstack/react-table";

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

const columnHelper = createColumnHelper<User>();

const columns = [
  columnHelper.accessor("name", { header: "Name" }),
  columnHelper.accessor("email", { header: "Email" }),
  columnHelper.accessor("role", { header: "Role" }),
];

<DataTable
  data={users}
  columns={columns}
  enableSorting
  enablePagination
/>;
```

## Features

| Feature | Prop | Descripcion |
|---------|------|-------------|
| Sorting | `enableSorting` | Ordenamiento por columnas |
| Filtering | `enableFiltering` | Filtros por columna (texto y seleccion multiple) |
| Pagination | `enablePagination` | Paginacion client-side o server-side (`manualPagination`) |
| Column visibility | `enableColumnVisibility` | Toggle de columnas visibles |
| Column resizing | `enableColumnResizing` | Redimensionar columnas con drag |
| Column pinning | `enableColumnPinning` | Fijar columnas a izquierda/derecha |
| Column DnD | `enableColumnDnD` | Reordenar columnas arrastrando (requiere @dnd-kit) |
| Row selection | `enableRowSelection` | Checkboxes para seleccionar filas |
| Global search | `enableGlobalSearch` | Busqueda global en todas las columnas |
| Export | `enableExport` | Exportar a CSV/Excel |
| i18n | `translations` | Traducciones personalizables |
| Loading | `isLoading` | Skeleton de carga animado |

### Ejemplo completo

```tsx
<DataTable
  data={users}
  columns={columns}
  enableSorting
  enableFiltering
  enablePagination
  enableColumnVisibility
  enableColumnResizing
  enableColumnPinning
  enableColumnDnD
  enableRowSelection
  enableGlobalSearch
  enableExport
  exportFilename="users-export"
  pageSize={10}
  getFilterType={(columnId) => filterTypeMap[columnId] ?? "text"}
  getHeaderAlign={(columnId) => columnId === "id" ? "center" : "left"}
  nonFilterableColumnIds={["id", "createdAt"]}
  nonHideableColumnIds={["name"]}
  onSelectionChange={(rows) => console.log("Selected:", rows)}
  onRowClick={(row) => console.log("Clicked:", row.original)}
/>
```

### Server-side pagination

```tsx
<DataTable
  data={pageData}
  columns={columns}
  enablePagination
  manualPagination
  pageCount={totalPages}
  rowCount={totalRows}
  currentPage={page}
  onPageChange={(p) => setPage(p)}
  onPageSizeChange={(size) => setPageSize(size)}
/>
```

### Traducciones

```tsx
<DataTable
  data={users}
  columns={columns}
  translations={{
    noResults: "No se encontraron resultados",
    pagination: {
      showing: "Mostrando {from} a {to} de {total}",
      rowsPerPage: "Filas por pagina",
      previous: "Anterior",
      next: "Siguiente",
    },
  }}
/>
```

## API Reference

### DataTableProps\<TData\>

| Prop | Tipo | Default | Descripcion |
|------|------|---------|-------------|
| `data` | `TData[]` | — | Datos de la tabla |
| `columns` | `ColumnDef<TData>[]` | — | Definiciones de columnas (TanStack Table) |
| `isLoading` | `boolean` | `false` | Muestra skeleton de carga |
| `loadingRowsCount` | `number` | `5` | Cantidad de filas skeleton |
| `enableSorting` | `boolean` | `false` | Habilita sorting |
| `initialSorting` | `SortingState` | `[]` | Estado de sorting inicial |
| `enableFiltering` | `boolean` | `false` | Habilita filtros por columna |
| `nonFilterableColumnIds` | `string[]` | `[]` | Columnas excluidas del filtro |
| `enableColumnVisibility` | `boolean` | `false` | Habilita toggle de visibilidad |
| `nonHideableColumnIds` | `string[]` | `[]` | Columnas que no se pueden ocultar |
| `enableColumnResizing` | `boolean` | `false` | Habilita redimensionamiento |
| `enablePagination` | `boolean` | `false` | Habilita paginacion |
| `manualPagination` | `boolean` | `false` | Paginacion server-side |
| `pageSize` | `number` | `10` | Tamanio de pagina inicial |
| `pageCount` | `number` | — | Total de paginas (manual) |
| `rowCount` | `number` | — | Total de filas (manual) |
| `currentPage` | `number` | — | Pagina actual (manual, 1-indexed) |
| `onPageChange` | `(page: number) => void` | — | Callback cambio de pagina |
| `onPageSizeChange` | `(size: number) => void` | — | Callback cambio de tamanio |
| `enableColumnPinning` | `boolean` | `false` | Habilita pinning de columnas |
| `pinnedColumns` | `{ left?: string[]; right?: string[] }` | — | Columnas fijadas iniciales |
| `enableColumnDnD` | `boolean` | `false` | Habilita drag & drop de columnas |
| `nonDraggableColumnIds` | `string[]` | `[]` | Columnas que no se pueden mover |
| `enableRowSelection` | `boolean` | `false` | Habilita seleccion de filas |
| `onSelectionChange` | `(rows: TData[]) => void` | — | Callback cambio de seleccion |
| `enableGlobalSearch` | `boolean` | `false` | Habilita busqueda global |
| `enableExport` | `boolean` | `false` | Habilita exportacion CSV/Excel |
| `exportFilename` | `string` | `"export"` | Nombre del archivo exportado |
| `getFilterType` | `(columnId: string) => FilterType` | — | Tipo de filtro por columna (`"text"` \| `"select"`) |
| `getFormatOption` | `(columnId: string) => ((value: string) => string) \| undefined` | — | Formateador de opciones del filtro select |
| `getHeaderAlign` | `(columnId: string) => HeaderAlign` | — | Alineacion del header (`"left"` \| `"center"` \| `"right"`) |
| `getHeaderClassName` | `(columnId: string) => string` | — | Clases CSS custom para headers |
| `getCellClassName` | `(columnId: string) => string` | — | Clases CSS custom para celdas |
| `tableClassName` | `string` | — | Clase CSS para el `<table>` |
| `rowClassName` | `string \| (row: Row<TData>) => string` | — | Clases CSS para filas |
| `onRowClick` | `(row: Row<TData>) => void` | — | Callback click en fila |
| `translations` | `Partial<DataTableTranslations>` | — | Override parcial de traducciones |

## Licencia

MIT