modifications to time period descriptions, see #200

phetsims · Aug 10, 2022 · 8fe9a4b · 8fe9a4b
1 parent 4ce5df0
commit 8fe9a4b
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 38 deletions.
diff --git a/greenhouse-effect-strings_en.json b/greenhouse-effect-strings_en.json
@@ -448,18 +448,30 @@
     "timePeriodDescriptionPattern": {
       "value": "{{timePeriod}} and {{description}}"
     },
-    "twentyTwentyDescription": {
+    "thereAreManyHomesAndFactories": {
       "value": "there are many homes and factories"
     },
-    "nineteenFiftyDescription": {
+    "thereAreAFewHomesAndFactories": {
       "value": "there are a few homes and factories"
     },
-    "seventeenFiftyDescription": {
+    "thereIsAFarm": {
       "value": "there is a farm"
     },
-    "iceAgeDescription": {
+    "thereIsALargeGlacier": {
       "value": "there is a large glacier"
     },
+    "manyHomesAndFactories": {
+      "value": "many homes and factories"
+    },
+    "aFewHomesAndFactories": {
+      "value": "a few homes and factories"
+    },
+    "aFarm": {
+      "value": "a farm"
+    },
+    "aLargeGlacier": {
+      "value": "a large glacier"
+    },
     "currentlyTimePeriodDescriptionPattern": {
       "value": "Currently, {{timePeriodDescription}}"
     },
@@ -512,7 +524,7 @@
       "value": "Surface temperature is {{description}}."
     },
     "observationWindowTimePeriodPattern": {
-      "value": "Now {{timePeriodDescription}} in observation window."
+      "value": "Now {{timePeriodDescription}}."
     },
     "photons": {
       "homeScreenDescription": {

diff --git a/greenhouse-effect_a11y_view.html b/greenhouse-effect_a11y_view.html
@@ -19,8 +19,7 @@
     }
 
     body {
-      margin: 1em 1em 2em;
-      width: 100%;
+      margin: 1em;
       background: #ccc;
     }
 
@@ -30,10 +29,6 @@
       padding: 0;
     }
 
-    #content {
-      margin: 1em;
-    }
-
     .alert_copy_container ul {
       -webkit-padding-start: 1.1em
     }
@@ -107,8 +102,7 @@
 
     div.wrapper {
       height: auto;
-      width: 95%;
-      margin-bottom: 2em;
+      width: 97%;
     }
 
     .dynamic {
@@ -172,10 +166,17 @@ <h1>A11y View: Greenhouse Effect</h1>
       <details>
         <summary>About the A11y View Tool</summary>
         <p>
-          The A11y View is a design and presentation tool that we use to visually review and demonstrate the Interactive Description design of a simulation. The descriptions we design live within our accessibility layer, we call the Parallel DOM, or PDOM. The HTML of the PDOM provides document and interaction semantics for State Descriptions (copied into the blue box), and timely delivery of Responsive Descriptions (copied into the orange box). For a learner accessing the simulation with screen reader software, the State Descriptions provide on-demand access the current state of simulation while Responsive Descriptions deliver relevant changes - in real time - as the learner interacts with the simulation.
+          The A11y View is a design and presentation tool that we use to visually review and demonstrate the Interactive
+          Description design of a simulation. The descriptions we design live within our accessibility layer, we call
+          the Parallel DOM, or PDOM. The HTML of the PDOM provides document and interaction semantics for State
+          Descriptions (copied into the blue box), and timely delivery of Responsive Descriptions (copied into the
+          orange box). For a learner accessing the simulation with screen reader software, the State Descriptions
+          provide on-demand access the current state of simulation while Responsive Descriptions deliver relevant
+          changes - in real time - as the learner interacts with the simulation.
         </p>
         <p>
-          <b>Please note</b> that learners who use screen reader software do not use this A11y View, they use the same simulation that all learners use.
+          <b>Please note</b> that learners who use screen reader software do not use this A11y View, they use the same
+          simulation that all learners use.
         </p>
       </details>
     </div>
@@ -192,7 +193,12 @@ <h3 class="activity-log-heading-item">Activity log of Responsive Descriptions</h
         </div>
         <details>
           <summary>About Responsive Descriptions</summary>
-          Responsive Descriptions deliver changes made to interactive objects (Object Responses) and changes to the surrounding context (Context Responses). Only responses powered by ARIA Live appear in the activity log below, and most are Context Responses. Most responses powered by ARIA Live are delivered politely, but some are really important so we make them assertive (occasional line highlighted in pink). Note that many Object Responses are delivered using the aria-valuetext attribute (see grey text under slider interactions in the blue box).
+          Responsive Descriptions deliver changes made to interactive objects (Object Responses) and changes to the
+          surrounding context (Context Responses). Only responses powered by ARIA Live appear in the activity log below,
+          and most are Context Responses. Most responses powered by ARIA Live are delivered politely, but some are
+          really important so we make them assertive (occasional line highlighted in pink). Note that many Object
+          Responses are delivered using the aria-valuetext attribute (see 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'>
@@ -208,7 +214,10 @@ <h3 class="activity-log-heading-item">Activity log of Responsive Descriptions</h
         <h3>State Descriptions for Greenhouse Effect</h3>
         <details>
           <summary>About State Descriptions</summary>
-          State Descriptions provide on-demand access to a full description of the current state of the simulation. This lengthy description is accessible to the learner from the moment the simulation loads, and during any point as they explore. The dynamic parts of the State Descriptions update silently as the learner interacts and makes changes.
+          State Descriptions provide on-demand access to a full description of the current state of the simulation. This
+          lengthy description is accessible to the learner from the moment the simulation loads, and during any point as
+          they explore. The dynamic parts of the State Descriptions update silently as the learner interacts and makes
+          changes.
         </details>
         <div id="dom-copy-container" class="dom_copy_container" role="presentation"></div>
       </div>
@@ -313,7 +322,7 @@ <h3>State Descriptions for Greenhouse Effect</h3>
 
       // 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" ) {
+      if ( element.className !== 'pdom-style' ) {
         element.removeAttribute( 'style' );
       }
     }
@@ -329,7 +338,7 @@ <h3>State Descriptions for Greenhouse Effect</h3>
   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( "*" ) );
+    const allElements = Array.prototype.slice.call( rootNode.getElementsByTagName( '*' ) );
 
     for ( let i = 0; i < allElements.length; i++ ) {
       const element = allElements[ i ];
@@ -495,7 +504,7 @@ <h3>State Descriptions for Greenhouse Effect</h3>
    * children from https://stackoverflow.com/questions/3955229/remove-all-child-elements-of-a-dom-node-in-javascript
    */
   function clearActivityLog( listElement ) {
-    while( listElement.firstChild ) {
+    while ( listElement.firstChild ) {
       listElement.removeChild( listElement.lastChild );
     }
   }

diff --git a/js/common/view/describers/ConcentrationDescriber.ts b/js/common/view/describers/ConcentrationDescriber.ts
@@ -76,10 +76,14 @@ const seventeenFiftyString = greenhouseEffectStrings.a11y.timePeriodDescriptions
 const nineteenFiftyString = greenhouseEffectStrings.a11y.timePeriodDescriptions.nineteenFifty;
 const twentyTwentyString = greenhouseEffectStrings.a11y.timePeriodDescriptions.twentyTwenty;
 
-const iceAgeDescriptionString = greenhouseEffectStrings.a11y.iceAgeDescription;
-const seventeenFiftyDescriptionString = greenhouseEffectStrings.a11y.seventeenFiftyDescription;
-const nineteenFiftyDescriptionString = greenhouseEffectStrings.a11y.nineteenFiftyDescription;
-const twentyTwentyDescriptionString = greenhouseEffectStrings.a11y.twentyTwentyDescription;
+const thereIsALargeGlacierString = greenhouseEffectStrings.a11y.thereIsALargeGlacier;
+const thereIsAFarmString = greenhouseEffectStrings.a11y.thereIsAFarm;
+const thereAreAFewHomesAndFactoriesString = greenhouseEffectStrings.a11y.thereAreAFewHomesAndFactories;
+const thereAreManyHomesAndFactoriesString = greenhouseEffectStrings.a11y.thereAreManyHomesAndFactories;
+const aLargeGlacierString = greenhouseEffectStrings.a11y.aLargeGlacier;
+const aFarmString = greenhouseEffectStrings.a11y.aFarm;
+const aFewHomesAndFactoriesString = greenhouseEffectStrings.a11y.aFewHomesAndFactories;
+const manyHomesAndFactoriesString = greenhouseEffectStrings.a11y.manyHomesAndFactories;
 
 // strings used to describe the sky
 const skyDescriptionPatternString = greenhouseEffectStrings.a11y.sky.skyDescriptionPattern;
@@ -139,12 +143,12 @@ class ConcentrationDescriber {
 
   /**
    * Get a description of a particular time period, including the date. Returns something like
-   * "year twenty twenty and there are lots of homes and factories" or
+   * "year twenty twenty and there are many homes and factories" or
    * "ice age and there is a large glacier"
    */
   public static getDescribedTimePeriodString( timePeriodValue: ConcentrationDate ): string {
     const timePeriodString = ConcentrationDescriber.getTimePeriodString( timePeriodValue );
-    const timePeriodDescriptionString = ConcentrationDescriber.getTimePeriodDescription( timePeriodValue );
+    const timePeriodDescriptionString = ConcentrationDescriber.getTimePeriodWithExistenceFragmentDescription( timePeriodValue );
 
     return StringUtils.fillIn( greenhouseEffectStrings.a11y.timePeriodDescriptionPattern, {
       timePeriod: timePeriodString,
@@ -153,19 +157,32 @@ class ConcentrationDescriber {
   }
 
   /**
-   * Get a description of the time period, just the isolated fragment. Will return something like
-   * "a few homes and factories" or
-   * "a large number of homes and factories"
+   * Get a description of the time period with a prefix fragment like "there is". Will return something like
+   * "there is a farm" or
+   * "there are many homes and factories"
+   */
+  public static getTimePeriodWithExistenceFragmentDescription( timePeriodValue: ConcentrationDate ): string {
+    return timePeriodValue === ConcentrationDate.ICE_AGE ? thereIsALargeGlacierString :
+           timePeriodValue === ConcentrationDate.SEVENTEEN_FIFTY ? thereIsAFarmString :
+           timePeriodValue === ConcentrationDate.NINETEEN_FIFTY ? thereAreAFewHomesAndFactoriesString :
+           thereAreManyHomesAndFactoriesString;
+  }
+
+  /**
+   * Get a short description of the current time period, just including graphical contents like
+   * "a farm" or
+   * "many homes and factories"
    */
   public static getTimePeriodDescription( timePeriodValue: ConcentrationDate ): string {
-    return timePeriodValue === ConcentrationDate.ICE_AGE ? iceAgeDescriptionString :
-           timePeriodValue === ConcentrationDate.SEVENTEEN_FIFTY ? seventeenFiftyDescriptionString :
-           timePeriodValue === ConcentrationDate.NINETEEN_FIFTY ? nineteenFiftyDescriptionString :
-           twentyTwentyDescriptionString;
+    return timePeriodValue === ConcentrationDate.ICE_AGE ? aLargeGlacierString :
+           timePeriodValue === ConcentrationDate.SEVENTEEN_FIFTY ? aFarmString :
+           timePeriodValue === ConcentrationDate.NINETEEN_FIFTY ? aFewHomesAndFactoriesString :
+           manyHomesAndFactoriesString;
   }
 
   /**
-   * Returns a string that describes the current time period in the observation window, will return something like
+   * Returns a string that describes the current time period in the observation window. This is a shorter
+   * statement to be used when the time period will return something like
    * "Now a few homes and houses in observation window." or
    * "Now a large number of homes and factories in observation window."
    */

diff --git a/js/greenhouseEffectStrings.ts b/js/greenhouseEffectStrings.ts
@@ -199,10 +199,14 @@ type StringsType = {
       }
     };
     'timePeriodDescriptionPattern': string;
-    'twentyTwentyDescription': string;
-    'nineteenFiftyDescription': string;
-    'seventeenFiftyDescription': string;
-    'iceAgeDescription': string;
+    'thereAreManyHomesAndFactories': string;
+    'thereAreAFewHomesAndFactories': string;
+    'thereIsAFarm': string;
+    'thereIsALargeGlacier': string;
+    'manyHomesAndFactories': string;
+    'aFewHomesAndFactories': string;
+    'aFarm': string;
+    'aLargeGlacier': string;
     'currentlyTimePeriodDescriptionPattern': string;
     'nowLevelsOfConcentrationPattern': string;
     'nowRelativeLevelOfConcentrationPattern': string;