@cnamts/synapse 1.0.27 → 1.1.1

package/src/components/Customs/SyCheckBoxGroup/composables/useSyCheckBoxGroupValidation.ts

@@ -0,0 +1,107 @@
+import { computed, ref, toRef, type ComputedRef, type Ref } from 'vue'
+import { useValidation, type ValidationRule } from '@/composables/unifyValidation/useValidation'
+import type { SyCheckBoxGroupValidationProps } from '../types'
+
+export interface UseSyCheckBoxGroupValidationReturn {
+	validate: () => Promise<boolean>
+	validateOnSubmit: () => Promise<boolean>
+	clearValidation: () => void
+	errors: Ref<string[]>
+	warnings: Ref<string[]>
+	successes: Ref<string[]>
+	hasError: ComputedRef<boolean | undefined>
+	hasWarning: ComputedRef<boolean | undefined>
+	hasSuccess: ComputedRef<boolean | undefined>
+	defaultRules: ComputedRef<ValidationRule[]>
+	focused: Ref<boolean>
+}
+
+/**
+ * Composable pour gérer la validation du composant SyCheckBoxGroup
+ *
+ * Ce composable encapsule toute la logique de validation spécifique aux groupes de checkboxes :
+ * - Validation required avec message personnalisé (supporte les modes single et multiple)
+ * - Support des customRules, customWarningRules, customSuccessRules
+ * - Désactivation automatique des messages de succès en mode Vuetify
+ * - Intégration avec useValidation du design system
+ *
+ * @example
+ * const { validate, errors, hasError, defaultRules } = useSyCheckBoxGroupValidation(props, model)
+ */
+export function useSyCheckBoxGroupValidation(
+	props: SyCheckBoxGroupValidationProps,
+	model: Ref<(string | number) | (string | number)[] | null>,
+	focused?: Ref<boolean>,
+): UseSyCheckBoxGroupValidationReturn {
+	// Utiliser la variable focused passée en paramètre, sinon en créer une locale
+	const focusedRef = focused !== undefined ? focused : ref(false)
+
+	// Construction des règles de validation par défaut (required)
+	const defaultRules = computed<ValidationRule[]>(() =>
+		props.required
+			? [{
+					type: 'required',
+					options: {
+						message: `Le champ ${props.fieldIdentifier || props.label || 'ce champ'} est requis.`,
+						fieldIdentifier: props.label,
+					},
+				}]
+			: [],
+	)
+
+	// Vuetify ne gère pas les messages de succès, on désactive automatiquement en mode Vuetify
+	const effectiveShowSuccessMessages = computed(() =>
+		props.useVuetifyValidation ? false : (props.showSuccessMessages ?? false),
+	)
+
+	const {
+		validate,
+		clearValidation,
+		errors,
+		warnings,
+		successes,
+		hasError,
+		hasWarning,
+		hasSuccess,
+	} = useValidation({
+		modelValue: model,
+		readonly: toRef(() => props.readonly ?? false),
+		disabled: toRef(() => props.disabled ?? false),
+		required: toRef(() => props.required ?? false),
+		isValidateOnBlur: toRef(() => props.isValidateOnBlur ?? false),
+		showSuccessMessages: effectiveShowSuccessMessages,
+		disableErrorHandling: toRef(() => props.disableErrorHandling ?? false),
+		useVuetifyValidation: toRef(() => props.useVuetifyValidation ?? false),
+		label: toRef(() => props.label ?? ''),
+		rules: toRef(() => props.rules),
+		customRules: computed(() => [...defaultRules.value, ...(props.customRules || [])]),
+		customWarningRules: toRef(() => props.customWarningRules ?? []),
+		customSuccessRules: toRef(() => props.customSuccessRules ?? []),
+		errorMessages: toRef(() => props.errorMessages ?? null),
+		warningMessages: toRef(() => props.warningMessages ?? null),
+		successMessages: toRef(() => props.successMessages ?? null),
+		hasErrorProp: toRef(() => props.hasError ?? false),
+		hasWarningProp: toRef(() => props.hasWarning ?? false),
+		hasSuccessProp: toRef(() => props.hasSuccess ?? false),
+		maxErrors: toRef(() => props.maxErrors ?? 1),
+		focused: focusedRef,
+	})
+
+	const validateOnSubmit = async (): Promise<boolean> => {
+		return await validate()
+	}
+
+	return {
+		validate,
+		validateOnSubmit,
+		clearValidation,
+		errors,
+		warnings,
+		successes,
+		hasError,
+		hasWarning,
+		hasSuccess,
+		defaultRules,
+		focused: focusedRef,
+	}
+}

