feat: improve TouchBarButton accessibility (electron#20454)

codebytere · John Kleinschmidt · commit c16a186de045 · 2019-10-08T11:13:57.000-04:00
diff --git a/docs/api/touch-bar-button.md b/docs/api/touch-bar-button.md
@@ -8,16 +8,23 @@ Process: [Main](../tutorial/application-architecture.md#main-and-renderer-proces
 
 * `options` Object
   * `label` String (optional) - Button text.
+  * `accessibilityLabel` String (optional) - A short description of the button for use by screenreaders like VoiceOver.
   * `backgroundColor` String (optional) - Button background color in hex format,
     i.e `#ABCDEF`.
   * `icon` [NativeImage](native-image.md) | String (optional) - Button icon.
   * `iconPosition` String (optional) - Can be `left`, `right` or `overlay`. Defaults to `overlay`.
   * `click` Function (optional) - Function to call when the button is clicked.
 
+When defining `accessibilityLabel`, ensure you have considered macOS [best practices](https://developer.apple.com/documentation/appkit/nsaccessibilitybutton/1524910-accessibilitylabel?language=objc).
+
 ### Instance Properties
 
 The following properties are available on instances of `TouchBarButton`:
 
+#### `touchBarButton.accessibilityLabel`
+
+A `String` representing the description of the button to be read by a screen reader. Will only be read by screen readers if no label is set.
+
 #### `touchBarButton.label`
 
 A `String` representing the button's current text. Changing this value immediately updates the button
diff --git a/docs/api/touch-bar-label.md b/docs/api/touch-bar-label.md
@@ -8,8 +8,11 @@ Process: [Main](../tutorial/application-architecture.md#main-and-renderer-proces
 
 * `options` Object
   * `label` String (optional) - Text to display.
+  * `accessibilityLabel` String (optional) - A short description of the button for use by screenreaders like VoiceOver.
   * `textColor` String (optional) - Hex color of text, i.e `#ABCDEF`.
 
+When defining `accessibilityLabel`, ensure you have considered macOS [best practices](https://developer.apple.com/documentation/appkit/nsaccessibilitybutton/1524910-accessibilitylabel?language=objc).
+
 ### Instance Properties
 
 The following properties are available on instances of `TouchBarLabel`:
@@ -19,6 +22,10 @@ The following properties are available on instances of `TouchBarLabel`:
 A `String` representing the label's current text. Changing this value immediately updates the label in
 the touch bar.
 
+#### `touchBarLabel.accessibilityLabel`
+
+A `String` representing the description of the label to be read by a screen reader.
+
 #### `touchBarLabel.textColor`
 
 A `String` hex code representing the label's current text color. Changing this value immediately updates the
diff --git a/lib/browser/api/touch-bar.js b/lib/browser/api/touch-bar.js
@@ -191,12 +191,12 @@ TouchBar.TouchBarButton = class TouchBarButton extends TouchBarItem {
     super()
     if (config == null) config = {}
     this._addImmutableProperty('type', 'button')
-    const { click, icon, iconPosition, label, backgroundColor } = config
-    this._addLiveProperty('label', label)
-    this._addLiveProperty('backgroundColor', backgroundColor)
-    this._addLiveProperty('icon', icon)
-    this._addLiveProperty('iconPosition', iconPosition)
-    if (typeof click === 'function') {
+    this._addLiveProperty('label', config.label)
+    this._addLiveProperty('accessibilityLabel', config.accessibilityLabel)
+    this._addLiveProperty('backgroundColor', config.backgroundColor)
+    this._addLiveProperty('icon', config.icon)
+    this._addLiveProperty('iconPosition', config.iconPosition)
+    if (typeof config.click === 'function') {
       this._addImmutableProperty('onInteraction', () => {
         config.click()
       })
@@ -209,14 +209,13 @@ TouchBar.TouchBarColorPicker = class TouchBarColorPicker extends TouchBarItem {
     super()
     if (config == null) config = {}
     this._addImmutableProperty('type', 'colorpicker')
-    const { availableColors, change, selectedColor } = config
-    this._addLiveProperty('availableColors', availableColors)
-    this._addLiveProperty('selectedColor', selectedColor)
+    this._addLiveProperty('availableColors', config.availableColors)
+    this._addLiveProperty('selectedColor', config.selectedColor)
 
-    if (typeof change === 'function') {
+    if (typeof config.change === 'function') {
       this._addImmutableProperty('onInteraction', (details) => {
         this._selectedColor = details.color
-        change(details.color)
+        config.change(details.color)
       })
     }
   }
@@ -239,6 +238,7 @@ TouchBar.TouchBarLabel = class TouchBarLabel extends TouchBarItem {
     if (config == null) config = {}
     this._addImmutableProperty('type', 'label')
     this._addLiveProperty('label', config.label)
+    this._addLiveProperty('accessibilityLabel', config.accessibilityLabel)
     this._addLiveProperty('textColor', config.textColor)
   }
 }
@@ -262,16 +262,15 @@ TouchBar.TouchBarSlider = class TouchBarSlider extends TouchBarItem {
     super()
     if (config == null) config = {}
     this._addImmutableProperty('type', 'slider')
-    const { change, label, minValue, maxValue, value } = config
-    this._addLiveProperty('label', label)
-    this._addLiveProperty('minValue', minValue)
-    this._addLiveProperty('maxValue', maxValue)
-    this._addLiveProperty('value', value)
+    this._addLiveProperty('label', config.label)
+    this._addLiveProperty('minValue', config.minValue)
+    this._addLiveProperty('maxValue', config.maxValue)
+    this._addLiveProperty('value', config.value)
 
-    if (typeof change === 'function') {
+    if (typeof config.change === 'function') {
       this._addImmutableProperty('onInteraction', (details) => {
         this._value = details.value
-        change(details.value)
+        config.change(details.value)
       })
     }
   }
@@ -290,17 +289,16 @@ TouchBar.TouchBarSegmentedControl = class TouchBarSegmentedControl extends Touch
   constructor (config) {
     super()
     if (config == null) config = {}
-    const { segmentStyle, segments, selectedIndex, change, mode } = config
     this._addImmutableProperty('type', 'segmented_control')
-    this._addLiveProperty('segmentStyle', segmentStyle)
-    this._addLiveProperty('segments', segments || [])
-    this._addLiveProperty('selectedIndex', selectedIndex)
-    this._addLiveProperty('mode', mode)
+    this._addLiveProperty('segmentStyle', config.segmentStyle)
+    this._addLiveProperty('segments', config.segments || [])
+    this._addLiveProperty('selectedIndex', config.selectedIndex)
+    this._addLiveProperty('mode', config.mode)
 
-    if (typeof change === 'function') {
+    if (typeof config.change === 'function') {
       this._addImmutableProperty('onInteraction', (details) => {
         this._selectedIndex = details.selectedIndex
-        change(details.selectedIndex, details.isSelected)
+        config.change(details.selectedIndex, details.isSelected)
       })
     }
   }
@@ -310,15 +308,16 @@ TouchBar.TouchBarScrubber = class TouchBarScrubber extends TouchBarItem {
   constructor (config) {
     super()
     if (config == null) config = {}
-    const { items, selectedStyle, overlayStyle, showArrowButtons, continuous, mode } = config
     let { select, highlight } = config
     this._addImmutableProperty('type', 'scrubber')
-    this._addLiveProperty('items', items)
-    this._addLiveProperty('selectedStyle', selectedStyle || null)
-    this._addLiveProperty('overlayStyle', overlayStyle || null)
-    this._addLiveProperty('showArrowButtons', showArrowButtons || false)
-    this._addLiveProperty('mode', mode || 'free')
-    this._addLiveProperty('continuous', typeof continuous === 'undefined' ? true : continuous)
+    this._addLiveProperty('items', config.items)
+    this._addLiveProperty('selectedStyle', config.selectedStyle || null)
+    this._addLiveProperty('overlayStyle', config.overlayStyle || null)
+    this._addLiveProperty('showArrowButtons', config.showArrowButtons || false)
+    this._addLiveProperty('mode', config.mode || 'free')
+
+    const cont = typeof config.continuous === 'undefined' ? true : config.continuous
+    this._addLiveProperty('continuous', cont)
 
     if (typeof select === 'function' || typeof highlight === 'function') {
       if (select == null) select = () => {}
diff --git a/shell/browser/ui/cocoa/atom_touch_bar.mm b/shell/browser/ui/cocoa/atom_touch_bar.mm
@@ -363,6 +363,10 @@ - (void)updateButton:(NSCustomTouchBarItem*)item
     button.bezelColor = nil;
   }
 
+  std::string accessibilityLabel;
+  settings.Get("accessibilityLabel", &accessibilityLabel);
+  button.accessibilityLabel = base::SysUTF8ToNSString(accessibilityLabel);
+
   std::string label;
   settings.Get("label", &label);
   button.title = base::SysUTF8ToNSString(label);
@@ -405,6 +409,10 @@ - (void)updateLabel:(NSCustomTouchBarItem*)item
   settings.Get("label", &label);
   text_field.stringValue = base::SysUTF8ToNSString(label);
 
+  std::string accessibilityLabel;
+  settings.Get("accessibilityLabel", &accessibilityLabel);
+  text_field.accessibilityLabel = base::SysUTF8ToNSString(accessibilityLabel);
+
   std::string textColor;
   if (settings.Get("textColor", &textColor) && !textColor.empty()) {
     text_field.textColor = [self colorFromHexColorString:textColor];
