Keyboard Accessibility - samvera-labs/ramp GitHub Wiki

Keyboard accessibility is one of the most important aspect of accessibility in web content. This provides an alternative way for users to access and navigate content on a web page when using a mouse or touch input is not feasible.

Historically, Ramp has had keyboard navigation implemented in the MediaPlayer component as hot-keys improve usability for keyboard users. And as part of @samvera/[email protected], this feature has been extended towards other components such as StructuredNavigation and Transcript. These components adapt accessible design patterns from W3C's patterns that are relevant for their respective usage and appearance.

Our goal in implementing keyboard navigation for individual components is to make it easier for a user to navigate in between components as well as within a single component. This was identified as an action item as part of an accessibility audit performed on Ramp's components in Fall 2023. Even though Ramp doesn't trap keyboard focus within a component, it can sometimes take a while for a user to reach some content on the page. For an example; when a Manifest with a longer structure is displayed in Ramp's demo site the user has to tab through every link in the structure to reach transcript content that is displayed after structure.

Please refer to the next section for documentation on keyboard navigation shortcuts and keys for each component.

MediaPlayer component

These keyboard accessibility shortcuts were introduced in @samvera/[email protected] and has been improved since. The keyboard shortcuts (hot-keys) enabled for MediaPlayer component are as follows;

List of supported hotkeys in the player are as follows;

  • Space key: play/pause media playback
  • M key: mute/un-mute media
  • F key: toggle full-screen on/off
  • Up arrow key: increase volume by 10% (full volume is equal to 100%)
  • Down arrow key: decrease volume by 10%
  • Left arrow key: jump 5 seconds backward from the current time in the player
  • Right arrow key: jump 5 seconds forward from the current time in the player

These keyboard interactions expected to work when a keyboard focus is not on an actionable HTML element such as an input field, a button, etc. These hotkeys were initially implemented using videojs-hotkeys plugin (Ramp V1.2.0), and later brought into Ramp's code as a in-built feature (Ramp V3.0.0) to allow more flexibility for extending future keyboard navigation implementations.

NEW 💥 Following keyboard accessibility shortcuts are introduced in @samvera/[email protected] 💥

AutoAdvanceToggle component

This component is rendered as a toggle button (switch) in the UI allowing the user to turn ON/OFF auto-advance between sections in the structure. Therefore, it adapts the Switch accessibility design pattern from W3C to implement keyboard navigation and accessibility. This implementation enables the use of both Enter and Space to toggle auto-advance with playback.

Annotations component

This component renders the annotations in a list view similar to transcript component with some additional features. Each annotation is displayed as an element that can be selected and clicked-on to seek the player to the respective timestamp. Therefore, it adapts the Listbox accessibility design pattern from W3C to implement keyboard navigation and accessibility. The specific mechanism implemented in the Annotations component for navigating the annotations is roving tabindex.

