Documentation Yayaw Table

Yayaw Table est une librairie de tableaux de données flexible pour React. Un seul composant, une API claire : vous passez getTableConfig et getTableActions, puis la table gère l'état URL (Nuqs), les données server-side et les actions CRUD/bulk.

🚀 Démarrage rapide

Installez via la registry Shadcn, puis branchez la configuration et les actions à DataTable :

import { DataTable } from "@/components/ui/yayaw-table";
import { getTableConfig, getTableActions } from "./table-config";

export const MyTable = () => (
  <DataTable
    tableType="products"
    getTableConfig={getTableConfig}
    getTableActions={getTableActions}
    title="Produits"
  />
);

Il vous faut au minimum getTableConfig (colonnes, options de table) et getTableActions (par exemple list pour les données). Pour Next.js avec état URL, ajoutez NuqsAdapter dans votre layout. Voir Provider & Setup pour la configuration complète.

✅ Bénéfices

• Moins de code répétitif – API claire et focalisée
• Setup minimal – Valeurs par défaut robustes
• Stable – Pas de boucles d'hydratation avec Next.js
• Propulsé par TanStack Table – Excellentes performances
• Regroupement intégré – Support expand/collapse
• Type-safe – Typage TypeScript de bout en bout
• Compatible SSR – Fonctionne avec Next.js 15+

🔧 Fonctionnalités

Groupement

Le groupement, la pagination et le tri sont activés via la configuration de table et les types de colonnes. Pas de câblage lourd.

Vues enregistrées

Les utilisateurs peuvent enregistrer et restaurer des vues basées sur l'état URL : filtres, recherche, tri, layout de colonnes, mode d'affichage, réglages Kanban, réglages Gallery, groupement, pinning et taille de page.

Modes d'affichage

Utilisez la vue table par défaut, un Kanban basé sur Kibo UI ou une grille Gallery responsive depuis la même source de données. Kanban et Gallery conservent la sélection, les actions de ligne, le comportement de clic, les filtres, le tri, la pagination et les vues enregistrées comme la table.

Pagination

Contrôles de pagination accessibles avec ARIA correct et navigation clavier.

Tri

Cliquez sur les en-têtes pour trier. Activation/désactivation par colonne.

Types de colonnes

const columns = [
  { id: "name", type: "text", header: "Nom" },
  { id: "brand", type: "tag", header: "Marque" },
  { id: "price", type: "number", header: "Prix" },
  { id: "active", type: "boolean", header: "Actif" },
  { id: "date", type: "date", header: "Créé le" },
];

Barre d'outils & menus

Tout est accessible depuis la barre d'outils :

• Tri via les en-têtes de colonnes
• Filtres de colonnes et panneau de filtres avancés
• Bascules de regroupement quand le type de colonne le permet
• Menu de visibilité des colonnes (afficher/masquer, réinitialiser l'ordre)
• Vues enregistrées et sélecteur d'affichage table, Kanban et Gallery
• Recherche globale
• Export CSV depuis la barre d'outils (toutes les lignes filtrées)
• Mode barre d'outils compact (icône + tooltip) via table.actionsAsIcons
• Menu d'actions de masse (Modifier, Copier, Exporter, Supprimer)
• Formulaires d'édition auto-générés pour les lignes/éléments

📖 Documentation

• Installation – Installation registry Shadcn et setup projet
• Provider & Setup – getTableConfig, getTableActions, getFormConfig, props DataTable
• Formulaires et champs collection – Champs de formulaire, éditeurs de tableaux natifs, collections imbriquées et validation
• DataTable – Référence des props du composant
• Configuration – Options table et colonnes
• Columns – Types et définitions de colonnes
• Actions – Forme de l'API d'actions (list, create, update, delete, bulk)
• Query Integration – Architecture QueryClient partagé et invalidation
• Bulk Actions – Flux de confirmation et contrat des callbacks
• Server-side & Server Actions – Server Actions Next.js pour list et CRUD
• URL state (Nuqs) – Tri, filtres, modes d'affichage, vues enregistrées et pagination dans l'URL
• Troubleshooting – Résoudre les problèmes runtime fréquents
• Translations – Surcharger les chaînes UI

🎨 Personnalisation

La table utilise Tailwind par défaut. Vous pouvez personnaliser les classes via les props className standards.

🔗 Exemple

Consultez /example dans ce repo pour un exemple complet d'intégration UI : état URL (Nuqs), vues enregistrées, modes table/Kanban/Gallery, filtres avancés, édition de masse et données de démonstration conservées en local (localStorage + réinitialisation du jeu de données).

Pour l'approche server-driven, voir Server-side & Server Actions.

🙏 Remerciements

Yayaw Table s'appuie sur d'excellents projets open-source. Merci à leurs mainteneurs et contributeurs :

• TanStack Table - moteur de table et fondations de performance
• TanStack Query - modèle de récupération de données et cache asynchrone
• shadcn/ui - modèle d'intégration registry et primitives UI
• Nuqs - modèles de gestion d'état URL
• Jotai - état atomique léger pour l'UI/table
• dnd-kit - drag-and-drop pour les interactions de colonnes
• Floating UI et Base UI - primitives headless accessibles et positionnement robuste