@cnamts/synapse 1.0.2 → 1.0.3

package/src/stories/GuideDuDev/ClassesUtilitaires/DataUtilities.mdx

@@ -0,0 +1,318 @@
+import { Meta, Source } from '@storybook/addon-docs'
+
+<Meta title="Guide du dev/Classes utilitaires/Utilitaires de données" />
+
+# Utilitaires de données
+
+Ces utilitaires vous aident à manipuler et transformer des données dans vos applications.
+
+## deepCopy
+
+Cette fonction crée une copie profonde d'un objet ou d'un tableau, ce qui permet de dupliquer complètement une structure de données sans conserver de références à l'original.
+
+### Importation
+
+<Source dark code={`import { deepCopy } from '@cnamts/synpase'`}/>
+
+### Utilisation
+
+<Source dark code={`// Copie d'un objet simple
+const originalObject = { name: 'John', age: 30 }
+const copy = deepCopy(originalObject)
+
+// Modification de la copie sans affecter l'original
+copy.age = 31
+console.log(originalObject.age) // 30
+console.log(copy.age) // 31
+
+// Copie d'un objet complexe avec des objets imbriqués
+const complexObject = {
+  user: {
+    name: 'John',
+    settings: {
+      theme: 'dark',
+      notifications: true
+    }
+  },
+  permissions: ['read', 'write']
+}
+
+const complexCopy = deepCopy(complexObject)
+
+// Modification d'une propriété imbriquée
+complexCopy.user.settings.theme = 'light'
+console.log(complexObject.user.settings.theme) // 'dark'
+console.log(complexCopy.user.settings.theme) // 'light'
+`}/>
+
+### Exemple pratique
+
+<Source dark code={`<template>
+  <div>
+    <v-form @submit.prevent="saveForm">
+      <v-text-field
+        v-model="formData.name"
+        label="Nom"
+      />
+      
+      <v-select
+        v-model="formData.category"
+        :items="categories"
+        label="Catégorie"
+      />
+      
+      <v-checkbox
+      
+      <v-btn
+        @click="resetForm"
+        text
+      >
+        Réinitialiser
+      </v-btn>
+    </v-form>
+  </div>
+</template>
+
+<script>
+import { ref, reactive } from 'vue'
+import { deepCopy } from '@cnamts/synpase'
+
+export default {
+  props: {
+    initialData: {
+      type: Object,
+      default: () => ({
+        name: '',
+        category: null
+      })
+    }
+  },
+  
+  setup(props) {
+    // Créer une copie profonde des données initiales
+    const originalData = deepCopy(props.initialData)
+    
+    // Utiliser la copie pour initialiser le formulaire
+    const formData = reactive(deepCopy(originalData))
+    
+    const categories = ref(['Produit', 'Service', 'Autre'])
+    
+    // Réinitialiser le formulaire avec les données originales
+    const resetForm = () => {
+      Object.assign(formData, deepCopy(originalData))
+    }
+    
+    const saveForm = () => {
+      // Créer une copie des données du formulaire pour les envoyer
+      const dataToSubmit = deepCopy(formData)
+      
+      // Envoyer les données (simulation)
+      console.log('Données envoyées:', dataToSubmit)
+      
+      // Mettre à jour les données originales avec les nouvelles valeurs
+      Object.assign(originalData, deepCopy(formData))
+    }
+    
+    return {
+      formData,
+      categories,
+      resetForm,
+      saveForm
+    }
+  }
+}
+</script>`}/>
+### Cas d'utilisation courants
+
+#### 1. Sauvegarde de l'état initial
+
+<Source dark code={`import { deepCopy } from '@cnamts/synpase'
+
+export default {
+  setup() {
+    // État initial
+    const initialState = {
+      user: {
+        name: '',
+        email: '',
+        preferences: {
+          theme: 'light',
+          language: 'fr'
+        }
+      },
+      settings: {
+        notifications: true,
+        autoSave: false
+      }
+    }
+    
+    // Création d'une copie de travail
+    const state = reactive(deepCopy(initialState))
+    
+    // Fonction pour réinitialiser l'état
+    const resetState = () => {
+      Object.assign(state, deepCopy(initialState))
+    }
+    
+    return {
+      state,
+      resetState
+    }
+  }
+}`}/>
+
+#### 2. Comparaison avant/après
+
+<Source dark code={`import { deepCopy } from '@cnamts/synpase'
+
+export default {
+  props: {
+    record: {
+      type: Object,
+      required: true
+    }
+  },
+  setup(props) {
+    // Sauvegarde de l'état initial
+    const originalRecord = deepCopy(props.record)
+    
+    // Copie de travail
+    const workingCopy = reactive(deepCopy(props.record))
+    
+    // Vérification des modifications
+    const hasChanges = computed(() => {
+      // Comparaison simplifiée (dans un cas réel, utilisez une fonction de comparaison profonde)
+      return JSON.stringify(workingCopy) !== JSON.stringify(originalRecord)
+    })
+    
+    // Obtention des champs modifiés
+    const getModifiedFields = () => {
+      const modifiedFields = []
+      
+      // Parcours des propriétés de premier niveau
+      for (const key in workingCopy) {
+        if (JSON.stringify(workingCopy[key]) !== JSON.stringify(originalRecord[key])) {
+          modifiedFields.push(key)
+        }
+      }
+      
+      return modifiedFields
+    }
+    
+    return {
+      workingCopy,
+      hasChanges,
+      getModifiedFields
+    }
+  }
+}`}/>
+
+#### 3. Gestion d'un historique d'actions
+
+<Source dark code={`import { deepCopy } from '@cnamts/synpase'
+
+export default {
+  setup() {
+    // État actuel
+    const currentState = reactive({
+      title: 'Mon document',
+      content: 'Contenu initial',
+      tags: ['document', 'brouillon']
+    })
+    
+    // Historique des états
+    const history = ref([deepCopy(currentState)])
+    const historyIndex = ref(0)
+    
+    // Enregistrement d'un nouvel état
+    const saveState = () => {
+      // Suppression des états futurs si on a fait des annulations
+      if (historyIndex.value < history.value.length - 1) {
+        history.value = history.value.slice(0, historyIndex.value + 1)
+      }
+      
+      // Ajout de l'état actuel à l'historique
+      history.value.push(deepCopy(currentState))
+      historyIndex.value = history.value.length - 1
+    }
+    
+    // Annulation (undo)
+    const undo = () => {
+      if (historyIndex.value > 0) {
+        historyIndex.value--
+        Object.assign(currentState, deepCopy(history.value[historyIndex.value]))
+      }
+    }
+    
+    // Rétablissement (redo)
+    const redo = () => {
+      if (historyIndex.value < history.value.length - 1) {
+        historyIndex.value++
+        Object.assign(currentState, deepCopy(history.value[historyIndex.value]))
+      }
+    }
+    
+    return {
+      currentState,
+      saveState,
+      undo,
+      redo
+    }
+  }
+}`}/>
+
+## Bonnes pratiques
+
+### Quand utiliser deepCopy
+
+- Lorsque vous devez créer une copie indépendante d'un objet complexe
+- Pour sauvegarder l'état initial d'un formulaire ou d'une entité
+- Avant de modifier des objets reçus via des props
+- Pour implémenter des fonctionnalités d'annulation/rétablissement
+
+### Limitations
+
+- `deepCopy` peut être coûteux en performance pour de très grands objets
+- Certains types spéciaux (comme Map, Set, Date) peuvent nécessiter un traitement particulier
+- Les références circulaires peuvent causer des problèmes
+
+### Alternatives
+
+- Pour des copies simples d'objets plats : `{ ...object }`
+- Pour des tableaux simples : `[...array]`
+- Pour des cas plus complexes nécessitant des performances optimales, envisagez d'utiliser des bibliothèques spécialisées comme Immer ou Immutable.js
+
+### Exemple avec des types TypeScript
+
+<Source dark code={`interface User {
+  id: number;
+  name: string;
+  preferences: {
+    theme: 'light' | 'dark';
+    notifications: boolean;
+  };
+}
+
+import { deepCopy } from '@cnamts/synpase'
+
+// Fonction qui modifie une copie sans affecter l'original
+function updateUserTheme(user: User, newTheme: 'light' | 'dark'): User {
+  const userCopy = deepCopy(user)
+  userCopy.preferences.theme = newTheme
+  return userCopy
+}
+
+const originalUser: User = {
+  id: 1,
+  name: 'John',
+  preferences: {
+    theme: 'light',
+    notifications: true
+  }
+}
+
+const updatedUser = updateUserTheme(originalUser, 'dark')
+
+console.log(originalUser.preferences.theme) // 'light'
+console.log(updatedUser.preferences.theme) // 'dark'
+`}/>