Guide for keyboard navigation in Annotations component;

  • User can tab into the Annotations component using Tab key
  • Once the user tabs into the Annotations component,
    • pressing Tab consecutively move from from container to drop-down select menu, auto-scroll checkbox, and annotations display in order
  • When focus is on the annotation set select drop-down menu
    • pressing either Enter/Space key toggles the drop-down menu
    • pressing ArrowDown/ArrowUp keys opens the drop-down menu
    • pressing any printable character key opens the drop-down menu and focuses on the first annotation set that starts with the character (if there's such an option exists)
    • once the drop-down menu is opened,
      • pressing ArrowDown/ArrowUp allows the user to focus on each annotation set option in the list
      • pressing End key focuses the last annotation set in the list
      • pressing Home key focuses the first annotation set in the list
      • pressing any printable character key focuses the first annotation set in the list that starts with the character (if such an option exists)
    • once focus is on an option pressing Enter/Space selects/un-selects the annotation set
    • once focus is on an option pressing Escape/Tab key closes the drop-down menu
  • When focus is on the auto-scroll checkbox
    • pressing Enter/Space checks/unchecks auto-scroll checkbox
    • pressing Tab moves the focus to the first annotation row
  • When focus is on an annotation row
    • pressing Enter/Space keys activates the annotation and seek the player to the annotation's timestamp
    • pressing ArrowDown/ArrowUp keys moves the focus to the next/previous annotation respectively
    • pressing Tab key when focused on an annotation with plain text moves focus to the next element in the tab order
    • pressing Tab key when focused on an annotation with links or show more/less button moves the focus into these links or buttons
    • pressing Shift+Tab keys moves the focus away from annotation row to its parent container

StructuredNavigation component

Ramp's StructuredNavigation component is rendered as a nested tree. Structure is broken into different sections, and each section can have multiple nested children. Therefore, StructuredNavigation component adapts the TreeView accessibility design pattern from W3C to implement keyboard navigation and accessibility.

Guide for keyboard navigation in StructuredNavigation component;

  • User can tab into the StructuredNavigation component using Tab key
  • When focus is on the component user can use ArrowDown key to move focus to the first structure item that either a button (section) or a link (timespan)
  • When keyboard focus is on a section (a button) item that is expanded;
    • pressing ArrowRight key moves the focus to its first child timespan
    • pressing ArrowLeft key collapses the section
    • pressing either Enter or Space loads the section into the media player
  • When keyboard focus is on a section (a button) item that is collapsed;
    • pressing ArrowLeft key does nothing
    • pressing ArrowRight key expands the section
    • pressing ArrowRight again moves the focus to its first child timespan
    • pressing either Enter or Space loads the section into the media player
  • When keyboard focus is on a timespan (a link);
    • pressing ArrowRight key doesn't do anything (disabled +5 second jump in the player)
    • pressing ArrowLeft key moves the focus to its parent section item
    • pressing Space or Enter key selects the timespan (seek the player to its start time)
  • When keyboard focus is on the collapse/expand all sections button on top of the structure;
    • pressing ArrowLeft collapses all sections and toggles the text in the button
    • pressing ArrowRight expands all section and toggles the text in the button
    • pressing Space or Enter key toggles all the sections
  • When keyboard focus is on any of the structure items;
    • pressing Shift + Tab moves the focus back to theStructuredNavigation container
    • pressing Tab moves the focus to the next UI portion on the page, in Ramp demo site this the Details tab next to structure

Transcript component

This component renders the transcript cues in a list view. Each cue is displayed as an element that can be selected and clicked-on to seek the player to the respective timestamp. Therefore, it adapts the Listbox accessibility design pattern from W3C to implement keyboard navigation and accessibility. The specific mechanism implemented in the Transcript component for navigating the cues is roving tabindex.

Guide for keyboard navigation in Transcript component;

  • User can tab into the Transcript component using Tab key
  • Pressing Tab key once more will move focus to transcript search field if it is present otherwise to the dropdown selection menu for selecting transcripts
  • When keyboard focus is on the transcript select drop-down menu,
    • pressing either ArrowUp or ArrowDown key will open the drop-down
    • pressing Tab key again will close the drop-down
    • pressing Tab key again will move focus to the transcript download button
  • When keyboard focus is on the file download button,
    • pressing Enter key will download the selected transcript file
    • pressing Tab key again will move focus to the auto-scroll checkbox
  • When keyboard focus is on the auto-scroll checkbox,
    • pressing Space key will uncheck/check the checkbox
    • pressing Tab key again will move focus to the first transcript cue in the list
  • When keyboard focus is on,
    • first transcript cue, pressing ArrowUp key will move focus to the last cue in the list
    • last transcript cue, pressing ArrowDown key will move focus to the first cue in the list
    • on any other cue, pressing ArrowUp key will move focus to the previous cue and pressing ArrowDown key will move focus to the next cue
    • pressing Enter key will activate the cue and seek the player to the cue's timestamp
  • To exit from the component, press Shift+Tab