Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/MelSumner/e-a11y-modal

A simple modal for accessible Ember applications.
https://github.com/MelSumner/e-a11y-modal

Last synced: about 1 month ago
JSON representation

A simple modal for accessible Ember applications.

Awesome Lists containing this project

README 

        
# Ember A11y Modal



This addon is intended to provide a simple, accessible, button-triggered modal. **For the user with a screen reader, either the modal will exist, or the rest of the page will exist, but never both at the same time.**



Please read _all_ of the design details before considering this modal for your application.



## Compatibility



* Ember.js v3.8.0 or above

* Ember CLI v3.8.0 or above



## Installation



Once this addon is published:



```

ember install e-a11y-modal

```



## Design



This modal was intentionally designed, and as a result may not fit into an existing application, if it has not previously considered accessibility and other best practices for front-end web design and development.  It is intended to be used with application development that follows the best practices of web design and development, and considers accessibility and the user experience from a practical perspective.



The following should be kept in mind when considering use of this addon:



* this addon uses the `inert` browser polyfill (see https://github.com/WICG/inert).

* the modal has a z-index of 10.

* when triggered, the initial focus placement is on the outside of the modal so the entire content can be read out. While this is a departure from current WCAG advice, many accessibility experts agree that this is better for user experience.

* the modal has a close button on the top right of the modal, but can also be closed by pressing the ESC key.

* when the modal is open, scrolling of content underneath the modal is prevented.

* when the modal is open, focus (either by TAB key or virtual cursor) will not reach the window underneath, but users will still be able to reach the URL bar (users can typically do this anyway by pressing the F6 key)



Addons & libraries used in making this addon:



* @ember/optional-features (to turn off the [wrapping `div`](https://github.com/emberjs/ember-optional-features) in an Ember App)

* wicg-inert to add the `inert` functionality

* ember-wormhole (this will be used until Ember provides this functionality in a native way)



## Usage



* authors must only use one modal per page.

* authors must put all application content inside a landmark element (see https://www.w3.org/WAI/PF/aria/roles#landmark_roles).

* authors must provide a value for `buttonText`.

* authors must provide a value for `modalHeadingText`.



### Example: standard usage



```hbs



  {{!-- Any modal content can go in this block --}}



```  



### Example: page layout



When the modal is triggered, the landmarks will be marked with `inert` and `aria-hidden="true"` will be applied, which will effectively trap the focus inside of the modal while it is open. For the user with a screen reader, **either** the modal will exist, **or** the rest of the page will exist, but never both at the same time.



```hbs



  

  

    {{!-- header block content here --}}

      

          {{!-- Any modal content can go in this block --}}

      

  

  

  

    {{!-- main block content here --}}

  



  

    {{!-- footer block content here --}}

  



```



## Contributing



Contributions to this addon are welcome. Contributors should consider the design constraints (listed above in "Design" and "Usage") when submitting a PR for consideration. Please ensure that any PR includes what is being done, tests, and any screenshots that may aid in consideration for inclusion in this addon.



## License



This project is licensed under the [MIT License](LICENSE.md).