-
Notifications
You must be signed in to change notification settings - Fork 6
/
circuit-construction-kit-dc-virtual-lab_a11y_view.html
592 lines (487 loc) · 21 KB
/
circuit-construction-kit-dc-virtual-lab_a11y_view.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
<!DOCTYPE HTML>
<!-- Top-level HTML file for viewing, generated by 'grunt generate-a11y-view-html' DO NOT EDIT THIS FILE ONCE BUILT-->
<html>
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<meta name="mobile-web-app-capable" content="yes">
<meta name="phet-sim-level" content="production">
<!--have to scroll right and left! allows to resize also-->
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>A11y View: Circuit Construction Kit: DC - Virtual Lab</title>
<style>
html {
font-family: Arial, Helvetica, sans-serif;
line-height: 1.4;
}
body {
margin: 1em;
background: #ccc;
}
h1, h3, p {
margin-top: .55em;
margin-bottom: 0;
padding: 0;
}
.alert_copy_container ul {
-webkit-padding-start: 1.1em
}
.left {
width: 47%;
position: -webkit-sticky;
position: sticky;
top: .55em;
display: inline-block;
}
/* This class was found online as a way to preserve an iframe aspect ratio,
see https://fettblog.eu/blog/2013/06/16/preserving-aspect-ratio-for-embedded-iframes/*/
iframe {
width: 100%;
position: fixed;
}
.aspect-ratio {
position: relative;
width: 100%;
height: 0;
padding-bottom: 69%;
}
.aspect-ratio iframe {
position: absolute;
width: 100%;
height: 100%;
left: 0;
top: 0;
}
div.right {
background: #ccc;
float: right;
width: 47%;
overflow: auto;
}
div.clearfix {
clear: both;
}
p.alert {
opacity: 0.6;
}
div.alert_copy_container {
background: #e5c45b;
border-radius: 1em;
padding: .25em .75em 1em;
min-height: 18em;
}
p.alert_copy {
min-height: 5em;
}
div.dom_copy_container {
background: #a0e1e7;
border-radius: 1em;
padding: 1em;
}
div.dom_copy_container li {
margin-bottom: .5em;
}
div.wrapper {
height: auto;
width: 97%;
}
.dynamic {
background-color: #9adaa6;
border-bottom: double .167em #000; /*or a border in dark green*/
}
div#alerts, div#pdom {
margin-bottom: 1.1em;
}
em { /* this is the same as the dynamic class, but should be changed as part of https://github.com/phetsims/a11y-research/issues/67*/
background-color: #9adaa6;
border-bottom: double .167em #000; /*or a border in dark green*/
}
.highlight {
/*use outline instead of border because border doesn't apply to all DOMElements, add margin because outline
doesn't take up any space*/
outline: thick double red;
margin: 1%;
}
.bold {
font-weight: bold;
}
.assertive {
background-color: pink; /* do not change color without changing the doc in "About Interactive Alerts" */
border-radius: .2em;
}
.activity-log-heading-container {
display: flex;
align-content: space-between;
align-items: flex-start;
justify-content: space-between;
padding-top: 0.5em;
}
.activity-log-heading-item {
align-self: center;
font-size: 1.17em;
}
/* ************SAFARI ONLY *********************** */
.left-safari {
display: inline-block;
width: 47%;
}
</style>
</head>
<body>
<div class="wrapper">
<div id="content">
<div id="intro">
<h1>A11y View: Circuit Construction Kit: DC - Virtual Lab</h1>
<details>
<summary>About the A11y View Tool</summary>
<p>
The A11y View is a design and presentation tool that visually displays a copy of the descriptions we design
for the Interactive Description feature. The State Descriptions (blue box) track the current state of the
simulation. The Responsive Descriptions (orange box) deliver relevant changes in real time as they happen.
Using this tool, designers can test and assess the descriptions during the design process without using a
screen reader. Educators can also use this tool to see if the content of the descritpions meets their teaching
and learning needs.
</p>
<p>
<b>Please note:</b> The A11y View is not for learners. In learning contexts, screen reader users access the
Interactive Desctiption feature using the same simulation as everyone else.
</p>
</details>
</div>
<!--The sim and alert containers will both be placed in here -->
<div id="left" class="left">
<div class="aspect-ratio">
<iframe id="iframe" allowfullscreen scrolling="no" title="Interact with Circuit Construction Kit: DC - Virtual Lab"></iframe>
</div>
<div id="alerts">
<div class="activity-log-heading-container">
<h3 class="activity-log-heading-item">Activity log of Responsive Descriptions</h3>
<button class="activity-log-heading-item" id="clear-activity-log-button">Clear Log</button>
</div>
<details>
<summary>About Responsive Descriptions</summary>
Responsive Descriptions are a combination of object responses, descriptions of changes made directly to
interactive objects, and context responses, descriptions of changes to the surrounding context. Together, they
are designed to deliver relevant changes in real time as they happen. The object and context responses powered
by ARIA Live appear in the activity log below. The object responses for slider interactions are powered by the
aria-valuetext attribute, and are found in grey text under slider interactions in the blue box.
</details>
<div id='alert-copy-container' class='alert_copy_container' role='presentation'>
<div id='polite-element-container'>
<ul class='alert_copy' id='alert-list'></ul>
</div>
</div>
</div>
</div>
<!--The PDOM copy will be placed in this container -->
<div class="right" id="right">
<div id="pdom">
<h3>State Descriptions for Circuit Construction Kit: DC - Virtual Lab</h3>
<details>
<summary>About State Descriptions</summary>
State Descriptions are a combination of static state descriptions (descriptions that never change) and dynamic
state descriptions (descriptions that update silently as the simulation changes). Together, they form a
complete description of the current state at any given moment. These are the descriptions that a screen reader
user can read through or review as they feel the need when they are accessing a simulation (i.e., not the A11y
View tool).
</details>
<div id="dom-copy-container" class="dom_copy_container" role="presentation"></div>
</div>
</div>
<!--clear the blocks after the float effect-->
<div class="clearfix"></div>
</div>
</div>
<script type="application/javascript">
const IS_BUILT_STRING = '{{IS_BUILT}}';
const IS_BUILT = IS_BUILT_STRING.indexOf( '{{' ) !== 0; // escape for better syntax highlighting support
// Grab all query parameters to pass to the simulation, and a couple of params that are required for this test
let simulationQueryString = window.location.search;
if ( simulationQueryString.indexOf( '?' ) >= 0 ) {
simulationQueryString += '&';
}
else {
simulationQueryString += '?';
}
const noPostMessage = simulationQueryString.indexOf( 'postMessageOnLoad&postMessageOnError' ) === -1;
const noAccessibility = simulationQueryString.indexOf( 'supportsInteractiveDescription' ) === -1;
noPostMessage && ( simulationQueryString += 'postMessageOnLoad&postMessageOnError&' );
noAccessibility && ( simulationQueryString += 'supportsInteractiveDescription=true' );
// in unbuilt mode and on phet-server, the brand suffix is removed
const filenameEnding = ( window.location.hostname === 'phet.colorado.edu' || !IS_BUILT ) ? '.html' : '_phet.html';
// Unbuilt sims include all locales in the en file, built versions only include all strings in the all file
const repoLocale = `circuit-construction-kit-dc-virtual-lab_${IS_BUILT ? 'all' : 'en'}`;
const simURL = repoLocale + filenameEnding + simulationQueryString;
// set the source of the sim iframe
document.getElementById( 'iframe' ).setAttribute( 'src', simURL );
// apply sticky styling for all browsers except chrome.
const left = document.getElementById( 'left' );
const ua = navigator.userAgent.toLowerCase();
if ( ua.indexOf( 'safari' ) !== -1 ) {
if ( ua.indexOf( 'chrome' ) > -1 ) {
left.classList.add( 'left' );
}
else {
left.classList.add( 'left-safari' );
}
}
</script>
<script>
// Number of alerts that remain in the Activity log before fading out.
const ACTIVITY_LOG_LENGTH = 10;
// The attributes that we want to display as additional data in the PDOM copy. Otherwise these are invisible unless you
// inspect the DOM.
const IMPORTANT_ARIA_ATTRIBUTES = [ 'aria-valuetext', 'aria-expanded' ];
/*******************************************************************************
* Helper Functions
*/
/**
* Get all 'element' nodes off the parent element, placing them in an array for easy traversal. Note that this
* includes all elements, even those that are 'hidden' or purely for structure.
*
* @param {HTMLElement} ancestor - parent whose children will be linearized
* @returns {HTMLElement[]}
*/
function getAllDOMElementsAsLinear( ancestor ) {
// gets ALL descendant children for the element
const children = ancestor.getElementsByTagName( '*' );
const linearDOM = [];
for ( let i = 0; i < children.length; i++ ) {
// searching for the HTML element nodes (NOT Scenery nodes)
if ( children[ i ].nodeType === Node.ELEMENT_NODE ) {
linearDOM[ i ] = ( children[ i ] );
}
}
return linearDOM;
}
/**
* Apply the necessary styling to the PDOM copy so that it looks and behaves well. This includes removing from
* navigation order and ensuring that all of the styling copied from the actual PDOM is removed so that the copy
* is visible and elements have proper dimensions.
*
* @param {HTMLElement} root - ancestor element, this and all descendants will be styled
*/
function styleCopy( root ) {
const allElements = getAllDOMElementsAsLinear( root );
for ( let i = 0; i < allElements.length; i++ ) {
const element = allElements[ i ];
// make sure nothing in copy is focusable
element.tabIndex = '-1';
// make sure that styling is removed, unless some styling was added just for the copy
if ( element.className !== 'pdom-style' ) {
element.removeAttribute( 'style' );
}
}
}
/**
* Convert the inline ARIA labels with label information to input values or additional label elements in the
* PDOM copy so that they are visible in demonstrations. For example, this could be an aria-label, aria-valuetext,
* and so on.
*
* @param {HTMLElement} rootNode - descendants of this root are traversed so we have
*/
function addInlineAttributesTHTML( rootNode ) {
// all elements in the PDOM - a defensive copy since we may be adding new elements to the DOM
const allElements = Array.prototype.slice.call( rootNode.getElementsByTagName( '*' ) );
for ( let i = 0; i < allElements.length; i++ ) {
const element = allElements[ i ];
// this check works because PDOMInstance sets hidden on the entire subtree of PDOMInstances when not visible on
// an accessible display rather than just the hidden ancestor
if ( !element.hidden ) {
if ( element.hasAttribute( 'aria-label' ) && element.innerHTML === '' ) {
const ariaLabel = element.getAttribute( 'aria-label' );
// remove the style
element.removeAttribute( 'style' );
if ( element.tagName.toLowerCase() === 'input' ) {
if ( element.type === 'button' ) {
// set the value of the input to be the same as the aria-label appears inside the button
element.setAttribute( 'value', ariaLabel );
}
else {
// add a special label element to appear before the input element
const labelElement = document.createElement( 'label' );
labelElement.textContent = ariaLabel;
const parentElement = element.parentNode;
parentElement.insertBefore( labelElement, parentElement.firstChild );
}
}
else {
// if not an input, then add it to the innerHTML of an element, without overriding what is already there.
element.innerHTML = ariaLabel + element.innerHTML;
}
}
IMPORTANT_ARIA_ATTRIBUTES.forEach( attribute => {
if ( element.hasAttribute( attribute ) ) {
const value = element.getAttribute( attribute );
// add a new element to the DOM that displays the value of the attribute
const valueElement = document.createElement( 'p' );
// Assign a className so that we can avoid removing this specific styling when we present the PDOM copy
valueElement.className = 'pdom-style';
valueElement.style.opacity = 0.55;
valueElement.style.display = 'inline-block';
valueElement.style.paddingLeft = '1em';
valueElement.textContent = `(${attribute}: ${value})`;
// insert directly after the element that has the attribute. This handles the case if element is last, see https://stackoverflow.com/questions/4793604/how-to-insert-an-element-after-another-element-in-javascript-without-using-a-lib
element.parentNode.insertBefore( valueElement, element.nextSibling );
}
} );
}
}
}
/**
* Copy the necessary PDOM content over to the a11y view
* @param {HTMLElement} pdomRoot
* @param {HTMLElement} copyContainer - the parent of where the copy will be added in the a11y view
*/
function setPDOMCopyContent( pdomRoot, copyContainer ) {
// NOTE: This is extremely inefficient every time the document changes, make a new copy, remove
// the visual DOM, and add a new one.
copyContainer.innerHTML = '';
const pdomCopy = pdomRoot.cloneNode( true );
pdomCopy.removeAttribute( 'style' );
copyContainer.appendChild( pdomCopy );
addInlineAttributesTHTML( pdomCopy );
// we have to update styles of all elements when they are cloned
styleCopy( pdomCopy );
}
/**
* Add an observer to the PDOM root that will update the a11y view copy whenever the sim pdom changes.
* @param {HTMLElement} pdomRoot
* @param {HTMLElement} copyContainer - the PDOM copy will be added as a child here, see setPDOMCopyContent
* @param {Object} mutationConfig
*/
function addPDOMObserver( pdomRoot, copyContainer, mutationConfig ) {
// Initially dirty so that the PDOM copy is updated on the first frame
let dirty = true;
// poll for updates to help performance on chrome
setInterval( () => {
if ( dirty ) {
// update the PDOM copy after a delay to fix a FF/Safari bug where cloneNode prevents hidden DOM elements
// in the iframe from staying hidden - see https://github.com/phetsims/chipper/issues/648
setTimeout( () => {
setPDOMCopyContent( pdomRoot, copyContainer );
dirty = false;
}, 10 );
}
}, 300 ); // as of this writing, 200 ms was pretty good, but could get a bit laggy at times on chrome while using NVDA.
// whenever an element in the parallel DOM changes, we need to update its copied element as well
const domObserver = new MutationObserver( mutations => { dirty = true; } );
// pass in the target node, as well as the observer configuration options
domObserver.observe( pdomRoot, MUTATION_OBSERVER_CONFIG );
}
/**
* add mutation observers to each of the aria-live elements
* @param {HTMLElement} originalElement
* @param {HTMLElement} listElement
* @param {Object} mutationConfig
*/
function addLiveObserver( originalElement, listElement, mutationConfig ) {
const liveObserver = new MutationObserver( mutations => {
mutations.forEach( mutation => {
// Only display added DOM nodes. ariaLiveAnnouncer will remove the content from aria-live elements so that it
// can't be read by the virtual cursor. This registers as a "mutation", but we don't want to display
// the removal.
if ( mutation.addedNodes.length > 0 ) {
const alertText = mutation.target.textContent;
// update the text content of the copied element to match the element in the iframe document
// create a list item to add to the alert list
if ( alertText.length > 0 ) {
const listItem = document.createElement( 'li' );
listItem.style.opacity = 1.0;
listItem.textContent = alertText;
if ( mutation.target.id.includes( 'assertive' ) ) {
listItem.classList.add( 'assertive' );
}
listElement.insertBefore( listItem, listElement.children[ 0 ] );
// items fade out as they get older
for ( let j = 0; j < listElement.children.length; j++ ) {
listElement.children[ j ].style.opacity = 1.0 / ( j + 1 ) + 0.50;
}
// if the list is too large, remove the last items from the list
const childrenArray = Array.prototype.slice.call( listElement.children );
const fadeArray = childrenArray.slice( ACTIVITY_LOG_LENGTH, childrenArray.length );
for ( let i = 0; i < fadeArray.length; i++ ) {
const fadeChild = fadeArray[ i ];
const intervalId = window.setInterval( () => {
fadeChild.style.opacity = fadeChild.style.opacity * 0.95;
// stop animating and remove child
if ( listElement.contains( fadeChild ) && fadeChild.style.opacity < 0.1 ) {
window.clearInterval( intervalId );
listElement.removeChild( fadeChild );
}
}, 20 );
}
}
}
} );
} );
liveObserver.observe( originalElement, mutationConfig );
}
/**
* Remove all alerts from the activity log by removing all children of the parent containing them. Solution to clear
* children from https://stackoverflow.com/questions/3955229/remove-all-child-elements-of-a-dom-node-in-javascript
*/
function clearActivityLog( listElement ) {
while ( listElement.firstChild ) {
listElement.removeChild( listElement.lastChild );
}
}
// constants
// see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserverInit for details
const MUTATION_OBSERVER_CONFIG = {
attributes: true,
childList: true,
characterData: true,
subtree: true
};
// handling messages from sims
window.addEventListener( 'message', event => {
if ( !event.data ) {
return;
}
let data;
try {
data = JSON.parse( event.data );
}
catch( e ) {
return;
}
// if load is successful, create a visualization of the parallel DOM
if ( data.type === 'load' ) {
const simFrame = document.getElementById( 'iframe' );
const innerWindow = simFrame.contentWindow;
// eslint-disable-next-line dot-notation
const PDOMRoot = innerWindow[ 'phet' ].joist.display.pdomRootElement; // copy of the parallel DOM
// get the alert dom elements from the iframe's inner document
// eslint-disable-next-line dot-notation
const ariaLiveElementsContainer = innerWindow[ 'phet' ].joist.sim.display.descriptionUtteranceQueue.announcer.ariaLiveContainer;
// get the alert dom elements from the PDOM copy
const alertList = document.getElementById( 'alert-list' );
// get the parent container for the parallel DOM copy and the alert content
const copyContainer = document.getElementById( 'dom-copy-container' );
// update the PDOM copy whenever the sim's PDOM changes
addPDOMObserver( PDOMRoot, copyContainer, MUTATION_OBSERVER_CONFIG );
// observe each of the live elements and add new text content to the list view
for ( let i = 0; i < ariaLiveElementsContainer.children.length; i++ ) {
addLiveObserver( ariaLiveElementsContainer.children[ i ], alertList, MUTATION_OBSERVER_CONFIG );
}
// clear all alerts when the "Clear Log" button is pressed
const clearButton = document.getElementById( 'clear-activity-log-button' );
clearButton.addEventListener( 'click', () => clearActivityLog( alertList ) );
const iframe = document.getElementById( 'iframe' );
const iframeDocument = iframe.contentWindow.document
// set focus to the loaded iframe
iframe.focus();
let previousElement = null;
iframeDocument.addEventListener( 'focusin', event => {
if ( previousElement ) {
previousElement.classList.remove( 'highlight' );
}
previousElement = iframeDocument.activeElement;
previousElement.classList.add( 'highlight' );
} );
}
} );
</script>
</body>
</html>