@cnamts/synapse 0.0.11-alpha → 0.0.13-alpha

package/src/stories/GuideDuDev/UtiliserLesRules.mdx

@@ -1,108 +1,351 @@
-import {Meta, Source} from '@storybook/addon-docs/blocks';
+import { Meta, Source } from '@storybook/addon-docs/blocks';
 
-<Meta title="Guide Du Dev/Utiliser les rules"/>
+<Meta title="Guide Du Dev/Utiliser le système de validation"/>
 
-# Utiliser les règles de validation
+# Utiliser le système de validation
 
-Ce guide décrit comment utiliser le composable `useFieldValidation` pour créer des règles de validation flexibles et personnalisées dans votre projet Vue.js.
+Ce guide décrit comment utiliser le système de validation de formulaires du Design System pour créer des validations flexibles et intuitives.
 
 ## Introduction
 
-Le composable `useFieldValidation` vous permet de définir des règles de validation dynamiques pour différents champs dans vos formulaires. Ce composable est conçu pour être flexible, réutilisable et facilement intégrable avec des bibliothèques comme Vuetify.
+Le système de validation repose sur deux composables principaux :
+- `useFieldValidation` : Gère la création des règles de validation
+- `useValidation` : Gère l'état de validation et l'affichage des messages
+
+## Les 3 types de validation
+
+Notre système supporte trois types de retours de validation :
+
+1. **Erreurs** (rouge 🔴) : Bloquent la soumission du formulaire
+2. **Avertissements** (orange 🟠) : Informent l'utilisateur sans bloquer
+3. **Succès** (vert 🟢) : Confirment la validité du champ
+
+### Priorité des validations
+
+Les validations suivent un ordre de priorité :
+1. Si une erreur est présente, elle est affichée en priorité
+2. S'il n'y a pas d'erreur mais des avertissements, ils sont affichés
+3. S'il n'y a ni erreur ni avertissement, les messages de succès sont affichés
+
+## Structure des types
+
+### Type `ValidationOptions`
+
+Options de configuration pour la validation :
+
+<Source dark code={`
+interface ValidationOptions {
+  showSuccessMessages?: boolean;  // Activer/désactiver les messages de succès
+  fieldIdentifier?: string;       // Nom du champ pour les messages
+  customRules?: ValidationRule[]; // Règles personnalisées
+  warningRules?: ValidationRule[]; // Règles d'avertissement
+  successRules?: ValidationRule[]; // Règles de succès
+}
+`}/>
+
+### Type `ValidationRule`
+
+Structure d'une règle de validation :
+
+<Source dark code={`
+type ValidationRule = {
+  type: string;     // Type de règle (ex: 'required', 'email')
+  options: RuleOptions;
+}
+`}/>
 
-## Structure du composable
-#
 ### Type `RuleOptions`
 
+Options disponibles pour configurer une règle :
+
 <Source dark code={`
-type RuleOptions = {
-  fieldName?: string; // Nom du champ utilisé dans les messages d'erreur
-  message?: string; // Message personnalisé pour la règle
-  successMessage?: string; // Message personnalisé de validation réussie
-  length?: number; // Longueur minimale ou maximale
-  value?: number; // Valeur minimale ou maximale
-  pattern?: RegExp; // Motif à valider
-  ignoreSpace?: boolean; // Ignorer les espaces lors de la validation de longueur
+interface RuleOptions {
+  message?: string;         // Message d'erreur personnalisé
+  successMessage?: string;  // Message de succès personnalisé
+  warningMessage?: string;  // Message d'avertissement personnalisé
+  fieldName?: string;      // Nom du champ pour les messages
+  fieldIdentifier?: string; // Identifiant du champ
+  value?: any;             // Valeur pour les règles min/max
+  length?: number;         // Longueur pour minLength/maxLength
+  pattern?: RegExp;        // Expression régulière
+  ignoreSpace?: boolean;   // Ignorer les espaces
+  isWarning?: boolean;     // Traiter comme un avertissement
   validate?: (value: any) => boolean | string; // Validation personnalisée
-};
-`}
-/>
+}
+`}/>
+
+## Exemple complet d'utilisation
+
+### Avec un input simple
+
+Voici un exemple complet montrant les différentes possibilités de validation :
+
+<Source dark code={`
+<script lang="ts" setup>
+import { ref } from 'vue'
+import { useValidation } from '@cnamts/synapse'
+
+const password = ref('')
+
+const { validateField, hasError, hasWarning, hasSuccess, errors, warnings, successes } = useValidation({
+  fieldIdentifier: 'Mot de passe',
+  showSuccessMessages: true
+})
+
+// Règles d'erreur (bloquantes)
+const errorRules = [
+  { 
+    type: 'required',
+    options: { message: 'Le mot de passe est requis' }
+  },
+  { 
+    type: 'minLength',
+    options: { length: 6, message: 'Le mot de passe doit contenir au moins 6 caractères' }
+  }
+]
+
+// Règles d'avertissement (non-bloquantes)
+const warningRules = [
+  {
+    type: 'minLength',
+    options: { 
+      length: 8,
+      warningMessage: 'Un mot de passe de 8 caractères minimum est recommandé'
+    }
+  }
+]
 
