Add Accessibility API (#10961)

Add AccessibilityInformation interface.
Add optional accessibilityInformation to StatusBarItem and TreeItem.
Proposed API:
Add StatusBarItemOptions (containing accessibilityInformation).
Provide window.createStatusBarItem(StatusBarItemOptions).

Update createStatusBarItem handler to handle StatusBarItems.

Contributed on behalf of STMicroelectronics.

Author: sgraband

CHANGELOG.md

@@ -10,10 +10,10 @@
 
 - [core] Move code for untitled resources into `core` from `plugin-ext` and allow users to open untitled editors with `New File` command. [#10868](https://github.com/eclipse-theia/theia/pull/10868)
 - [plugin] added support for `SnippetString.appendChoice` [#10969](https://github.com/eclipse-theia/theia/pull/10969) - Contributed on behalf of STMicroelectronics
+- [plugin] added support for `AccessibilityInformation` [#10961](https://github.com/eclipse-theia/theia/pull/10961) - Contributed on behalf of STMicroelectronics
 
 <a name="breaking_changes_1.25.0">[Breaking Changes:](#breaking_changes_1.25.0)</a>
 
-
 ## v1.24.0 - 3/31/2022
 
 [1.24.0 Milestone](https://github.com/eclipse-theia/theia/milestone/32)

packages/core/src/browser/shell/application-shell.ts

@@ -1422,6 +1422,10 @@ export class ApplicationShell extends Widget {
                 alignment: StatusBarAlignment.RIGHT,
                 tooltip: 'Toggle Bottom Panel',
                 command: 'core.toggle.bottom.panel',
+                accessibilityInformation: {
+                    label: 'Toggle Bottom Panel',
+                    role: 'button'
+                },
                 priority: -1000
             };
             this.statusBar.setElement(BOTTOM_PANEL_TOGGLE_ID, element);

packages/core/src/browser/status-bar/status-bar.tsx

@@ -22,6 +22,7 @@ import { ReactWidget } from '../widgets/react-widget';
 import { FrontendApplicationStateService } from '../frontend-application-state';
 import { LabelParser, LabelIcon } from '../label-parser';
 import { PreferenceService } from '../preferences';
+import { AccessibilityInformation } from '../../common/accessibility';
 
 export interface StatusBarEntry {
     /**
@@ -44,20 +45,14 @@ export interface StatusBarEntry {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     arguments?: any[];
     priority?: number;
+    accessibilityInformation?: AccessibilityInformation;
     onclick?: (e: MouseEvent) => void;
 }
 
 export enum StatusBarAlignment {
     LEFT, RIGHT
 }
 
-export interface StatusBarEntryAttributes {
-    className?: string;
-    title?: string;
-    style?: object;
-    onClick?: (e: MouseEvent) => void;
-}
-
 export const STATUSBAR_WIDGET_FACTORY_ID = 'statusBar';
 
 export const StatusBar = Symbol('StatusBar');
@@ -169,15 +164,15 @@ export class StatusBarImpl extends ReactWidget implements StatusBar {
         };
     }
 
-    protected createAttributes(entry: StatusBarEntry): StatusBarEntryAttributes {
-        const attrs: StatusBarEntryAttributes = {};
+    protected createAttributes(entry: StatusBarEntry): React.Attributes & React.HTMLAttributes<HTMLElement> {
+        const attrs: React.Attributes & React.HTMLAttributes<HTMLElement> = {};
 
         if (entry.command) {
             attrs.onClick = this.onclick(entry);
             attrs.className = 'element hasCommand';
         } else if (entry.onclick) {
             attrs.onClick = e => {
-                if (entry.onclick) {
+                if (entry.onclick && e instanceof MouseEvent) {
                     entry.onclick(e);
                 }
             };
@@ -189,15 +184,20 @@ export class StatusBarImpl extends ReactWidget implements StatusBar {
         if (entry.tooltip) {
             attrs.title = entry.tooltip;
         }
+        if (entry.className) {
+            attrs.className += ' ' + entry.className;
+        }
+        if (entry.accessibilityInformation) {
+            attrs['aria-label'] = entry.accessibilityInformation.label;
+            attrs.role = entry.accessibilityInformation.role;
+        } else {
+            attrs['aria-label'] = [entry.text, entry.tooltip].join(', ');
+        }
 
         attrs.style = {
             color: entry.color || this.color
         };
 
-        if (entry.className) {
-            attrs.className += ' ' + entry.className;
-        }
-
         return attrs;
     }
 

packages/core/src/common/accessibility.ts

@@ -0,0 +1,33 @@
+// *****************************************************************************
+// Copyright (C) 2022 STMicroelectronics and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
+// *****************************************************************************
+
+/**
+ * Accessibility information which controls screen reader behavior.
+ */
+export interface AccessibilityInformation {
+    /**
+     * Label to be read out by a screen reader once the item has focus.
+     */
+    readonly label: string;
+
+    /**
+     * Role of the widget which defines how a screen reader interacts with it.
+     * The role should be set in special cases when for example a tree-like element behaves like a checkbox.
+     * If role is not specified the editor will pick the appropriate role automatically.
+     * More about aria roles can be found here https://w3c.github.io/aria/#widget_roles
+     */
+    readonly role?: string;
+}

packages/messages/src/browser/notifications-contribution.ts

@@ -55,7 +55,10 @@ export class NotificationsContribution implements FrontendApplicationContributio
             alignment: StatusBarAlignment.RIGHT,
             priority: -900,
             command: NotificationsCommands.TOGGLE.id,
-            tooltip: this.getStatusBarItemTooltip(count)
+            tooltip: this.getStatusBarItemTooltip(count),
+            accessibilityInformation: {
+                label: this.getStatusBarItemTooltip(count)
+            }
         });
     }
     protected getStatusBarItemText(count: number): string {

packages/plugin-ext/src/common/plugin-api-rpc.ts

@@ -407,6 +407,7 @@ export interface StatusBarMessageRegistryMain {
         color: string | undefined,
         tooltip: string | undefined,
         command: string | undefined,
+        accessibilityInformation: theia.AccessibilityInformation,
         args: any[] | undefined): PromiseLike<void>;
     $dispose(id: string): void;
 }
@@ -713,6 +714,8 @@ export interface TreeViewItem {
 
     command?: Command;
 
+    accessibilityInformation?: theia.AccessibilityInformation;
+
 }
 
 export interface TreeViewSelection {

packages/plugin-ext/src/main/browser/status-bar-message-registry-main.ts

@@ -45,15 +45,22 @@ export class StatusBarMessageRegistryMainImpl implements StatusBarMessageRegistr
         color: string | undefined,
         tooltip: string | undefined,
         command: string | undefined,
+        accessibilityInformation: types.AccessibilityInformation,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         args: any[] | undefined): Promise<void> {
+        const ariaLabel = accessibilityInformation?.label;
+        const role = accessibilityInformation?.role;
+
         const entry = {
             text: text || '',
+            ariaLabel,
+            role,
             priority,
             alignment: alignment === types.StatusBarAlignment.Left ? StatusBarAlignment.LEFT : StatusBarAlignment.RIGHT,
             color: color && (this.colorRegistry.getCurrentColor(color) || color),
             tooltip,
             command,
+            accessibilityInformation,
             args
         };
 

packages/plugin-ext/src/main/browser/view/tree-view-widget.tsx

@@ -45,6 +45,7 @@ import { ContextKeyService } from '@theia/core/lib/browser/context-key-service';
 import * as markdownit from '@theia/core/shared/markdown-it';
 import { isMarkdownString } from '../../../plugin/markdown-string';
 import { LabelParser } from '@theia/core/lib/browser/label-parser';
+import { AccessibilityInformation } from '@theia/plugin';
 
 export const TREE_NODE_HYPERLINK = 'theia-TreeNodeHyperlink';
 export const VIEW_ITEM_CONTEXT_MENU: MenuPath = ['view-item-context-menu'];
@@ -63,6 +64,7 @@ export interface TreeViewNode extends SelectableTreeNode {
     tooltip?: string;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     description?: string | boolean | any;
+    accessibilityInformation?: AccessibilityInformation;
 }
 export namespace TreeViewNode {
     export function is(arg: TreeNode | undefined): arg is TreeViewNode {
@@ -159,6 +161,7 @@ export class PluginTree extends TreeImpl {
             tooltip: item.tooltip,
             contextValue: item.contextValue,
             command: item.command,
+            accessibilityInformation: item.accessibilityInformation,
         };
         const node = this.getNode(item.id);
         if (item.collapsibleState !== undefined && item.collapsibleState !== TreeViewItemCollapsibleState.None) {
@@ -301,6 +304,14 @@ export class TreeViewWidget extends TreeViewWelcomeWidget {
             id: node.id
         };
 
+        if (node.accessibilityInformation) {
+            attrs = {
+                ...attrs,
+                'aria-label': node.accessibilityInformation.label,
+                'role': node.accessibilityInformation.role
+            };
+        }
+
         if (node.tooltip && isMarkdownString(node.tooltip)) {
             // Render markdown in custom tooltip
             const tooltip = this.markdownIt.render(node.tooltip.value);

packages/plugin-ext/src/plugin/status-bar/status-bar-item.ts

@@ -29,6 +29,7 @@ export class StatusBarItemImpl implements theia.StatusBarItem {
     private _tooltip: string;
     private _color: string | ThemeColor;
     private _command: string | theia.Command;
+    private _accessibilityInformation: theia.AccessibilityInformation;
 
     private _isVisible: boolean;
     private _timeoutHandle: NodeJS.Timer | undefined;
@@ -73,6 +74,10 @@ export class StatusBarItemImpl implements theia.StatusBarItem {
         return this._command;
     }
 
+    public get accessibilityInformation(): theia.AccessibilityInformation {
+        return this._accessibilityInformation;
+    }
+
     public set text(text: string) {
         this._text = text;
         this.update();
@@ -93,6 +98,11 @@ export class StatusBarItemImpl implements theia.StatusBarItem {
         this.update();
     }
 
+    public set accessibilityInformation(information: theia.AccessibilityInformation) {
+        this._accessibilityInformation = information;
+        this.update();
+    }
+
     public show(): void {
         this._isVisible = true;
         this.update();
@@ -126,6 +136,7 @@ export class StatusBarItemImpl implements theia.StatusBarItem {
                 typeof this.color === 'string' ? this.color : this.color && this.color.id,
                 this.tooltip,
                 commandId,
+                this.accessibilityInformation,
                 args);
         }, 0);
     }

packages/plugin-ext/src/plugin/tree/tree-views.ts

@@ -386,7 +386,8 @@ class TreeViewExtImpl<T> implements Disposable {
                     tooltip: treeItem.tooltip,
                     collapsibleState: treeItem.collapsibleState,
                     contextValue: treeItem.contextValue,
-                    command: this.commandsConverter.toSafeCommand(treeItem.command, toDisposeElement)
+                    command: this.commandsConverter.toSafeCommand(treeItem.command, toDisposeElement),
+                    accessibilityInformation: treeItem.accessibilityInformation
                 } as TreeViewItem;
 
                 return treeViewItem;