scanning: a11y: Announce scan progress updates

Use a timer for setting the scan preview aria label with scan progress
updates.

Bug: 1059779
Change-Id: I83d59cb8b70e2fba262d52584deb532ebc9adcf9
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2617358Reviewed-by: Jesse Schettler <jschettler@chromium.org>
Commit-Queue: Gavin Williams <gavinwill@chromium.org>
Cr-Commit-Position: refs/heads/master@{#842120}

chromeos/chromeos_strings.grd

@@ -612,6 +612,9 @@ Try tapping the mic to ask me anything.
         =1 {Scanning completed. 1 page scanned}
         other {Scanning completed. {NUMBER_OF_PAGES} pages scanned}}
       </message>
+      <message name="IDS_SCANNING_APP_SCANNING_IMAGES_ARIA_LABEL" desc="The text read by the screen reader announcing progress updates for an ongoing scan job.">
+        Scanning page <ph name="PAGE_NUM">$1<ex>2</ex></ph>. <ph name="PERCENTAGE_VALUE">$2<ex>50</ex></ph>% completed.
+      </message>
 
       <!-- Diagnostics App -->
       <message name="IDS_DIAGNOSTICS_TITLE" desc="The title of the diagnostics app.">

chromeos/chromeos_strings_grd/IDS_SCANNING_APP_SCANNING_IMAGES_ARIA_LABEL.png.sha1

+f03b91b0ab49ab9f5074149cac87c09bc40bfca9
\ No newline at end of file

chromeos/components/scanning/resources/scan_preview.js

@@ -12,6 +12,9 @@ import {afterNextRender, html, Polymer} from 'chrome://resources/polymer/v3_0/po
 import {AppState} from './scanning_app_types.js';
 import {ScanningBrowserProxy, ScanningBrowserProxyImpl} from './scanning_browser_proxy.js';
 
+/** @type {number} */
+const PROGRESS_TIMER_MS = 3000;
+
 /**
  * @fileoverview
  * 'scan-preview' shows a preview of a scanned document.
@@ -72,16 +75,23 @@ Polymer({
       value: false,
     },
 
-    /** @type {string} */
+    /** @private {string} */
     progressTextString_: String,
 
-    /** @type {string} */
+    /** @private {string} */
     previewAriaLabel_: String,
+
+    /** @private {?number} */
+    progressTimer_: {
+      type: Number,
+      value: null,
+    },
   },
 
   observers: [
-    'setPreviewAriaLabel_(showScannedImages_, showScanProgress_,' +
-        ' showCancelingProgress_, showHelperText_, progressTextString_)',
+    'setPreviewAriaLabel_(showScannedImages_, showCancelingProgress_,' +
+        ' showHelperText_)',
+    'setScanProgressTimer_(showScanProgress_, progressPercent)',
   ],
 
   /** @override */
@@ -118,9 +128,8 @@ Polymer({
   /**
    * Sets the ARIA label used by the preview area based on the app state and the
    * current page showing. In the initial state, use the scan preview
-   * instructions from the page as the label. While scanning, update the label
-   * each time the page number increases. When the scan completes, announce the
-   * total number of pages scanned.
+   * instructions from the page as the label. When the scan completes, announce
+   * the total number of pages scanned.
    * @private
    */
   setPreviewAriaLabel_() {
@@ -133,11 +142,6 @@ Polymer({
       return;
     }
 
-    if (this.showScanProgress_) {
-      this.previewAriaLabel_ = this.progressTextString_;
-      return;
-    }
-
     if (this.showCancelingProgress_) {
       this.previewAriaLabel_ = this.i18n('cancelingScanningText');
       return;
@@ -150,6 +154,48 @@ Polymer({
       afterNextRender(this, () => {
         this.previewAriaLabel_ = this.$.helperText.innerText;
       });
+      return;
+    }
+  },
+
+  /**
+   * When receiving progress updates from an ongoing scan job, only update the
+   * preview section aria label after a timer elapses to prevent successive
+   * progress updates from spamming ChromeVox.
+   * @private
+   */
+  setScanProgressTimer_() {
+    // Only set the timer if scanning is still in progress.
+    if (!this.showScanProgress_) {
+      return;
+    }
+
+    // Always announce when a page is completed. Bypass and clear any existing
+    // timer and immediately update the aria label.
+    if (this.progressPercent === 100) {
+      clearTimeout(this.progressTimer_);
+      this.onScanProgressTimerComplete_();
+      return;
+    }
+
+    // If a timer is already in progress, do not set another timer.
+    if (this.progressTimer_) {
+      return;
     }
+
+    this.progressTimer_ = setTimeout(
+        () => this.onScanProgressTimerComplete_(), PROGRESS_TIMER_MS);
+  },
+
+  /** @private */
+  onScanProgressTimerComplete_() {
+    // Only update the aria label if scanning is still in progress.
+    if (!this.showScanProgress_) {
+      return;
+    }
+
+    this.previewAriaLabel_ = this.i18n(
+        'scanningImagesAriaLabel', this.pageNumber, this.progressPercent);
+    this.progressTimer_ = null;
   },
 });

chromeos/components/scanning/scanning_ui.cc

@@ -94,6 +94,7 @@ void AddScanningAppStrings(content::WebUIDataSource* html_source) {
       {"scanPreviewProgressText", IDS_SCANNING_APP_SCAN_PREVIEW_PROGRESS_TEXT},
       {"scanToDropdownLabel", IDS_SCANNING_APP_SCAN_TO_DROPDOWN_LABEL},
       {"scannerDropdownLabel", IDS_SCANNING_APP_SCANNER_DROPDOWN_LABEL},
+      {"scanningImagesAriaLabel", IDS_SCANNING_APP_SCANNING_IMAGES_ARIA_LABEL},
       {"selectFolderOption", IDS_SCANNING_APP_SELECT_FOLDER_OPTION},
       {"showFileLocationLabel", IDS_SCANNING_APP_SHOW_FILE_LOCATION_LABEL},
       {"sourceDropdownLabel", IDS_SCANNING_APP_SOURCE_DROPDOWN_LABEL},