Forem Creators and Builders 🌱

Cover image for Keyboard shortcuts
Andrew Bone
Andrew Bone

Posted on

Keyboard shortcuts

It's now possible to 'easily' add keyboard shortcuts to components used in forem. Some already exist like pressing / to focus on the search bar or pressing 0 to enter 'zen' mode on the feed.

Also feed navigation is coming

A11y: Add keyboard navigation to article feed #10468

What type of PR is this? (check all applicable)

  • [ ] Refactor
  • [x] Feature
  • [ ] Bug Fix
  • [ ] Optimization
  • [ ] Documentation Update

Description

This adds keyboard navigation to the article feed (and potentially more stuff).

Related Tickets & Documents

Closes #596

QA Instructions, Screenshots, Recordings

Keys

  1. j goes down
  2. k goes up

Behavior

If no article is focused on (or anything inside an article), the first article that is visible in the feed is focused on

Demo

demo

Added tests?

  • [x] yes
  • [ ] no, because they aren't needed
  • [ ] no, because I need help

Added to documentation?

  • [ ] docs.forem.com
  • [ ] readme
  • [x] no documentation needed

JSDoc added

How it works

The hook can be called in any functional component.

useGlobalListNavigation(
  'article[id=featured-story-marker],article[id^=article-]',
  'a[id^=article-link-]',
  'div.paged-stories',
);
Enter fullscreen mode Exit fullscreen mode

3 params

  1. itemContainerSelector: The selector for the highest level of the list item
  2. focusableSelector: What should actually be focused on in the list item container
  3. waterfallItemContainerSelector (optional): selector of the waterfall container if the list of items uses a waterfall-like architecture, like the article feed.

Flow

It uses the new global key event listener hook (which is now used by the search bar for / and 0) to listen for j and k.

On the first keypress, it focuses on the first visible article. Then it follows one of the next paths:

Happy path:

  1. Get closest parent article of the currently focused-on element
  2. Get next or previous sibling
  3. Get the link of sibling
  4. Focus on link

Dealing with the article feed waterfall

What I refer to as the waterfall:

<article></article>
<article></article>
<article></article>
<div class="paged-stories">
  <article></article>
  <article></article>
  <article></article>
  <div class="paged-stories">
    <article></article>
    <article></article>
    <article></article>
  </div>
</div>
Enter fullscreen mode Exit fullscreen mode
Going down the waterfall
  1. Get closest parent article of the currently focused-on element
  2. Get next sibling (is a paged-stories div)
  3. Get the next article link in DOM (article link of the first article in the div)
  4. Focus on the article link
Going up the waterfall
  1. Get closest parent article of the currently focused-on element
  2. Get previous sibling (there is none)
  3. Get parent paged-stories div
  4. Get previous sibling (is an article)
  5. Get the article link
  6. Focus on the article link

Are there any keyboard shortcuts you'd like to see? Make some suggestions down below or make a feature request over on the Repo.

PR to add keyboard shortcuts:

If you're interested in the hook that is used to make keyboard shortcuts easy it's here.

Feel free to explore it and even use it to add your own shortcuts (once the team accepts the feature request).

Allow keyboard shortcuts #10713

What type of PR is this? (check all applicable)

  • [ ] Refactor
  • [x] Feature
  • [ ] Bug Fix
  • [ ] Optimization
  • [ ] Documentation Update

Description

Add handler for keyboard shortcuts. This allows custom shortcuts to be set up on a page by page (or even component by component) basis.

React demo

Usage

In this example we're going to run a function when the user presses CTRL+SHIFT+P

const shortcuts = {
  "ctrl+shift+KeyP":  (e) => {
    e.preventDefault();
    someFunction();
  }
}

<KeyboardShortcuts shortcuts={shortcuts} />
Enter fullscreen mode Exit fullscreen mode

Related Tickets & Documents

related: #5023 #596

QA Instructions, Screenshots, Recordings

This facilitates changes in the future

Added tests?

  • [x] yes
  • [ ] no, because they aren't needed
  • [ ] no, because I need help

Added to documentation?

  • [ ] docs.forem.com
  • [ ] readme
  • [x] no documentation needed

[optional] Are there any post deployment tasks we need to perform?

Once this is merged I'd like to modify this current shortcut to use this method before thinking about what other shortcuts could/should be added.

[optional] What gif best describes this PR or how it makes you feel?

seeing the code

Top comments (2)

Collapse
 
ben profile image
Ben Halpern

This is great. One shortcut that "went missing" when we updated the design of the comment and reworked keyboard functionality area was the ability to command/ctrl+return to submit.

When the functionality was less organized, I'm not surprised we lost it without a regression test, but glad we have a better approach to this now.

Collapse
 
ben profile image
Ben Halpern

Made an issue

cmd/ctrl+return to submit comment #11086

This functionality used to exist and then went missing without a regression test. We now have more sophisticated approaches for doing keyboard shortcuts. We should re-enable this.