Update: Alert screen reader users when content has been added (fixes #232)

.github/pull_request_template.md

@@ -8,7 +8,7 @@
 * A sentence describing each fix
 
 ### Update
-* A sentence describing each udpate
+* A sentence describing each update
 
 ### New
 * A sentence describing each new feature

js/TrickleButtonModel.js

@@ -132,18 +132,18 @@ export default class TrickleButtonModel extends ComponentModel {
     const text = (isDisabled && trickleConfig._button.disabledText) ?
       trickleConfig._button.disabledText :
       (isStart && trickleConfig._button.startText) ?
-      trickleConfig._button.startText :
-      (isFinal && trickleConfig._button.finalText) ?
-      trickleConfig._button.finalText :
-      trickleConfig._button.text;
+        trickleConfig._button.startText :
+        (isFinal && trickleConfig._button.finalText) ?
+          trickleConfig._button.finalText :
+          trickleConfig._button.text;
 
     const ariaLabel = (isDisabled && trickleConfig._button.disabledAriaLabel) ?
-      trickleConfig._button.disabledAriaLabel : 
+      trickleConfig._button.disabledAriaLabel :
       (isStart && trickleConfig._button.startAriaLabel) ?
-      trickleConfig._button.startAriaLabel :
-      (isFinal && trickleConfig._button.finalAriaLabel) ?
-      trickleConfig._button.finalAriaLabel :
-      trickleConfig._button.ariaLabel;
+        trickleConfig._button.startAriaLabel :
+        (isFinal && trickleConfig._button.finalAriaLabel) ?
+          trickleConfig._button.finalAriaLabel :
+          trickleConfig._button.ariaLabel;
 
     this.set({
       buttonText: text,

js/TrickleButtonView.js

@@ -1,5 +1,6 @@
 import Adapt from 'core/js/adapt';
 import a11y from 'core/js/a11y';
+import notify from 'core/js/notify';
 import ComponentView from 'core/js/views/componentView';
 import controller from './controller';
 import {
@@ -118,7 +119,7 @@ class TrickleButtonView extends ComponentView {
     this.$('.js-trickle-btn-container').toggleClass('u-display-none', isButtonHidden);
     const isButtonDisabled = this.model.get('_isButtonDisabled');
     const $button = this.$('.js-trickle-btn');
-    const $ariaLabel = this.$('.aria-label');
+    const $ariaLabel = this.$('.aria-label:not(.trickle__status)');
     a11y.toggleEnabled($button, !isButtonDisabled);
     if (!isButtonDisabled) {
       // move focus forward if it's on the aria-label
@@ -202,10 +203,30 @@ class TrickleButtonView extends ComponentView {
    */
   async continue() {
     const parent = this.model.getParent();
-    await controller.continue();
+    const childrenAdded = await controller.continue();
+    if (!childrenAdded) return;
+    await this.announceContentLoaded();
     await controller.scroll(parent);
   }
 
+  /**
+   * Announce a message to screenreaders letting them know that additional
+   * content has been loaded on the page.
+   */
+  async announceContentLoaded() {
+    const globals = Adapt.course.get('_globals');
+    const message = globals?._extensions?._trickle?.additionalContentLoaded;
+    if (!message) return;
+
+    notify.create({ _type: 'a11y-push', body: message });
+
+    // Rough estimate: 200ms per word + buffer
+    const words = message.split(' ').length;
+    const delay = (words * 200) + 300;
+
+    return new Promise(resolve => setTimeout(resolve, delay));
+  }
+
   tryButtonAutoHide() {
     if (!this.model.get('_isButtonVisible')) return;
     const trickleConfig = getModelConfig(this.model.getParent());

js/controller.js

@@ -115,8 +115,9 @@ class TrickleController extends Backbone.Controller {
    */
   async continue() {
     applyLocks();
-    await Adapt.parentView.addChildren();
+    const addedCount = await Adapt.parentView.addChildren();
     await Adapt.parentView.whenReady();
+    return addedCount;
   }
 
   /**
@@ -160,8 +161,8 @@ class TrickleController extends Backbone.Controller {
 
     let scrollToId = getScrollToId();
     if (!scrollToId) {
-      logging.error(`Cannot scroll to the next id as none was found at id: "${fromModel.get('_id')}" with _scrollTo: "${trickleConfig._scrollTo}". Suggestion: Set _showEndOfPage to false.`)
-      return
+      logging.error(`Cannot scroll to the next id as none was found at id: "${fromModel.get('_id')}" with _scrollTo: "${trickleConfig._scrollTo}". Suggestion: Set _showEndOfPage to false.`);
+      return;
     }
 
     const isDescendant = Adapt.parentView.model.getAllDescendantModels().some(model => {

properties.schema

@@ -11,6 +11,16 @@
       "inputType": "Text",
       "validators": [],
       "translatable": true
+    },
+    "additionalContentLoaded": {
+      "type": "string",
+      "required": true,
+      "title": "Additional content loaded.",
+      "default": "Loading.",
+      "inputType": "Text",
+      "help": "Announced to screen readers when additional content is loaded. Recommend keeping this short.",
+      "validators": [],
+      "translatable": true
     }
   },
   "properties": {

schema/course.schema.json

@@ -28,6 +28,15 @@
                       "_adapt": {
                         "translatable": true
                       }
+                    },
+                    "additionalContentLoaded": {
+                      "type": "string",
+                      "title": "Additional content loaded",
+                      "default": "Loading.",
+                      "description": "Announced to screen readers when additional content is loaded. Recommend keeping this short.",
+                      "_adapt": {
+                        "translatable": true
+                      }
                     }
                   }
                 }