@cnamts/synapse 1.0.22 → 1.0.24

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

@@ -5,6 +5,7 @@ import SyTextField from '@/components/Customs/SyTextField/SyTextField.vue'
 import SyCheckbox from '@/components/Customs/SyCheckbox/SyCheckbox.vue'
 import SySelect from '@/components/Customs/Selects/SySelect/SySelect.vue'
 import { VBtn } from 'vuetify/components'
+import { fn } from '@storybook/test'
 
 export default {
 	title: 'Composants/Formulaires/SyForm',
@@ -42,6 +43,10 @@ export default {
 type Story = StoryObj<typeof SyForm>
 
 export const Basic: Story = {
+	args: {
+		onReset: fn(),
+		onSubmit: fn(),
+	},
 	render: args => ({
 		components: { SyForm, SyTextField, VBtn },
 		setup() {
@@ -126,6 +131,11 @@ const onSubmit = (event: { isValid: boolean }) => {
 }
 
 export const CustomValidation: Story = {
+	args: {
+		validateOnSubmit: false,
+		onReset: fn(),
+		onSubmit: fn(),
+	},
 	render: args => ({
 		components: { SyForm, SyTextField, VBtn },
 		setup() {
@@ -142,7 +152,7 @@ export const CustomValidation: Story = {
 
 			const confirmPasswordRules = computed(() => [
 				{ type: 'custom', options: {
-					validate: value => value === password.value || 'Les mots de passe ne correspondent pas',
+					validate: (value: string) => value === password.value,
 					message: 'Les mots de passe ne correspondent pas',
 				} },
 				{ type: 'required', options: { message: 'Veuillez confirmer le mot de passe' } },
@@ -150,7 +160,7 @@ export const CustomValidation: Story = {
 
 			const submitForm = async (e: { isValid: boolean }) => {
 				if (e.isValid) {
-					alert('Inscription réussie !')
+					alert('Inscription réussie ! (validate on submit = ' + args.validateOnSubmit + ')')
 				}
 				else {
 					alert('Formulaire invalide, veuillez corriger les erreurs.')
@@ -171,7 +181,7 @@ export const CustomValidation: Story = {
 		},
 		template: `
       <div>
-        <SyForm ref="form" v-bind="args" @submit="submitForm" :validate-on-submit="false">
+        <SyForm ref="form" v-bind="args" @submit="submitForm" :validate-on-submit="args.validateOnSubmit">
           <div class="d-flex flex-column gap-4">
             <SyTextField v-model="username" label="Nom d'utilisateur" required class="mb-2" />
             <SyTextField v-model="password" label="Mot de passe" type="password" :custom-rules="passwordRules" class="mb-2" />
@@ -238,7 +248,7 @@ const passwordRules = computed(() => [
 
 const confirmPasswordRules = computed(() => [
 	{ type: 'custom', options: {
-		validate: value => value === password.value || 'Les mots de passe ne correspondent pas',
+		validate: (value: string) => value === password.value,
 		message: 'Les mots de passe ne correspondent pas',
 	} },
 	{ type: 'required', options: { message: 'Veuillez confirmer le mot de passe' } },
@@ -267,6 +277,10 @@ const validateManually = () => {
 }
 
 export const MixedFields: Story = {
+	args: {
+		onReset: fn(),
+		onSubmit: fn(),
+	},
 	render: args => ({
 		components: { SyForm, SyTextField, SySelect, SyCheckbox, VBtn },
 		setup() {
@@ -372,6 +386,9 @@ export const MixedFields: Story = {
 				if (event.isValid) {
 					alert('Formulaire valide ! Données: ' + JSON.stringify(formData.value))
 				}
+				else {
+					alert('Formulaire invalide, veuillez corriger les erreurs.')
+				}
 			}
 		</script>
 `,
@@ -381,6 +398,10 @@ export const MixedFields: Story = {
 }
 
 export const Reset: Story = {
+	args: {
+		onReset: fn(),
+		onSubmit: fn(),
+	},
 	render: args => ({
 		components: { SyForm, SyTextField, VBtn },
 		setup() {
@@ -408,7 +429,12 @@ export const Reset: Story = {
 				form.value?.clearValidation()
 			}
 
-			return { name, email, emailRules, form, submitForm, clearAll, args }
+			function onFormReset() {
+				alert('Formulaire réinitialisé !')
+				args.onReset?.()
+			}
+
+			return { name, email, emailRules, form, submitForm, clearAll, onFormReset, args }
 		},
 		template: `
       <SyForm ref="form" v-bind="args" @submit="submitForm" @reset="onFormReset">

package/src/components/Customs/SyIcon/SyIcon.vue

@@ -70,7 +70,7 @@
 		:size="props.size"
 		:role="props.role"
 		:aria-label="resolvedDecorative ? undefined : props.label"
-		:aria-hidden="resolvedDecorative ? 'true' : undefined"
+		:aria-hidden="resolvedDecorative ? true : undefined"
 	>
 		{{ icon }}
 	</v-icon>

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

@@ -0,0 +1,20 @@
+// @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 SyIcon from '../SyIcon.vue'
+
+describe('SyIcon – accessibility (axe)', () => {
+	it('has no obvious axe violations', async () => {
+		const wrapper = mount(SyIcon, {
+			props: {
+				icon: 'home',
+			},
+		})
+
+		const results = await axe(wrapper.element as HTMLElement)
+		assertNoA11yViolations(results, 'SyIcon – default state')
+	})
+})

package/src/components/Customs/SyIconButton/SyIconButton.mdx

@@ -0,0 +1,46 @@
+import { Meta, Primary, Controls, Canvas } from '@storybook/blocks';
+import * as SyIconButtonStories from './SyIconButton.stories';
+import '@/stories/styles/shared.css';
+
+<Meta of={SyIconButtonStories} />
+
+<div className="header">
+  <h1>SyIconButton</h1>
+  <p>Le composant `SyIconButton` est un bouton icône qui combine `v-btn` de Vuetify et `SyIcon` en garantissant l'accessibilité via une prop `label` obligatoire portée par `aria-label`.</p>
+</div>
+
+<Canvas of={SyIconButtonStories.Default} />
+
+# API
+
+<Controls of={SyIconButtonStories.Default} />
+
+
+# Accessibilité
+
+Le composant `SyIconButton` gère automatiquement les attributs ARIA :
+
+- **Label obligatoire** : la prop `label` est portée par le bouton via `aria-label` — elle constitue le nom accessible du bouton
+- **Icône décorative** : `SyIcon` interne reçoit `:decorative="true"` car le bouton porte déjà le nom accessible via `aria-label` — l'icône est donc ignorée par les lecteurs d'écran
+
+> **Important :** Le `label` doit décrire l'**action** du bouton et non l'icône elle-même (ex. _"Fermer"_ plutôt que _"Croix"_). Ne jamais fournir un `label` vide.
+
+Pour plus d'informations sur l'accessibilité, consultez la [page dédiée à l'accessibilité](?path=/docs/customs-syiconbutton--accessibility).
+
+## Exemples
+
+### Bouton icône par défaut
+
+<Canvas of={SyIconButtonStories.Default} />
+
+### Bouton icône désactivé
+
+<Canvas of={SyIconButtonStories.Disabled} />
+
+### Bouton icône avec couleur
+
+<Canvas of={SyIconButtonStories.WithColor} />
+
+### Bouton icône avec taille personnalisée
+
+<Canvas of={SyIconButtonStories.WithSize} />

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

@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+import { fn } from '@storybook/test'
+import SyIconButton from './SyIconButton.vue'
+import { mdiClose, mdiAlert, mdiMagnify } from '@mdi/js'
+
+const meta = {
+	title: 'Composants/Boutons/SyIconButton',
+	component: SyIconButton,
+	decorators: [
+		() => ({
+			template: '<div style="padding: 20px;"><story/></div>',
+		}),
+	],
+	argTypes: {
+		'icon': {
+			control: { type: 'text' },
+			description: 'Nom de l\'icône à afficher (format Material Design Icons)',
+		},
+		'label': {
+			control: { type: 'text' },
+			description: 'Texte accessible obligatoire porté par `aria-label` sur le bouton',
+		},
+		'color': {
+			control: { type: 'text' },
+			description: 'Couleur de l\'icône (nom de couleur Vuetify)',
+		},
+		'size': {
+			options: ['x-small', 'small', 'default', 'large', 'x-large'],
+			control: {
+				type: 'select',
+			},
+			description: 'Taille du bouton et de l\'icône',
+			default: 'default',
+		},
+		'disabled': {
+			control: { type: 'boolean' },
+			description: 'Désactive le bouton',
+			default: false,
+		},
+		'onClick-icon-button': {
+			action: 'click-icon-button',
+			description: 'Événement émis lors du clic sur le bouton',
+		},
+		'variant': {
+			options: ['flat', 'elevated', 'tonal', 'outlined', 'text', 'plain'],
+			control: { type: 'select' },
+			description: 'Variante visuelle du bouton',
+		},
+	},
+} satisfies Meta<typeof SyIconButton>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+	parameters: {
+		sourceCode: [
+			{
+				name: 'Template',
+				language: 'vue',
+				code: `
+				<template>
+					<SyIconButton :icon="mdiClose" label="Fermer" @click-icon-button="handleClick" />
+				</template>`,
+			},
+		],
+	},
+	args: {
+		'icon': mdiClose,
+		'label': 'Fermer',
+		'onClick-icon-button': fn(),
+	},
+	render: args => ({
+		components: { SyIconButton },
+		setup() {
+			const handleClick = () => {
+				alert('Bouton cliqué !')
+			}
+			return { args, mdiClose, handleClick }
+		},
+		template: `
+			<div class="pa-4">
+				<SyIconButton v-bind="args" @click-icon-button="handleClick" />
+			</div>
+		`,
+	}),
+}
+
+export const Disabled: Story = {
+	parameters: {
+		sourceCode: [
+			{
+				name: 'Template',
+				language: 'vue',
+				code: `
+				<template>
+					<SyIconButton :icon="mdiClose" label="Fermer" :disabled="true" />
+				</template>`,
+			},
+		],
+	},
+	args: {
+		'icon': mdiClose,
+		'label': 'Fermer',
+		'disabled': true,
+		'onClick-icon-button': fn(),
+	},
+	render: args => ({
+		components: { SyIconButton },
+		setup() {
+			return { args, mdiClose }
+		},
+		template: `
+			<div class="pa-4">
+				<SyIconButton v-bind="args" />
+			</div>
+		`,
+	}),
+}
+
+export const WithColor: Story = {
+	parameters: {
+		sourceCode: [
+			{
+				name: 'Template',
+				language: 'vue',
+				code: `
+				<template>
+					<SyIconButton :icon="mdiAlert" label="Alerte" color="red" />
+				</template>`,
+			},
+		],
+	},
+	args: {
+		'icon': mdiAlert,
+		'label': 'Alerte',
+		'color': 'red',
+		'onClick-icon-button': fn(),
+	},
+	render: args => ({
+		components: { SyIconButton },
+		setup() {
+			return { args, mdiAlert }
+		},
+		template: `
+			<div class="pa-4">
+				<SyIconButton v-bind="args" />
+			</div>
+		`,
+	}),
+}
+
+export const WithSize: Story = {
+	parameters: {
+		sourceCode: [
+			{
+				name: 'Template',
+				language: 'vue',
+				code: `
+				<template>
+					<SyIconButton :icon="mdiMagnify" label="Rechercher" size="small" />
+				</template>`,
+			},
+		],
+	},
+	args: {
+		'icon': mdiMagnify,
+		'label': 'Rechercher',
+		'onClick-icon-button': fn(),
+	},
+	render: args => ({
+		components: { SyIconButton },
+		setup() {
+			const sizes = ['x-small', 'small', 'default', 'large', 'x-large']
+			return { args, mdiMagnify, sizes }
+		},
+		template: `
+			<div class="pa-4 d-flex align-center ga-4">
+				<SyIconButton v-for="size in sizes" :key="size" v-bind="args" :size="size" />
+			</div>
+		`,
+	}),
+}

package/src/components/Customs/SyIconButton/SyIconButton.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+	import type { IconValue } from 'vuetify/lib/composables/icons.mjs'
+	import SyIcon from '../SyIcon/SyIcon.vue'
+
+	type Size = 'x-small' | 'small' | 'default' | 'large' | 'x-large'
+	type Variant = 'flat' | 'text' | 'elevated' | 'tonal' | 'outlined' | 'plain'
+	type Color = 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info' | (string & {})
+
+	const props = defineProps<{
+		icon: IconValue
+		label: string
+		color?: Color
+		size?: Size
+		disabled?: boolean
+		variant?: Variant
+	}>()
+
+	defineEmits<{ 'click-icon-button': [] }>()
+</script>
+
+<template>
+	<v-btn
+		:disabled="props.disabled"
+		:aria-label="props.label"
+		:variant="props.variant ?? 'text'"
+		:size="props.size"
+		class="rounded-circle"
+		icon
+		@click="$emit('click-icon-button')"
+	>
+		<SyIcon
+			:icon="props.icon"
+			:size="props.size"
+			:color="props.color"
+			:decorative="true"
+		/>
+	</v-btn>
+</template>

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

@@ -0,0 +1,64 @@
+import { Meta, Primary } from '@storybook/blocks';
+import * as SyIconButtonStories from '../SyIconButton.stories';
+import AccessibilityIcon from '@/common/imgs/accessibility-svgrepo-com.svg';
+import {
+	AccessibilityGuideLayout,
+	CriteriaSection,
+	CriteriaCard,
+	DemoSection,
+	BestPracticesSection,
+	ResourcesSection,
+} from '@/stories/accessibility/AccessibilityGuideLayout.mdx';
+
+<Meta of={SyIconButtonStories} />
+
+<AccessibilityGuideLayout
+	componentName="SyIconButton"
+	iconSrc={AccessibilityIcon}
+>
+	<CriteriaSection>
+		<CriteriaCard icon="🔍" title="Structure sémantique">
+			<ul>
+				<li><strong>Élément bouton</strong> : le composant repose sur un <code>v-btn</code> qui génère un élément <code>&lt;button&gt;</code> natif — il est nativement reconnu par les lecteurs d'écran et les outils d'assistance</li>
+				<li><strong>Prop <code>label</code> obligatoire</strong> : la prop <code>label</code> est requise et est portée par le bouton via <code>aria-label</code> — elle constitue le nom accessible du bouton</li>
+				<li><strong>Icône décorative</strong> : le composant <code>SyIcon</code> interne reçoit <code>:decorative="true"</code> — l'icône est ignorée par les lecteurs d'écran car le bouton porte déjà le nom accessible via <code>aria-label</code></li>
+				<li><strong>Prop <code>disabled</code></strong> : lorsque <code>disabled</code> est à <code>true</code>, l'attribut <code>disabled</code> est appliqué nativement sur le <code>&lt;button&gt;</code>, le rendant inaccessible au clavier et annoncé comme désactivé par les lecteurs d'écran</li>
+				<li><strong>Prop <code>variant</code></strong> : par défaut à <code>text</code> — les autres variantes (<code>outlined</code>, <code>tonal</code>, etc.) n'affectent pas l'accessibilité du bouton</li>
+			</ul>
+		</CriteriaCard>
+
+		<CriteriaCard icon="⌨️" title="Navigation clavier">
+			<ul>
+				<li><strong>Focusable</strong> : le bouton est naturellement focusable via <kbd>Tab</kbd> grâce à l'élément <code>&lt;button&gt;</code> natif</li>
+				<li><strong>Activation</strong> : le bouton peut être activé via <kbd>Entrée</kbd> ou <kbd>Espace</kbd> nativement</li>
+				<li><strong>État désactivé</strong> : lorsque <code>disabled</code> est à <code>true</code>, le bouton est retiré de l'ordre de tabulation et ne peut pas être activé au clavier</li>
+				<li><strong>Événement</strong> : le composant émet <code>click-icon-button</code> au clic ou à l'activation clavier</li>
+			</ul>
+		</CriteriaCard>
+	</CriteriaSection>
+
+	<DemoSection componentName="SyIconButton">
+		<Primary />
+	</DemoSection>
+
+	<BestPracticesSection>
+		<ul>
+			<li>La prop <code>label</code> est <strong>obligatoire</strong> — sans elle, le bouton icône n'a pas de nom accessible et sera incompréhensible pour les utilisateurs de lecteurs d'écran</li>
+			<li>Le <code>label</code> doit décrire l'<strong>action</strong> du bouton et non l'icône elle-même (ex. <em>"Fermer"</em> plutôt que <em>"Croix"</em>)</li>
+			<li>Ne jamais fournir un <code>label</code> vide (<code>""</code>) — cela rendrait le bouton inaccessible</li>
+			<li>Utiliser <code>disabled</code> plutôt que de masquer le bouton lorsqu'il est temporairement indisponible, afin de préserver la cohérence de la mise en page</li>
+			<li>Ne pas ajouter d'<code>aria-label</code> supplémentaire sur le composant parent — celui du <code>v-btn</code> est suffisant</li>
+			<li>La prop <code>variant</code> ne doit pas être choisie pour des raisons d'accessibilité — s'assurer que le contraste reste suffisant quelle que soit la variante utilisée (WCAG 1.4.3)</li>
+		</ul>
+	</BestPracticesSection>
+
+	<ResourcesSection>
+		<ul>
+			<li><a href="https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html" target="_blank" style={{ color: '#0C41BD' }}>WCAG 4.1.2 – Name, Role, Value</a></li>
+			<li><a href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html" target="_blank" style={{ color: '#0C41BD' }}>WCAG 1.1.1 – Non-text Content</a></li>
+			<li><a href="https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html" target="_blank" style={{ color: '#0C41BD' }}>WCAG 2.1.1 – Keyboard</a></li>
+			<li><a href="https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html" target="_blank" style={{ color: '#0C41BD' }}>WCAG 1.4.3 – Contrast (Minimum)</a></li>
+			<li><a href="https://www.w3.org/WAI/ARIA/apg/patterns/button/" target="_blank" style={{ color: '#0C41BD' }}>ARIA Authoring Practices – Button Pattern</a></li>
+		</ul>
+	</ResourcesSection>
+</AccessibilityGuideLayout>

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

@@ -0,0 +1,87 @@
+// @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 SyIconButton from '../SyIconButton.vue'
+
+const globalStubs = {
+	global: {
+		stubs: {
+			'v-btn': {
+				template: '<button :aria-label="ariaLabel" :disabled="disabled"><slot></slot></button>',
+				props: ['ariaLabel', 'disabled', 'size', 'variant', 'icon'],
+			},
+			'SyIcon': {
+				template: '<span class="sy-icon" :aria-hidden="decorative ? true : undefined"></span>',
+				props: ['icon', 'color', 'size', 'decorative'],
+			},
+		},
+	},
+}
+
+describe('SyIconButton – accessibility (axe)', () => {
+	it('has no obvious axe violations in default state', async () => {
+		const wrapper = mount(SyIconButton, {
+			props: {
+				icon: 'mdi-close',
+				label: 'Fermer',
+			},
+			...globalStubs,
+		})
+
+		const results = await axe(wrapper.element as HTMLElement)
+		assertNoA11yViolations(results, 'SyIconButton – default state', {
+			ignoreRules: ['region'],
+		})
+	})
+
+	it('has no obvious axe violations when disabled', async () => {
+		const wrapper = mount(SyIconButton, {
+			props: {
+				icon: 'mdi-close',
+				label: 'Fermer',
+				disabled: true,
+			},
+			...globalStubs,
+		})
+
+		const results = await axe(wrapper.element as HTMLElement)
+		assertNoA11yViolations(results, 'SyIconButton – disabled', {
+			ignoreRules: ['region'],
+		})
+	})
+
+	it('has no obvious axe violations with color and size', async () => {
+		const wrapper = mount(SyIconButton, {
+			props: {
+				icon: 'mdi-alert',
+				label: 'Alerte importante',
+				color: 'primary',
+				size: 'large',
+			},
+			...globalStubs,
+		})
+
+		const results = await axe(wrapper.element as HTMLElement)
+		assertNoA11yViolations(results, 'SyIconButton – color and size', {
+			ignoreRules: ['region'],
+		})
+	})
+
+	it('has aria-label on the button', async () => {
+		const wrapper = mount(SyIconButton, {
+			props: {
+				icon: 'mdi-close',
+				label: 'Fermer',
+			},
+			...globalStubs,
+		})
+
+		const results = await axe(wrapper.element as HTMLElement)
+
+		assertNoA11yViolations(results, 'SyIconButton – aria-label on button', {
+			ignoreRules: ['region'],
+		})
+	})
+})