@cnamts/synapse 1.0.2 → 1.0.3

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

@@ -0,0 +1,364 @@
+import { Meta, Source } from '@storybook/addon-docs'
+
+<Meta title="Guide du dev/Classes utilitaires/Utilitaires de validation" />
+
+# Utilitaires de validation
+
+Les utilitaires de validation vous permettent de vérifier la validité des données dans vos applications, notamment les dates et les emails.
+
+## propValidator
+
+Cette fonction facilite la validation des props dans les composants Vue.
+
+### Importation
+
+<Source dark code={`import { propValidator } from '@cnamts/synpase'
+`}/>
+
+### Utilisation
+
+<Source dark code={`export default {
+  props: {
+    // Valider une prop avec des valeurs spécifiques
+    size: {
+      type: String,
+      validator: propValidator('size', ['small', 'medium', 'large'])
+    },
+    
+    // Valider une prop avec des valeurs numériques
+    priority: {
+      type: Number,
+      validator: propValidator('priority', [1, 2, 3, 4, 5])
+    }
+  }
+}
+`}/>
+
+### Exemple pratique
+
+<Source dark code={`<template>
+  <div :class="\`button-\${size}\`">
+    <slot />
+  </div>
+</template>
+
+<script>
+import { propValidator } from '@cnamts/synpase'
+
+export default {
+  name: 'CustomButton',
+  props: {
+    size: {
+      type: String,
+      default: 'medium',
+      validator: propValidator('size', ['small', 'medium', 'large'])
+    },
+    variant: {
+      type: String,
+      default: 'primary',
+      validator: propValidator('variant', ['primary', 'secondary', 'outline', 'text'])
+    }
+  }
+}
+</script>
+`}/>
+
+## ruleMessage
+
+Cette fonction génère un message d'erreur formaté pour les règles de validation.
+
+### Importation
+
+<Source dark code={`import { ruleMessage } from '@cnamts/synpase'
+`}/>
+
+### Utilisation
+
+<Source dark code={`// Message simple
+ruleMessage('Ce champ est requis') // 'Ce champ est requis'
+
+// Message avec nom de champ
+ruleMessage('Ce champ est requis', 'Email') // 'Email : Ce champ est requis'
+`}/>
+
+### Exemple pratique
+
+<Source dark code={`<template>
+  <v-form ref="form">
+    <v-text-field
+      v-model="email"
+      label="Email"
+      :rules="emailRules"
+    />
+    <v-text-field
+      v-model="password"
+      label="Mot de passe"
+      type="password"
+      :rules="passwordRules"
+    />
+  </v-form>
+</template>
+
+<script>
+import { ref } from 'vue'
+import { ruleMessage } from '@cnamts/synpase'
+
+export default {
+  setup() {
+    const email = ref('')
+    const password = ref('')
+    
+    const emailRules = [
+      v => !!v || ruleMessage('Ce champ est requis', 'Email'),
+      v => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v) || ruleMessage('Format d\'email invalide', 'Email')
+    ]
+    
+    const passwordRules = [
+      v => !!v || ruleMessage('Ce champ est requis', 'Mot de passe'),
+      v => v.length >= 8 || ruleMessage('Le mot de passe doit contenir au moins 8 caractères', 'Mot de passe')
+    ]
+    
+    return {
+      email,
+      password,
+      emailRules,
+      passwordRules
+    }
+  }
+}
+</script>
+`}/>
+
+## Validation de dates
+
+### isDateAfter
+
+Vérifie si une date est postérieure à une autre date.
+
+#### Importation
+
+<Source dark code={`import { isDateAfter } from '@cnamts/synpase'
+`}/>
+
+#### Utilisation
+
+<Source dark code={`// Avec des chaînes de dates (format DD/MM/YYYY)
+isDateAfter('15/02/2023', '10/02/2023') // true
+isDateAfter('10/02/2023', '15/02/2023') // false
+ `}/>
+
+<Source dark code={`// Avec des objets Date
+isDateAfter(new Date('2023-02-15'), new Date('2023-02-10')) // true
+`}/>
+
+### isDateBefore
+
+Vérifie si une date est antérieure à une autre date.
+
+#### Importation
+
+<Source dark code={`import { isDateBefore } from '@cnamts/synpase'
+`}/>
+
+#### Utilisation
+
+<Source dark code={`// Avec des chaînes de dates (format DD/MM/YYYY)
+isDateBefore('10/02/2023', '15/02/2023') // true
+isDateBefore('15/02/2023', '10/02/2023') // false
+
+// Avec des objets Date
+isDateBefore(new Date('2023-02-10'), new Date('2023-02-15')) // true
+`}/>
+
+### isDateInRange
+
+Vérifie si une date est comprise dans une plage de dates.
+
+#### Importation
+
+<Source dark code={`import { isDateInRange } from '@cnamts/synpase'
+`}/>
+
+#### Utilisation
+
+<Source dark code={`// Avec des chaînes de dates (format DD/MM/YYYY)
+isDateInRange('15/02/2023', '10/02/2023', '20/02/2023') // true
+isDateInRange('05/02/2023', '10/02/2023', '20/02/2023') // false
+
+// Avec des objets Date
+isDateInRange(
+  new Date('2023-02-15'),
+  new Date('2023-02-10'),
+  new Date('2023-02-20')
+) // true
+`}/>
+
+### isDateValidUtil
+
+Vérifie si une chaîne de date est valide.
+
+#### Importation
+
+<Source dark code={`import { isDateValidUtil } from '@cnamts/synpase'
+`}/>
+
+#### Utilisation
+
+<Source dark code={`// Dates valides
+isDateValidUtil('15/02/2023') // true
+isDateValidUtil('2023-02-15') // true
+
+// Dates invalides
+isDateValidUtil('31/02/2023') // false (février n'a pas 31 jours)
+isDateValidUtil('date invalide') // false
+`}/>
+
+### isWeekend
+
+Vérifie si une date correspond à un jour de week-end (samedi ou dimanche).
+
+#### Importation
+
+<Source dark code={`import { isWeekend } from '@cnamts/synpase'
+`}/>
+
+#### Utilisation
+
+<Source dark code={`// Avec des objets Date
+isWeekend(new Date('2023-02-18')) // true (samedi)
+isWeekend(new Date('2023-02-19')) // true (dimanche)
+isWeekend(new Date('2023-02-20')) // false (lundi)
+
+// Avec des chaînes de dates (format DD/MM/YYYY)
+isWeekend('18/02/2023') // true (samedi)
+`}/>
+
+## Validation d'email
+
+### isEmailValid
+
+Vérifie si une chaîne est un email valide.
+
+#### Importation
+
+<Source dark code={`import { isEmailValid } from '@cnamts/synpase'
+`}/>
+
+#### Utilisation
+
+<Source dark code={`// Emails valides
+isEmailValid('user@example.com') // true
+isEmailValid('user.name+tag@example.co.uk') // true
+
+// Emails invalides
+isEmailValid('invalid-email') // false
+isEmailValid('user@') // false
+`}/>
+
+## Exemple pratique complet
+
+Voici un exemple de formulaire utilisant plusieurs utilitaires de validation :
+
+<Source dark code={`<template>
+  <v-form ref="form" v-model="isFormValid">
+    <v-text-field
+      v-model="formData.email"
+      label="Email"
+      :rules="emailRules"
+    />
+    
+    <v-text-field
+      v-model="formData.startDate"
+      label="Date de début"
+      placeholder="JJ/MM/AAAA"
+      :rules="startDateRules"
+    />
+    
+    <v-text-field
+      v-model="formData.endDate"
+      label="Date de fin"
+      placeholder="JJ/MM/AAAA"
+      :rules="endDateRules"
+    />
+    
+    <v-btn
+      color="primary"
+      :disabled="!isFormValid"
+      @click="submitForm"
+    >
+      Valider
+    </v-btn>
+  </v-form>
+</template>
+
+<script>
+import { ref, reactive, computed } from 'vue'
+import {
+  isEmailValid,
+  isDateValidUtil,
+  isDateAfter,
+  isWeekend,
+  ruleMessage
+} from '@cnamts/synpase'
+
+export default {
+  setup() {
+    const form = ref(null)
+    const isFormValid = ref(false)
+    
+    const formData = reactive({
+      email: '',
+      startDate: '',
+      endDate: ''
+    })
+    
+    // Règles de validation pour l'email
+    const emailRules = [
+      v => !!v || ruleMessage('Ce champ est requis', 'Email'),
+      v => isEmailValid(v) || ruleMessage('Format d\'email invalide', 'Email')
+    ]
+    
+    // Règles de validation pour la date de début
+    const startDateRules = [
+      v => !!v || ruleMessage('Ce champ est requis', 'Date de début'),
+      v => isDateValidUtil(v) || ruleMessage('Format de date invalide (JJ/MM/AAAA)', 'Date de début'),
+      v => !isWeekend(v) || ruleMessage('La date ne peut pas être un week-end', 'Date de début')
+    ]
+    
+    // Règles de validation pour la date de fin
+    const endDateRules = computed(() => [
+      v => !!v || ruleMessage('Ce champ est requis', 'Date de fin'),
+      v => isDateValidUtil(v) || ruleMessage('Format de date invalide (JJ/MM/AAAA)', 'Date de fin'),
+      v => !isWeekend(v) || ruleMessage('La date ne peut pas être un week-end', 'Date de fin'),
+      v => !formData.startDate || !v || isDateAfter(v, formData.startDate) || 
+        ruleMessage('La date de fin doit être postérieure à la date de début', 'Date de fin')
+    ])
+    
+    const submitForm = () => {
+      if (form.value.validate()) {
+        // Traitement du formulaire
+        console.log('Formulaire valide', formData)
+      }
+    }
+    
+    return {
+      form,
+      isFormValid,
+      formData,
+      emailRules,
+      startDateRules,
+      endDateRules,
+      submitForm
+    }
+  }
+}
+</script>
+`}/>
+
+## Bonnes pratiques
+
+- Utilisez `propValidator` pour valider les props de vos composants avec des valeurs spécifiques
+- Utilisez `ruleMessage` pour créer des messages d'erreur cohérents dans vos formulaires
+- Combinez les différentes fonctions de validation pour créer des règles de validation complexes
+- Validez toujours les dates avant de les utiliser dans des calculs ou des comparaisons
+- Pour les validations de formulaire plus complexes, envisagez d'utiliser les règles de validation fournies par le Design System

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

