Add keyboard shortcuts for common actions

[maxpatiiuk]

Like this:

• [x] Particular menu item edit: decided not to do this in favor of allowing setting keyboard shortcuts for a URL as that would be more generic
• [ ] Expand/Collapse/Toggle side
• [ ] Common actions on different pages (save query, open mapping editor, ...)
• [ ] All common form actions (next,prev,add,remove, close dialog, next/prev attachment, save)
• [ ] Next/Previous attachment (#3057)
• [ ] Keyboard shortcut to change a pref (i.e, imagine a shortcut to toggle dark mode or switch the query combo box search algorithm)
• [ ] Allow adding keyboard shortcuts to any page or record
  • Or any collection of pages (Workspaces - https://github.com/specify/specify7/issues/2627)
• [ ] Allow remaining hardcoded key combinations like alt-click for new tab, shift/cntrl for tree click without foucs, shift/ctrl/cmd for select all in between

To meet the WCAG 2.1 requirements, these shortcuts must be customizable

Implementation idea: Split user preferences into 3 ultra-sections: Options (everything that is not in the next two) Theme (for setting UI colors - and add ability to customize more colors) Keyboard Shortcuts

[maxpatiiuk]

@CarolineDenis This one might be interesting for you

I have the code for the keyboard picker component already written so can push it if you want to work on it The remaining thing would be to create a hook like useKey('category', 'subcategory', 'item', callback) where 'category', 'subcategory', 'item' matches what you see in user prefs, and the callback is a function that will be called by the hook when the user presses the keyboard shortcut.

Edge cases to handle: If user assigned a shortcut like B (without Ctrl/alt/or other modified), than you have to make sure to only trigger the keyboard shortcut if user is not currently typing into a text field

[grantfitzsimmons]

1. When browsing records in forms view, I miss a keyboard shortcut for moving to the next/previous record.

This would be so nice to have!

Requested By: Eyal at The Hebrew University of Jerusalem

[maxpatiiuk]

Implementation idea: Split user preferences into 3 ultra-sections: Options (everything that is not in the next two) Theme (for setting UI colors - and add ability to customize more colors) Keyboard Shortcuts

I don't think this is the best solution anymore. Better implementation:

• Keep user preferences as is
• Add a new "Keyboard Shortcuts" item to User Tools menu that will have UI identical to user preferences (will use the same react component under the hood), but will be used only for setting keyboard shortcuts
• Do not add ways to arbitrary customize every color used in specify. Reasons:
  • that may only be used by more advanced users
  • the customized colors may make the specify appear broken (i.e when contrast becomes very low or non existent in certain places)
  • it would be a pain to maintain this in the future as specify UI changes without breakages to customizations people did
  • Instead, if there would be desire to expand themeing, an approach similar to what Grant suggested in https://github.com/specify/specify7/issues/1460 would be more manageable - extend the "Dark" and "Light" mode themes with more variants (Blue, Pink, Beige, ...)
  • optionally in the future also reduce the ability to pick 6 accent colors in specify to just 2 accent colors, from which specify will derive the other 4 by means of increasing and decreasing luminosity or other HSL manipulations

[grantfitzsimmons]

yes 100x to @maxpatiiuk 🎉

[maxpatiiuk]

Did a bit of research on this.

Complications:

• Many keyboard shortcuts are already taken by OS, browsers and browser extensions. And what shortcuts are taken can warry across operating systems. Picking a single default keyboard shortcut that works across systems is going to leave us with a very limited choice unless we go for harder-to-remember 3 and 4 key combinations
  • See a few options in https://stackoverflow.com/a/59010351/8584605. What I can do is have keyboard shortcuts that are just letters, (Q, W, R, D) but only activate them if user is not currently in a place where their input is accepted (input, textarea, text editor)
• A keyboard shortcut like Cmd+Shift+Q (i.e for opening query builder), presents several internationalization challenges:
  • if we are listening for letter Q being pressed, then the key shortcut is not going to work if you have a non-English keyboard layout - meaning our default keyboard shortcuts would only work on English keyboards (unless we settle for only using keyboard shortcuts that don't include letters in them - like Cmd+Shift+ArrowUp and etc)
  • if we are listening for a press of a key that is key q on US keyboards, then the shortcut would work on all keyboard layouts, but may no longer correspond to what is printed as letter Q on their keyboard (i.e French keyboards). So if our UI shows press letter Q, they will have to find a key labeled Q on their keyboard, even if they keyboard layout has no such letter.
  • Fortunately, in many regions, even if non-English language is used day to day, the keys are dual-labeled with local language + English letters, so software often shows Ctrl+Q keyboard shortcut in the UI, and expects users to know where that is
  • another issue is that a shortcut like Ctrl+O may be ambiguous. Let's say Specify is listening for press of the key that has O on it in US English layout. In a Cyrillic layout, there is a Cyrillic letter O, which is in place where English J is located, and so pressing this won't trigger the Ctrl+O shortcut (but will trigger Ctrl+J if there is such)
    • to reduce confusion, we should not localize the modifier keys between languages. however, we should change the name of modifiers between platforms (mac: ⌘⌃⌥⇧; others: Ctrl,Alt,Option,Shift) as that is the less confusing path
  • in other languages, query builder may not begin with the letter q (which might not even be in their alphabet), thus making this shortcut harder to remember than it is for English users (partially mitigated by the fact that we will let people re-assign the shortcuts)
• An easy, but non-satisfactory solution is if we simply don't assign default values to keyboard shortcuts, with the exception of cross-language keyboard shortcuts that don't utilize letter keys (ctrl+shift+home, or cmd+option+arrow left, and etc). But, that shifts the responsibility to set shortcuts to the user, which probably means most users won't have shortcuts as they won't bother or won't know how to set the keyboard shortcuts

Going to do a bit of reverse-engineering of Gmail's and Asana's source code to see how they handled these things. Will also look at what Google Sheets and Google Docs are doing since there they have a lot of text entry happening, thus complicating single-letter keyboard shortcuts

For now, I am thinking that:

• We should definitely have keyboard shortcuts for going to first, previous, next, and last record and have these key shortcuts be the same across record sets, attachment viewers, workbench and as many more places as we can manage.
• We can have default single-letter no-modifier keyboard shortcuts like D or Q. For example M in the workbench to open the data mapper and etc. Only activate these if not actively typing in text.
• All keyboard shortcuts that we have will be disable-able and customizable by the user. This is a WCAG a11y requirement
  • Just like browsers allow both F5 and Ctrl+R for page refresh, we could allow multiple keyboard shortcuts for an action as that does not complicate the implementation much.
• Any keyboard shortcut set by the user (or by us by default) for one platform (i.e mac) will automatically apply itself on Windows and Linux too (with ctrl swapped for cmd and wise versa). BUT, as soon as the user in any way modifies that key on the other platform (i.e windows), then any further changes to the key shortcut on windows do not affect mac and wise versa. In code this is quite simple - read shortcut for current system, if not present, check if shortcut is present for other system and read it but translate ctrl->cmd; when setting shortcut, set for current system only.
• If a shortcut is set for i.e opening the workbench mapper, then the button for the workbench mapper will include the shortcut inside of its tooltip to remind people. This won't require code changes in every place as the tooltip manager itself can check if any shortcut is active for the URL a link is pointing to, and if so, add the tooltip
• There will be a way for user to set a shortcut for any URL. This lets them set a shortcut to a form for creating new Collection Object, or printing labels from a commonly used label definition. The fact that we have a code structure with all front-end routes makes this simpler.

[maxpatiiuk]

Observations:

• Asana:
  • uses Tab + letter key for many keyboard shortcuts (alongside single-letter shortcuts and Cmd+letter). I am afraid of using that Tab key as it's essential for a11y, and so any code we write would have to be tested in many scenarios and systems - something Asana can do, but we don't have the resources to do
  • shortcuts work even if I change keyboard layout. looking at the code, they are listening for key codes being pressed, not letters
  • Most keyboard shortcuts use letters or numbers only, without modifier keys
• Google Calendar
  • This one is surprisingly bad!
  • Keyboard shortcuts don't work at all in non-English layouts
  • No way to change keyboard shortcuts
  • They use Alt in the UI even on mac (though they do correctly use Cmd)
• Google Docs
  • since you are constantly in an editor, single-letter shortcuts are not an option for them
  • most shortcuts are 3 or even 4 key long
  • some shortcuts overwrite browser defaults
  • shortcuts work even when in different language
  • they have a language switcher in the menu, but I'm not sure what it's for - it doesn't change the UI language, not typing language, nor keyboard shortcut language, nor help docs language
• Google Sheets
  • similar to Google Docs, except they also let enable Excel shortcuts (without mentioning Excel 😊, they call it "enable compatible keyboard shortcuts you may have used")
• Gmail
  • In all of the above websites, Cmd+/ opens the keyboard shortcuts list. But in Gmail, it is ? instead
  • They have all styles of keyboard shortcuts - letter only, 1 modifier, 2 modifiers,...

[maxpatiiuk]

Started work on this on a branch: https://github.com/specify/specify7/pull/5097

Not completed yet, but if someone is interested, it's good enough now to preview the keyboard setting UI and keyboard shortcuts in action

For now, I only set the shortcuts for going between recordset items and adding a new item - will add several dozen more

My favorite part: the UI displays a hint in the tooltip if a keyboard shortcut is defined for a given action:

[lexiclevenger]

@maxpatiiuk, Corinna P has provided us with feedback on existing keyboard shortcuts and a list of tasks that users at CSIRO would like to see keyboard shortcuts for:

Our Herbarium users are doing large amounts of front-end data entry and have provided us with a bit of feedback regarding the current shortcuts that are available to them, which we wanted to pass on for possible integration into the above GH ticket.

For reference, we have been referring them to the section on shortcuts on this page: https://discourse.specifysoftware.org/t/using-forms-in-specify-7/959  

• Closing a window should be enabled by using the Esc button. E.g., when you open a sub-form in a new window there should be an option to quickly close it when no editing is required. Currently, you have to tab through all fields to get to the Close button at the bottom of the form.
• Edit mode shortcut 'toggle'. Users have requested a quick way to turn on/off Edit mode. If you want to go from the CO form to the locality form you currently have to click the Edit button three times. A shortcut would minimise the amount of mouse-work required.
• Save is inconsistent. The provided shortcut is Ctrl+Enter; this only works in Firefox. We found through trial and error that Shift+Enter works in Chrome and Edge, however, this only works if you are in a non-expandable field. In a note field, for example, it just creates a new line. Noting that in the old herbarium system a save was achieved via F10.
• Jump between sub-sections in a form. Users would like the ability to jump by section/sub-form. Currently they have to tab through every field to get further get to subsections further down in the form.

(Asana)

[maxpatiiuk]

Closing a window should be enabled by using the Esc button. E.g., when you open a sub-form in a new window there should be an option to quickly close it when no editing is required. Currently, you have to tab through all fields to get to the Close button at the bottom of the form.

I suppose by window this means a dialog? Esc key works to close modal dialogs (those that darken the screen behind them). It's disabled for non-modal dialogs. I believe it's disabled so as to prevent accidental loss of data if you have begun doing some edits in that dialog. Having Esc key work until you made any change in that dialog would be a nice improvement!

---

Edit mode shortcut 'toggle'. Users have requested a quick way to turn on/off Edit mode. If you want to go from the CO form to the locality form you currently have to click the Edit button three times. A shortcut would minimise the amount of mouse-work required.

Hmm, a bit of clarification on this one would be nice.

to turn on/off Edit mode

A shortcut for toggling the app-wide toggle readonly mode?

If you want to go from the CO form to the locality form you currently have to click the Edit button three times

Or do you mean the small edit button in the query combo box? We could have a shortcut that would "click" on the edit button in the query combo box, but that shortcut would only work if the query combo box is focused - otherwise there could be several query combo boxes on the page, so it wouldn't be clear to specify which one the user means to open.

Or did you mean quickly switching between creating a new Collection Object and creating a new Location? The v1 implementation of keyboard shortcuts will include ability to bind a custom keyboard shortcut for any specify URL, letting you bind a keyboard shortcut for opening the form for creating a new "Locality" for example. Does that work for you, or did I misunderstand the request?

Save is inconsistent. The provided shortcut is Ctrl+Enter; this only works in Firefox. We found through trial and error that Shift+Enter works in Chrome and Edge, however, this only works if you are in a non-expandable field. In a note field, for example, it just creates a new line. Noting that in the old herbarium system a save was achieved via F10.

This is controlled by the browser. The specify form is rendered as a native HTML form and the save button is the submit button - thus whatever is the keyboard shortcut in that browser for submitting the form, that is the behavior Specify uses. We could definitely though let people bind a custom shortcut for saving the form so as to circumvent the differences between browsers.

Jump between sub-sections in a form. Users would like the ability to jump by section/sub-form. Currently they have to tab through every field to get further get to subsections further down in the form

Ah, that's a great idea. What I have already implemented on a branch is a keyboard shortcut for going to first/previous/next/last record. Having a shortcut for moving focus one form section up/down would be a nice feature to have!

[CorinnaPaeper]

Hi @maxpatiiuk . Trying to add some clarifications for you 😊

Windows – I assume window and dialog box are referring to the same thing. What I was referring to was the new window/dialog box that pops up when I open a subform via a button or QCBX. For example, all our collections have shared CEs so we are using the QCBX. When I open the event it shows up as a new window. This can’t be closed other than with the ‘Close’ button at the end of the form.

Edit mode toggle – yes, this is in reference to the app-wide edit mode. We have turned RO-mode by default on for most of our instances now. It would be useful to have a short-cut that lets users toggle quickly between the RO/Edit mode rather than needing to click on the ‘Edit’ button repeatedly. The example provided was just highlighting how much clicking is involved. If you start in the CO, you need to click ‘Edit’ to be able to edit the record. From there, you open the CE, which is in RO-mode when it opens, so need to click ‘Edit’ again. Then you go to Locality, which again opens in RO-mode, so again need to click on ‘Edit’ to be able to modify the record.

Does this help?