@cnamts/synapse 1.0.20 → 1.0.21

package/src/components/Customs/SyCheckBoxGroup/SyCheckBoxGroup.vue

@@ -0,0 +1,334 @@
+<script lang="ts" setup>
+	import { computed, onMounted, ref, watch } from 'vue'
+	import { VMessages } from 'vuetify/components'
+	import { useValidation, type ValidationRule } from '@/composables/validation/useValidation'
+	import { useValidatable } from '@/composables/validation/useValidatable'
+	import SyCheckbox from '@/components/Customs/SyCheckbox/SyCheckbox.vue'
+	import { locales } from './locales'
+	import type { Option } from './types'
+
+	const props = withDefaults(
+		defineProps<{
+			ariaLabel?: string
+			ariaLabelledby?: string
+			color?: string
+			customRules?: ValidationRule[]
+			customSuccessRules?: ValidationRule[]
+			customWarningRules?: ValidationRule[]
+			density?: 'default' | 'comfortable' | 'compact'
+			disabled?: boolean
+			disableErrorHandling?: boolean
+			displayAsterisk?: boolean
+			errorMessages?: string[] | null
+			hideDetails?: boolean | 'auto'
+			id?: string
+			isValidateOnBlur?: boolean
+			label?: string
+			modelValue?: (string | number) | (string | number)[] | null
+			multiple?: boolean
+			name?: string
+			options?: Option[]
+			readonly?: boolean
+			required?: boolean
+			showSuccessMessages?: boolean
+			successMessages?: string[] | null
+			title?: string
+			warningMessages?: string[] | null
+		}>(),
+		{
+			ariaLabel: undefined,
+			ariaLabelledby: undefined,
+			color: 'primary',
+			customRules: () => [],
+			customSuccessRules: () => [],
+			customWarningRules: () => [],
+			density: 'default',
+			disabled: false,
+			disableErrorHandling: false,
+			displayAsterisk: false,
+			errorMessages: null,
+			hideDetails: 'auto',
+			id: undefined,
+			isValidateOnBlur: false,
+			label: undefined,
+			modelValue: null,
+			multiple: false,
+			name: undefined,
+			options: () => [],
+			readonly: false,
+			required: false,
+			showSuccessMessages: true,
+			successMessages: null,
+			title: undefined,
+			warningMessages: null,
+		},
+	)
+
+	const emit = defineEmits(['update:modelValue', 'change'])
+
+	const isMultiple = computed(() => props.multiple)
+
+	const model = computed({
+		get() {
+			return props.modelValue
+		},
+		set(value) {
+			emit('update:modelValue', value)
+			emit('change', value)
+		},
+	})
+
+	const generatedLabel = computed(() => (props.label || '') + (props.displayAsterisk ? '*' : ''))
+
+	const isSubmitted = ref(false)
+
+	const validation = useValidation({
+		customRules: props.customRules,
+		warningRules: props.customWarningRules,
+		successRules: props.customSuccessRules,
+		showSuccessMessages: props.showSuccessMessages,
+		fieldIdentifier: props.label,
+		disableErrorHandling: props.disableErrorHandling,
+	})
+
+	watch(() => props.errorMessages, value => (validation.errors.value = value || []), { immediate: true })
+	watch(() => props.warningMessages, value => (validation.warnings.value = value || []), { immediate: true })
+	watch(() => props.successMessages, value => (validation.successes.value = value || []), { immediate: true })
+
+	const defaultRules = computed<ValidationRule[]>(() =>
+		props.required
+			? [{
+				type: 'required',
+				options: {
+					message: `Le champ ${props.label || 'ce champ'} est requis.`,
+					fieldIdentifier: props.label,
+				},
+			}]
+			: [],
+	)
+
+	function isOptionChecked(value: string | number): boolean {
+		if (isMultiple.value) {
+			return Array.isArray(model.value) && model.value.includes(value)
+		}
+		return model.value === value
+	}
+
+	function toggleOption(value: string | number): void {
+		if (props.readonly || props.disabled) return
+
+		if (isMultiple.value) {
+			const current = Array.isArray(model.value) ? model.value : []
+			model.value = current.includes(value)
+				? current.filter(v => v !== value)
+				: [...current, value]
+			return
+		}
+
+		model.value = model.value === value ? null : value
+	}
+
+	function getValidationValue(): (string | number) | (string | number)[] | null {
+		if (isMultiple.value) {
+			return Array.isArray(model.value) ? model.value : []
+		}
+		return model.value as (string | number) | null
+	}
+
+	const validateField = (value: (string | number) | (string | number)[] | null) => {
+		if (props.readonly) {
+			validation.clearValidation()
+			return true
+		}
+
+		if (!props.required && (value === null || (Array.isArray(value) && value.length === 0))) {
+			validation.clearValidation()
+			return true
+		}
+
+		const result = validation.validateField(
+			value,
+			[...defaultRules.value, ...props.customRules],
+			props.customWarningRules,
+			props.customSuccessRules,
+		)
+		return !result.hasError
+	}
+
+	const validateOnSubmit = () => {
+		isSubmitted.value = true
+		return validateField(getValidationValue())
+	}
+
+	const checkErrorOnBlur = () => {
+		validateField(getValidationValue())
+	}
+
+	watch(model, (newValue) => {
+		if (!props.isValidateOnBlur || isSubmitted.value) {
+			validateField(newValue as (string | number) | (string | number)[] | null)
+		}
+	})
+
+	const hasError = computed(() => validation.hasError.value)
+	const hasWarning = computed(() => validation.hasWarning.value)
+	const hasSuccess = computed(() => validation.hasSuccess.value)
+
+	const checkboxColor = computed(() => (hasError.value ? 'error' : props.color))
+
+	const errors = computed(() => validation.errors.value)
+	const warnings = computed(() => validation.warnings.value)
+	const successes = computed(() => validation.successes.value)
+
+	const labelId = computed(() => (props.id ? `${props.id}-label` : undefined))
+	const computedAriaLabelledby = computed(() => {
+		if (props.label && labelId.value) {
+			return [props.ariaLabelledby, labelId.value].filter(Boolean).join(' ')
+		}
+		return props.ariaLabelledby
+	})
+
+	const messagesRef = ref<InstanceType<typeof VMessages> | null>(null)
+	const vMessagesId = computed(() => messagesRef.value?.$el.id)
+
+	const requiredHintId = computed(() => (props.id ? `${props.id}-required-hint` : undefined))
+	const computedAriaDescribedby = computed(() => {
+		const ids: string[] = []
+
+		const shouldShowMessages = props.hideDetails !== true && (hasError.value || hasWarning.value || (hasSuccess.value && props.showSuccessMessages))
+		if (vMessagesId.value && shouldShowMessages) {
+			ids.push(vMessagesId.value)
+		}
+
+		if (requiredHintId.value && props.required && !props.ariaLabel && !computedAriaLabelledby.value) {
+			ids.push(requiredHintId.value)
+		}
+
+		return ids.length > 0 ? ids.join(' ') : undefined
+	})
+
+	onMounted(() => {
+		if (!props.isValidateOnBlur && !props.required) {
+			validateField(getValidationValue())
+		}
+	})
+
+	useValidatable(validateOnSubmit)
+
+	defineExpose({
+		validation,
+		validateOnSubmit,
+		checkErrorOnBlur,
+	})
+</script>
+
+<template>
+	<fieldset
+		:id="props.id"
+		class="sy-checkbox-group"
+		:class="{
+			'warning-field': hasWarning && !hasError,
+			'success-field': hasSuccess && !hasError && !hasWarning,
+			'error-field': hasError,
+		}"
+		:aria-describedby="computedAriaDescribedby"
+		:title="props.title"
+	>
+		<legend
+			v-if="props.label"
+			:id="labelId"
+			class="v-label sy-checkbox-group__label"
+		>
+			{{ generatedLabel }}
+		</legend>
+
+		<div
+			class="sy-checkbox-group__options"
+		>
+			<SyCheckbox
+				v-for="opt in props.options"
+				:id="opt.id"
+				:key="opt.value"
+				:model-value="isOptionChecked(opt.value)"
+				:label="opt.label"
+				:color="checkboxColor"
+				:disabled="props.disabled || opt.disabled"
+				:readonly="props.readonly || opt.readonly"
+				:name="opt.name || props.name"
+				:aria-label="opt.ariaLabel || `Option ${opt.value}`"
+				:title="opt.title"
+				:hide-details="props.hideDetails"
+				:density="props.density"
+				@update:model-value="() => toggleOption(opt.value)"
+				@blur="checkErrorOnBlur"
+			/>
+		</div>
+
+		<div
+			v-if="props.hideDetails !== true && (hasError || hasWarning || (hasSuccess && props.showSuccessMessages))"
+			class="v-input__details sy-checkbox-group__messages"
+		>
+			<VMessages
+				ref="messagesRef"
+				:active="hasError || hasWarning || (hasSuccess && props.showSuccessMessages)"
+				:messages="hasError ? errors : (hasWarning ? warnings : (hasSuccess && props.showSuccessMessages ? successes : []))"
+			/>
+		</div>
+
+		<span
+			v-if="requiredHintId && props.required && !props.ariaLabel && !computedAriaLabelledby"
+			:id="requiredHintId"
+			class="d-sr-only"
+		>
+			{{ locales.labelledbyMessage }} <span v-if="props.label">{{ props.label + (props.displayAsterisk ? '*' : '')
+			}}</span>.
+		</span>
+	</fieldset>
+</template>
+
+<style scoped>
+.sy-checkbox-group {
+	border: 0;
+}
+
+.sy-checkbox-group__label {
+	margin-bottom: 4px;
+	font-weight: 500;
+}
+
+:deep(.v-messages) {
+	opacity: 1;
+}
+
+.warning-field :deep(.v-messages__message) {
+	color: rgb(var(--v-theme-warning)) !important;
+}
+
+.error-field :deep(.v-messages__message) {
+	color: rgb(var(--v-theme-error)) !important;
+}
+
+.error-field :deep(.v-selection-control__input > .v-icon) {
+	opacity: 1 !important;
+}
+
+.success-field :deep(.v-messages__message) {
+	color: rgb(var(--v-theme-success)) !important;
+}
+
+:deep(.v-messages__message) {
+	animation: sy-messages-in 0.25s cubic-bezier(0.4, 0, 0.2, 1) !important;
+}
+
+@keyframes sy-messages-in {
+	from {
+		opacity: 0;
+		transform: translateY(-8px);
+	}
+
+	to {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+</style>

package/src/components/Customs/SyCheckBoxGroup/accessibilite/Accessibility.mdx

@@ -0,0 +1,243 @@
+import { Meta, Primary } from '@storybook/blocks';
+import * as SyCheckBoxGroupStories from '../SyCheckBoxGroup.stories.ts';
+import AccessibilityIcon from '@/common/imgs/accessibility-svgrepo-com.svg';
+import '@/stories/styles/shared.css';
+
+<Meta of={SyCheckBoxGroupStories} name="Accessibility" />
+
+<div className="accessibility-guide">
+	<div className="header">
+		<h1>Guide d'Accessibilité du Composant SyCheckBoxGroup</h1>
+	</div>
+
+	<div className="intro-section">
+		<img
+			src={AccessibilityIcon}
+			alt="Icône d'accessibilité"
+			className="accessibility-icon"
+		/>
+		<p className="intro-text">
+			Le composant SyCheckBoxGroup a été conçu en suivant rigoureusement les recommandations d'accessibilité du W3C,
+			notamment le modèle <a href="https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/" target="_blank" rel="noopener noreferrer">WAI-ARIA pour les cases à cocher</a>.
+			Ce guide détaille comment notre implémentation respecte ces standards et garantit une expérience utilisateur inclusive.
+		</p>
+	</div>
+
+	<div className="criteria-section">
+		<h2>Critères d'accessibilité respectés</h2>
+
+		<div className="criteria-card">
+			<div className="criteria-header">
+				<span className="criteria-icon">🔍</span>
+				<h3>Structure sémantique</h3>
+			</div>
+			<ul>
+				<li><strong>Regroupement</strong> : Les cases à cocher sont regroupées dans une structure cohérente (fieldset/legend ou équivalent).</li>
+				<li><strong>Étiquetage explicite</strong> : Le groupe dispose d’un libellé clair via la prop <code>label</code>.</li>
+				<li><strong>Association label / contrôle</strong> : Chaque option dispose d’un label associé à la case à cocher.</li>
+			</ul>
+		</div>
+
+		<div className="criteria-card">
+			<div className="criteria-header">
+				<span className="criteria-icon">⌨️</span>
+				<h3>Navigation clavier complète</h3>
+			</div>
+			<ul>
+				<li><strong>Touche Tab</strong> : Navigation séquentielle à travers les cases à cocher.</li>
+				<li><strong>Touche Espace</strong> : (Dé)cocher une option.</li>
+				<li><strong>Focus visible</strong> : Indication claire de l’élément actuellement focalisé.</li>
+			</ul>
+		</div>
+
+		<div className="criteria-card">
+			<div className="criteria-header">
+				<span className="criteria-icon">📱</span>
+				<h3>États et retours d'information</h3>
+			</div>
+			<ul>
+				<li><strong>État requis</strong> : Support du mode <code>required</code> et affichage d’un message d’erreur en cas de soumission invalide.</li>
+				<li><strong>États disabled / readonly</strong> : Les états sont communiqués visuellement et empêchent l’interaction selon le cas.</li>
+				<li><strong>Retour textuel</strong> : Les messages de validation sont affichés dans la zone dédiée aux détails.</li>
+			</ul>
+		</div>
+
+		<div className="criteria-card">
+			<div className="criteria-header">
+				<span className="criteria-icon">🎨</span>
+				<h3>Personnalisation accessible</h3>
+			</div>
+			<ul>
+				<li><strong>Densité ajustable</strong> : La prop <code>density</code> permet d’adapter l’espacement sans casser l’accessibilité.</li>
+				<li><strong>Couleurs</strong> : La prop <code>color</code> permet d’adapter l’apparence tout en conservant les états d’erreur (prioritaires).</li>
+			</ul>
+		</div>
+	</div>
+
+	<div className="demo-section">
+		<h2>Démonstration interactive</h2>
+		<p>
+			Explorez ci-dessous un exemple de SyCheckBoxGroup. Essayez de naviguer en utilisant uniquement votre clavier (Tab pour naviguer, Espace pour activer)
+			pour tester l'accessibilité.
+		</p>
+		<Primary />
+	</div>
+
+	<div className="best-practices">
+		<h2>Bonnes pratiques d'utilisation</h2>
+		<ul>
+			<li>Utilisez un libellé de groupe explicite et des libellés d’options concis.</li>
+			<li>Pour un groupe requis, expliquez clairement la contrainte (ex. « choisissez au moins une option »).</li>
+			<li>Évitez de baser le sens uniquement sur la couleur (toujours fournir un message textuel).</li>
+			<li>Assurez-vous que les zones cliquables restent confortables sur mobile.</li>
+		</ul>
+	</div>
+
+	<div className="resources-section">
+		<h2>Ressources supplémentaires</h2>
+		<ul>
+			<li><a href="https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/" target="_blank" rel="noopener noreferrer">Guide des pratiques d'auteur WAI-ARIA : Checkbox</a></li>
+			<li><a href="https://www.w3.org/WAI/WCAG21/quickref/" target="_blank" rel="noopener noreferrer">Référence rapide WCAG 2.1</a></li>
+			<li><a href="https://www.w3.org/TR/wai-aria-1.2/#checkbox" target="_blank" rel="noopener noreferrer">Spécification WAI-ARIA 1.2 : role checkbox</a></li>
+		</ul>
+	</div>
+</div>
+
+<style>
+{`
+  .accessibility-guide {
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 20px;
+    color: #333;
+  }
+
+  .intro-section {
+    display: flex;
+    align-items: center;
+    margin-bottom: 30px;
+    background-color: #f8f9fa;
+    padding: 20px;
+    border-radius: 8px;
+    border-left: 5px solid #0077cc;
+  }
+
+  .accessibility-icon {
+    width: 60px;
+    height: 60px;
+    margin-right: 20px;
+    flex-shrink: 0;
+  }
+
+  .intro-text {
+    font-size: 1.1em;
+    line-height: 1.6;
+    margin: 0;
+  }
+
+  .criteria-section {
+    margin-bottom: 40px;
+  }
+
+  .criteria-section h2,
+  .demo-section h2,
+  .best-practices h2,
+  .resources-section h2 {
+    border-bottom: 2px solid #eaecef;
+    padding-bottom: 10px;
+    margin-top: 30px;
+    margin-bottom: 20px;
+    color: #0077cc;
+  }
+
+  .criteria-card {
+    background-color: #fff;
+    border-radius: 8px;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+    padding: 20px;
+    margin-bottom: 20px;
+  }
+
+  .criteria-header {
+    display: flex;
+    align-items: center;
+    margin-bottom: 15px;
+  }
+
+  .criteria-icon {
+    font-size: 1.8em;
+    margin-right: 15px;
+  }
+
+  .criteria-header h3 {
+    margin: 0;
+    font-size: 1.3em;
+    color: #0077cc;
+  }
+
+  .criteria-card ul {
+    margin: 0;
+    padding-left: 20px;
+  }
+
+  .criteria-card li {
+    margin-bottom: 8px;
+    line-height: 1.5;
+  }
+
+  .demo-section {
+    background-color: #f8f9fa;
+    padding: 20px;
+    border-radius: 8px;
+    margin-bottom: 40px;
+  }
+
+  .best-practices {
+    background-color: #f5f5f5;
+    padding: 20px;
+    border-radius: 8px;
+    margin-bottom: 30px;
+  }
+
+  .best-practices ul {
+    padding-left: 20px;
+  }
+
+  .best-practices li {
+    margin-bottom: 10px;
+    line-height: 1.5;
+  }
+
+  .resources-section {
+    background-color: #f8f9fa;
+    padding: 20px;
+    border-radius: 8px;
+  }
+
+  .resources-section ul {
+    padding-left: 20px;
+  }
+
+  .resources-section li {
+    margin-bottom: 10px;
+  }
+
+  .resources-section a {
+    color: #0077cc;
+    text-decoration: none;
+  }
+
+  .resources-section a:hover {
+    text-decoration: underline;
+  }
+
+  code {
+    background-color: #f0f0f0;
+    padding: 2px 5px;
+    border-radius: 3px;
+    font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
+    font-size: 0.9em;
+  }
+`}
+</style>

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

@@ -0,0 +1,3 @@
+export const locales = {
+	labelledbyMessage: 'Sélectionner l\'option',
+}

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

@@ -0,0 +1,30 @@
+// @vitest-environment jsdom
+
+import { describe, it } from 'vitest'
+import { mount } from '@vue/test-utils'
+import { axe } from 'vitest-axe'
+import { assertNoA11yViolations } from '@tests/unit/accessibility/axeUtils'
+import SyCheckBoxGroup from '../SyCheckBoxGroup.vue'
+
+// Scénario d’accessibilité : groupe de cases à cocher requis avec label.
+
+describe('SyCheckBoxGroup – accessibility (axe)', () => {
+	it('has no obvious axe violations for required checkbox group', async () => {
+		const wrapper = mount(SyCheckBoxGroup, {
+			props: {
+				label: 'Choisissez une option',
+				modelValue: null,
+				required: true,
+				options: [
+					{ label: 'Option A', value: 'A', id: 'opt-a' },
+					{ label: 'Option B', value: 'B', id: 'opt-b' },
+				],
+			},
+		})
+
+		const results = await axe(wrapper.element as HTMLElement)
+		assertNoA11yViolations(results, 'SyCheckBoxGroup – required group', {
+			ignoreRules: ['region'],
+		})
+	})
+})