Utilisation de <CrudPage>

Le composant <CrudPage> est le cœur de la librairie @codifyo/vue-crud. Il orchestre l'affichage du tableau, la pagination asynchrone, les filtres, le sélecteur de colonnes et la gestion complète des actions (pages, modales, édition en ligne, confirmations).

---

Sommaire

• 1. Exemple d'utilisation
• 2. API de Configuration (CrudConfig)
• 3. Options Globales (options)
• 4. Méthodes Exposées (defineExpose) & Utilitaires

Pour la documentation détaillée, consultez :

• Configuration des Colonnes
• Gestion des Actions
• Surcharge et Slots

---

1. Exemple d'utilisation

<template>
  <CrudPage ref="crudRef" :config="config" />
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { CrudPage, defineCrudConfig } from '@codifyo/vue-crud';

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
  status: string;
}

const crudRef = ref<InstanceType<typeof CrudPage> | null>(null);

const config = defineCrudConfig<User>({
  title: 'Gestion des Utilisateurs',
  itemName: 'Utilisateur',
  idKey: 'id',
  enableBulkActions: true,
  
  columns: [
    { key: 'name', label: 'Nom', sortable: true },
    { key: 'email', label: 'Email', type: 'link', sortable: true },
    { key: 'role', label: 'Rôle', type: 'badge' },
    { key: 'status', label: 'Statut', type: 'badge' }
  ],
  
  api: {
    fetchList: async ({ page, limit, sort, dir, filters }) => {
      const query = new URLSearchParams({ page: String(page), limit: String(limit), sort, dir, ...filters });
      const response = await fetch(`/api/users?${query}`);
      const data = await response.json();
      return { data: data.items, total: data.total };
    }
  },

  options: {
    perPage: 15,
    perPageChoices: [10, 15, 25, 50],
    syncUrl: true,
    columnChooserStorageKey: 'crud_users_columns'
  }
});
</script>

---

2. API de Configuration (CrudConfig)

Propriété	Type	Requis	Description
title	string	Oui	Titre principal affiché dans l'en-tête de la page.
itemName	string	Oui	Nom au singulier de l'entité (ex: 'Utilisateur'), utilisé dans les messages et titres par défaut.
idKey	string | keyof T	Non	Nom de la clé identifiant chaque ligne (défaut : 'id').
columns	CrudColumn[]	Oui	Liste de la configuration des colonnes affichées dans le tableau.
api	Object	Oui	Objet réseau contenant la méthode obligatoire fetchList et les méthodes optionnelles (create, update, delete).
enableBulkActions	boolean	Non	Active les cases à cocher de sélection multiple et la barre d'actions groupées (défaut : false).
filterFormConfig	Record<string, any>	Non	Configuration du formulaire de filtre transmise au composant de filtre (ou @codifyo/form-vue).
filterRemoveExtra	boolean	Non	Si true, nettoie les valeurs vides des filtres avant envoi (défaut : true).
editFormConfig	Record<string, any>	Non	Configuration du formulaire d'édition transmis par défaut aux actions de type form.
actions	{ global?, item?, bulk? }	Non	Dictionnaire des actions configurées (global, item, bulk).
options	CrudOptions	Non	Options de personnalisation globale du comportement et de l'interface.

---

3. Options Globales (options)

export interface CrudOptions {
  perPage?: number;           // Nombre d'éléments par page par défaut (défaut : 15)
  perPageChoices?: number[];  // Choix d'éléments par page (ex: [10, 15, 25, 50, 100])
  defaultSort?: string;       // Clé de la colonne triée par défaut au chargement initial (ex: 'createdAt')
  defaultSortDir?: 'asc' | 'desc'; // Direction du tri par défaut (défaut : 'asc')
  syncUrl?: boolean;          // Synchronise pagination, tris, filtres et actions dans l'URL (défaut : true)
  debounceMs?: number;        // Délai de debounce en ms pour la modification des filtres (défaut : 400ms)
  updateUrl?: (query: Record<string, string>) => void; // Adaptateur manuel pour mettre à jour l'URL (reçoit la query seule, jamais le chemin d'une action à `route`)
  baseRoute?: string;         // Chemin de la liste où revenir à la fermeture d'une action à `route` (défaut : dernier chemin de liste visité, puis '/') ; voir ACTIONS.md, « Actions à Route »
  emptyState?: {
    title?: string;
    subtitle?: string;
    icon?: string;            // Icône FontAwesome pour le tableau vide
  };
  onToast?: (toast: { type: 'success' | 'danger' | 'info' | 'warning'; message: string }) => boolean | void;
  enableColumnChooser?: boolean; // Active le sélecteur de colonnes dans la barre d'outils (défaut : true)
  columnChooserStorageKey?: string; // Clé localStorage pour persister les colonnes masquées (défaut: crud_cols_{itemName})
  allowedActionsKey?: string; // Propriété de l'item listant les noms d'actions autorisées (ex: '_allowed_actions')
}

---

4. Méthodes Exposées (defineExpose) & Utilitaires

Méthodes exposées sur l'instance <CrudPage> (ref)

Si vous récupérez une référence sur le composant <CrudPage ref="crudRef"> (fortement typé avec CrudExposedMethods) :

const crudRef = ref<InstanceType<typeof CrudPage> | null>(null);

// Déclencher une action par son nom ou son objet :
crudRef.value?.triggerAction('print-invoice', item);

// Déclencher une action groupée :
crudRef.value?.triggerAction('bulk-delete', undefined, selectedIds);

// Recharger silencieusement la liste depuis le serveur :
crudRef.value?.fetchList(true);

// Rafraîchir la liste :
crudRef.value?.refreshList();

// Invalider la liste (vide le cache et force un rechargement au prochain affichage) :
crudRef.value?.invalidateList();

// Rafraîchir la page active (composant distant de la vue) :
crudRef.value?.refreshPage();

// Fermer l'action / la modale / la page active :
crudRef.value?.closeAction();

// Boîte de dialogue de confirmation programmatique :
const ok = await crudRef.value?.confirm('Voulez-vous continuer ?');

Utilitaires et Composables exportés par la librairie

import { 
  defineCrudConfig, 
  useCrudConfig,
  useCrudContext,
  isActionVisibleInLocation, 
  interpolateUrl, 
  sanitizeBackUrl, 
  useTheme 
} from '@codifyo/vue-crud';

// 1. DX Helper pour l'autocomplétion TypeScript
const config = defineCrudConfig({ ... });

// 2. Accéder à la configuration CRUD courante depuis un sous-composant / slot :
const currentConfig = useCrudConfig();

// 3. Accéder aux méthodes de contexte CRUD depuis n'importe quel composant enfant :
const { refreshList, invalidateList, refreshPage, triggerAction } = useCrudContext() || {};

// 4. Tester la visibilité d'une action dans un emplacement
const isVisible = isActionVisibleInLocation(action, 'view', item);

// 5. Interpoler des variables dans un modèle d'URL
const url = interpolateUrl('/api/users/{id}/details', { id: 42 }); // => '/api/users/42/details'

// 6. Valider une URL de retour non fiable (query string) : même origine uniquement, sinon ''
const back = sanitizeBackUrl(params.get('backUrl') || ''); // 'javascript:alert(1)' => '', '//evil.com' => ''