Guide d'Intégration IA : Librairie CrudPage

Ce document explique à une IA comment implémenter et utiliser la librairie CrudPage dans un projet Vue 3 cible.

1. Installation et Importation

La librairie s'installe via NPM. Elle inclut ses propres types.

npm install @codifyo/vue-crud

Dans un composant Vue 3 (Composition API) de l'application cliente :

<script setup lang="ts">
import { CrudPage, type CrudConfig } from '@codifyo/vue-crud';
import '@codifyo/vue-crud/dist/style.css'; // Si des styles personnalisés existent
import MyCustomFormComponent from '@/components/MyCustomFormComponent.vue';
</script>

<template>
  <!-- Le composant de formulaire est passé via un slot dynamique ou via injection globale -->
  <CrudPage :config="config">
    <template #form="{ formConfig, modelValue, updateModelValue }">
      <MyCustomFormComponent 
        :config="formConfig"
        :modelValue="modelValue"
        @update:modelValue="updateModelValue"
      />
    </template>
  </CrudPage>
</template>

2. Configuration d'une Instance (CrudConfig)

Voici comment définir un objet de configuration complet. L'IA doit utiliser les types exportés pour s'assurer de respecter la signature attendue.

const config: CrudConfig = {
  title: 'Gestion des Clients',
  itemName: 'Client',
  
  // 1. Fonctions API (Doivent retourner des Promises)
  api: {
    fetchList: async (params) => {
      // params contient : page, limit, sort, dir, filters
      const response = await api.get('/clients', { params });
      // Doit retourner { data: Array, total: number }
      return { data: response.data.items, total: response.data.total };
    },
    delete: async (id) => await api.delete(`/clients/${id}`),
    // update: ..., create: ...
  },

  // 2. Colonnes
  columns: [
    { key: 'id', label: 'ID', sortable: true },
    { key: 'name', label: 'Nom Complet', sortable: true },
    { key: 'status', label: 'Statut', type: 'badge' },
    { key: 'createdAt', label: 'Date', type: 'date' }
  ],

  // 3. Configurations des formulaires (Transmises au MyCustomFormComponent)
  filterFormConfig: { /* Structure propre au composant de l'application parente */ },
  editFormConfig: { /* Structure propre au composant de l'application parente */ },

  // 4. Actions
  actions: {
    global: [
      { name: 'create', label: 'Nouveau', displayMode: 'modal', style: 'primary', trackInUrl: true }
    ],
    item: [
      { name: 'edit', label: 'Modifier', displayMode: 'page', trackInUrl: true },
      { name: 'delete', label: 'Supprimer', style: 'danger', confirm: true, displayMode: 'none', 
        handler: async ({ item }) => {
          await api.delete(`/clients/${item.id}`);
        }
      }
    ]
  },
  
  options: {
    perPage: 20,
    syncUrl: true // Conserve pagination et filtres dans l'URL (?page=2&sort=name...)
  }
};

3. Particularités Importantes (Tips pour IA)

• trackInUrl : Si une action (ex: edit) a l'option trackInUrl: true, le CrudPage changera l'URL en ?action=edit&id=123. Cela rend l'état copiable/collable. CrudPage gère lui-même la lecture de cette URL au montage pour réafficher directement le formulaire.
• Filtres dans les actions : Le handler d'une action reçoit toujours { item?, ids?, formData?, filters?, sort?, dir? } (état de la liste au clic). En JSON, includeFilters: true ajoute sort, dir et filters[...] à la query string de la requête de l'action (globale, bulk, form ou view), quelle que soit la méthode HTTP ; une action bulk confirm envoie aussi ids[].
• Skeletons : La librairie gère les indicateurs de chargement (skeletons Bootstrap) de manière autonome lorsqu'elle attend la résolution de la promesse fetchList. L'IA n'a pas besoin de gérer de isLoading dans le parent.
• Composant Externe : Le CRUD n'essaie pas de réinventer la roue des champs de formulaires complexes (DatePicker complexes, Select multiples avec recherche, etc.). Il délègue cela au composant spécifié dans les slots. Le rôle de l'IA utilisant cette librairie est de mapper correctement les props formConfig au système de formulaire existant dans l'application cible.