@conciergerie-dev/select-a11y

Select-a11y

select-a11y transforms selects (multiple or not) into suggestions list with search input. It is compliant with Web Content Accessibility Guidelines (WCAG) and General Accessibility Framework for Administrations (Référentiel général d'accessibilité pour les administrations - RGAA).

This fork is based on the original select-a11y from Pidila.

To see the demo, three solutions are available:

• view the Pidila online demo ;
• download or clone this repository, then open the file /public/index.html ;
• install locally by cloning the repository, and then running the commands $ npm install then $ gulp dev.

References

• https://select2.github.io/examples.html
• https://a11y.nicolas-hoffmann.net/autocomplet-list/
• http://pidila.gitlab.io/select-a11y/

Use

All you need is the files in the dist/ directory.

The source files are in the src/ directory.

• Call the dist/main.js script in the bottom of your page, just before the body closing tag, or compile the dist/module.js with your others scripts.

• Add the css or scss in your style files. You can retrieve dist/select-a11y.css, an already compiled version.

To be transformed by select-a11y, the fastest way is to add the data-select-a11y attribute on the select tag you want to transform.

Code sample

<!-- select simple -->
<div class="form-group">
  <label for="select-option">Is your website…</label>
  <select class="form-control" id="select-option" data-select-a11y>
      <option>Perceivable</option>
      <option>Operable</option>
      <option>Understandable</option>
      <option>Robust</option>
  </select>
</div>

<!-- select multiple -->
<div class="form-group">
  <label for="select-element">What do you want to do today?</label>
  <select class="form-control" id="select-element" multiple data-select-a11y data-placeholder="Search in list">
      <option>Sleeping</option>
      <option>Climbing trees</option>
      <option>Knitting</option>
      <option selected>Dancing with unicorns</option>
      <option>Dreaming</option>
  </select>
</div>

Then, add the following JavaScript code in one of your file (that must be after select-a11y script):

var selects = document.querySelectorAll('select[data-select-a11y]');

var selectA11ys = Array.prototype.map.call(selects, function(select){
  return new Select(select);
});

The default texts used for accessibility can be changed. When creating a new select a11y, you can pass an object containing the text property as a second parameter:

var selects = document.querySelectorAll('select[data-select-a11y]');

var selectA11ys = Array.prototype.map.call(selects, function(select){
  new Select(select, {
    text:{
      help: 'Utilisez la tabulation (ou la touche flèche du bas) pour naviguer dans la liste des suggestions',
      placeholder: 'Rechercher dans la liste',
      noResult: 'Aucun résultat',
      results: '{x} suggestion(s) disponibles',
      deleteItem: 'Supprimer {t}',
      delete: 'Supprimer'
    }
  })
});

The texts in the example are the default texts used in the script.

Contribute

This project is under Test Driven Development with tape.

Requisite: Node.js 10.x, npm, npm gulp 3.x globally installed.

Installation and development

After cloning this repository, install dependencies:

$ npm install

Display locally (localhost:3000)

$ gulp

This task is a combination of the gulp build (compilation of sources and sending to the demo directory) and gulp dev (launching the server to display the page locally and recompiling sources on the fly if modified) tasks.

Run tests

$ npm test

Content of the repository

• public/ : demo page and its assets
  • assets/css : the compiled css
  • assets/img : the images (only used for demo)
  • assets/scripts : the select-a11y.js script and instantiation for the demo in main.js
  • assets/scss : sass sources for the demo page (style.scss imports styles dedicated to select-a11y + demo specific styles)
  • index.html : html source of the demo page
• src/ : source files (js and sass)
• tests/ : index.js to run the tests

Important note: do not directly modify the assets/scripts/select-a11y.js file or the assets/css/select-a11y.css file : they are generated by the build tasks.

What can I do to help?

• close issues
• testing and report issues
• suggest enhancement
• translate documentation in english
• enhance documentation in english or in french
• say thank you if you use it :)

Authors

Developpers and reviewers: Alain Batifol, Thomas Beduneau, Nicolas Bovorasmy, Anne Cavalier, Laurent Dutheil, Lucile Houdinet, Aurélien Lévy, Hugues Moreno - For the DILA, Direction de l'information légale et administrative.

License

MIT and CeCILL-B. Feel free to use it with one or the other.