Accessibility

Overview

Common Canvas supports accessibility through the use of Carbon components and, where necessary, with bespoke functions for UI components such as the flow editor canvas. The application can override styles such as color, line widths, etc and when this is done it is the responsibility of the application to ensure the customizations comply with accessibility guidelines.

Note: In the remarks below whereever Tab is mentioned to move focus highlighting between objects, you can assume that Shift + Tab can be used to do the reverse of what is described.

Keyboard Navigation

A major part of accessibility is allowing the user to move the focus highlighting around the different components of the UI and interact with those components using only the keyboard. The user can also press keyboard shortcuts to interact with those components.

Common Canvas supports keyboard navigation of the focus highlighting around its different components as follow:

Toolbar

The user can tab into and out of the toolbar. Once the focus highlighting is on a tool in the toolbar, the user can use the left and right arrow keys to move through the tools. The user can activate the tool with focus by pressing the space bar or return key.

The space bar or return key can be used to open any drop-down list associated with the tool and the up and down arrow keys can then be used to navigate through the menu options of the drop-down.

Additionally, the space bar or return key can also be used to open any sub-panel associated with the tool. The exitance of a sub-pannel is usually shown with a small triangular chevron in the bottom right corrner of the icon.

Once the focus is moved inside the sub-panel, the user can press the tab key to move focus through the panel’s components. It is recommended that the React object that the application provides to display the contents of a sub-panel should trap focus within the panel so that focus loops around inside the panel as the Tab is continuously pressed. The user can press the escape (esc) key to return focus to the toolbar button.

Palette

When focus is moved to the palette the user can use the Tab key to move focus from the Search field to the palette categories. When focus is on a category the space bar or return key can be used to open the category. When the category is open, the user can press the up and down arrow keys to move focus up and down through the nodes in the category.

When focus is on a node, the user can press the space bar or return key to add the node to the flow and, if a viable source node is available, a link will be created from it to the added node. (This is the equivalent of double-clicking the palette node).

If the user presses shift plus either the space bar or return key the node will be added to the flow without any link being created. (This is the equivalent of dragging the node from the palette onto the flow editor canvas).

Notification Panel

When the notificaiton panel is opened the focus highlighting appears on the close (X) button. The user can then navigate through the contents of the panel, including the messages and panel buttons, using the Tab key.

To exit the panel, the keyboard user can press the escape (esc) key or put the focus on the close (X) button and press the space bar or return key.

Flow Editor

When focus highlighting is moved to the flow editor, initially the whole viewport is highlighted. Pressing Cmnd + <comma> will display the context menu for the flow editor just like right-clicking on the flow editor background.

The user can press the Tab key to navigate through groups of unconnected nodes/comments within the flow. Once focus highlighting is on a member of group of connected nodes/comments, the user can use the arrow keys to navigate through the nodes and comments. Left and right arrow keys move focus along the flow while up and down arrow keys, when focus is on a link, will cycle through the set of links for the node or comment from which the focus was moved.

Navigation to a node or link’s sub-objects

Sub-objects are those elements within a node or link that the user may want to move focus to:

• For a node, they are input ports, output ports or decorations
• For a link, they are decorations or the start handle or end handle of the link (which can be moved, when the config property enableLinkSelection is set to Handles or Detachable).

For a node, the input ports can be made focusable by setting the inputPortFocusable property (of the node layout object) to true wheile output ports are made focuable by setting outputPortFocusable to true.

When focus is on a node or link, the user can press Option + Tab to put focus on the first of any of the “sub-objects” of the node or link. Once focus is on a sub-object the user can press Tab to move focus through the other sub-objects of the node or link. The focus is trapped on the node or link: that is, it loops around to the first sub-object after the user presses Tab with focus on the last sub-object. This prevents focus moving away from the node or link in an unexpected manner. The user can press the escape (esc) key to move focus away from the sub-objects and back to the parent node or link.

Navigation into and out of a node’s React object

If the application provides a React object to be displayed as the content of a node it is the application’s responsibility to ensure the focus can be moved around the components displayed by the React object as required.

For tabbing consistency, it is recommended that the application adopt the same approach as Common Canvas for sub-objects in that, once focus is moved to one of the sub-objects, the focus is ‘trapped’ inside the node so, for example, continuously pressing Tab will move the focus through all the focusable components in the React object.

There are a number of steps that need to be coded to make the application’s React object’s sub-objects work correctly with the keyboard navigation functions in Common Canvas, as follows:

1. The React object must have a focus(evt) method. This method will be called by Common Canvas whenever the user presses the Tab key or Shift + Tab to move the focus into the React object. The focus function is called with an evt parameter which is the Keyboard Event that caused the focus to move. The shiftKey property of the Event can be checked to see if the shift key was pressed with Tab or not. The React object code should then move the focus to the appropriate component in the React object or, it may be possible to rely on the browser’s tabbing capability to allow the focus to move.

2. The React object must register the ‘focus function’ with Common Canvas like this:

   this.props.canvasController.setSubObjectFocusFunction(this.props.nodeData.id, this.focus.bind(this));
   

   This can be done in the constructor of the React code. This will let Common Canvas know which function to call when the user presses the appropriate shortcut to move focus to the React object’s components.

3. The React object must call back to Common Canvas when appropriate. When the movement of focus reaches the point where focus needs to go back to the Common Canvas provided sub-objects (like ports or decorations) the React code should call either:

   this.props.canvasController.setFocusNextSubObject(this.props.nodeData, evt);
   

   or

   this.props.canvasController.setFocusPreviousSubObject(this.props.nodeData, evt);
   

   depending on whether the user pressed Tab or Shift + Tab respectively.

4. Make objects tabbable or untabbable. To prevent any spurious tabbing behavior, when the React object is first created and when the focus moves outside of the React object, any components inside the object must not be tabbable (that is, they should have their tabindex set to -1). When focus moves inside the React object any objects that need to be tabbed to must be made tabbable (that is, they should have their tabindex set to 0) if the React object is replying on the browser’s tabbing capability.

Warning: Some HTML elements, such as input and button, have a tabindex of 0 by default so they will need the tabindex to be set explicitely as appropriate.

The prompt react node in the Prompt sample application in the test harness implements these steps.