package/src/components/Customs/SyCheckBoxGroup/tests/SyCheckBoxGroup.spec.ts

@@ -3,6 +3,7 @@ import SyCheckbox from '@/components/Customs/SyCheckbox/SyCheckbox.vue'
 import { mount } from '@vue/test-utils'
 import { describe, it, expect } from 'vitest'
 import { nextTick } from 'vue'
+import type { ValidationRule } from '@/composables/unifyValidation/useValidation'
 
 describe('SyCheckBoxGroup', () => {
 	it('should render correctly', () => {
@@ -82,17 +83,17 @@ describe('SyCheckBoxGroup', () => {
 			},
 		})
 
-		await wrapper.vm.validateOnSubmit()
+		const isValidInitial = await wrapper.vm.validateOnSubmit()
 		await nextTick()
-		expect(wrapper.vm.validation.hasError.value).toBe(true)
-		expect(wrapper.vm.validation.errors.value[0]).toContain('est requis')
+		expect(isValidInitial).toBe(false)
+		expect(wrapper.text()).toContain('est requis')
 
 		await wrapper.find('input').setValue(true)
 
-		await wrapper.vm.validateOnSubmit()
+		const isValidAfterSelection = await wrapper.vm.validateOnSubmit()
 		await nextTick()
 
-		expect(wrapper.vm.validation.hasError.value).toBe(false)
+		expect(isValidAfterSelection).toBe(true)
 		expect(wrapper.props('modelValue')).toBe('X')
 	})
 
@@ -141,12 +142,184 @@ describe('SyCheckBoxGroup', () => {
 
 		const isValidInitial = await wrapper.vm.validateOnSubmit()
 		expect(isValidInitial).toBe(false)
-		expect(wrapper.vm.validation.errors.value).toContain('Vous devez sélectionner une option.')
+		// Vérifier que le message d'erreur de la règle required ou custom est affiché
+		expect(wrapper.text()).toContain('requis') // Le message required par défaut
 
 		await wrapper.setProps({ modelValue: 'OK' })
 
 		const isValidCorrect = await wrapper.vm.validateOnSubmit()
 		expect(isValidCorrect).toBe(true)
-		expect(wrapper.vm.validation.errors.value).toHaveLength(0)
+		// Vérifier que le message d'erreur n'est plus présent
+		expect(wrapper.text()).not.toContain('requis')
+	})
+
+	it('should display asterisk when displayAsterisk is true and required', () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				label: 'Required Field',
+				required: true,
+				displayAsterisk: true,
+				options: [{ label: 'X', value: 'X', id: 'opt-x' }],
+			},
+		})
+
+		expect(wrapper.text()).toContain('Required Field *')
+	})
+
+	it('should not display asterisk when displayAsterisk is false', () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				label: 'Required Field',
+				required: true,
+				displayAsterisk: false,
+				options: [{ label: 'X', value: 'X', id: 'opt-x' }],
+			},
+		})
+
+		expect(wrapper.text()).not.toContain('Required Field *')
+	})
+
+	it('should handle external error messages', async () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				label: 'CheckBox Group',
+				options: [{ label: 'X', value: 'X', id: 'opt-x' }],
+				errorMessages: ['Erreur externe'],
+			},
+		})
+
+		await nextTick()
+
+		const errorMessages = wrapper.findAll('.v-messages__message')
+		expect(errorMessages.length).toBeGreaterThan(0)
+		expect(errorMessages[0]?.text()).toContain('Erreur externe')
+	})
+
+	it('should handle warning and success rules', async () => {
+		const warningRule: ValidationRule = {
+			type: 'custom',
+			options: {
+				validate: (value: unknown) => {
+					if (value !== 'A') {
+						return 'Vous devez sélectionner l\'option A'
+					}
+					return true
+				},
+			},
+		}
+
+		const successRule: ValidationRule = {
+			type: 'custom',
+			options: {
+				validate: (value: unknown) => value === 'A',
+				successMessage: 'Option A sélectionnée',
+			},
+		}
+
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				'modelValue': null,
+				'customWarningRules': [warningRule],
+				'customSuccessRules': [successRule],
+				'showSuccessMessages': true,
+				'isValidateOnBlur': false,
+				'options': [
+					{ label: 'Option A', value: 'A', id: 'opt-a' },
+					{ label: 'Option B', value: 'B', id: 'opt-b' },
+				],
+				'onUpdate:modelValue': e => wrapper.setProps({ modelValue: e }),
+			},
+		})
+
+		// Sélectionner B devrait afficher un warning
+		await wrapper.setProps({ modelValue: 'B' })
+		await wrapper.vm.validateOnSubmit()
+		await nextTick()
+
+		expect(wrapper.text()).toContain('Vous devez sélectionner l\'option A')
+
+		// Sélectionner A devrait afficher un succès
+		await wrapper.setProps({ modelValue: 'A' })
+		await wrapper.vm.validateOnSubmit()
+		await nextTick()
+
+		expect(wrapper.text()).toContain('Option A sélectionnée')
+
+		const isValid = await wrapper.vm.validateOnSubmit()
+		expect(isValid).toBe(true)
+	})
+
+	it('should validate on selection change when isValidateOnBlur is false', async () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				'modelValue': null,
+				'required': true,
+				'isValidateOnBlur': false,
+				'options': [
+					{ label: 'Option A', value: 'A', id: 'opt-a' },
+					{ label: 'Option B', value: 'B', id: 'opt-b' },
+				],
+				'onUpdate:modelValue': e => wrapper.setProps({ modelValue: e }),
+			},
+		})
+
+		// Pas d'erreur au montage car pas de validation forcée
+		await nextTick()
+
+		// Sélectionner une option valide
+		await wrapper.setProps({ modelValue: 'A' })
+		await nextTick()
+
+		const isValid = await wrapper.vm.validateOnSubmit()
+		expect(isValid).toBe(true)
+	})
+
+	it('should handle useVuetifyValidation mode', async () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				'modelValue': null,
+				'required': true,
+				'useVuetifyValidation': true,
+				'rules': [(v: unknown) => !!v || 'Champ requis'],
+				'options': [
+					{ label: 'Option A', value: 'A', id: 'opt-a' },
+				],
+				'onUpdate:modelValue': e => wrapper.setProps({ modelValue: e }),
+			},
+		})
+
+		// Vérifier que la validation Vuetify est active
+		await nextTick()
+		const isValidInitial = await wrapper.vm.validateOnSubmit()
+		expect(isValidInitial).toBe(false)
+		expect(wrapper.text()).toContain('Champ requis')
+
+		// Sélectionner une option
+		await wrapper.setProps({ modelValue: 'A' })
+		const isValidAfter = await wrapper.vm.validateOnSubmit()
+		expect(isValidAfter).toBe(true)
+	})
+
+	it('should expose checkErrorOnBlur method', async () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				modelValue: null,
+				required: true,
+				isValidateOnBlur: true,
+				options: [
+					{ label: 'Option A', value: 'A', id: 'opt-a' },
+				],
+			},
+		})
+
+		// Vérifier que la méthode est exposée
+		expect(typeof wrapper.vm.checkErrorOnBlur).toBe('function')
+
+		// Appeler la méthode (simule le blur)
+		await wrapper.vm.checkErrorOnBlur()
+		await nextTick()
+
+		// Devrait afficher l'erreur car champ vide
+		expect(wrapper.text()).toContain('requis')
 	})
 })

