@progress/wct-a11y-spec/dist/design-system/Chart.json

Contains accessibility and keyboard navigation specification of Telerik and Kendo web components.

[
    {
        "h2": "Accessibility Support"
    },
    {
        "p": "Out of the box, the Telerik and Kendo UI Chart provides extensive accessibility support and enables users with disabilities to acquire complete control over its features."
    },
    {
        "p": "The Chart is compliant with the [Web Content Accessibility Guidelines (WCAG) 2.2 standards](https://www.w3.org/TR/WCAG22/) and [Section 508](http://www.section508.gov/) requirements, follows the [Web Accessibility Initiative - Accessible Rich Internet Applications (WAI-ARIA)](https://www.w3.org/WAI/ARIA/apg/) best practices for implementing the [keyboard navigation](#keyboard-navigation) for its `component` role, provides options for [managing its focus](#managing-the-focus) and is tested against the most popular [screen readers](#screen-readers)."
    },
    {
        "h3": "WAI-ARIA"
    },
    {
        "p": "This section lists the selectors, attributes, and behavior patterns supported by the component and its composite elements, if any."
    },
    {
        "p": "The Chart is an interactive Graphics Document (https://www.w3.org/TR/graphics-aria-1.0/#graphics-document). All actions available for mouse users are also available via keyboard shortcuts."
    },
    {
        "table": {
            "headers": [
                "Selector",
                "Attribute",
                "Usage"
            ],
            "rows": [
                {
                    "Selector": "`.k-chart`",
                    "Attribute": "`role=graphics-document`",
                    "Usage": "Indicates that the Chart element is a Graphics Document."
                },
                {
                    "Selector": "",
                    "Attribute": "`aria-roledescription`",
                    "Usage": "User-set value that clarifies the type of Chart to screen reader users."
                },
                {
                    "Selector": "",
                    "Attribute": "`aria-label`",
                    "Usage": "Announces the user-set title of the Chart."
                },
                {
                    "Selector": "`.k-chart-point`",
                    "Attribute": "`role=graphics-symbol`",
                    "Usage": "Specifies the role of the series point elements."
                },
                {
                    "Selector": "",
                    "Attribute": "`aria-roledescription=Point`",
                    "Usage": "Describes the role of the series point elements."
                },
                {
                    "Selector": "`.k-chart-legend-item`",
                    "Attribute": "`role=checkbox`",
                    "Usage": "Specifies the role of the legend item element."
                },
                {
                    "Selector": "",
                    "Attribute": "`aria-label`",
                    "Usage": "Specifies the name of the series associated with this legend item."
                },
                {
                    "Selector": "",
                    "Attribute": "`aria-roledescription=Legend item`",
                    "Usage": "Specifies the name of the series associated with this legend item."
                }
            ]
        }
    },
    {
        "h3": "Managing the Focus"
    },
    {
        "p": "This feature aims to add keyboard support to the Chart widget. Keyboard navigation will be enabled for points of the chart series, as well as legend items. Moving focus along these points allows screen readers to access the points accessibility attributes."
    },
    {
        "p": "The method by which focus is moved through the points will be consistent with other big Kendo widgets, such as the Grid and Scheduler. The only focusable element will be the chart itself, so that users can quickly tab in and out of the component. Moving through points will be done using the arrow keys (and tab/shift+tab between the chart and legend area), and updating an `aria-activedescendant` attribute on the focused chart element. The individual points will not be focusable. Clicking on a point or legend item will move the focus inside the chart, and focus the clicked item."
    },
    {
        "h3": "Keyboard Navigation"
    },
    {
        "p": "Once the element receives focus, there will be `focusable areas` the user can be in. Initially focus is set on the first point in the series. If the user hits `Tab` focus is moved to the legend items. Hitting `Tab` again moves focus out of the chart and onto the next focusable element on the page. If the chart doesn't have a legend, hitting `Tab` the first time moves focus out of the chart directly."
    },
    {
        "p": "Note: if the legend position is `top` or `left`, the order is reversed - the legend will be the first to receive focus, and the chart second."
    },
    {
        "p": "So there are two contexts, in which the user can navigate:"
    },
    {
        "h4": "Focus is in the chart area"
    },
    {
        "p": "When going through the items of a series with the arrow keys, when you reach the end of the series you will be moved to the first item of the next series (and vice versa). This will allow going through all items in the chart using only one arrow key - for instance in a bar chart pressing `Right Arrow` will move through all items of series A, then all items of series B, then all items of series C, and only then loop back to series A."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Tab`",
                    "Behavior": "Moves focus to the Legend items, focusing the first legend item. If legend is not available, moves focus to the next focusable element on the page."
                },
                {
                    "Shortcut": "`Shift + Tab`",
                    "Behavior": "Moves focus to the previous focusable element on the page."
                },
                {
                    "Shortcut": "`Arrow` keys",
                    "Behavior": "Based on the chart type, the arrow keys move through points or series."
                },
                {
                    "Shortcut": "`Enter` key",
                    "Behavior": "Triggers the click action for the series point or legend item."
                },
                {
                    "Shortcut": "`Escape` key",
                    "Behavior": "Closes the series tooltip if it was open. A second press will move the focus to the root element of the chart."
                }
            ]
        }
    },
    {
        "h5": "Categorical charts"
    },
    {
        "p": "These include `Area`, `RangeArea`, `Bar`, `Column`, `RangeBar`, `Bullet`, `Waterfall`, `Line`, `CandleStick`, `BoxPlot`."
    },
    {
        "p": "They can be either horizontal (bar), or vertical (column). The orientation is determined by the first series type. All other charts adhere to this orientation."
    },
    {
        "p": "Charts in this category can also have several panes, oriented below each other. This is only supported in the `column/vertical` orientation."
    },
    {
        "p": "When the charts are grouped in several panes, the `Up/Down arrow` keys should move between series taking the panes into consideration first. That is to say, pressing `Down arrow` should loop through all series from the top pane before going to the series in the bottom pane, regardless of the points value. Since panes apply only to vertical charts, there is no equivalent requirement for the `Left/Right arrow` keys in the vertical horizontal charts."
    },
    {
        "p": "When the chart is horizontal, the flow if items in the series is inverted - instead of points going from left to right, they go from top to bottom. So to preserve the natural flow of the keyboard navigation, the `Up/Down` and `Left/Right` keys are swapped (`Up/Down arrow` goes through items of a series, while `Left/Right arrow` goes through different series)."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Up/Down` arrow keys",
                    "Behavior": "Move through the different series. The order in which this occurs determines the action of the arrow keys. For stacked `Bar/Column` charts and `Line/Area` charts `Up/Down arrow` keys will move focus to next/previous series item, based on its coordinates. Thus moving the the closest point available. If several series are present on a single pane, the focus first moves through all items of series of the same type, before jumping on the next. Thus if you have a stacked bar with two series and a single line series, the focus will first traverse all bar series before moving to the line, regardless of the line point coordinates. Regular `Bar` charts and it's derivatives (`Waterfall`, `Candlestick` etc.) will move focus according to the database order."
                },
                {
                    "Shortcut": "`Left/Right` arrow keys",
                    "Behavior": "Move through the points in the series."
                }
            ]
        }
    },
    {
        "h5": "Donut charts"
    },
    {
        "p": "Only the `Donut` chart type lives here. You can have several series, which become nested in the plot area."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Up` arrow key",
                    "Behavior": "Move to the outer series."
                },
                {
                    "Shortcut": "`Down` arrow key",
                    "Behavior": "Move to inner series."
                },
                {
                    "Shortcut": "`Right` arrow key",
                    "Behavior": "Move through the points of the series in a clockwise direction."
                },
                {
                    "Shortcut": "`Left` arrow key",
                    "Behavior": "Move through the points of the series in a anti-clockwise direction."
                }
            ]
        }
    },
    {
        "h5": "Pie charts"
    },
    {
        "p": "Only the `Pie` chart type lives here. Each pie chart can display only one series."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Right` arrow key",
                    "Behavior": "Move through the points of the series in a clockwise direction."
                },
                {
                    "Shortcut": "`Left` arrow key",
                    "Behavior": "Move through the points of the series in a anti-clockwise direction."
                }
            ]
        }
    },
    {
        "h5": "Scatter charts"
    },
    {
        "p": "The scatter charts are `Scatter`, `ScatterLine` and `Bubble`. You can have multiple series of each on the same plot area."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Up/Down` arrow keys",
                    "Behavior": "Move through the series. Since the scatter chart is chaotic by design, the only natural and predictable order is the one from the datasource. Several competitors have tried to follow a visual order for these keys, which results in broken and unexpected navigation (going up through items follows a different order than going down, several points are unaccessible etc.)."
                },
                {
                    "Shortcut": "`Left/Right` arrow keys",
                    "Behavior": "Move through items in the current series."
                }
            ]
        }
    },
    {
        "h5": "Funnel charts"
    },
    {
        "p": "Here are the `Funnel` and `Pyramid` charts. Only one series can be displayed at a time."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Up/Down` arrow keys",
                    "Behavior": "Move through the items in the chart."
                }
            ]
        }
    },
    {
        "h5": "Radar charts"
    },
    {
        "p": "Here you have `RadarLine`, `RadarBar` and `RadarArea`. Radar charts are basically categorical charts. You can have multiple series of each on the same plot area."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Up/Down` arrow keys",
                    "Behavior": "Here we have a difference between the `RadarColumn` and `RadarLine/Area` charts. In the `RadarColumn` chart series are placed next to each other, and thus `Up/Down arrow` is expected to move in a clockwise/anti-clockwise manner, moving through them respectively. `RadarLine/Area` charts however place the series on top of each other, and therefore each point is visually above or below the respective points in the other series based on it's value. Here the `Up/Down arrow` keys move relative to the value of the points, and move the next/previous series point based on the value, rather than the datasource order. In essence pressing `Up arrow` will move to points away from the center of the chart, and pressing `Down arrow` will move towards the center."
                },
                {
                    "Shortcut": "`Right` arrow key",
                    "Behavior": "Move through the points of the series in a clockwise direction."
                },
                {
                    "Shortcut": "`Left` arrow key",
                    "Behavior": "Move through the points of the series in a anti-clockwise direction."
                }
            ]
        }
    },
    {
        "h5": "Polar charts"
    },
    {
        "p": "Here you have `PolarLine`, `PolarArea` and `PolarScatter`. Radar charts are basically scatter charts. You can have multiple series of each on the same plot area."
    },
    {
        "p": "Since the charts are basically scatter charts, they follow the same keboard navigation logic."
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Up/Down` arrow keys",
                    "Behavior": "Move through the series. Since the scatter chart is chaotic by design, the only natural and predictable order is the one from the datasource."
                },
                {
                    "Shortcut": "`Left/Right` arrow keys",
                    "Behavior": "Move through items in the current series."
                }
            ]
        }
    },
    {
        "h5": "Heatmap"
    },
    {
        "p": "The heatmap will resemble a grid or excel table when navigating. The arrow keys will move through items in the respective direction, skipping over empty spaces."
    },
    {
        "h5": "Stock Chart"
    },
    {
        "p": "The stock chart is basically a regular chart, with the addition of a navigator. Only the regular chart series will be included in the tab order, while the navigator will not be accessible."
    },
    {
        "h4": "Focus is in the legend area"
    },
    {
        "table": {
            "headers": [
                "Shortcut",
                "Behavior"
            ],
            "rows": [
                {
                    "Shortcut": "`Tab` key",
                    "Behavior": "Move focus to the next focusable element on the page."
                },
                {
                    "Shortcut": "`Shift + Tab` key",
                    "Behavior": "Move focus to the chart area, focusing the first point in the first series."
                },
                {
                    "Shortcut": "`Up/Left` arrow key",
                    "Behavior": "Move focus to the previous legend item. If we're already at the first item, focus cycles to the last item."
                },
                {
                    "Shortcut": "`Down/Right` arrow key",
                    "Behavior": "Move focus to the next legend item. If we're already at the last item, focus cycles to the first item."
                },
                {
                    "Shortcut": "`Enter` key",
                    "Behavior": "Toggles the series visibility similar to the click action."
                },
                {
                    "Shortcut": "`Escape` key",
                    "Behavior": "Moves the focus to the root element of the chart."
                }
            ]
        }
    },
    {
        "h3": "Interactions"
    },
    {
        "h4": "Hover and inactive states"
    },
    {
        "p": "The chart has a functionality where upon hovering a point or a legend item, the other points in the series or other series become faded (inactive). Here's how this feature will work alongside focus, and the focused state:"
    },
    {
        "ul": [
            "While a point or legend item is focused, if the mouse hovers over a point/series, the behavior will be the same as it is currently - the inactive points will be faded. If the focused point is also a part of the inactive points, it will receive the lower opacity look. It will not however lose the focused styles and state.",
            "When the focused item changes through the arrow/tab keys, it's series will become active again, and focus will move accordingly. The other series will be marked as inactive, as if the focused point was hovered."
        ]
    },
    {
        "h4": "Series tooltips"
    },
    {
        "p": "Focusing a series point with the keyboard will also open the tooltip, if configured. To close the tooltip, press Escape or use Tab to move the focus to a different element."
    },
    {
        "h3": "Testing"
    },
    {
        "p": "The Chart has been extensively tested automatically with [axe-core](https://github.com/dequelabs/axe-core) and manually with the most popular screen readers."
    },
    {
        "h3": "Screen Readers"
    },
    {
        "p": "The Chart has been tested with the following screen readers and browsers combinations:"
    },
    {
        "table": {
            "headers": [
                "Environment",
                "Tool"
            ],
            "rows": [
                [
                    "Firefox",
                    "NVDA"
                ],
                [
                    "Chrome",
                    "JAWS"
                ],
                [
                    "Microsoft Edge",
                    "JAWS"
                ]
            ]
        }
    },
    {
        "h3": "Resources"
    },
    {
        "ul": [
            {
                "link": {
                    "source": "https://www.w3.org/TR/graphics-aria-1.0/",
                    "title": "WAI-ARIA Graphics Module"
                }
            },
            {
                "link": {
                    "source": "https://a11y-style-guide.com/style-guide/section-media.html#kssref-media-svgs",
                    "title": "Accessibility Style Guide: SVGs"
                }
            }
        ]
    }
]