January 19, 2023

# Tab roadblocks and other keyboard enemies in the notebook widget

For the last few weeks, I have been trying to fix the [keyboard trap](https://www.w3.org/TR/WCAG21/#no-keyboard-trap) (what I've been calling a tab roadblock) in JupyterLab notebook cells.

You might be wondering: but I can get out of a code cell editor by pressing the escape key, so why is it a tab trap? The way the notebook extension works, when you press the escape key, it focuses the notebook widget's node, which essentially moves you backwards on the page. That's why I call them tab roadblocks rather than tab traps. It's not exactly a trap because you can get out of it using only the keyboard, but you can't move past it, so it's like a roadblock.[^first]

I can't seem to come up with a solution for the notebook cell tab roadblock that doesn't have some serious drawback or another. Perhaps I should start with how I would like keyboard-only interaction with the notebook to behave.

1. A user moves to different cells in the notebook with the up and down arrow keys or with 'J' and 'K', not with tab or shift+tab.
- Current behavior: Same, but user can get into code cells by pressing the tab key.
2. Whenever any interactive element inside of the notebook has received focus, whether it is a cell, the expand/collapse button, a button on a cell toolbar, a link, a diagram, or an ipywidget, all notebook keyboard shortcuts (such as 'J' and 'K') should still work, **unless the key is handled by that focussed element**. For example, when the user is typing within a code cell, we do not want 'J' or 'K' to move the user to a different cell , but if the user has focussed on a link in the notebook, then I think it makes sense that a 'J' or 'K' should move them to the cell below or above.
- Current behavior: most of the keyboard shortcuts only work when the notebook widget node has focus, [selector = ".jp-Notebook:focus"](https://github.com/jupyterlab/jupyterlab/blob/master/packages/notebook-extension/schema/tracker.json#L372). So for example, if you tab-focus onto a button in a cell's hover toolbar and then press 'J' or 'K', nothing happens.
3. Whenever the user moves the active cell cursor, the document focus should also move. This is to help blind and other non-sighted users who cannot rely on the visual indicator (which is currently a blue vertical bar, sometimes orange) to know which cell is active.
- Current behavior: document/browser focus does not move with the active cell cursor. Typically, focus alternates between the cell editor (edit mode) and the whole notebook node (command mode).
4. Exactly one cell wrapper in the notebook should always be tab-focusable. Note that I wrote cell wrapper to distinguish from the cell editor. I do not want the editor inside of the cell to be tab-focusable because that would (re)introduce a tab roadblock. In order to move inside of a cell editor, the user should press the enter key. To exit, they press the escape key. This allows the user to leave the notebook via the tab key and then return to the same cell via the tab key. This helps to put non-sighted users on a par with sighted users for being able to return to where they left off in the notebook.
- Current behavior: the only elements in the notebook that are tab-focusable are interactive elements that are tab-focusable by default: buttons, content-editable divs, input elements, and the like.

So what has been keeping me so far from building this experience?

The main issue that I've run into is trying to solve for #2. The notebook keyboard shortcuts are currently specified in [packages/notebook-extension/schema/tracker.json](https://github.com/jupyterlab/jupyterlab/blob/master/packages/notebook-extension/schema/tracker.json). These keyboard shortcuts [get processed on the capture phase](https://github.com/jupyterlab/lumino/blob/main/packages/application/src/index.ts#L580) of the keydown event, as opposed to the bubbling phase. This makes it hard for me to write code within the JupyterLab app that, for example, prevents the keyboard shortcut from executing if the event happens within some kind of text input element—because by the time the runtime gets to my code (if it gets to my code, either in the bubbling phase, or later in the capture phase of the event), the keyboard shortcut has already been handled.

Now, you might be thinking, well the notebook already has two modes (command and edit) which are [reflected in the DOM as classes](https://github.com/jupyterlab/jupyterlab/blob/master/packages/notebook/src/widget.ts#L63) (`jp-mod-commandMode` and `jp-mod-editMode`), so I should be able to simply hook into those in the shortcuts definition file, like so:

{
  "command": "notebook:move-cursor-down",
  "keys": ["J"],
  "selector": ".jp-Notebook.jp-mod-commandMode"
}

The problem is that a notebook cell's output area can contain almost anything. For example, if you put

import pdb; pdb.set_trace()

in a cell and run it, you will get dropped into a text input ([wrapped by the Stdin class](https://github.com/jupyterlab/jupyterlab/blob/master/packages/outputarea/src/widget.ts#L909)), but the notebook does not switch from command to edit mode. So the selector will apply, and pressing 'J' will move you to the next cell rather than put the letter 'j' into the text input.

We could consider moving these shortcuts out of the JSON file and into the Notebook class for more fine-grained control, but I think that would make it difficult to override the shortcuts via settings, am I correct?

If you're familiar with Lumino, you might be thinking about adding the [data-lm-suppress-shortcuts](https://github.com/jupyterlab/lumino/blob/main/packages/commands/src/index.ts#L1599) attribute to the output area. That would solve most of the issues. But it would also mean that while the user is focussed on any element inside the output area, none of the notebook keyboard shortcuts will work. For example, if the output area contains a link and the user tabs to that link and then presses the down arrow key, nothing will happen. Which means that the UX will diverge between links in rendered markdown versus links in code cell output. This discrepancy could create confusion for the user. They might think it's a bug: why would keyboard shortcuts like 'J' and 'K' work when focussed on one link in the notebook but not when focussed on another?

I have a sneaking sense that there may be some obvious solution staring me in the face, but I can't see it because I'm looking in the wrong place. I dunno. I'm curious to get other people's thoughts and insights.

[^first]: You might be thinking: but I can move out of the code cell by pressing the down arrow key, so is it _really_ a keyboard trap? I would argue yes, because even though you can get all the way down to the last code cell in the notebook, you can't actually get past the end of the notebook to the next focusable part of the JupyterLab UI. There is only one way that I've found, using only the keyboard, to get to focusable elements that come after a notebook. And that is to shift-tab backwards until you reach the beginning of the UI and then wrap back around to the end and work your way backwards until you get back to the end of the notebook. But that is such a convoluted workaround, I don't think it would be fair to use it as a way to argue that code cells are not a keyboard trap.