package/src/components/Customs/SyCheckBoxGroup/tests/SyCheckBoxGroup.visual.cy.ts

@@ -0,0 +1,55 @@
+import SyCheckBoxGroup from '../SyCheckBoxGroup.vue'
+
+const defaultOptions = [
+	{ label: 'Option A', value: 'a' },
+	{ label: 'Option B', value: 'b' },
+	{ label: 'Option C', value: 'c' },
+]
+
+describe('SyCheckBoxGroup - Visual regression tests', () => {
+	it('displays the checkbox group by default', () => {
+		cy.mountWithVuetify(SyCheckBoxGroup, {
+			props: { options: defaultOptions },
+		})
+
+		cy.get('.sy-checkbox-group').should('be.visible')
+		cy.matchImageSnapshot('sy-checkbox-group-default', cy.get('.sy-checkbox-group'))
+	})
+
+	it('displays the checkbox group with some items selected', () => {
+		cy.mountWithVuetify(SyCheckBoxGroup, {
+			props: {
+				options: defaultOptions,
+				modelValue: ['a', 'c'],
+				multiple: true,
+			},
+		})
+
+		cy.get('.sy-checkbox-group').should('be.visible')
+		cy.matchImageSnapshot('sy-checkbox-group-selected', cy.get('.sy-checkbox-group'))
+	})
+
+	it('displays the checkbox group with a label', () => {
+		cy.mountWithVuetify(SyCheckBoxGroup, {
+			props: {
+				options: defaultOptions,
+				label: 'Choisissez vos options',
+			},
+		})
+
+		cy.get('.sy-checkbox-group').should('be.visible')
+		cy.matchImageSnapshot('sy-checkbox-group-with-label', cy.get('.sy-checkbox-group'))
+	})
+
+	it('displays the checkbox group in disabled state', () => {
+		cy.mountWithVuetify(SyCheckBoxGroup, {
+			props: {
+				options: defaultOptions,
+				disabled: true,
+			},
+		})
+
+		cy.get('.sy-checkbox-group').should('be.visible')
+		cy.matchImageSnapshot('sy-checkbox-group-disabled', cy.get('.sy-checkbox-group'))
+	})
+})

