81 |
82 |
85 |
96 |
97 |
98 |
--------------------------------------------------------------------------------
/iron-a11y-announcer.js:
--------------------------------------------------------------------------------
1 | /**
2 | @license
3 | Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
4 | This code may only be used under the BSD style license found at
5 | http://polymer.github.io/LICENSE.txt The complete set of authors may be found at
6 | http://polymer.github.io/AUTHORS.txt The complete set of contributors may be
7 | found at http://polymer.github.io/CONTRIBUTORS.txt Code distributed by Google as
8 | part of the polymer project is also subject to an additional IP rights grant
9 | found at http://polymer.github.io/PATENTS.txt
10 | */
11 | import '@polymer/polymer/polymer-legacy.js';
12 |
13 | import {Polymer} from '@polymer/polymer/lib/legacy/polymer-fn.js';
14 | import {html} from '@polymer/polymer/lib/utils/html-tag.js';
15 |
16 | /**
17 | `iron-a11y-announcer` is a singleton element that is intended to add a11y
18 | to features that require on-demand announcement from screen readers. In
19 | order to make use of the announcer, it is best to request its availability
20 | in the announcing element.
21 |
22 | Example:
23 |
24 | Polymer({
25 |
26 | is: 'x-chatty',
27 |
28 | attached: function() {
29 | // This will create the singleton element if it has not
30 | // been created yet:
31 | Polymer.IronA11yAnnouncer.requestAvailability();
32 | }
33 | });
34 |
35 | After the `iron-a11y-announcer` has been made available, elements can
36 | make announces by firing bubbling `iron-announce` events.
37 |
38 | Example:
39 |
40 | this.fire('iron-announce', {
41 | text: 'This is an announcement!'
42 | }, { bubbles: true });
43 |
44 | Note: announcements are only audible if you have a screen reader enabled.
45 |
46 | @demo demo/index.html
47 | */
48 | export const IronA11yAnnouncer = Polymer({
49 | /** @override */
50 | _template: html`
51 |
58 |
[[_text]]
59 | `,
60 |
61 | is: 'iron-a11y-announcer',
62 |
63 | properties: {
64 |
65 | /**
66 | * The value of mode is used to set the `aria-live` attribute
67 | * for the element that will be announced. Valid values are: `off`,
68 | * `polite` and `assertive`.
69 | */
70 | mode: {type: String, value: 'polite'},
71 |
72 | /**
73 | * The timeout on refreshing the announcement text. Larger timeouts are
74 | * needed for certain screen readers to re-announce the same message.
75 | */
76 | timeout: {type: Number, value: 150},
77 |
78 | _text: {type: String, value: ''},
79 | },
80 |
81 | /** @override */
82 | created: function() {
83 | if (!IronA11yAnnouncer.instance) {
84 | IronA11yAnnouncer.instance = this;
85 | }
86 |
87 | document.addEventListener('iron-announce', this._onIronAnnounce.bind(this));
88 | },
89 |
90 | /**
91 | * Cause a text string to be announced by screen readers.
92 | *
93 | * @param {string} text The text that should be announced.
94 | */
95 | announce: function(text) {
96 | this._text = '';
97 | this.async(function() {
98 | this._text = text;
99 | }, this.timeout);
100 | },
101 |
102 | _onIronAnnounce: function(event) {
103 | if (event.detail && event.detail.text) {
104 | this.announce(event.detail.text);
105 | }
106 | }
107 | });
108 |
109 | IronA11yAnnouncer.instance = null;
110 |
111 | IronA11yAnnouncer.requestAvailability = function() {
112 | if (!IronA11yAnnouncer.instance) {
113 | IronA11yAnnouncer.instance = document.createElement('iron-a11y-announcer');
114 | }
115 |
116 | if (document.body) {
117 | document.body.appendChild(IronA11yAnnouncer.instance);
118 | } else {
119 | document.addEventListener('load', function() {
120 | document.body.appendChild(IronA11yAnnouncer.instance);
121 | });
122 | }
123 | };
124 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
14 | [](https://www.npmjs.com/package/@polymer/iron-a11y-announcer)
15 | [](https://travis-ci.org/PolymerElements/iron-a11y-announcer)
16 | [](https://webcomponents.org/element/@polymer/iron-a11y-announcer)
17 |
18 | ## <iron-a11y-announcer>
19 |
20 | `iron-a11y-announcer` is a singleton element that is intended to add a11y
21 | to features that require on-demand announcement from screen readers. In
22 | order to make use of the announcer, it is best to request its availability
23 | in the announcing element.
24 | Note: announcements are only audible if you have a screen reader enabled.
25 |
26 | See: [Documentation](https://www.webcomponents.org/element/@polymer/iron-a11y-announcer),
27 | [Demo](https://www.webcomponents.org/element/@polymer/iron-a11y-announcer/demo/demo/index.html)
28 |
29 | ## Usage
30 |
31 | ### Installation
32 | ```
33 | npm install --save @polymer/iron-a11y-announcer
34 | ```
35 |
36 | ### In an html file
37 | ```html
38 |
39 |
40 |
49 |
50 |
51 | ```
52 |
53 | ### In a Polymer 3 element
54 | ```js
55 | import {PolymerElement, html} from '@polymer/polymer';
56 | import {IronA11yAnnouncer} from '@polymer/iron-a11y-announcer/iron-a11y-announcer.js';
57 |
58 | class SampleElement extends PolymerElement {
59 | static get template() {
60 | return html`
61 |
62 | `;
63 | }
64 | function attached() {
65 | IronA11yAnnouncer.requestAvailability();
66 | }
67 |
68 | // After the `iron-a11y-announcer` has been made available, elements can
69 | // make announces by firing bubbling `iron-announce` events.
70 | // Note: announcements are only audible if you have a screen reader enabled.
71 | function announce() {
72 | IronA11yAnnouncer.instance.fire('iron-announce',
73 | {text: 'Hello there!'}, {bubbles: true});
74 | }
75 | }
76 | customElements.define('sample-element', SampleElement);
77 | ```
78 |
79 | ## Contributing
80 | If you want to send a PR to this element, here are
81 | the instructions for running the tests and demo locally:
82 |
83 | ### Installation
84 | ```sh
85 | git clone https://github.com/PolymerElements/iron-a11y-announcer
86 | cd iron-a11y-announcer
87 | npm install
88 | npm install -g polymer-cli
89 | ```
90 |
91 | ### Running the demo locally
92 | ```sh
93 | polymer serve --npm
94 | open http://127.0.0.1:/demo/
95 | ```
96 |
97 | ### Running the tests
98 | ```sh
99 | polymer test --npm
100 | ```
101 |
102 | ## Known Issues
103 | This element doesn't work on Firefox (it doesn't read anything in Voice Over), since
104 | `aria-live` has been broken since the Quantum redesign (see the [MDN docs demo](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions))
105 | -- we tested it on Firefox 60, but it doesn't look like a regression, so
106 | it's probably broken on older versions as well.
107 |
--------------------------------------------------------------------------------