[RFC]: add support for keyboard shortcuts

kgryte commented 3 years ago

Description

This RFC proposes adding support for keyboard shortcuts to the API documentation. Would be nice, e.g., to be able to open and close the side menu, to focus on the search input element, etc.

A list of possible keyboard shortcuts:

/: focus on search (Algolia used cmd + k)
fn + <-: navigate to "previous" package
fn + ->: navigate to "next" package
m: toggle side menu
shift + f: focus on side menu filter (similar to cmd + f/ctrl + f for browser find)
shift + return: run code example (once supported)
?: display help page (i.e., how to use the documentation, including keyboard shortcuts)
b: open benchmarks page (if exists)
t: open tests page (if exists)
shift + t: navigate to TypeScript docs (if exists)
s: navigate to source code (if exists)
p: navigate to package doc page (if, e.g., currently on a package's benchmarks page)
c: navigate to a package's changelog (if exists)
d: toggle dark mode (once supported)
esc: close search results/help/settings menu

Others?

Related Issues

No.

Questions

No.

Other

WebAIM: list of shortcuts used for web accessibility. We should avoid overlapping with these.

Checklist

[X] I have read and understood the Code of Conduct.
[X] Searched for existing issues and pull requests.
[X] The issue name begins with RFC:.

kgryte commented 2 years ago

Given that more than two themes may be supported, should think about how keyboard shortcuts should work for theming. Could use modifiers and numbers or could use the same key to cycle through themes.

Should also consider keyboard shortcuts for other settings, such as documentation mode and example code syntax.

lovelindhoni commented 6 months ago

@kgryte, I would like to work on this enhancement, but before that, I would appreciate it if you could clarify something for me. ~~How about using third-party hooks like react-hotkeys-hook~~

Edit: I've noticed that using react-hotkeys-hook inside a class component requires a lot of patchwork. I will write my own logic instead.

lovelindhoni commented 6 months ago

hello @kgryte, I could really use your input on something. Could you provide me with additional context regarding this package's changelog? Additionally, I need some guidance on setting up shortcuts for navigating to previous and next packages, since the usage of prop drillling appears extensive, I'm struggling to grasp its flow.

Description

This RFC proposes adding support for keyboard shortcuts to the API documentation. Would be nice, e.g., to be able to open and close the side menu, to focus on the search input element, etc.

A list of possible keyboard shortcuts:

/: focus on search (Algolia used cmd + k)

fn + <-: navigate to "previous" package

fn + ->: navigate to "next" package

m: toggle side menu

shift + f: focus on side menu filter (similar to cmd + f/ctrl + f for browser find)

shift + return: run code example (once supported)

?: display help page (i.e., how to use the documentation, including keyboard shortcuts)

b: open benchmarks page (if exists)

t: open tests page (if exists)

shift + t: navigate to TypeScript docs (if exists)

s: navigate to source code (if exists)

p: navigate to package doc page (if, e.g., currently on a package's benchmarks page)

c: navigate to a package's changelog (if exists)

d: toggle dark mode (once supported)

esc: close search results/help/settings menu

Others?

Related Issues

No.

Questions

No.

Other

WebAIM: list of shortcuts used for web accessibility. We should avoid overlapping with these.

Checklist

[x] I have read and understood the Code of Conduct.

[x] Searched for existing issues and pull requests.

[x] The issue name begins with RFC:.

kgryte commented 6 months ago

@lovelindhoni What are you wanting to know about the Changelog?

For pagination, see https://github.com/stdlib-js/www/blob/master/src/components/readme/next.jsx and https://github.com/stdlib-js/www/blob/master/src/components/readme/prev.jsx. One possibility for implementing prev/next shortcuts is to have global keypress listeners which then simply trigger a click event on the respective links, thus triggering navigation. E.g., query the document for the element with the pagination-link-next class. Note, however, that, in this case, prev/next navigation should only happen when the user is currently viewing a package README with prev/next links in the README footer.

lovelindhoni commented 6 months ago

Thank you, @kgryte, I have nearly implemented all of the proposed keyboard shortcuts. In the help page, what else could it include besides keyboard shortcuts? If so, does the help page should be accessible to mobile users?

kgryte commented 6 months ago

For now just the keyboard shortcuts can be displayed in the help page.

Re: mobile. We should probably disable keyboard shortcuts on mobile devices.

stdlib-js / www