@cnamts/synapse 1.0.21 → 1.0.23

package/src/components/Customs/Selects/SySelect/tests/SySelect.spec.ts

@@ -965,4 +965,76 @@ describe('SySelect.vue', () => {
 			wrapper.unmount()
 		})
 	})
+
+	describe('keyboard navigation', () => {
+		it('navigates options with arrow keys', async () => {
+			const items = [
+				{ text: 'Option 1', value: '1' },
+				{ text: 'Option 2', value: '2' },
+				{ text: 'Option 3', value: '3' },
+			]
+			const wrapper = mount(SySelect, {
+				props: {
+					items,
+					modelValue: null,
+					textKey: 'text',
+					valueKey: 'value',
+				},
+				attachTo: document.body,
+			})
+
+			await wrapper.find('.v-field').trigger('click')
+			await wrapper.vm.$nextTick()
+
+			const list = wrapper.findComponent(VList).find('.v-list')!
+
+			// expect the first item to be highlighted
+			const firstItem = wrapper.findComponent(VList).findAll('.v-list-item').at(0)
+
+			await wrapper.vm.$nextTick()
+			expect(firstItem?.classes()).toContain('active')
+			expect(firstItem?.attributes('tabindex')).toBe('0')
+
+			await list.trigger('keydown.down')
+			await wrapper.vm.$nextTick()
+
+			const secondItem = wrapper.findComponent(VList).findAll('.v-list-item').at(1)
+			expect(firstItem?.classes()).not.toContain('keyboard-focused')
+			expect(firstItem?.attributes('tabindex')).toBe('-1')
+			expect(secondItem?.classes()).toContain('keyboard-focused')
+			expect(secondItem?.attributes('tabindex')).toBe('0')
+
+			wrapper.unmount()
+		})
+
+		it('selects an option with enter key', async () => {
+			const items = [
+				{ text: 'Option 1', value: '1' },
+				{ text: 'Option 2', value: '2' },
+				{ text: 'Option 3', value: '3' },
+			]
+			const wrapper = mount(SySelect, {
+				props: {
+					items,
+					modelValue: null,
+					textKey: 'text',
+					valueKey: 'value',
+				},
+				attachTo: document.body,
+			})
+
+			await wrapper.find('.v-field').trigger('click')
+			await wrapper.vm.$nextTick()
+
+			const list = wrapper.findComponent(VList).find('.v-list')!
+			await list.trigger('keydown.down')
+			await wrapper.vm.$nextTick()
+			await list.trigger('keydown.enter')
+			await wrapper.vm.$nextTick()
+
+			expect(wrapper.emitted()['update:modelValue']).toEqual([['2']])
+
+			wrapper.unmount()
+		})
+	})
 })

package/src/components/Customs/SyCheckbox/SyCheckbox.vue

@@ -206,7 +206,7 @@
 
 	const ariaChecked = computed(() => {
 		if (internalIndeterminate.value) return 'mixed'
-		return model.value ? 'true' : 'false'
+		return model.value ? 'true' : undefined
 	})
 
 	const labelColor = computed(() => {

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

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { describe, it } from 'vitest'
+import { describe, it, expect } from 'vitest'
 import { mount } from '@vue/test-utils'
 import { axe } from 'vitest-axe'
 import { assertNoA11yViolations } from '@tests/unit/accessibility/axeUtils'
@@ -19,7 +19,7 @@ describe('SyIcon – accessibility (axe)', () => {
 			global: {
 				stubs: {
 					'v-icon': {
-						template: '<span class="v-icon" role="img" :aria-label="ariaLabel"><slot></slot></span>',
+						template: '<span class="v-icon" :role="role" :aria-label="ariaLabel" :aria-hidden="ariaHidden"><svg><slot></slot></svg></span>',
 						props: ['color', 'size', 'role', 'aria-hidden', 'aria-label'],
 					},
 				},
@@ -34,4 +34,33 @@ describe('SyIcon – accessibility (axe)', () => {
 			ignoreRules: ['region'],
 		})
 	})
+
+	it('hides decorative icons from assistive tech (aria-hidden)', async () => {
+		const wrapper = mount(SyIcon, {
+			props: {
+				icon: 'mdi-star',
+				decorative: true,
+			},
+			global: {
+				stubs: {
+					'v-icon': {
+						template: '<span class="v-icon" :role="role" :aria-label="ariaLabel" :aria-hidden="ariaHidden"><svg><slot></slot></svg></span>',
+						props: ['color', 'size', 'role', 'aria-hidden', 'aria-label'],
+					},
+				},
+				directives: {
+					'rgaa-svg-fix': () => {},
+				},
+			},
+		})
+
+		const iconEl = wrapper.find('.v-icon')
+		expect(iconEl.attributes('aria-hidden')).toBe('true')
+
+		// Axe should not report a visible control with missing label since it is hidden
+		const results = await axe(wrapper.element as HTMLElement)
+		assertNoA11yViolations(results, 'SyIcon – decorative icon hidden from AT', {
+			ignoreRules: ['region'],
+		})
+	})
 })

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

@@ -34,10 +34,12 @@
 		size?: string
 	}>()
 
+	const resolvedDecorative = computed(() => props.decorative ?? true)
+
 	// Configuration pour la directive rgaaSvgFix
 	const rgaaSvgFixConfig = computed(() => {
 		return {
-			isDecorative: props.decorative,
+			isDecorative: resolvedDecorative.value,
 			role: props.role,
 			autoDetectButton: props.autoDetectButton,
 		}
@@ -45,16 +47,16 @@
 
 	// Vérification à l'initialisation du composant
 	onMounted(() => {
-		checkAccessibility(props.icon, props.decorative, props.label)
+		checkAccessibility(props.icon, resolvedDecorative.value, props.label)
 	})
 
 	// Vérification à chaque changement des props concernées
 	watch(
 		[() => props.decorative, () => props.label, () => props.icon],
-		([decorative, label, icon]) => {
+		([, label, icon]) => {
 			checkAccessibility(
 				icon as string,
-				decorative as boolean | undefined,
+				resolvedDecorative.value,
 				label as string | undefined,
 			)
 		},
@@ -66,7 +68,9 @@
 		v-rgaa-svg-fix="rgaaSvgFixConfig"
 		:color="props.color"
 		:size="props.size"
-		:aria-label="props.label"
+		:role="props.role"
+		:aria-label="resolvedDecorative ? undefined : props.label"
+		: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'],
+		})
+	})
+})