-### Type `ValidationResult`
+// Règles de succès (messages positifs)
+const successRules = [
+  {
+    type: 'minLength',
+    options: { 
+      length: 12,
+      successMessage: 'Excellent ! Votre mot de passe est très sécurisé'
+    }
+  }
+]
+
+const validate = () => {
+  const result = validateField(
+    password.value,
+    errorRules,
+    warningRules,
+    successRules
+  )
+  
+  // result contient :
+  // - hasError: boolean
+  // - hasWarning: boolean
+  // - hasSuccess: boolean
+  // - state: { errors, warnings, successes }
+}
+</script>
+
+<template>
+  <div>
+    <input 
+      v-model="password"
+      @input="validate"
+      :class="{ 
+        'error': hasError,
+        'warning': hasWarning && !hasError,
+        'success': hasSuccess
+      }"
+    />
+    
+    <!-- Affichage des messages -->
+    <div v-if="hasError" class="error-messages">
+      <p v-for="error in errors" :key="error">{{ error }}</p>
+    </div>
+    
+    <div v-else-if="hasWarning" class="warning-messages">
+      <p v-for="warning in warnings" :key="warning">{{ warning }}</p>
+    </div>
+    
+    <div v-else-if="hasSuccess" class="success-messages">
+      <p v-for="success in successes" :key="success">{{ success }}</p>
+    </div>
+  </div>
+</template>
+`}/>
+
+### Avec SyTextField
+
+Le `SyTextField` intègre nativement notre système de validation. Voici un exemple complet :
 
 <Source dark code={`
-type ValidationResult = {
-  success?: string; // Message de validation réussie
-  error?: string; // Message d'erreur
-};
-`}
-/>
+<script lang="ts" setup>
+import { ref } from 'vue'
+import { SyTextField } from '@cnamts/synapse'
 
-## Exemple d'intégration
+const password = ref('')
+
+// Règles d'erreur (bloquantes)
+const rules = [
+  { 
+    type: 'required',
+    options: { message: 'Le mot de passe est requis' }
+  },
+  { 
+    type: 'minLength',
+    options: { length: 6, message: 'Le mot de passe doit contenir au moins 6 caractères' }
+  }
+]
+
+// Règles d'avertissement (non-bloquantes)
+const warningRules = [
+  {
+    type: 'minLength',
+    options: { 
+      length: 8,
+      warningMessage: 'Un mot de passe de 8 caractères minimum est recommandé'
+    }
+  }
+]
+
+// Règles de succès (messages positifs)
+const successRules = [
+  {
+    type: 'minLength',
+    options: { 
+      length: 12,
+      successMessage: 'Excellent ! Votre mot de passe est très sécurisé'
+    }
+  }
+]
+</script>
 
-### Script Vue.js
+<template>
+  <SyTextField
+    v-model="password"
+    label="Mot de passe"
+    type="password"
+    :customRules="rules"
+    :customWarningRules="warningRules"
+    :customSuccessRules="successRules"
+    placeholder="Entrez votre mot de passe"
+  />
+</template>
+`}/>
+
+Le composant affichera automatiquement :
+- Une icône et un message d'erreur en rouge si le champ est vide ou contient moins de 6 caractères
+- Une icône et un message d'avertissement en orange si le mot de passe fait entre 6 et 8 caractères
+- Une icône et un message de succès en vert si le mot de passe fait 12 caractères ou plus
+
+### Validation personnalisée avec SyTextField
+
+Voici un exemple plus avancé avec une validation personnalisée :
 
 <Source dark code={`
 <script lang="ts" setup>
-import { ref } from 'vue';
-import { useFieldValidation } from '@cnamts/synapse';
-
-const { generateRules } = useFieldValidation();
-
-const firstName = ref('');
-const email = ref('');
-const age = ref('');
-
-const rules = {
-  firstName: generateRules([
-    { type: 'required', options: { message: 'Ce champ est requis.' } },
-    { type: 'minLength', options: { length: 3, ignoreSpace: true } },
-    { type: 'maxLength', options: { length: 20 } },
-  ]),
-  email: generateRules([
-    { type: 'required', options: { fieldName: 'Email' } },
-    { type: 'email' },
-  ]),
-  age: generateRules([
-    { type: 'min', options: { value: 18 } },
-    { type: 'max', options: { value: 99 } },
-  ]),
-};
-
-const validateField = (field: string) => {
-  return rules[field].every((rule) => rule(field));
-};
-
-const handleSubmit = () => {
-  if (validateField('firstName') && validateField('email') && validateField('age')) {
-    alert('Formulaire valide.');
-  } else {
-    alert('Merci de vérifier les champs.');
+import { ref } from 'vue'
+import { SyTextField } from '@cnamts/synapse'
+
+const email = ref('')
+
+// Règle personnalisée pour vérifier le domaine ameli.fr
+const rules = [
+  { 
+    type: 'required',
+    options: { message: 'L\'email est requis' }
+  },
+  { 
+    type: 'email',
+    options: { message: 'Format d\'email invalide' }
+  },
+  {
+    type: 'custom',
+    options: {
+      validate: (value: string) => {
+        if (!value.endsWith('@ameli.fr')) {
+          return 'L\'email doit être un email ameli.fr'
+        }
+        return true
+      }
+    }
+  }
+]
+
+// Règle d'avertissement pour le format prénom.nom
+const warningRules = [
+  {
+    type: 'custom',
+    options: {
+      validate: (value: string) => {
+        const [localPart] = value.split('@')
+        if (!/^[a-z]+\.[a-z]+$/.test(localPart)) {
+          return 'Format recommandé : prenom.nom@ameli.fr'
+        }
+        return true
+      },
+      isWarning: true
+    }
   }
-};
+]
 </script>
-`}
-/>
 
