@cnamts/synapse 0.0.3-alpha → 0.0.5-alpha

package/src/stories/GuideDuDev/CommentUtiliserLesRules.mdx

@@ -0,0 +1,132 @@
+import {Meta, Source} from '@storybook/addon-docs/blocks';
+
+<Meta title="Guide Du Dev/Comment utiliser les rules"/>
+
+# Comment utiliser les règles 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.
+
+---
+
+## 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.
+
+---
+
+## Structure du composable
+
+### Type `RuleOptions`
+
+    <Source dark code={`
+type RuleOptions = {
+fieldName?: string; // Nom du champ utilisé dans les messages d'erreur
+message?: string; // Message personnalisé pour la règle
+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
+};
+`} />
+
+---
+
+## Exemple d'intégration
+
+### Script Vue.js
+
+    <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.');
+}
+};
+</script>
+`} />
+---
+
+### Template Vue.js
+
+    <Source dark code={`
+<template>
+    <v-form
+    @submit.prevent="handleSubmit">
+    <v-text-field
+        v-model="firstName"
+    :rules="rules.firstName"
+    label="Prénom"
+    @blur="validateField('firstName')"
+    />
+    <v-text-field
+        v-model="email"
+    :rules="rules.email"
+    label="Email"
+    @blur="validateField('email')"
+    />
+    <v-text-field
+        v-model="age"
+    :rules="rules.age"
+    label="Âge"
+    @blur="validateField('age')"
+    />
+    <v-btn block class="mt-2" type="submit">Soumettre</v-btn>
+</v-form>
+</template>
+`} />
+---
+
+## Fonctionnalités supportées
+
+- **Validation requise** (`required`)
+- **Longueur minimale** (`minLength`)
+- **Longueur maximale** (`maxLength`)
+- **Valeur minimale** (`min`)
+- **Valeur maximale** (`max`)
+- **Validation par motif** (`matchPattern`)
+- **Validation d'email** (`email`)
+
+---
+
+## Bonnes pratiques
+
+- Toujours tester les messages d'erreur personnalisés pour garantir une bonne expérience utilisateur.
+- Centraliser la logique de validation pour une meilleure maintenance.
+- Documenter les règles complexes pour aider votre équipe à comprendre leur fonctionnement.
+
+---
+
+## Conclusion
+
+Avec `useFieldValidation`, vous disposez d'un moyen simple et flexible pour gérer vos validations de formulaires dans Vue.js. Combinez-le avec des bibliothèques comme Vuetify pour une expérience utilisateur optimisée.

package/src/stories/GuideDuDev/moduleDeNotification.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks';
+import { Meta, Source } from '@storybook/addon-docs/blocks';
 
 <Meta title="Guide Du Dev/Services/useNotificationService" />
 # useNotificationService
@@ -7,78 +7,82 @@ import { Meta } from '@storybook/addon-docs/blocks';
 
 ## Importation et utilisation
 
-```
-import { useNotificationService } from '@/services/useNotificationService'
+<Source dark code={`
+import { useNotificationService } from '@cnamts/synapse/src/services/useNotificationService'
 
 const { notificationQueue, addNotification, removeNotification, clearQueue } = useNotificationService()
-```
+`} />
 
-Propriétés et Méthodes:
+## Propriétés et méthodes :
 
-```
+<Source dark code={`
 notificationQueue: Ref<Notification[]>
-```
+`} />
 
 Une référence réactive à la file d'attente des notifications. Elle contient un tableau d'objets de type Notification.
 
-``` addNotification(notification: Notification): void ```
+<Source dark code={`
+addNotification(notification: Notification): void
+`} />
 
 Ajoute une nouvelle notification à la file d'attente, à condition qu'une notification avec le même id ne soit pas déjà présente.
 
-```
+<Source dark code={`
 addNotification({
   id: 'notif-1',
   message: 'Notification 1',
   type: 'info',
   duration: 5000
 })
-```
+`} />
 
-```
+<Source dark code={`
 removeNotification(id: string): void
-```
+`} />
 Supprime une notification de la file d'attente en fonction de son id.
 
-```
+<Source dark code={`
 removeNotification('notif-1')
-```
+`} />
 
-```
+<Source dark code={`
 clearQueue(): void
-```
+`} />
 
 Efface toutes les notifications de la file d'attente.
 
 
-```
+<Source dark code={`
 clearQueue()
-```
+`} />
 
-Typage de Notification
+## Typage de Notification
 
 Le type Notification est défini comme suit :
 
-```
-
+<Source dark code={`
 type Notification = {
   id: string
   message: string
   type: 'success' | 'error' | 'info' | 'warning'
   duration?: number
 }
-```
+`} />
+
 Propriétés de Notification
-```
+
+<Source dark code={`
     id: string — Identifiant unique de la notification.
     message: string — Le texte à afficher dans la notification.
     type: 'success' | 'error' | 'info' | 'warning' — Le type de la notification, qui peut influencer son apparence.
     duration?: number — Durée pendant laquelle la notification sera visible (en millisecondes).
-```
-Exemples d'utilisation
-Ajouter une notification
+`} />
 
-```
+## Exemples d'utilisation
 
+Ajouter une notification
+
+<Source dark code={`
 const { addNotification } = useNotificationService()
 
 addNotification({
@@ -87,39 +91,40 @@ addNotification({
   type: 'success',
   duration: 3000
 })
-```
+`} />
+
 Supprimer une notification
 
-```
+<Source dark code={`
 const { removeNotification } = useNotificationService()
 
 removeNotification('notif-2')
-```
-Effacer la file d'attente de notifications
+`} />
 
-```
+Effacer la file d'attente de notifications
 
+<Source dark code={`
 const { clearQueue } = useNotificationService()
 
 clearQueue()
-```
+`} />
 
 Accéder à la file d'attente
 
-```
+<Source dark code={`
 const { notificationQueue } = useNotificationService()
 
 console.log(notificationQueue.value) // Affiche toutes les notifications présentes dans la file d'attente
-```
+`} />
+
 Utilisation dans un composant Vue
 
-```
-<script setup lang="ts">
+<Source dark code={`
 <script setup lang="ts">
 	import { VBtn } from 'vuetify/components'
-	import NotificationBar from '@/components/NotificationBar/NotificationBar.vue'
-	import { useNotificationService } from '@/services/NotificationService'
-	import type { Notification } from '@/components/NotificationBar/types'
+	import NotificationBar from '@cnamts/synapse'
+	import { useNotificationService } from '@cnamts/synapse/src/services/NotificationService'
+	import type { Notification } from '@cnamts/synapse/src/components/NotificationBar/types'
 
 	const { addNotification } = useNotificationService()
 
@@ -171,12 +176,11 @@ Utilisation dans un composant Vue
 </template>
 
 <style scoped>
-.button-group {
-  display: flex;
-  flex-direction: column;
-  gap: 16px;
-  margin-top: 20px;
-}
+    .button-group {
+      display: flex;
+      flex-direction: column;
+      gap: 16px;
+      margin-top: 20px;
+    }
 </style>
-
-```
+`} />

package/src/stories/GuideDuDev/vuetifyOptions.mdx

@@ -1,4 +1,4 @@
-import { Meta } from '@storybook/addon-docs/blocks';
+import { Meta, Source } from '@storybook/addon-docs/blocks';
 
 <Meta title="Guide Du Dev/VuetifyOptions" />
 
@@ -13,60 +13,63 @@ Utilisation de vuetifyOptions
 Certains composants du design system acceptent une prop vuetifyOptions qui vous permet de personnaliser le comportement et le style du composant basé sur Vuetify.
 Vous trouverez des exemples de configurations directement dans la documentation de chaque composant que nous proposons pour mieux comprendre comment les personnaliser.
 
-Exemple d'utilisation dans un composant vuetify:
+## Exemple d'utilisation dans un composant Vuetify:
 
 Prenons l'exemple d'un bouton (VBtn).
 
 Voici un exemple d'utilisation du composant :
 
-```vue
-
+<Source dark code={`
 <MyButton
-:title="'Cliquez ici'"
-:vuetifyOptions="{ btn: { color: 'secondary', icon: true } }"
-    />
-```
+    :title="'Cliquez ici'"
+    :vuetifyOptions="{ btn: { color: 'secondary', icon: true } }"
+/>
+`} />
+
 Dans cet exemple :
 
-    Le texte du bouton est défini via la prop title.
-    Vous pouvez passer un objet vuetifyOptions pour personnaliser les propriétés du composant Vuetify sous-jacent (ici, VBtn).
+> Le texte du bouton est défini via la prop title.
 
-Explication
+> Vous pouvez passer un objet vuetifyOptions pour personnaliser les propriétés du composant Vuetify sous-jacent (ici, VBtn).
 
-    Propriétés de Vuetify : Vous pouvez configurer n'importe quelle option reconnue par Vuetify. Par exemple, pour un bouton (VBtn), vous pourriez ajuster sa couleur, son icône, son style (outlined, elevation, etc.).
+<b>Explication</b>
 
-    Fusion des options : Le design system gère la fusion des options par défaut et celles que vous fournissez dans vuetifyOptions. Si vous ne définissez pas une option spécifique, la valeur par défaut sera utilisée.
+> Propriétés de Vuetify : Vous pouvez configurer n'importe quelle option reconnue par Vuetify. Par exemple, pour un bouton (VBtn), vous pourriez ajuster sa couleur, son icône, son style (outlined, elevation, etc.).
 
-Exemple détaillé
+> Fusion des options : Le design system gère la fusion des options par défaut et celles que vous fournissez dans vuetifyOptions. Si vous ne définissez pas une option spécifique, la valeur par défaut sera utilisée.
+
+<b>Exemple détaillé</b>
 
 Voici un exemple plus complet :
-```
-vue
 
+<Source dark code={`
 <MyButton
-:title="'Valider'"
-:vuetifyOptions="{ btn: { color: 'primary', outlined: false, icon: true } }"
-    />
-```
+    :title="'Valider'"
+    :vuetifyOptions="{ btn: { color: 'primary', outlined: false, icon: true } }"
+ />
+`} />
+
 Dans cet exemple :
 
-    Le bouton sera bleu (color: 'primary').
-    Il n'aura pas de contour (outlined: false).
-    Une icône sera affichée sur le bouton (icon: true).
+> Le bouton sera bleu (color: 'primary').
 
-Options par défaut
+> Il n'aura pas de contour (outlined: false).
+
+> Une icône sera affichée sur le bouton (icon: true).
+
+## Options par défaut
 
 Chaque composant du design system dispose d'options par défaut qui lui assurent un style et un comportement cohérents. Cependant, si vous souhaitez personnaliser ces options, vous pouvez utiliser la prop vuetifyOptions pour adapter ces composants à vos besoins spécifiques sans compromettre la structure de base du design system.
 Exemple de bouton par défaut
 
 Sans fournir de vuetifyOptions, le bouton pourrait ressembler à ceci :
 
-```vue
-
+<Source dark code={`
 <MyButton :title="'Par défaut'" />
-```
+`} />
+
 Ce bouton utilisera les options par défaut définies dans le design system, telles que la couleur, le style de bordure ou les icônes.
 
-Conclusion
+## Conclusion
 
 L'intégration des vuetifyOptions dans les composants de ce design system vous offre une grande flexibilité pour personnaliser les composants en fonction de vos besoins spécifiques. Grâce à ce mécanisme, vous pouvez ajuster des propriétés telles que la couleur, les icônes et d'autres configurations Vuetify tout en vous appuyant sur des valeurs par défaut bien définies. Vous n'avez pas à vous soucier de la gestion interne des options : il vous suffit de passer les options personnalisées via la prop vuetifyOptions, et le composant s'adaptera automatiquement.

package/src/stories/{Fondamentaux → Guidelines}/Accessibilite/Accessibilite.mdx

@@ -13,8 +13,7 @@ En tant que personne morale de droit public nous concevons les composants de not
 
 Le RGAA est un outil méthodologique de certification permettant d'assurer par le respect de ses critères une manipulation des produits numériques dans le domaine du Web de manière égale entre chaque citoyen, qu'il soit ou non en situation de handicap (visuel, auditif, moteur, trouble dys...). Basé sur les travaux du W3C Web Accessibility Initiative (WAI) il vise à garantir quatre indices de performance:**la bonne perceptibilité de l'information**, une **manipulation efficiente dans la navigation**, une **bonne compréhension** et une **robustesse efficace** dans l'usage des produits numériques.
 
-[En savoir plus sur le RGAA](https://www.numerique.gouv.fr/publications/rgaa-accessibilite/#contenu)
-
+[En savoir plus sur le RGAA](https://www.numerique.gouv.fr/publications/rgaa-accessibilite/#contenu)<br/>
 [En savoir plus sur le W3C WAI](https://www.w3.org/WAI/fundamentals/)
 
 [](https://digital-design-system.netlify.app/fondamentaux/accessibilite#quels-sont-les-criteres-du-rgaa)Quels sont les critères du RGAA?

package/src/stories/{Fondamentaux → Guidelines}/Accessibilite/Accessibilite.stories.ts

@@ -3,7 +3,7 @@ import type { StoryObj } from '@storybook/vue3'
 import { AccessibiliteItems } from './AccessibiliteItems'
 
 export default {
-	title: 'Fondamentaux/Accessibilite',
+	title: 'Guidelines/Accessibilité',
 }
 
 export const AccessibilitePanel: StoryObj = {

package/src/stories/{Fondamentaux → Guidelines}/EcoConception/Econception.stories.ts

@@ -1,9 +1,9 @@
 import { VExpansionPanels, VExpansionPanel } from 'vuetify/components'
 import type { StoryObj } from '@storybook/vue3'
-import { ecoDesignItems } from '@/stories/Fondamentaux/EcoConception/ecoDesignItems'
+import { ecoDesignItems } from '@/stories/Guidelines/EcoConception/ecoDesignItems'
 
 export default {
-	title: 'Fondamentaux/EcoConception',
+	title: 'Guidelines/Éco-conception',
 }
 
 export const EcoPanel: StoryObj = {

package/src/utils/functions/throttleDisplayFn/tests/throttleDisplayFn.spec.ts

@@ -0,0 +1,47 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import throttleDisplayFn from '../throttleDisplayFn'
+
+describe('throttleDisplayFn', () => {
+	vi.stubGlobal('requestAnimationFrame', (fn: () => void) => fn())
+
+	beforeEach(() => {
+		vi.useFakeTimers()
+	})
+
+	afterEach(() => {
+		vi.restoreAllMocks()
+		vi.clearAllTimers()
+	})
+
+	it('should call the function immediately if delay has passed', () => {
+		const mockFn = vi.fn()
+		const delay = 100
+		const throttledFn = throttleDisplayFn(mockFn, delay)
+
+		throttledFn()
+		expect(mockFn).toHaveBeenCalledTimes(1)
+
+		vi.spyOn(performance, 'now').mockReturnValue(performance.now() + delay + 1)
+		throttledFn()
+		expect(mockFn).toHaveBeenCalledTimes(2)
+	})
+
+	it('should call the function after the delay if called multiple times within the delay', () => {
+		const mockFn = vi.fn()
+		const delay = 100
+		const throttledFn = throttleDisplayFn(mockFn, delay)
+
+		throttledFn()
+		expect(mockFn).toHaveBeenCalledTimes(1)
+
+		throttledFn()
+		throttledFn()
+
+		expect(mockFn).toHaveBeenCalledTimes(1)
+
+		// Advance timers to trigger the setTimeout
+		vi.advanceTimersByTime(delay)
+
+		expect(mockFn).toHaveBeenCalledTimes(2)
+	})
+})

package/src/utils/functions/throttleDisplayFn/throttleDisplayFn.ts

@@ -0,0 +1,26 @@
+/**
+ * Returns a throttled version of the provided function that will only be called once every `delay` milliseconds.
+ */
+export default function throttleDisplayFn<
+	F extends (...args: unknown[]) => void,
+>(fn: F, delay: number) {
+	let timeout: number | null = null
+	let lastCalled = 0
+
+	return function (...args: Parameters<F>) {
+		if (timeout !== null) {
+			window.clearTimeout(timeout)
+		}
+
+		if (performance.now() - lastCalled >= delay) {
+			window.requestAnimationFrame(() => fn(...args))
+			lastCalled = performance.now()
+		}
+		else {
+			timeout = window.setTimeout(() => {
+				fn(...args)
+				lastCalled = performance.now()
+			}, delay)
+		}
+	}
+}

package/src/utils/rules/exactLength/index.ts

@@ -0,0 +1,33 @@
+import { ruleMessage } from '../required/ruleMessageHelper'
+import type {
+	ValidationRule,
+	ValidationResult,
+	ErrorMessages,
+	Value,
+} from '../types'
+
+import { defaultErrorMessages } from './locales'
+
+/** Check that the value does not exceeds the specified length */
+export function exactLengthFn(
+	lengthValue: number,
+	ignoreSpaces = false,
+	errorMessages: ErrorMessages<number> = defaultErrorMessages,
+): ValidationRule {
+	return (value: Value): ValidationResult => {
+		if (!value) {
+			return true
+		}
+
+		if (ignoreSpaces) {
+			value = value.replace(/\s/g, '')
+		}
+
+		return (
+			value.length === lengthValue
+			|| ruleMessage(errorMessages, 'default', [lengthValue])
+		)
+	}
+}
+
+export const exactLength = exactLengthFn

package/src/utils/rules/exactLength/locales.ts

@@ -0,0 +1,6 @@
+import type { ErrorMessages } from '../types'
+
+export const defaultErrorMessages: ErrorMessages<number> = {
+	default: (length: number) =>
+		`La longueur du champ doit être de ${length} caractères.`,
+}

package/src/utils/rules/required/index.ts

@@ -0,0 +1,25 @@
+import { ruleMessage } from './ruleMessageHelper'
+import type { ValidationRule, ValidationResult, ErrorMessages } from '../types'
+
+import { defaultErrorMessages } from './locales'
+
+export type Value = string | string[] | null
+
+export function requiredFn(
+	errorMessages: ErrorMessages = defaultErrorMessages,
+): ValidationRule<Value> {
+	return (value: Value): ValidationResult => {
+		let valid: boolean
+
+		if (Array.isArray(value)) {
+			valid = value.length !== 0
+		}
+		else {
+			valid = Boolean(typeof value === 'string' ? value.trim() : value)
+		}
+
+		return valid || ruleMessage(errorMessages, 'default')
+	}
+}
+
+export const required = requiredFn()

package/src/utils/rules/required/locales.ts

@@ -0,0 +1,5 @@
+import type { ErrorMessages } from '../types'
+
+export const defaultErrorMessages: ErrorMessages = {
+	default: 'Le champ est requis.',
+}

package/src/utils/rules/required/ruleMessageHelper.ts

@@ -0,0 +1,14 @@
+import type { ErrorMessages, GenericFnOpt } from '../types'
+
+/** Get the value of an error message */
+export function ruleMessage<T>(
+	errorMessages: ErrorMessages<T>,
+	key: string,
+	args: T[] = [],
+): string {
+	if (typeof errorMessages[key] === 'function') {
+		return (errorMessages[key] as GenericFnOpt<T>)(...args)
+	}
+
+	return errorMessages[key] as string
+}

package/src/utils/rules/required/tests/index.spec.ts

@@ -0,0 +1,47 @@
+import { requiredFn } from '../index'
+import { describe, it, expect } from 'vitest'
+
+describe('requiredFn', () => {
+	it('returns true for non-empty string', () => {
+		const rule = requiredFn()
+		const result = rule('non-empty')
+		expect(result).toBe(true)
+	})
+
+	it('returns false for empty string', () => {
+		const rule = requiredFn()
+		const result = rule('')
+		expect(result).toBe('Le champ est requis.')
+	})
+
+	it('returns true for non-empty array', () => {
+		const rule = requiredFn()
+		const result = rule(['item'])
+		expect(result).toBe(true)
+	})
+
+	it('returns false for empty array', () => {
+		const rule = requiredFn()
+		const result = rule([])
+		expect(result).toBe('Le champ est requis.')
+	})
+
+	it('returns true for non-null value', () => {
+		const rule = requiredFn()
+		const result = rule('value')
+		expect(result).toBe(true)
+	})
+
+	it('returns false for null value', () => {
+		const rule = requiredFn()
+		const result = rule(null)
+		expect(result).toBe('Le champ est requis.')
+	})
+
+	it('returns custom error message for empty string', () => {
+		const customMessages = { default: 'Custom required message' }
+		const rule = requiredFn(customMessages)
+		const result = rule('')
+		expect(result).toBe('Custom required message')
+	})
+})