@@ -0,0 +1,292 @@
+import { Meta, Source } from '@storybook/addon-docs'
+
+<Meta title="Guide du dev/Classes utilitaires" />
+
+# Classes utilitaires
+
+Le Design System fournit un ensemble de fonctions utilitaires pour faciliter le développement d'applications. Ces fonctions sont regroupées par catégories et peuvent être importées individuellement selon vos besoins.
+
+## Sommaire
+
+- [Utilitaires de stockage](#utilitaires-de-stockage)
+- [Utilitaires de formatage](#utilitaires-de-formatage)
+- [Utilitaires de validation](#utilitaires-de-validation)
+- [Utilitaires DOM & Navigateur](#utilitaires-dom--navigateur)
+- [Utilitaires de données](#utilitaires-de-données)
+- [Règles de validation](#règles-de-validation)
+
+## Utilitaires de stockage
+
+### LocalStorageUtility
+
+Classe utilitaire pour manipuler le localStorage avec gestion des préfixes et de la sérialisation.
+
+<Source dark code={`import { LocalStorageUtility } from '@cnamts/synpase'
+
+// Création d'une instance avec un préfixe
+const storage = new LocalStorageUtility('my-app')
+
+// Stocker une valeur
+storage.setItem('user', { name: 'John', role: 'admin' })
+
+// Récupérer une valeur
+const user = storage.getItem('user')
+console.log(user) // { name: 'John', role: 'admin' }
+
+// Supprimer une valeur
+storage.removeItem('user')
+
+// Vérifier si une clé existe
+const hasUser = storage.hasItem('user')
+console.log(hasUser) // false
+
+// Effacer toutes les valeurs avec le préfixe
+storage.clear()
+`}/>
+
+## Utilitaires de formatage
+
+### calcHumanFileSize
+
+Convertit une taille en octets en une chaîne de caractères lisible par un humain.
+
+<Source dark code={`import { calcHumanFileSize } from '@cnamts/synpase'
+
+console.log(calcHumanFileSize(1024)) // '1 Ko'
+console.log(calcHumanFileSize(1048576)) // '1 Mo'
+console.log(calcHumanFileSize(1073741824)) // '1 Go'
+`}/>
+
+### convertToUnit
+
+Convertit une valeur en unité CSS (px, em, rem, etc.).
+
+<Source dark code={`import { convertToUnit } from '@cnamts/synpase'
+
+console.log(convertToUnit(16)) // '16px'
+console.log(convertToUnit('16')) // '16px'
+console.log(convertToUnit('16px')) // '16px'
+console.log(convertToUnit('2rem')) // '2rem'
+console.log(convertToUnit(null)) // undefined
+`}/>
+
+### formatDate
+
+Formate une date selon un format spécifique.
+
+<Source dark code={`import { formatDate } from '@cnamts/synpase'
+
+const date = new Date('2023-01-15')
+
+console.log(formatDate(date)) // '15/01/2023'
+console.log(formatDate(date, 'DD/MM/YYYY HH:mm')) // '15/01/2023 00:00'
+console.log(formatDate('2023-01-15')) // '15/01/2023'
+`}/>
+
+### parseDate
+
+Parse une chaîne de caractères en objet Date.
+
+<Source dark code={`import { parseDate } from '@cnamts/synpase'
+
+console.log(parseDate('15/01/2023').toISOString()) // '2023-01-15T00:00:00.000Z'
+console.log(parseDate('2023-01-15').toISOString()) // '2023-01-15T00:00:00.000Z'
+`}/>
+
+## Utilitaires de validation
+
+### propValidator
+
+Valide les props d'un composant Vue.
+
+<Source dark code={`import { propValidator } from '@cnamts/synpase'
+
+export default {
+  props: {
+    size: {
+      type: String,
+      validator: propValidator('size', ['small', 'medium', 'large'])
+    }
+  }
+}
+`}/>
+
+### ruleMessage
+
+Génère un message d'erreur pour les règles de validation.
+
+<Source dark code={`import { ruleMessage } from '@cnamts/synpase'
+
+const message = ruleMessage('Ce champ est requis')
+console.log(message) // 'Ce champ est requis'
+
+// Avec un nom de champ
+const fieldMessage = ruleMessage('Ce champ est requis', 'Email')
+console.log(fieldMessage) // 'Email : Ce champ est requis'
+`}/>
+
+### Validation de dates
+
+<Source dark code={`import { 
+  isDateAfter,
+  isDateBefore,
+  isDateInRange,
+  isDateValidUtil,
+  isWeekend
+} from '@cnamts/synpase'
+
+// Vérifier si une date est après une autre
+console.log(isDateAfter('15/02/2023', '10/02/2023')) // true
+
+// Vérifier si une date est avant une autre
+console.log(isDateBefore('10/02/2023', '15/02/2023')) // true
+
+// Vérifier si une date est dans une plage
+console.log(isDateInRange('15/02/2023', '10/02/2023', '20/02/2023')) // true
+
+// Vérifier si une date est valide
+console.log(isDateValidUtil('15/02/2023')) // true
+console.log(isDateValidUtil('31/02/2023')) // false (février n'a pas 31 jours)
+
+// Vérifier si une date est un week-end
+console.log(isWeekend(new Date('2023-02-18'))) // true (samedi)
+console.log(isWeekend(new Date('2023-02-19'))) // true (dimanche)
+console.log(isWeekend(new Date('2023-02-20'))) // false (lundi)
+`}/>
+
+### Validation d'email
+
+<Source dark code={`import { isEmailValid } from '@cnamts/synpase'
+
+console.log(isEmailValid('user@example.com')) // true
+console.log(isEmailValid('invalid-email')) // false
+`}/>
+
+## Utilitaires DOM & Navigateur
+
+### copyToClipboard
+
+Copie un texte dans le presse-papier.
+
+<Source dark code={`import { copyToClipboard } from '@cnamts/synpase'
+
+// Copier un texte dans le presse-papier
+copyToClipboard('Texte à copier')
+  .then(() => console.log('Texte copié avec succès'))
+  .catch(error => console.error('Erreur lors de la copie', error))
+`}/>
+
+### downloadFile
+
+Télécharge un fichier à partir d'une URL ou d'un Blob.
+
+<Source dark code={`import { downloadFile } from '@cnamts/synpase'
+
+// 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')
+`}/>
+
+### throttleDisplayFn
+
+Limite le nombre d'appels à une fonction d'affichage pour améliorer les performances.
+
+<Source dark code={`import { throttleDisplayFn } from '@cnamts/synpase'
+
+// Fonction originale qui pourrait être appelée trop fréquemment
+const updateUI = () => {
+  // Mise à jour coûteuse de l'interface
+}
+
+// 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)
+`}/>
+
+## Utilitaires de données
+
+### deepCopy
+
+Crée une copie profonde d'un objet.
+
+<Source dark code={`import { deepCopy } from '@cnamts/synpase'
+
+const originalObject = {
+  user: {
+    name: 'John',
+    settings: {
+      theme: 'dark',
+      notifications: true
+    }
+  }
+}
+
+const copy = deepCopy(originalObject)
+
+// Modifier la copie n'affecte pas l'original
+copy.user.settings.theme = 'light'
+console.log(originalObject.user.settings.theme) // 'dark'
+`}/>
+
+## Règles de validation
+
+Le Design System fournit également un ensemble de règles de validation prêtes à l'emploi pour les formulaires Vuetify.
+
+<Source dark code={`import { 
+  doMatchPattern,
+  isDateValid,
+  isExactLength,
+  isHolidayDay,
+  isMaxLength,
+  isMinLength,
+  isNotAfterDate,
+  isNotAfterToday,
+  isNotBeforeDate,
+  isNotBeforeToday,
+  isRequired,
+  isValidEmail
+} from '@cnamts/synpase'
+
+export default {
+  setup() {
+    // Exemple d'utilisation dans un formulaire
+    const form = ref({
+      email: '',
+      password: '',
+      birthDate: ''
+    })
+
+    const rules = {
+      email: [
+        isRequired(),
+        isValidEmail()
+      ],
+      password: [
+        isRequired(),
+        isMinLength(8),
+        isMaxLength(20),
+        doMatchPattern(/^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]+$/, 
+          'Le mot de passe doit contenir au moins une majuscule, une minuscule, un chiffre et un caractère spécial')
+      ],
+      birthDate: [
+        isRequired(),
+        isDateValid(),
+        isNotAfterToday(),
+        v => !isHolidayDay(v) || 'La date ne peut pas être un jour férié'
+      ]
+    }
+
+    return {
+      form,
+      rules
+    }
+  }
+}
+`}/>
+
+Pour plus de détails sur l'utilisation des règles, consultez la [documentation des règles de validation](?path=/docs/guide-du-dev-r%C3%A8gles-de-validation-les-r%C3%A8gles-de-validation--docs).