example-sim/example-sim_a11y_view.html at master · mdltesting/example-sim · GitHub

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
<!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="apple-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: Example Simulation</title>

  <style>
    html {
      font-family: Arial, Helvetica, sans-serif;
      line-height: 1.4;
    }

    body {
      margin: 1em 1em 2em;
      width: 100%;
      background: #ccc;
    }

    h1, h3, p {
      margin-top: .55em;
      margin-bottom: 0;
      padding: 0;
    }

    #content {
      margin: 1em;
    }

    .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: 10em;
    }

    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: 95%;
      margin-bottom: 2em;
    }

    .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;
    }

    /* ************SAFARI ONLY *********************** */
    .left-safari {
      display: inline-block;
      width: 47%;
    }
  </style>

</head>
<body>

<div class="wrapper">

  <div id="content">
    <div id="intro">
      <h1>A11y View: Example Simulation</h1>
      <details>
        <summary>About the A11y View</summary>
        <p>
          The A11y View is a design and presentation tool that allows us to visually demonstrate the accessibility layer
          of the simulation. We refer to this layer as the Parallel DOM, or PDOM. The PDOM (copied into the blue box)
          exposes the simulation’s full document structure and all the dynamic descriptive content that lives within
          that structure to a student accessing the simulation using assistive technology, such as screen reader
          software. The activity log (copied into the orange box), exposes the interactive alerts that a student would
          hear in real-time as they interact with the simulation. Interact with the accessible version of
          Example Simulation in the iframe, with either a keyboard or a mouse, and notice how the activity log (orange
          box) and the content of the PDOM (blue box) update as you interact.
        </p>
        <p>
          <b>Please note</b> that students do not use the A11y View, they use the accessible simulation, alone, which is
          rendered here inside the iframe.
        </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 Example Simulation"></iframe>
      </div>
      <div id="alerts">
        <h3>Activity log of Interactive Alerts</h3>
        <details>
          <summary>About Interactive Alerts</summary>
          Interactive alerts (powered by aria-live) are read out as the user interacts providing a description of what
          is happening in real-time. Alerts appear in reverse chronological order with the latest on top. In general
          all aria-live alerts are polite, but assertive alerts are highlighted with pink.
        </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>PDOM & Descriptions for Example Simulation</h3>
        <details>
          <summary>About the PDOM & Descriptions</summary>
          Content in the blue box updates in real-time to provide an always-available description of the current
          state of the sim.
        </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' );

  const repoLocale = 'example-sim_en';
  const filenameEnding = IS_BUILT ? '_phet.html' : '.html';
  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>

  /*******************************************************************************
   * 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 ];

      // TODO: see https://github.com/phetsims/chipper/issues/740, for some reason this makes Chrome very slow
      // 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
      // TODO: pdom-style is not used anywhere. Should we keep it? https://github.com/phetsims/chipper/issues/916
      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;
          }
        }
        if ( element.hasAttribute( 'aria-valuetext' ) ) {

          // if the element has aria-valuetext, render this text in a new element so we can see the content of this
          // inline attribute
          const valueTextElement = document.createElement( 'p' );
          valueTextElement.className = 'pdom-style';
          valueTextElement.style.opacity = 0.55;
          valueTextElement.textContent = element.getAttribute( 'aria-valuetext' );

          // insert directly after the element that has the valuetext. 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( valueTextElement, 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 ) {

    // This is extremely inefficient every time the document changes, make a new copy, remove
    // the visual DOM, and add a new one
    // TODO: Work on refining this, and only modifying the elements that change in the PDOM https://github.com/phetsims/chipper/issues/916
    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 ) {

    let dirty = false;

    // 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( function() {
          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.25;
            }

            // 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( 5, 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 )
  }

</script>

<script type="application/javascript">

  // 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;
      const PDOMRoot = innerWindow.phet.joist.display.pdomRootElement; // copy of the parallel DOM

      // get the alert dom elements from the iframe's inner document
      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' );

      // strip the styling from the copied DOM elements

      // TODO: why do we do this? Isn't this an element purely in the a11y view? https://github.com/phetsims/chipper/issues/916
      alertList.removeAttribute( 'style' );

      // get the parent container for the parallel DOM copy and the alert content
      const copyContainer = document.getElementById( 'dom-copy-container' );

      // once for initial setup
      // TODO: do we have to do this? https://github.com/phetsims/chipper/issues/916
      setPDOMCopyContent( PDOMRoot, copyContainer );

      // 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 );
      }

      // set focus to the loaded iframe
      document.getElementById( 'iframe' ).focus();

      // Provide fake focus highlighting to the PDOM copy based on what is actually highlighted in the sim.
      // TODO: is polling the best way to do this? If so why 500? https://github.com/phetsims/chipper/issues/916
      let previousElement = null;
      setInterval( () => {

        if ( previousElement ) {
          previousElement.classList.remove( 'highlight' );
        }
        previousElement = document.getElementById( 'iframe' ).contentWindow.document.activeElement;
        previousElement.classList.add( 'highlight' );
      }, 500 );
    }
  } );
</script>
</body>
</html>