package/src/components/Customs/SyCheckBoxGroup/types.ts

@@ -1,3 +1,5 @@
+import type { FieldValidationProps, ValidationRule, VuetifyValidationRule } from '@/composables/unifyValidation/useValidation'
+
 export type Option = {
 	label: string
 	value: string | number
@@ -8,3 +10,50 @@ export type Option = {
 	ariaLabel?: string
 	title?: string
 }
+
+/**
+ * Props du composant SyCheckBoxGroup
+ */
+export interface SyCheckBoxGroupProps extends FieldValidationProps {
+	ariaLabel?: string
+	ariaLabelledby?: string
+	color?: string
+	density?: 'default' | 'comfortable' | 'compact'
+	displayAsterisk?: boolean
+	helpText?: string
+	hideDetails?: boolean | 'auto'
+	id?: string
+	label?: string
+	modelValue?: (string | number) | (string | number)[] | null
+	multiple?: boolean
+	name?: string
+	options?: Option[]
+	title?: string
+}
+
+/**
+ * Props de validation étendant FieldValidationProps du système unifié
+ */
+export interface SyCheckBoxGroupValidationProps extends FieldValidationProps {
+	modelValue?: (string | number) | (string | number)[] | null
+	multiple?: boolean
+	required?: boolean
+	readonly?: boolean
+	disabled?: boolean
+	customRules?: ValidationRule[]
+	customWarningRules?: ValidationRule[]
+	customSuccessRules?: ValidationRule[]
+	isValidateOnBlur?: boolean
+	showSuccessMessages?: boolean
+	useVuetifyValidation?: boolean
+	rules?: VuetifyValidationRule[]
+	errorMessages?: string[] | null
+	warningMessages?: string[] | null
+	successMessages?: string[] | null
+	hasError?: boolean
+	hasWarning?: boolean
+	hasSuccess?: boolean
+	maxErrors?: number
+	disableErrorHandling?: boolean
+	fieldIdentifier?: string
+}

package/src/components/Customs/SyCheckbox/SyCheckbox.stories.ts

@@ -2,11 +2,7 @@ import type { Meta, StoryObj } from '@storybook/vue3'
 import SyCheckbox from '@/components/Customs/SyCheckbox/SyCheckbox.vue'
 import { ref, watch } from 'vue'
 import { fn } from '@storybook/test'
-
-// Interface pour typer correctement le composant SyCheckbox avec sa méthode validateOnSubmit
-interface SyCheckboxInstance {
-	validateOnSubmit: () => Promise<boolean>
-}
+import { getValidationDocumentation } from '@/composables/unifyValidation/documentationValidationProps'
 
 const meta = {
 	title: 'Composants/Formulaires/SyCheckbox',
@@ -26,11 +22,16 @@ const meta = {
 		},
 	},
 	argTypes: {
+		...getValidationDocumentation(),
 		modelValue: { control: 'boolean' },
 		label: {
 			description: 'Texte affiché comme label de la case à cocher',
 			control: 'text',
 		},
+		helpText: {
+			description: 'Texte d\'aide affiché sous la case (masqué quand un message de validation est présent)',
+			control: 'text',
+		},
 		color: {
 			control: 'select',
 			options: ['primary', 'success', 'error', 'warning'],
@@ -202,6 +203,41 @@ Cette case à cocher est dans un état indéterminé, généralement utilisé lo
 	},
 }
 
+export const HelpText: Story = {
+	args: {
+		...Default.args,
+		helpText: 'Cochez cette case pour accepter les conditions générales.',
+	},
+	render: args => ({
+		components: { SyCheckbox },
+		setup() {
+			const checked = ref(false)
+			return { args, checked }
+		},
+		template: `<SyCheckbox v-model="checked" v-bind="args" label="Case à cocher" />`,
+	}),
+	parameters: {
+		sourceCode: [
+			{
+				name: 'Template',
+				code: `<SyCheckbox
+  v-model="checked"
+  label="Case à cocher"
+  help-text="Cochez cette case pour accepter les conditions générales."
+/>`,
+			},
+		],
+		docs: {
+			description: {
+				story: `
+### Case à cocher avec texte d'aide
+Un texte d'aide (\`helpText\`) s'affiche sous la case pour guider l'utilisateur, tant qu'aucun message de validation (erreur, avertissement, succès) n'est présent.
+				`,
+			},
+		},
+	},
+}
+
 export const WithControlsIds: Story = {
 	parameters: {
 		sourceCode: [
@@ -640,159 +676,3 @@ Le composant SyCheckbox peut être personnalisé avec différentes couleurs pour
 		`,
 	}),
 }
-
-export const FormValidation: Story = {
-	parameters: {
-		sourceCode: [
-			{
-				name: 'Template',
-				code: `
-<template>
-  <form @submit.prevent="validateForm">
-    <h3>Validation avec règles personnalisées</h3>
-    <SyCheckbox
-      ref="checkbox"
-      v-model="checked"
-      label="J'accepte les conditions générales d'utilisation"
-      :custom-rules="rules"
-      validate-on-submit
-    />
-    <h3>Validation avec la prop required</h3>
-    <SyCheckbox
-      ref="checkbox2"
-      v-model="checked2"
-      label="J'accepte les conditions générales d'utilisation"
-	  display-asterisk
-      required
-    />
-    <VBtn 
-      type="submit" 
-      color="primary"
-      class="mt-4"
-    >
-      Soumettre
-    </VBtn>
-    <p v-if="formSubmitted" style="margin-top: 16px; color: var(--v-success-base);">Formulaire soumis avec succès!</p>
-  </form>
-</template>
-
-<script setup lang="ts">
-import { ref, watch } from 'vue'
-
-const checkbox = ref<SyCheckboxInstance | null>(null)
-const checkbox2 = ref<SyCheckboxInstance | null>(null)
-const checked = ref(false)
-const checked2 = ref(false)
-const formSubmitted = ref(false)
-const hasError = ref(false)
-
-const rules = [
-  {
-    type: 'custom',
-    options: {
-      message: 'Cette case doit être cochée pour continuer.',
-      validate: (value: boolean) => value === true,
-    },
-  },
-]
-
-const validateForm = async (): Promise<void> => {
-  if (!checkbox.value || !checkbox2.value) return
-  hasError.value = true
-  const isValid = await checkbox.value.validateOnSubmit()
-  const isValid2 = await checkbox2.value.validateOnSubmit()
-  if (isValid && isValid2) {
-    formSubmitted.value = true
-    hasError.value = false
-  }
-}
-</script>`,
-			},
-		],
-		docs: {
-			description: {
-				story: `
-### Case à cocher avec validation au moment de la soumission
-Cette case à cocher utilise des règles de validation personnalisées et valide le formulaire lors de la soumission grâce à la propriété \`validateOnSubmit\`. Le bouton de soumission déclenche la validation et affiche un message de succès si la case est cochée.
-				`,
-			},
-		},
-	},
-	render: args => ({
-		components: { SyCheckbox },
-		setup() {
-			const checkbox = ref<SyCheckboxInstance | null>(null)
-			const checkbox2 = ref<SyCheckboxInstance | null>(null)
-			const checked = ref(false)
-			const checked2 = ref(false)
-			const formSubmitted = ref(false)
-			const hasError = ref(false)
-
-			// Revalider quand les valeurs changent
-			watch([checked, checked2], async () => {
-				if (hasError.value && checkbox.value && checkbox2.value) {
-					await checkbox.value.validateOnSubmit()
-					await checkbox2.value.validateOnSubmit()
-				}
-			})
-
-			const validateForm = async (): Promise<void> => {
-				if (!checkbox.value || !checkbox2.value) return
-				hasError.value = true
-				const isValid = await checkbox.value.validateOnSubmit()
-				const isValid2 = await checkbox2.value.validateOnSubmit()
-				if (isValid && isValid2) {
-					formSubmitted.value = true
-					hasError.value = false
-				}
-			}
-
-			return {
-				args,
-				checkbox,
-				checked,
-				checkbox2,
-				checked2,
-				formSubmitted,
-				hasError,
-				rules: [
-					{
-						type: 'custom',
-						options: {
-							message: 'Cette case doit être cochée pour continuer.',
-							validate: (value: boolean) => value === true,
-						},
-					},
-				],
-				validateForm,
-			}
-		},
-		template: `
-			<form @submit.prevent="validateForm">
-				<h3>Validation avec règles personnalisées</h3>
-				<SyCheckbox
-					ref="checkbox"
-					v-model="checked"
-					label="J'accepte les conditions générales d'utilisation"
-					:custom-rules="rules"
-				/>
-				<h3>Validation avec la prop required et display-asterisk</h3>
-				<SyCheckbox
-					ref="checkbox2"
-					v-model="checked2"
-					label="J'accepte les conditions générales d'utilisation"
-					required
-					display-asterisk
-				/>
-				<VBtn
-                    type="submit"
-                    color="primary"
-					class="mt-4"
-				>
-					Soumettre
-				</VBtn>
-				<p v-if="formSubmitted" style="margin-top: 16px; color: var(--v-success-base);">Formulaire soumis avec succès!</p>
-			</form>
-		`,
-	}),
-}