Descriptive aria-labels for Keyboard shortcuts which include punctuation previously ignored by screen readers

packages/widgets/src/commandpalette.ts

@@ -877,7 +877,14 @@ export namespace CommandPalette {
      */
     renderItemShortcut(data: IItemRenderData): VirtualElement {
       let content = this.formatItemShortcut(data);
-      return h.div({ className: 'lm-CommandPalette-itemShortcut' }, content);
+      let ariaContent = this.formatItemAria(data);
+      return h.div(
+        {
+          className: 'lm-CommandPalette-itemShortcut',
+          'aria-label': `${ariaContent}`
+        },
+        content
+      );
     }
 
     /**
@@ -973,6 +980,41 @@ export namespace CommandPalette {
       return kb ? CommandRegistry.formatKeystroke(kb.keys) : null;
     }
 
+    /**
+     * @returns The aria label content to add to the shortcut node.
+     */
+    formatItemAria(data: IItemRenderData): h.Child {
+      const keyToText: { [key: string]: string } = {
+        ']': 'Closing bracket',
+        '[': 'Opening bracket',
+        ',': 'Comma',
+        '.': 'Full stop',
+        "'": 'Single quote',
+        '-': 'Hyphen-minus'
+      };
+
+      let kbText = data.item.keyBinding;
+      let result = kbText ? CommandRegistry.formatKeystroke(kbText.keys) : null;
+
+      let punctuationRegex = /\p{P}/u;
+      let punctuations = result?.match(punctuationRegex);
+      if (!punctuations) {
+        return [];
+      }
+      for (const punctuation of punctuations) {
+        if (result != null && Object.keys(keyToText).includes(punctuation)) {
+          const individualKeys = result.split('+');
+          let index = individualKeys.indexOf(punctuation);
+          if (index != -1) {
+            individualKeys[index] = keyToText[punctuation];
+          }
+          const textShortcut = individualKeys.join('+');
+          return textShortcut;
+        }
+      }
+      return kbText ? CommandRegistry.formatKeystroke(kbText.keys) : null;
+    }
+
     /**
      * Create the render content for the item label node.
      *

packages/widgets/src/menu.ts

@@ -1221,7 +1221,14 @@ export namespace Menu {
      */
     renderShortcut(data: IRenderData): VirtualElement {
       let content = this.formatShortcut(data);
-      return h.div({ className: 'lm-Menu-itemShortcut' }, content);
+      let ariaContent = this.formatShortcutText(data);
+      return h.div(
+        {
+          className: 'lm-Menu-itemShortcut',
+          'aria-label': `${ariaContent}`
+        },
+        content
+      );
     }
 
     /**
@@ -1371,6 +1378,41 @@ export namespace Menu {
       let kb = data.item.keyBinding;
       return kb ? CommandRegistry.formatKeystroke(kb.keys) : null;
     }
+
+    /**
+     * @returns The aria label content to add to the shortcut node.
+     */
+    formatShortcutText(data: IRenderData): h.Child {
+      const keyToText: { [key: string]: string } = {
+        ']': 'Closing bracket',
+        '[': 'Opening bracket',
+        ',': 'Comma',
+        '.': 'Full stop',
+        "'": 'Single quote',
+        '-': 'Hyphen-minus'
+      };
+
+      let kbText = data.item.keyBinding;
+      let result = kbText ? CommandRegistry.formatKeystroke(kbText.keys) : null;
+
+      let punctuationRegex = /\p{P}/u;
+      let punctuations = result?.match(punctuationRegex);
+      if (!punctuations) {
+        return [];
+      }
+      for (const punctuation of punctuations) {
+        if (result != null && Object.keys(keyToText).includes(punctuation)) {
+          const individualKeys = result.split('+');
+          let index = individualKeys.indexOf(punctuation);
+          if (index != -1) {
+            individualKeys[index] = keyToText[punctuation];
+          }
+          const textShortcut = individualKeys.join('+');
+          return textShortcut;
+        }
+      }
+      return kbText ? CommandRegistry.formatKeystroke(kbText.keys) : null;
+    }
   }
 
   /**

packages/widgets/tests/src/commandpalette.spec.ts

@@ -552,6 +552,20 @@ describe('@lumino/widgets', () => {
           keys: ['Ctrl A'],
           selector: 'body'
         });
+        commands.addCommand('test-aria', {
+          label: 'Test Aria',
+          caption: 'A simple aria-label test',
+          className: 'testAriaClass',
+          isEnabled: () => enabledFlag,
+          isToggled: () => toggledFlag,
+          execute: () => {}
+        });
+        commands.addKeyBinding({
+          command: 'test-aria',
+          keys: ['Ctrl ,'],
+          selector: 'body'
+        });
+
         item = palette.addItem({
           command: 'test',
           category: 'Test Category'
@@ -827,6 +841,39 @@ describe('@lumino/widgets', () => {
           expect(child).to.equal('A simple test command');
         });
       });
+
+      describe('#formatItemShortcut()', () => {
+        it('should format the item shortcut text', () => {
+          let child = renderer.formatItemShortcut({
+            item,
+            indices: null,
+            active: false
+          });
+          if (Platform.IS_MAC) {
+            expect(child).to.equal('\u2303 A');
+          } else {
+            expect(child).to.equal('Ctrl+A');
+          }
+        });
+      });
+      describe('#formatItemAria', () => {
+        it('should format the item aria-label', () => {
+          let item = palette.addItem({
+            command: 'test-aria',
+            category: 'Test Category'
+          });
+          let child = renderer.formatItemAria({
+            item,
+            indices: null,
+            active: false
+          });
+          if (Platform.IS_MAC) {
+            expect(child).to.equal('\u2303 ,');
+          } else {
+            expect(child).to.equal('Ctrl+Comma');
+          }
+        });
+      });
     });
   });
 });

packages/widgets/tests/src/menu.spec.ts

@@ -85,6 +85,17 @@ describe('@lumino/widgets', () => {
       className: 'testClass',
       mnemonic: 0
     });
+    commands.addCommand('test-aria', {
+      execute: (args: JSONObject) => {
+        executed = 'test-aria';
+      },
+      label: 'Test Aria Label',
+      icon: iconRenderer,
+      iconClass,
+      caption: 'Test Caption',
+      className: 'testClass',
+      mnemonic: 0
+    });
     commands.addCommand('test-toggled', {
       execute: (args: JSONObject) => {
         executed = 'test-toggled';
@@ -127,6 +138,11 @@ describe('@lumino/widgets', () => {
       selector: 'body',
       command: 'test'
     });
+    commands.addKeyBinding({
+      keys: ['Ctrl ,'],
+      selector: 'body',
+      command: 'test-aria'
+    });
   });
 
   beforeEach(() => {
@@ -1591,6 +1607,21 @@ describe('@lumino/widgets', () => {
             expect(child).to.equal('Ctrl+T');
           }
         });
+        describe('#formatShortcutText()', () => {
+          it('should format the item aria-label', () => {
+            let item = menu.addItem({ command: 'test-aria' });
+            let child = renderer.formatShortcutText({
+              item,
+              active: false,
+              collapsed: false
+            });
+            if (Platform.IS_MAC) {
+              expect(child).to.equal('\u2303 ,');
+            } else {
+              expect(child).to.equal('Ctrl+Comma');
+            }
+          });
+        });
       });
     });
   });

review/api/widgets.api.md

@@ -245,6 +245,8 @@ export namespace CommandPalette {
         createItemDataset(data: IItemRenderData): ElementDataset;
         formatEmptyMessage(data: IEmptyMessageRenderData): h.Child;
         formatHeader(data: IHeaderRenderData): h.Child;
+        // (undocumented)
+        formatItemAria(data: IItemRenderData): h.Child;
         formatItemCaption(data: IItemRenderData): h.Child;
         formatItemLabel(data: IItemRenderData): h.Child;
         formatItemShortcut(data: IItemRenderData): h.Child;
@@ -763,6 +765,8 @@ export namespace Menu {
         createItemDataset(data: IRenderData): ElementDataset;
         formatLabel(data: IRenderData): h.Child;
         formatShortcut(data: IRenderData): h.Child;
+        // (undocumented)
+        formatShortcutText(data: IRenderData): h.Child;
         renderIcon(data: IRenderData): VirtualElement;
         renderItem(data: IRenderData): VirtualElement;
         renderLabel(data: IRenderData): VirtualElement;