-Vous pouvez retrouver un exemple complet sur le [NirField](/docs/composants-formulaires-nirfield--docs).
+<template>
+  <SyTextField
+    v-model="email"
+    label="Email professionnel"
+    :customRules="rules"
+    :customWarningRules="warningRules"
+    placeholder="prenom.nom@ameli.fr"
+  />
+</template>
+`}/>
 
-## Fonctionnalités supportées
+Dans cet exemple :
+- Le champ est invalide si l'email n'est pas au format @ameli.fr
+- Un avertissement s'affiche si l'email ne suit pas le format prenom.nom
+- La validation se fait automatiquement à la perte du focus
+- Les icônes et couleurs sont gérées automatiquement par le composant
 
-- **Validation requise** (`required`) : Assurez-vous qu'un champ est rempli.
-- **Longueur minimale** (`minLength`) : Validez un champ avec un nombre minimal de caractères.
-- **Longueur maximale** (`maxLength`) : Limitez un champ à un nombre maximal de caractères.
-- **Valeur minimale** (`min`) : Assurez-vous que la valeur est au moins égale à une valeur définie.
-- **Valeur maximale** (`max`) : Assurez-vous que la valeur ne dépasse pas une valeur définie.
-- **Validation par motif** (`matchPattern`) : Validez un champ à l'aide d'une expression régulière.
-- **Validation d'email** (`email`) : Assurez-vous que la valeur est une adresse email valide.
-- **Validation personnalisée** (`custom`) : Implémentez des règles spécifiques via une fonction.
+## Règles de validation disponibles
+
+- **required** : Vérifie qu'un champ est rempli
+- **email** : Valide le format d'une adresse email
+- **minLength** : Vérifie une longueur minimale
+- **maxLength** : Vérifie une longueur maximale
+- **min** : Vérifie une valeur minimale (nombre)
+- **max** : Vérifie une valeur maximale (nombre)
+- **pattern** : Valide avec une expression régulière
+- **custom** : Validation personnalisée via une fonction
 
 ## Bonnes pratiques
 
-- **Centralisation** : Centralisez la logique de validation pour garantir une maintenance facile.
-- **Accessibilité** : Vérifiez que les messages d'erreur sont clairs et concis pour tous les utilisateurs.
+1. **Messages clairs** : Utilisez des messages explicites qui guident l'utilisateur
+2. **Validation progressive** : Validez au fur et à mesure de la saisie
+3. **Avertissements utiles** : Utilisez les warnings pour des recommandations non-bloquantes
+4. **Messages de succès** : Encouragez les bonnes pratiques avec des messages positifs
+5. **Identifiants de champs** : Utilisez `fieldIdentifier` pour des messages contextuels
 
-## Conclusion
+## Exemple de validation personnalisée
+
+<Source dark code={`
+const customRules = [
+  {
+    type: 'custom',
+    options: {
+      validate: (value: string) => {
+        const hasNumber = /\d/.test(value)
+        const hasUpper = /[A-Z]/.test(value)
+        const hasLower = /[a-z]/.test(value)
+        
+        if (!hasNumber || !hasUpper || !hasLower) {
+          return 'Le mot de passe doit contenir au moins un chiffre, une majuscule et une minuscule'
+        }
+        
+        return true
+      },
+      successMessage: 'Votre mot de passe respecte les critères de sécurité'
+    }
+  }
+]
+`}/>
 
-Avec `useFieldValidation`, vous disposez d'un outil pour gérer les validations de vos formulaires dans Vue.js. Ce composable est idéal pour créer des validations personnalisées et intégrer des champs avec des bibliothèques comme Vuetify.
+## Conclusion
 
+Le système de validation du Design System offre une grande flexibilité tout en restant simple à utiliser. La combinaison des erreurs, avertissements et succès permet de créer une expérience utilisateur riche et intuitive.

package/src/stories/GuideDuDev/moduleDeNotification.mdx

@@ -8,7 +8,7 @@ import { Meta, Source } from '@storybook/addon-docs/blocks';
 ## Importation et utilisation
 
 <Source dark code={`