package/src/stories/GuideDuDev/ClassesUtilitaires/DomBrowserUtilities.mdx

@@ -0,0 +1,344 @@
+import { Meta, Source } from '@storybook/addon-docs'
+
+<Meta title="Guide du dev/Classes utilitaires/Utilitaires DOM & Navigateur" />
+
+# Utilitaires DOM & Navigateur
+
+Ces utilitaires facilitent les interactions avec le DOM et le navigateur, comme la copie dans le presse-papier, le téléchargement de fichiers et l'optimisation des performances.
+
+## copyToClipboard
+
+Cette fonction permet de copier un texte dans le presse-papier de l'utilisateur.
+
+### Importation
+
+<Source dark code={`import { copyToClipboard } from '@cnamts/synpase'
+`}/>
+
+### Utilisation
+
+<Source dark code={`// Copier un texte simple
+copyToClipboard('Texte à copier')
+  .then(() => {
+    console.log('Texte copié avec succès')
+  })
+  .catch(error => {
+    console.error('Erreur lors de la copie', error)
+  })
+`}/>
+
+### Exemple pratique
+
+<Source dark code={`<template>
+  <div>
+    <v-text-field
+      v-model="referenceCode"
+      label="Code de référence"
+      readonly
+    />
+    <v-btn
+      icon
+      @click="copyCode"
+      :loading="isCopying"
+    >
+      <v-icon>mdi-content-copy</v-icon>
+    </v-btn>
+    <v-snackbar
+      v-model="showSnackbar"
+      :timeout="3000"
+    >
+      Code copié dans le presse-papier
+    </v-snackbar>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+import { copyToClipboard } from '@cnamts/synpase'
+
+export default {
+  setup() {
+    const referenceCode = ref('REF-12345-ABCDE')
+    const isCopying = ref(false)
+    const showSnackbar = ref(false)
+    
+    const copyCode = async () => {
+      isCopying.value = true
+      
+      try {
+        await copyToClipboard(referenceCode.value)
+        showSnackbar.value = true
+      } catch (error) {
+        console.error('Erreur lors de la copie', error)
+      } finally {
+        isCopying.value = false
+      }
+    }
+    
+    return {
+      referenceCode,
+      isCopying,
+      showSnackbar,
+      copyCode
+    }
+  }
+}
+</script>
+`}/>
+
+## downloadFile
+
+Cette fonction permet de télécharger un fichier à partir d'une URL ou d'un Blob.
+
+### Importation
+
+<Source dark code={`import { downloadFile } from '@cnamts/synpase'
+`}/>
+
+### Utilisation
+
+<Source dark code={`// Télécharger un fichier à partir d'une URL
+downloadFile('https://example.com/document.pdf', 'mon-document.pdf')
+
+// Télécharger un fichier à partir d'un Blob
+const blob = new Blob(['contenu du fichier'], { type: 'text/plain' })
+downloadFile(blob, 'mon-fichier.txt')
+`}/>
+
+### Exemple pratique
+
+<Source dark code={`<template>
+  <div>
+    <v-btn
+      color="primary"
+      @click="downloadReport"
+      :loading="isDownloading"
+    >
+      Télécharger le rapport
+    </v-btn>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+import { downloadFile } from '@cnamts/synpase'
+
+export default {
+  props: {
+    reportUrl: {
+      type: String,
+      required: true
+    },
+    reportName: {
+      type: String,
+      required: true
+    }
+  },
+  setup(props) {
+    const isDownloading = ref(false)
+    
+    const downloadReport = async () => {
+      isDownloading.value = true
+      
+      try {
+        await downloadFile(props.reportUrl, props.reportName)
+      } catch (error) {
+        console.error('Erreur lors du téléchargement', error)
+      } finally {
+        isDownloading.value = false
+      }
+    }
+    
+    return {
+      isDownloading,
+      downloadReport
+    }
+  }
+}
+</script>
+`}/>
+
+### Génération de fichiers à la volée
+
+Vous pouvez également générer des fichiers à la volée à partir de données :
+
+<Source dark code={`<template>
+  <v-btn @click="exportToCsv">Exporter en CSV</v-btn>
+</template>
+
+<script>
+import { downloadFile } from '@cnamts/synpase'
+
+export default {
+  props: {
+    data: {
+      type: Array,
+      required: true
+    }
+  },
+  setup(props) {
+    const exportToCsv = () => {
+      // Créer l'en-tête du CSV
+      const headers = Object.keys(props.data[0]).join(',')
+      
+      // Créer les lignes de données
+      const rows = props.data.map(item => 
+        Object.values(item).join(',')
+      )
+      
+      // Combiner en-tête et lignes
+      const csvContent = [headers, ...rows].join('\n')
+      
+      // Créer un Blob et télécharger
+      const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' })
+      downloadFile(blob, 'export.csv')
+    }
+    
+    return {
+      exportToCsv
+    }
+  }
+}
+</script>
+`}/>
+
+## throttleDisplayFn
+
+Cette fonction limite le nombre d'appels à une fonction d'affichage pour améliorer les performances, particulièrement utile pour les événements qui se déclenchent fréquemment comme le scroll ou le resize.
+
+### Importation
+
+<Source dark code={`import { throttleDisplayFn } from '@cnamts/synpase'
+`}/>
+
+### Utilisation
+
+<Source dark code={`// Fonction originale qui pourrait être appelée trop fréquemment
+const updateUI = () => {
+  // Mise à jour de l'interface utilisateur
+  console.log('Mise à jour de l\'UI')
+}
+
+// Création d'une version limitée de la fonction
+const throttledUpdateUI = throttleDisplayFn(updateUI)
+
+// Utilisation dans un événement qui se déclenche fréquemment
+window.addEventListener('scroll', throttledUpdateUI)
+`}/>
+
+### Exemple pratique
+
+<Source dark code={`<template>
+  <div>
+    <div class="scroll-container" ref="scrollContainer">
+      <div v-for="item in items" :key="item.id" class="item">
+        {{ item.name }}
+      </div>
+    </div>
+    <div v-if="showScrollIndicator" class="scroll-indicator">
+      Faites défiler pour voir plus
+    </div>
+  </div>
+</template>
+
+<script>
+import { ref, onMounted, onBeforeUnmount } from 'vue'
+import { throttleDisplayFn } from '@cnamts/synpase'
+
+export default {
+  props: {
+    items: {
+      type: Array,
+      required: true
+    }
+  },
+  setup() {
+    const scrollContainer = ref(null)
+    const showScrollIndicator = ref(true)
+    
+    const checkScroll = () => {
+      if (!scrollContainer.value) return
+      
+      const { scrollTop, scrollHeight, clientHeight } = scrollContainer.value
+      
+      // Masquer l'indicateur si l'utilisateur a défilé jusqu'à un certain point
+      if (scrollTop > 100 || scrollTop + clientHeight >= scrollHeight - 20) {
+        showScrollIndicator.value = false
+      } else {
+        showScrollIndicator.value = true
+      }
+    }
+    
+    // Utilisation de throttleDisplayFn pour limiter les appels
+    const throttledCheckScroll = throttleDisplayFn(checkScroll)
+    
+    onMounted(() => {
+      if (scrollContainer.value) {
+        scrollContainer.value.addEventListener('scroll', throttledCheckScroll)
+      }
+    })
+    
+    onBeforeUnmount(() => {
+      if (scrollContainer.value) {
+        scrollContainer.value.removeEventListener('scroll', throttledCheckScroll)
+      }
+    })
+    
+    return {
+      scrollContainer,
+      showScrollIndicator
+    }
+  }
+}
+</script>
+
+<style scoped>
+.scroll-container {
+  height: 300px;
+  overflow-y: auto;
+}
+
+.item {
+  padding: 16px;
+  border-bottom: 1px solid #eee;
+}
+
+.scroll-indicator {
+  position: fixed;
+  bottom: 20px;
+  right: 20px;
+  padding: 8px 16px;
+  background-color: rgba(0, 0, 0, 0.7);
+  color: white;
+  border-radius: 4px;
+  animation: pulse 2s infinite;
+}
+
+@keyframes pulse {
+  0% { opacity: 0.7; }
+  50% { opacity: 1; }
+  100% { opacity: 0.7; }
+}
+</style>
+`}/>
+
+## Bonnes pratiques
+
+### Pour copyToClipboard
+
+- Toujours gérer les erreurs potentielles avec try/catch ou .catch()
+- Fournir un retour visuel à l'utilisateur lorsque la copie est réussie
+- Vérifier que le texte à copier n'est pas vide ou null
+
+### Pour downloadFile
+
+- Utiliser des noms de fichiers descriptifs et incluant l'extension appropriée
+- Gérer les erreurs potentielles lors du téléchargement
+- Indiquer à l'utilisateur que le téléchargement est en cours (loading state)
+- Pour les fichiers générés côté client, utiliser le type MIME approprié
+
+### Pour throttleDisplayFn
+
+- Utiliser pour les événements à haute fréquence (scroll, resize, mousemove)
+- Ne pas l'utiliser pour des événements critiques nécessitant une réponse immédiate
+- Nettoyer les écouteurs d'événements dans onBeforeUnmount pour éviter les fuites de mémoire