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
-
j
goes down -
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
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',
);
3 params
-
itemContainerSelector
: The selector for the highest level of the list item -
focusableSelector
: What should actually be focused on in the list item container -
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:
- Get closest parent article of the currently focused-on element
- Get next or previous sibling
- Get the link of sibling
- 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>
Going down the waterfall
- Get closest parent article of the currently focused-on element
- Get next sibling (is a paged-stories div)
- Get the next article link in DOM (article link of the first article in the div)
- Focus on the article link
Going up the waterfall
- Get closest parent article of the currently focused-on element
- Get previous sibling (there is none)
- Get parent paged-stories div
- Get previous sibling (is an article)
- Get the article link
- 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.
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} />
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.
Top comments (2)
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.
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.