-import { useNotificationService } from '@cnamts/synapse/src/services/useNotificationService'
+import { useNotificationService } from '@cnamts/synpase'
 
 const { notificationQueue, addNotification, removeNotification, clearQueue } = useNotificationService()
 `} />

package/src/utils/formatDate/index.ts

@@ -0,0 +1,6 @@
+import dayjs, { Dayjs } from 'dayjs'
+
+/** Format a date with dayjs */
+export function formatDate(date: Dayjs, format = 'DD/MM/YYYY'): string {
+	return dayjs(date).format(format)
+}

package/src/utils/formatDate/tests/formatDate.spec.ts

@@ -0,0 +1,18 @@
+import dayjs from 'dayjs'
+import { describe, it, expect } from 'vitest'
+
+import { formatDate } from '../'
+
+describe('formatDate', () => {
+	it('formats a valid date', () => {
+		const date = dayjs('2022-01-01')
+
+		expect(formatDate(date)).toEqual('01/01/2022')
+	})
+
+	it('does not format an invalid date', () => {
+		const date = dayjs(null)
+
+		expect(formatDate(date)).toEqual('Invalid Date')
+	})
+})

package/src/utils/functions/validation/isDateAfter/index.ts

@@ -0,0 +1,9 @@
+import { parseDate } from '@/utils/parseDate'
+
+/** Check if a date is after another date (DD/MM/YYYY format) */
+export function isDateAfter(maxDate: string, value: string): boolean {
+	const parsedValue = parseDate(value)
+	const parsedMaxDate = parseDate(maxDate)
+
+	return parsedValue.isAfter(parsedMaxDate)
+}

package/src/utils/functions/validation/isDateAfter/tests/isDateAfter.spec.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest'
+import dayjs from 'dayjs'
+import { formatDate } from '@/utils/formatDate'
+import { isDateAfter } from '..'
+
+describe('isDateAfter', () => {
+	const today = formatDate(dayjs())
+	const pasteDate = formatDate(dayjs().subtract(1, 'year'))
+	const futureDate = formatDate(dayjs().add(1, 'year'))
+
+	it('returns true with a future date', () => {
+		expect(isDateAfter(today, futureDate)).toBeTruthy()
+	})
+
+	it('returns false with a past date', () => {
+		expect(isDateAfter(today, pasteDate)).toBeFalsy()
+	})
+})

package/src/utils/functions/validation/isDateBefore/index.ts

@@ -0,0 +1,9 @@
+import { parseDate } from '@/utils/parseDate'
+
+/** Check if a date is before another date (DD/MM/YYYY format) */
+export function isDateBefore(minDate: string, value: string): boolean {
+	const parsedValue = parseDate(value)
+	const parsedMinDate = parseDate(minDate)
+
+	return parsedValue.isBefore(parsedMinDate)
+}

package/src/utils/functions/validation/isDateBefore/tests/isDateBefore.spec.ts

@@ -0,0 +1,23 @@
+import { isDateBefore } from '../'
+import { describe, it, expect } from 'vitest'
+
+import dayjs from 'dayjs'
+import { formatDate } from '@/utils/formatDate'
+
+describe('isDateBefore', () => {
+	const today = formatDate(dayjs())
+	const pasteDate = formatDate(dayjs().subtract(1, 'year'))
+	const futureDate = formatDate(dayjs().add(1, 'year'))
+
+	it('returns true with a past date', () => {
+		expect(isDateBefore(today, pasteDate)).toBeTruthy()
+	})
+
+	it('returns false with a future date', () => {
+		expect(isDateBefore(today, futureDate)).toBeFalsy()
+	})
+
+	it('returns false with the current date', () => {
+		expect(isDateBefore(today, today)).toBeFalsy()
+	})
+})

package/src/utils/functions/validation/isDateInRange/index.ts

@@ -0,0 +1,22 @@
+import dayjs from 'dayjs'
+
+import isBetween from 'dayjs/plugin/isBetween'
+dayjs.extend(isBetween)
+
+export type Interval = '()' | '[]' | '[)' | '(]'
+
+/** Check if a date is in a range */
+export function isDateInRange(
+	date: string,
+	startDate: string,
+	endDate: string,
+	interval: Interval = '[)', // '[' indicates inclusion, '(' indicates exclusion
+): boolean {
+	const rangePositive = dayjs(startDate).isBefore(dayjs(endDate))
+
+	if (rangePositive) {
+		return dayjs(date).isBetween(startDate, endDate, null, interval)
+	}
+
+	return false
+}

package/src/utils/functions/validation/isDateInRange/tests/isDateInRange.spec.ts

@@ -0,0 +1,28 @@
+import { isDateInRange } from '../'
+import { describe, it, expect } from 'vitest'
+
+const start = '2019-10-21'
+const end = '2019-10-27'
+
+const date = '2019-10-23'
+
+describe('isDateInRange', () => {
+	it('returns true if the date is in the range', () => {
+		expect(isDateInRange(date, start, end)).toBe(true)
+	})
+
+	it('returns false if the range is negative', () => {
+		// Invert start & end date to create a negative range
+		expect(isDateInRange(date, end, start)).toBe(false)
+	})
+
+	it('works with a custom interval', () => {
+		const start = '2019-10-21'
+		const end = '2019-10-27'
+
+		const date = '2019-10-27'
+
+		// We change the interval to allow the last day in the range
+		expect(isDateInRange(date, start, end, '[]')).toBe(true)
+	})
+})

package/src/utils/functions/validation/isDateValid/index.ts

@@ -0,0 +1,67 @@
+import { parseDate } from '@/utils/parseDate'
+import dayjs from 'dayjs'
+
+import isLeapYear from 'dayjs/plugin/isLeapYear'
+
+dayjs.extend(isLeapYear)
+
+const DATE_SEPARATORS = /[- /.]/
+/** Matches DD/MM/YYYY with one of the DATE_SEPARATORS */
+export const DATE_FORMAT_REGEX
+	= /(0[1-9]|[12][0-9]|3[01])[- /.](0[1-9]|1[012])[- /.]\d{4}/
+
+export enum DateErrorCodes {
+	WRONG_FORMAT = 'wrongFormat',
+	MONTH_NOT_MATCH = 'monthNotMatch',
+	NOT_LEAP_YEAR = 'notALeapYear',
+}
+
+/** Check if a date is valid */
+export function isDateValid(date: string): string | true {
+	if (!date.match(DATE_FORMAT_REGEX)) {
+		return DateErrorCodes.WRONG_FORMAT
+	}
+
+	const DAYS_IN_MONTH = [
+		31,
+		28, // Check leap year later
+		31,
+		30,
+		31,
+		30,
+		31,
+		31,
+		30,
+		31,
+		30,
+		31,
+	]
+
+	const parsedDate = date.split(DATE_SEPARATORS)
+
+	const day = parseInt(parsedDate[0], 10)
+	const month = parseInt(parsedDate[1], 10)
+
+	if (month !== 2) {
+		if (day > DAYS_IN_MONTH[month - 1]) {
+			return DateErrorCodes.MONTH_NOT_MATCH
+		}
+		else {
+			return true
+		}
+	}
+	else {
+		const parsed = parseDate(date)
+		const isLeap = parsed.isLeapYear()
+
+		if (isLeap && day > 29) {
+			return DateErrorCodes.MONTH_NOT_MATCH
+		}
+
+		if (!isLeap && day >= 29) {
+			return DateErrorCodes.NOT_LEAP_YEAR
+		}
+
+		return true
+	}
+}