Skip to content

Latest commit

 

History

History
167 lines (114 loc) · 6.09 KB

README.md

File metadata and controls

167 lines (114 loc) · 6.09 KB
Raw

A11Y Dropdown Component

Introduction

a11y-dropdown-component est une librairie écrite en JavaScript natif permettant de configurer facilement des menus déroulants accessibles.

Cette librairie respecte l'ensemble des critères d'accessibilité définis par WAI-ARIA tout en étant très légère (1.1 Ko minifiée et gzippée) et simple à configurer.

Fonctionnalités

  • Presser la touche Enter ou Space sur le bouton d'appel d'un menu replié, déplie le menu déroulant.
  • Presser la touche Enter ou Space sur le bouton d'appel d'un menu déplié, ferme le menu déroulant.
  • Presser la touche Escape, ferme le menu déroulant et déplace le focus clavier sur le bouton d'appel. (Un clic en dehors du menu déroulant, ferme également celui-ci).
  • Presser la touche Up Arrow sur le bouton d'appel ou sur un élément du menu, déplace le focus clavier sur l'élément précédent s'il existe, sinon sur le dernier élément du menu déroulant.
  • Presser la touche Down Arrow sur le bouton d'appel ou sur un élément du menu, déplace le focus clavier sur l'élément suivant s'il existe, sinon sur le premier élément du menu déroulant.
  • Presser la touche Home sur le bouton d'appel ou sur un élément du menu, déplace le focus clavier sur le premier élément du menu déroulant.
  • Presser la touche End sur le bouton d'appel ou sur un élément du menu, déplace le focus clavier sur le dernier élément du menu déroulant.

Installation

  • via npm : npm install a11y-dropdown-component
  • via yarn : yarn add a11y-dropdown-component
  • via jsDelivr : <script src="https://cdn.jsdelivr.net/npm/a11y-dropdown-component/dist/a11y-dropdown-component.min.js"></script>

Utilisation

1. Structure HTML du bouton d'appel

L'attribut de données data-component="dropdown" permet d'instancier un nouveau menu déroulant :

<button type="button" id="trigger" data-component="dropdown" data-target="dropdown-menu">...</button>

Attributs obligatoires :

  • id="trigger-ID" : Identifie le bouton d'appel.
  • data-target="dropdown-ID" : Associe le bouton d'appel à son menu déroulant.

Attribut facultatif :

  • data-open="true" : Ouvre le menu déroulant lors de son initialisation.
    Cet attribut de données générera l'attribut ARIA aria-expanded="true"

2. Structure HTML du menu déroulant

La librairie génère à la volée les attributs nécessaires afin de répondre aux critères d'accessibilité définis par WAI-ARIA.

Structure initiale :

<ul id="dropdown-menu" class="c-dropdown__menu">
  <li data-item><a href="#">Link 1</a></li>
  <li data-item><a href="#">Link 2</a></li>
  <li data-item><a href="#">Link 3</a></li>
</ul>

Structure finale (après le chargement du script) :

<ul id="dropdown-menu" class="c-dropdown__menu" role="menu" aria-labelledby="trigger" tabindex="-1">
  <li data-item role="none"><a href="#" role="menuitem" tabindex="-1">Link 1</a></li>
  <li data-item role="none"><a href="#" role="menuitem" tabindex="-1">Link 2</a></li>
  <li data-item role="none"><a href="#" role="menuitem" tabindex="-1">Link 3</a></li>
</ul>

3. Ajout de la librairie JavaScript

Vous pouvez importer directement a11y-dropdown-component dans votre projet JavaScript en utilisant une syntaxe ES6 (ES2015) ou CommonJS :

import Dropdowns from 'a11y-dropdown-component'; // es6 module
const Dropdowns = require('a11y-dropdown-component').default; // commonjs module

4. Instanciation JavaScript

L'instanciation de tous les menus déroulants possédant l'attribut de données data-component="dropdown" se fait simplement par la méthode init() :

Dropdowns.init();

5. Événements JavaScript

En cas de besoin, vous pouvez déclencher le rendu d'un ou plusieurs menus déroulants directement en JavaScript grâce à la méthode render('trigger-ID') :

Dropdowns.render('trigger-js');

Paramètre facultatif :

  • isOpen: true : Déclenche l'ouverture du menu déroulant.
Dropdowns.render('trigger-js', {
  isOpen: true,
});

Suppression d'un menu déroulant instancié :

Vous pouvez supprimer le rendu d'un ou plusieurs menus déroulants grâce à la méthode destroy('trigger-ID') :

Dropdowns.destroy('trigger-js');

6. Styles CSS

a11y-dropdown-component a fait le choix de ne pas embarquer de styles CSS par défaut.
Vous êtes donc libres d'utiliser les styles que vous souhaitez !

Néanmoins, nous recommandons au minimum ce style nécessaire à l'ouverture et à la fermeture d'un menu déroulant :

.c-dropdown__menu[aria-hidden="true"] {
  display: none;
}

Si vous désirez utiliser des styles CSS par défaut, vous pouvez consulter le fichier main.css de la démo disponible ici

Contribution

Si vous désirez contribuer à ce projet, rien de plus simple, suivez ces quelques étapes ! 😚
a11y-dropdown-component suit les standards de développement JavaScript ES2015.

Environnement de développement

  1. Clonez le dépôt GitHub : $git clone https://github.com/jonathanlevaillant/a11y-dropdown-component.git
  2. Installez le gestionnaire de packages yarn
  3. Installez les dépendances de développement : yarn start
  4. Lancez le projet (watch) : yarn dev
  5. Créez une pull-request 👌

D'autres librairies accessibles ?

Créateur

Jonathan Levaillant

Licence

Ce projet est sous licence MIT.