@wakastellar/ui 2.0.0 → 2.1.1

package/src/components/DataTable/README.md

@@ -0,0 +1,446 @@
+# 📊 DataTable
+
+Composant de table de données ultra-complet basé sur **TanStack Table v8**, totalement configurable et typé.
+
+## ✨ Fonctionnalités
+
+- ✅ **Tri multi-colonnes** (client & serveur)
+- ✅ **Filtrage global et par colonne**
+- ✅ **Pagination** (client & serveur)
+- ✅ **Sélection multiple** avec checkbox
+- ✅ **Export** (CSV, JSON)
+- ✅ **Import** (CSV)
+- ✅ **Layouts multiples** (standard, card, compact, split, infinite)
+- ✅ **Variants visuels** (bordered, minimal, striped, glass)
+- ✅ **Densité ajustable** (comfortable, compact)
+- ✅ **Toolbar personnalisable** avec actions
+- ✅ **Virtualisation** pour grandes données
+- ✅ **Thème clair/sombre** via TweakCN
+- ✅ **i18n** complet
+- ✅ **Responsive** (mobile-first)
+- ✅ **Accessibilité** (a11y)
+- ✅ **TypeScript** 100%
+
+## 📦 Installation
+
+```bash
+pnpm add @wakastart/ui @tanstack/react-table
+```
+
+## 🚀 Utilisation de base
+
+```tsx
+import { DataTable } from "@wakastart/ui"
+import { ColumnDef } from "@tanstack/react-table"
+
+interface User {
+  id: string
+  name: string
+  email: string
+}
+
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: "name",
+    header: "Name",
+  },
+  {
+    accessorKey: "email",
+    header: "Email",
+  },
+]
+
+const data: User[] = [
+  { id: "1", name: "John", email: "john@example.com" },
+  { id: "2", name: "Jane", email: "jane@example.com" },
+]
+
+function MyTable() {
+  return <DataTable data={data} columns={columns} />
+}
+```
+
+## 🎨 Exemples avancés
+
+### Table avec sélection et actions
+
+```tsx
+<DataTable
+  data={users}
+  columns={columns}
+  selection
+  toolbar={{
+    showSearch: true,
+    actions: [
+      {
+        id: "delete",
+        label: "Delete",
+        icon: <Trash />,
+        onClick: (selectedRows) => console.log(selectedRows),
+        requiresSelection: true,
+        variant: "destructive",
+      },
+    ],
+  }}
+  onSelectionChange={(selectedRows) => console.log(selectedRows)}
+/>
+```
+
+### Pagination serveur
+
+```tsx
+<DataTable
+  data={users}
+  columns={columns}
+  pagination={{
+    mode: "server",
+    currentPage: 0,
+    totalItems: 1000,
+    pageSize: 10,
+    onPageChange: (page) => fetchPage(page),
+    onPageSizeChange: (size) => setPageSize(size),
+  }}
+/>
+```
+
+### Export et Import
+
+```tsx
+<DataTable
+  data={users}
+  columns={columns}
+  enableExport
+  enableImport
+/>
+```
+
+### Layouts alternatifs
+
+```tsx
+<DataTable
+  data={users}
+  columns={columns}
+  layout="card" // ou "compact", "split", "infinite"
+  variant="glass" // ou "bordered", "minimal", "striped"
+  density="compact" // ou "comfortable"
+/>
+```
+
+### Header sticky
+
+```tsx
+<DataTable
+  data={users}
+  columns={columns}
+  headerSticky
+  virtualizationHeight={600}
+/>
+```
+
+### Filtres avancés avec autocomplete
+
+```tsx
+<DataTable
+  data={users}
+  columns={columns}
+  filterPosition="right" // ou "left", "top", "bottom", "modal"
+  filters={[
+    {
+      id: "name-filter",
+      label: "Nom",
+      type: "text",
+      column: "name",
+      placeholder: "Rechercher par nom...",
+    },
+    {
+      id: "role-filter",
+      label: "Rôle",
+      type: "multiselect",
+      column: "role",
+      placeholder: "Sélectionner des rôles...",
+    },
+    {
+      id: "status-filter",
+      label: "Statut",
+      type: "select",
+      column: "status",
+      options: [
+        { label: "Actif", value: "active" },
+        { label: "Inactif", value: "inactive" },
+      ],
+    },
+    {
+      id: "date-filter",
+      label: "Date de création",
+      type: "date",
+      column: "createdAt",
+    },
+    {
+      id: "age-filter",
+      label: "Âge",
+      type: "range",
+      column: "age",
+    },
+  ]}
+  onFiltersChange={(activeFilters) => console.log(activeFilters)}
+/>
+```
+
+**Caractéristiques des filtres** :
+- 🎯 **Bouton compact** : S'ouvre dans un panneau au clic (ne prend pas de place)
+- 🔍 **Autocomplete intelligent** : Suggestions automatiques basées sur les données de la colonne
+- 📝 **Types multiples** : text, select, multiselect, date, range
+- 📍 **Positions flexibles** :
+  - `top`/`bottom` : Popover compact (400px)
+  - `left`/`right` : Sheet latéral (400-540px)
+  - `modal` : Popover modal
+- ✅ **Gestion des filtres actifs** : Affichage et suppression facile des filtres appliqués
+- 🔧 **Opérateurs multiples** : contains, equals, startsWith, endsWith, in, notIn, between, etc.
+
+## 📚 Props
+
+### DataTableProps<TData>
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `TData[]` | **required** | Données à afficher |
+| `columns` | `ColumnDef<TData>[]` | **required** | Définition des colonnes |
+| `layout` | `DataTableLayout` | `"standard"` | Layout d'affichage |
+| `variant` | `DataTableVariant` | `"bordered"` | Variant visuel |
+| `density` | `DataTableDensity` | `"comfortable"` | Densité d'affichage |
+| `selection` | `boolean` | `false` | Activer la sélection |
+| `pagination` | `PaginationConfig` | `undefined` | Configuration pagination |
+| `toolbar` | `ToolbarConfig` | `undefined` | Configuration toolbar |
+| `filters` | `FilterConfig[]` | `undefined` | Configuration filtres |
+| `filterPosition` | `FilterPosition` | `"top"` | Position des filtres |
+| `loading` | `boolean` | `false` | État de chargement |
+| `error` | `string \| null` | `null` | Message d'erreur |
+| `emptyState` | `ReactNode` | `undefined` | État vide personnalisé |
+| `headerSticky` | `boolean` | `false` | Header fixe |
+| `enableExport` | `boolean \| ExportConfig` | `false` | Activer l'export |
+| `enableImport` | `boolean \| ImportConfig` | `false` | Activer l'import |
+| `enableVirtualization` | `boolean` | `false` | Activer virtualisation |
+| `onRowClick` | `(row: TData) => void` | `undefined` | Callback clic ligne |
+| `onSelectionChange` | `(rows: TData[]) => void` | `undefined` | Callback sélection |
+| `className` | `string` | `undefined` | Classe CSS |
+| `tableId` | `string` | `undefined` | ID pour persistance |
+
+### PaginationConfig
+
+```ts
+interface PaginationConfig {
+  mode?: "client" | "server"
+  pageSize?: number
+  pageSizeOptions?: number[]
+  currentPage?: number
+  totalItems?: number
+  onPageChange?: (page: number) => void
+  onPageSizeChange?: (size: number) => void
+}
+```
+
+### ToolbarConfig
+
+```ts
+interface ToolbarConfig {
+  actions?: TableAction[]
+  showSearch?: boolean
+  showColumnToggle?: boolean
+  showDensity?: boolean
+  showRefresh?: boolean
+  onRefresh?: () => void
+}
+```
+
+### TableAction
+
+```ts
+interface TableAction {
+  id: string
+  label: string
+  icon?: ReactNode
+  onClick: (selectedRows: TData[]) => void
+  requiresSelection?: boolean
+  variant?: "default" | "destructive" | "outline" | "ghost"
+  disabled?: boolean
+}
+```
+
+### FilterConfig
+
+```ts
+interface FilterConfig {
+  id: string
+  label: string
+  type: "text" | "select" | "multiselect" | "date" | "range"
+  column?: string
+  placeholder?: string
+  defaultValue?: any
+  options?: Array<{ label: string; value: string | number }>
+}
+```
+
+**Types de filtres** :
+- `text` : Champ texte avec autocomplete basé sur les valeurs de la colonne
+- `select` : Liste déroulante simple
+- `multiselect` : Sélection multiple avec checkboxes
+- `date` : Sélecteur de date
+- `range` : Plage numérique (min/max)
+
+## 🎛️ Hooks
+
+### useDataTable
+
+Hook principal pour gérer la logique du DataTable.
+
+```tsx
+const {
+  table,
+  sorting,
+  setSorting,
+  columnFilters,
+  setColumnFilters,
+  globalFilter,
+  setGlobalFilter,
+  selectedRows,
+  resetFilters,
+  exportData,
+} = useDataTable({
+  data,
+  columns,
+  pagination,
+  tableId,
+})
+```
+
+### useTableLayout
+
+Hook pour gérer le layout et la densité.
+
+```tsx
+const {
+  layout,
+  setLayout,
+  density,
+  setDensity,
+  toggleLayout,
+  toggleDensity,
+  isMobile,
+  densityClasses,
+} = useTableLayout("standard", "comfortable")
+```
+
+## 🌍 Internationalisation
+
+Le composant supporte l'i18n via `react-i18next`. Toutes les clés sont sous le namespace `datatable` :
+
+```json
+{
+  "datatable": {
+    "loading": "Chargement...",
+    "noData": "Aucune donnée",
+    "selectAll": "Tout sélectionner",
+    "pagination": {
+      "showing": "Affichage",
+      "to": "à",
+      "of": "sur",
+      "results": "résultats",
+      "rowsPerPage": "Lignes par page"
+    },
+    "toolbar": {
+      "search": "Rechercher...",
+      "selected": "sélectionnés",
+      "clear": "Effacer",
+      "export": "Exporter",
+      "columns": "Colonnes"
+    }
+  }
+}
+```
+
+## 🎨 Personnalisation
+
+### Styles personnalisés
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  className="custom-table"
+/>
+```
+
+### Variant personnalisé
+
+Le composant utilise Tailwind CSS. Vous pouvez personnaliser via les variants :
+
+- `bordered` : bordures et coins arrondis
+- `minimal` : sans bordures
+- `striped` : lignes alternées
+- `glass` : effet glassmorphism
+
+## 🔧 Utilitaires
+
+### Export
+
+```ts
+import { exportToCSV, exportToJSON } from "@wakastart/ui"
+
+exportToCSV(data, "users.csv")
+exportToJSON(data, "users.json")
+```
+
+### Import
+
+```ts
+import { parseCSV } from "@wakastart/ui"
+
+const data = await parseCSV(file)
+```
+
+### Persistance
+
+```ts
+import { saveTableState, loadTableState } from "@wakastart/ui"
+
+saveTableState("my-table", state)
+const state = loadTableState("my-table")
+```
+
+## 🧪 Tests
+
+```tsx
+import { render, screen } from "@testing-library/react"
+import { DataTable } from "@wakastart/ui"
+
+test("renders table with data", () => {
+  render(<DataTable data={testData} columns={testColumns} />)
+  expect(screen.getByText("John")).toBeInTheDocument()
+})
+```
+
+## 📖 Documentation complète
+
+- [TanStack Table](https://tanstack.com/table/v8)
+- [WakaStart UI](https://ui.wakastart.com)
+- [Exemples de démo](/demo/app/datatable)
+
+## 📝 Changelog
+
+### v1.0.0 (2024-10-15)
+
+- 🎉 Initial release
+- ✨ Support complet de TanStack Table v8
+- 🎨 Layouts multiples
+- 🌍 i18n complet
+- 📊 Export/Import
+- 🎯 TypeScript strict
+
+## 🤝 Contribution
+
+Contributions bienvenues ! Voir [CONTRIBUTING.md](../../../CONTRIBUTING.md)
+
+## 📄 License
+
+MIT © WakaStart
+