@oneteme/jquery-table 0.0.1 → 0.0.2

package/README.md

@@ -1,16 +1,24 @@
-# jQuery-Table
+# @oneteme/jquery-table
 
 Bibliothèque Angular qui encapsule Angular Material Table avec une API orientée configuration runtime.
 
 ## Features
 
-- Colonnes dynamiques (ajout/retrait à l'exécution)
-- Liste de colonnes optionnelles ajoutables via bouton `+`
-- Slice catégories à gauche (ex: status)
-- Filtrage temps réel selon la catégorie sélectionnée
-- Settings par colonne (⋯): filter by values + actions custom
-- Actions utilitaires custom par colonne (événements)
-- Intégration avec `@oneteme/jquery-core` (`field`, `DataProvider`)
+- Configuration déclarative du tableau via `TableProvider`
+- Colonnes optionnelles ajoutables/supprimables à l'exécution via menu View
+- Réordonnancement des colonnes par glisser-déposer
+- Tri natif Material par colonne
+- Recherche textuelle temps réel
+- Pagination standard et pagination par groupe
+- **Group by** : regroupement des lignes par colonne, groupes pliables/dépliables, pagination indépendante par groupe
+- **Slice panel** : filtres catégoriels latéraux, statiques (prédéfinis) ou dynamiques (colonne  valeurs uniques), multi-sélection configurable
+- **Chargement paresseux** (lazy) de cellules via Observable par colonne
+- Rendus de cellule personnalisés via directive `jqtCellDef`
+- État de chargement (`isLoading`) et état vide configurable
+- Événement de clic sur ligne (`rowSelected`)
+- CSS variables pour la personnalisation visuelle complète
+- Compatible mode allégé : `[dataSource]` + `[displayedColumns]` sans `config`
+- Intégration `@oneteme/jquery-core` (`DataProvider`)
 
 ## Installation
 
@@ -18,174 +26,483 @@ Bibliothèque Angular qui encapsule Angular Material Table avec une API orienté
 npm install @oneteme/jquery-core @oneteme/jquery-table @angular/material @angular/cdk
 ```
 
+---
+
 ## Utilisation rapide
 
 ```ts
-import { Component } from '@angular/core';
 import { TableComponent, TableProvider, col } from '@oneteme/jquery-table';
 
 interface Row {
-	issue: string;
-	status: 'Backlog' | 'In Progress' | 'Done';
-	owner: string;
-	priority: 'Low' | 'Medium' | 'High';
+  id: number;
+  name: string;
+  status: 'active' | 'inactive';
+  team: string;
 }
 
 @Component({
-	standalone: true,
-	imports: [TableComponent],
-	template: `
-		<jquery-table
-			[config]="tableConfig"
-			(columnAdded)="onColumnAdded($event)"
-			(columnRemoved)="onColumnRemoved($event)"
-			(categorySelected)="onCategorySelected($event)"
-		></jquery-table>
-	`,
+  imports: [TableComponent],
+  template: `<jquery-table [config]="table" [data]="rows" (rowSelected)="onRow($event)"></jquery-table>`,
 })
 export class DemoComponent {
-	tableConfig: TableProvider<Row> = {
-		title: 'Ticket board',
-		showAddColumnButton: true,
-		enableColumnRemoval: true,
-		columns: [col<Row>('issue', 'Issue'), col<Row>('status', 'Status')],
-		availableColumns: [col<Row>('owner', 'Owner'), col<Row>('priority', 'Priority')],
-		categorySlice: {
-			title: 'Status',
-			allLabel: 'Tous',
-			categories: [
-				{ key: 'backlog', label: 'Backlog', filter: (row) => row.status === 'Backlog' },
-				{ key: 'in-progress', label: 'In Progress', filter: (row) => row.status === 'In Progress' },
-				{ key: 'done', label: 'Done', filter: (row) => row.status === 'Done' },
-			],
-		},
-		data: [
-			{ issue: 'Fix auth', status: 'In Progress', owner: 'Anna', priority: 'High' },
-			{ issue: 'Improve docs', status: 'Backlog', owner: 'Leo', priority: 'Low' },
-		],
-	};
-
-	onColumnAdded() {}
-	onColumnRemoved() {}
-	onCategorySelected() {}
+  rows: Row[] = [];
+
+  table: TableProvider<Row> = {
+    title: 'Utilisateurs',
+    columns: [
+      col('id',     'ID'),
+      col('name',   'Nom',    { sortable: true }),
+      col('status', 'Statut', { sliceable: true }),
+      col('team',   'Équipe', { groupable: true, optional: true }),
+    ],
+    slices: [
+      {
+        title: 'Statut',
+        columnKey: 'status',
+        categories: [
+          { key: 'active',   label: 'Actif',   filter: r => r.status === 'active' },
+          { key: 'inactive', label: 'Inactif', filter: r => r.status === 'inactive' },
+        ],
+      },
+    ],
+    search:     { enabled: true },
+    pagination: { enabled: true, pageSize: 20 },
+    view:       { enabled: true, enableColumnDragDrop: true },
+    export:     { enabled: true, filename: 'utilisateurs' },
+  };
+
+  onRow(row: Row) { console.log(row); }
 }
 ```
 
-## Migration minimale depuis Angular Material Table
+---
 
-Si votre composant utilise déjà `dataSource` et `displayedColumns`, vous pouvez migrer avec très peu de changements:
+## Mode allégé  compatibilité `dataSource` / `displayedColumns`
 
-```html
-<!-- Avant -->
-<!-- <table mat-table [dataSource]="dataSource"> ... -->
+Pour une migration minimale depuis une `mat-table` existante :
 
-<!-- Après -->
+```html
 <jquery-table
-	[dataSource]="dataSource"
-	[displayedColumns]="displayedColumns"
-	[columnLabels]="columnLabels"
+  [dataSource]="rows"
+  [displayedColumns]="['id', 'name', 'status']"
+  [columnLabels]="{ id: 'ID', name: 'Nom', status: 'Statut' }"
+  [isLoading]="loading"
 ></jquery-table>
 ```
 
+Le `config` complet reste disponible pour activer les fonctionnalités avancées.
+
+---
+
+## API  `TableComponent`
+
+### Inputs
+
+| Propriété | Type | Description |
+|-----------|------|-------------|
+| `config` | `TableProvider<T>` | Configuration principale (colonnes, données, comportements) |
+| `data` | `T[]` | Données en entrée directe (remplace `config.data`) |
+| `dataSource` | `T[] \| { data: T[] }` | Alias compatibilité Material |
+| `displayedColumns` | `string[]` | Alias compatibilité Material  clés de colonnes à afficher |
+| `columnsConfig` | `TableColumnProvider<T>[]` | Configuration des colonnes (remplace `config.columns`) |
+| `columnLabels` | `Record<string, string>` | Labels des colonnes pour le mode allégé |
+| `isLoading` | `boolean` | Affiche l'état de chargement (défaut : `false`) |
+| `view` | `TableViewConfig` | Surcharge `config.view` si défini (mode HTML) |
+
+### Outputs
+
+| Événement | Payload | Description |
+|-----------|---------|-------------|
+| `rowSelected` | `T` | Ligne cliquée |
+| `columnAdded` | `TableColumnProvider<T>` | Colonne ajoutée aux colonnes actives |
+| `columnRemoved` | `TableColumnProvider<T>` | Colonne retirée des colonnes actives |
+| `categorySelected` | `string` | Catégorie de slice sélectionnée |
+| `addRequested` | `void` | Clic sur le bouton d'ajout de colonne |
+
+---
+
+## API — `TableProvider<T>`
+
 ```ts
-displayedColumns = ['issue', 'status', 'owner'];
+interface TableProvider<T = any> {
+  columns?:      TableColumnProvider<T>[];
+  title?:        string;
 
-columnLabels = {
-	issue: 'Issue',
-	status: 'Status',
-	owner: 'Owner',
-};
+  slices?:            SliceConfig<T>[];    // Filtres catégoriels (slice panel)
+  enableSliceToggle?: boolean;             // Défaut : true
+
+  search?:       TableSearchConfig;
+  pagination?:   TablePaginationConfig;
+  view?:         TableViewConfig;
+  labels?:       TableLabelsConfig;
+  export?:       TableExportConfig<T>;
+
+  defaultSort?:   { active: string; direction: 'asc' | 'desc' };
+  rowClass?:      (row: T, index: number) => string | string[] | Record<string, boolean>;
+}
 ```
 
-Le `config` complet reste disponible pour activer les fonctionnalités avancées (slice catégories, ajout/retrait de colonnes, menu d’options).
+> **Note** : les données (`data`) et l’état de chargement (`isLoading`) sont des `@Input` séparés
+> sur le composant, pas des champs de `TableProvider`.
 
-## API
+---
 
-### Inputs
+## API — `TableColumnProvider<T>`
+
+```ts
+interface TableColumnProvider<T = any> {
+  key:        string;
+  header?:    string;                  // Label de l'entête
+  icon?:      string;                  // Icône Material (affiché dans l'entête)
+  value?:     DataProvider<any>;       // (row, index) => valeur affichée
+  sortValue?: DataProvider<any>;       // Valeur pour le tri si différente de value
+  sortable?:  boolean;
+  width?:     string;                  // Largeur CSS en px uniquement pour le calcul min-width (ex: '120px')
+                                       // Les unités %, em, rem sont ignorées dans le calcul de tableMinWidth
+
+  optional?:  boolean;                 // Colonne masquée par défaut, ajoutables via View menu
+  removable?: boolean;                 // Peut être retirée manuellement
+
+  groupable?: boolean;                 // Disponible comme critère de regroupement dans View menu
+  sliceable?: boolean;                 // Disponible comme slice dynamique dans View menu
+  searchValue?: DataProvider<string>;  // Valeur utilisée par la recherche texte (si différente de value)
+
+  lazy?: {
+    fetchFn: () => Observable<any[]>;  // Retourne un tableau dans le même ordre que les lignes
+  };
+}
+```
 
-- `dataSource`: alias compatible Material (`T[]` ou `{ data: T[] }`)
-- `displayedColumns`: alias compatible Material (`string[]`)
-- `columnLabels`: labels optionnels pour `displayedColumns`
-- `config.showColumnSettings`: active les menus `⋯` en header de colonne
-- `config.maxFilterValuesPerColumn`: limite le nombre de valeurs proposées dans `Filter by values`
-- `config.columnUtilityActions`: actions custom globales par colonne
-- `config.columns`: colonnes initiales visibles
-- `config.optionalColumns` (ou `config.availableColumns`): colonnes optionnelles ajoutables via `+`
-- `config.showAddColumnButton`: active/désactive le bouton `+`
-- `config.showOptionsButton`: active/désactive le bouton `Options`
-- `config.bottomActionsLabel`: libellé des actions dockées en bas-gauche
-- `config.enableColumnRemoval`: autorise la suppression des colonnes
-- `config.categorySlice`: configuration du panel de catégories à gauche
-- `config.data`: dataset source
-
-### Smart adaptation (intelligence data-driven)
-Le wrapper est volontairement simple: pas de système d'inférence automatique complexe.
-Le développeur fournit explicitement les colonnes de base, les colonnes optionnelles et les filtres.
+---
 
-### Outputs
+## Helper `col()`
+
+Raccourci pour déclarer une colonne sans verbosité :
+
+```ts
+import { col } from '@oneteme/jquery-table';
+
+columns: [
+  col('name',   'Nom'),
+  col('status', 'Statut', { sortable: false, groupable: true }),
+  col('team',   'Équipe', { optional: true }),
+]
+```
+
+---
+
+## API — Sous-configurations
+
+### `TableSearchConfig`
 
-- `columnAdded`: émis après ajout effectif d'une colonne
-- `columnRemoved`: émis après suppression effective d'une colonne
-- `categorySelected`: émis au changement de catégorie
-- `columnSettingSelected`: émis au clic sur une action de menu colonne (built-in ou custom)
-- `optionSelected`: émis depuis le menu d'options
+```ts
+interface TableSearchConfig {
+  enabled?:       boolean;
+  initialQuery?:  string;     // Terme de recherche pré-rempli au chargement
+  searchColumns?: string[];   // Restreint la recherche à ces clés de colonnes
+}
+```
+
+### `TablePaginationConfig`
+
+```ts
+interface TablePaginationConfig {
+  enabled?:                boolean;
+  pageSize?:               number;
+  pageSizeOptions?:        number[];
+  pageSizeOptionsGroupBy?: number[];   // Options spécifiques au mode Group by
+}
+```
+
+### `TableViewConfig`
+
+```ts
+interface TableViewConfig {
+  enabled?:              boolean;   // Défaut : false  active le bouton View
+  enableColumnRemoval?:  boolean;   // Défaut : true   autorise la suppression de colonnes
+  enableColumnDragDrop?: boolean;   // Défaut : false  active le réordonnancement drag & drop
+}
+```
+
+### `TableLabelsConfig`
+
+```ts
+interface TableLabelsConfig {
+  empty?:   string;   // Défaut : 'Aucune donnée' (ou la valeur i18n injectée)
+  loading?: string;   // Défaut : 'Chargement des données...' (ou la valeur i18n injectée)
+}
+```
+
+### `TableExportConfig<T>`
+
+```ts
+interface TableExportConfig<T = any> {
+  enabled?:   boolean;                             // Affiche le bouton Export
+  filename?:  string;                              // Nom du fichier sans extension (défaut : 'export')
+  transform?: (row: T) => Record<string, string>;  // Transforme chaque ligne avant export
+}
+```
+
+L’export ne porte que sur les **données filtrées** (slice + recherche) et les **colonnes visibles**.
+Le fichier est généré avec un BOM UTF-8 pour une compatibilité Excel correcte.
 
-### Exemple settings colonne
+---
+
+## i18n
+
+Tous les labels de l’interface sont personnalisables via un `InjectionToken` :
 
 ```ts
-tableConfig = {
-	showColumnSettings: true,
-	maxFilterValuesPerColumn: 12,
-	columnUtilityActions: [
-		{ action: 'utility:copyColumnKey', label: 'Copy column key' },
-	],
+import { JQT_I18N } from '@oneteme/jquery-table';
+
+// Dans AppModule ou un provider racine
+providers: [
+  {
+    provide: JQT_I18N,
+    useValue: {
+      searchPlaceholder: 'Search…',
+      emptyState:        'No data',
+      loadingState:      'Loading…',
+      viewNoneSelected:  'None',
+      groupRemove:       'Remove grouping',
+      exportButtonLabel: 'Export',
+    },
+  },
+]
+```
+
+Seuls les champs fournis écrasent les défauts français. Voir `JqtI18n` pour la liste complète (24 labels).
+
+---
+
+## Fonctionnalité — Group by
+
+Le regroupement s'active en ajoutant `groupable: true` sur une ou plusieurs colonnes. L'utilisateur choisit ensuite la colonne de regroupement depuis le menu View.
+
+```ts
+columns: [
+  { key: 'team',   header: 'Équipe',  groupable: true },
+  { key: 'status', header: 'Statut',  groupable: true },
+  { key: 'name',   header: 'Nom' },
+],
+view:       { enabled: true },
+pagination: {
+  enabled: true,
+  pageSizeOptionsGroupBy: [5, 10, 25],
+},
+```
+
+Comportements inclus :
+- Groupes pliables/dépliables individuellement
+- Pagination indépendante par groupe
+- Tri des entêtes de groupe (asc / desc)
+- Scroll automatique vers l'entête du groupe actif
+
+---
+
+## Fonctionnalité — Slice panel
+
+Le slice panel est un panneau latéral de filtres catégoriels.
+
+### Slices statiques (catégories prédéfinies)
+
+```ts
+slices: [
+  {
+    title:     'Statut',
+    icon:      'circle',
+    columnKey: 'status',
+    categories: [
+      { key: 'active',   label: 'Actif',   filter: r => r.status === 'active' },
+      { key: 'inactive', label: 'Inactif', filter: r => r.status === 'inactive' },
+    ],
+  },
+  {
+    title:       'Priorité',
+    columnKey:   'priority',
+    multiSelect: true,
+    bucket:      r => r.priority,   // Auto-génère les catégories depuis les valeurs uniques
+  },
+],
+```
+
+### Slices dynamiques (depuis le menu View)
+
+Une colonne avec `sliceable: true` peut être ajoutée dynamiquement comme slice depuis le menu View.
+
+```ts
+columns: [
+  { key: 'team', header: 'Équipe', sliceable: true },
+],
+view: { enabled: true },
+```
+
+### `SliceConfig<T>`
+
+```ts
+interface SliceConfig<T = any> {
+  title?:       string;
+  icon?:        string;
+  columnKey?:   string;
+  multiSelect?: boolean;                     // Défaut : false
+  hidden?:      boolean;                     // Masqué par défaut dans le panel
+  categories?:  SliceCategory<T>[];
+  bucket?:      (row: T) => string;          // Auto-génère les catégories (ignoré si categories défini)
+}
+
+interface SliceCategory<T = any> {
+  key:    string;
+  label:  string;
+  filter: (row: T) => boolean;
+}
+```
+
+---
+
+## Fonctionnalité — lazy columns
+
+```ts
+columns: [
+  {
+    key:    'details',
+    header: 'Détails',
+    lazy: {
+      fetchFn: () => this.api.getDetails(),
+    },
+  },
+],
+```
+
+Le composant gère l'état `idle | loading | loaded | error` par colonne, avec possibilité de relancer la requête en cas d'erreur.
+
+---
+
+## Fonctionnalité — Cellules personnalisées (`jqtCellDef`)
+
+```html
+<jquery-table [config]="table">
+
+  <ng-template jqtCellDef="status" let-row>
+    <span [class]="'badge badge-' + row.status">{{ row.status }}</span>
+  </ng-template>
+
+  <ng-template jqtCellDef="actions" let-row let-index="index">
+    <button (click)="edit(row)">Éditer</button>
+  </ng-template>
+
+</jquery-table>
+```
+
+Contexte du template :
+- `$implicit`  la ligne brute (`T`)
+- `index`  index global de la ligne
+
+---
+
+## Fonctionnalité — Clic sur ligne
+
+```html
+<jquery-table [config]="table" (rowSelected)="onRow($event)"></jquery-table>
+```
+
+La ligne brute `T` est émise via l'Output `(rowSelected)`. Pour appliquer une classe conditionnelle aux lignes, utiliser `rowClass` dans `config` :
+
+```ts
+config: TableProvider<Row> = {
+  rowClass: (row) => row.status === 'error' ? 'row-error' : '',
 };
 ```
 
-## Personnalisation visuelle (CSS variables)
+---
+
+## Usage standalone — `SlicePanelComponent`
 
-Toutes les couleurs principales sont exposées via des CSS custom properties sur `:host`.  
-Pour les surcharger, ciblez `jquery-table` dans votre feuille de styles globale :
+`SlicePanelComponent` est exporté et utilisable indépendamment du tableau, par exemple pour filtrer les données d'un graphique :
+
+```html
+<jqt-slice-panel
+  [sliceConfigs]="slices"
+  [columns]="columns"
+  [data]="rows"
+  [showCounts]="true"
+  (filterChange)="applyFilter($event)"
+></jqt-slice-panel>
+```
+
+### Inputs `SlicePanelComponent`
+
+| Propriété | Type | Description |
+|-----------|------|-------------|
+| `sliceConfigs` | `SliceConfig<T>[]` | Configurations des slices |
+| `columns` | `SliceColumnDef<T>[]` | Définitions des colonnes pour la résolution des valeurs |
+| `data` | `T[]` | Données source |
+| `lazyData` | `Map<string, Map<any,any>>` | Valeurs lazy chargées |
+| `lazyStatus` | `Map<string, 'idle'\|'loading'\|'loaded'\|'error'>` | État par colonne lazy |
+| `showToggle` | `boolean` | Affiche le bouton collapse du panel (défaut : `true`) |
+| `showCounts` | `boolean` | Affiche le nombre de lignes par catégorie (défaut : `true`) |
+| `collapsedByDefault` | `boolean` | Les slices démarrent repliés (défaut : `false`) |
+| `alwaysShow` | `boolean` | Affiche le panel même si vide (défaut : `false`) |
+
+### Outputs `SlicePanelComponent`
+
+| Événement | Payload | Description |
+|-----------|---------|-------------|
+| `filterChange` | `(row: T) => boolean` | Prédicat de filtre à appliquer |
+| `activeKeysChange` | `string[][]` | Clés actives par slice |
+| `dynamicSliceKeysChange` | `string[]` | Clés des slices dynamiques actives |
+| `collapsedChange` | `boolean` | État replié/déplié du panel |
+
+---
+
+## Personnalisation visuelle — CSS variables
 
 ```scss
 jquery-table {
   /* Texte */
-  --jqt-title-color:       #1f2937;  /* titre du tableau (h3)                    */
-  --jqt-text-color:        #111827;  /* texte principal (cellules, labels)        */
-  --jqt-text-secondary:    #6b7280;  /* texte secondaire (badges, infos)          */
-  --jqt-text-muted:        #9ca3af;  /* placeholder, icônes discrètes            */
+  --jqt-title-color:       #1f2937;
+  --jqt-text-color:        #111827;
+  --jqt-text-secondary:    #6b7280;
+  --jqt-text-muted:        #9ca3af;
 
   /* Surfaces */
-  --jqt-surface-color:     #ffffff;  /* fond des éléments (barre de recherche…)  */
-  --jqt-surface-alt-color: #f9fafb;  /* fond alternatif subtil                   */
-  --jqt-row-hover-bg:      #f3f4f6;  /* survol d'une ligne / fond badge          */
+  --jqt-surface-color:     #ffffff;
+  --jqt-surface-alt-color: #f9fafb;
+  --jqt-row-hover-bg:      #f3f4f6;
 
   /* Bordures */
-  --jqt-border-color:      #e5e7eb;  /* bordures du tableau et éléments UI       */
+  --jqt-border-color:      #e5e7eb;
 
-  /* Groupes (groupBy) */
-  --jqt-group-bg:          #eef2f7;  /* fond des lignes de groupe                */
-  --jqt-group-bg-hover:    #e4ecf4;  /* fond au survol d'une ligne de groupe     */
-  --jqt-group-accent:      #94a3b8;  /* bande colorée gauche des groupes         */
-  --jqt-group-border:      #d1d9e4;  /* bordures haut/bas des groupes            */
+  /* Group by */
+  --jqt-group-bg:          #eef2f7;
+  --jqt-group-bg-hover:    #e4ecf4;
+  --jqt-group-accent:      #94a3b8;
+  --jqt-group-border:      #d1d9e4;
 
   /* Accent & danger */
-  --jqt-primary-color:     #1d4ed8;  /* couleur d'accent (focus, sélection)      */
-  --jqt-danger-color:      #dc2626;  /* bouton reset (survol)                    */
+  --jqt-primary-color:     #1d4ed8;
+  --jqt-danger-color:      #dc2626;
 }
 ```
 
-**Exemple** — thème violet :
+---
 
-```scss
-jquery-table {
-  --jqt-primary-color:  #7c3aed;
-  --jqt-group-accent:   #7c3aed;
-  --jqt-group-bg:       #f5f3ff;
-  --jqt-group-border:   #ddd6fe;
-}
+## Utilitaires exportés
+
+```ts
+import { normalizeCellValue, humanizeKey, getFrenchPaginatorIntl } from '@oneteme/jquery-table';
 ```
 
+| Fonction | Description |
+|----------|-------------|
+| `normalizeCellValue(value)` | Convertit n'importe quelle valeur de cellule en string affichable (gère `null`, `Date`, `Array`, objet `{label}` / `{name}`) |
+| `humanizeKey(key)` | Transforme `camelCase` / `snake_case` en label lisible (`createdAt` → `"Created at"`) |
+| `col(key, header, overrides?)` | Raccourci pour créer un `TableColumnProvider` en une ligne |
+| `getFrenchPaginatorIntl()` | Retourne un `MatPaginatorIntl` avec les labels en français |
+
+> **`normalizeCellValue`** utilise la locale navigateur (et non fr-FR) pour les dates.
+
+---
+
 ## Build
 
 ```bash