techtonica / keyboard-shortcuts-practice

Keyboard Shortcuts Practice App

Try it out here: https://techtonica.github.io/keyboard-shortcuts-practice/

Overview

Techtonica is a nonprofit that provides free tech training with stipends and job placement to women and non-binary adults with low incomes.

We discovered that our participants need an app similar to typing practice websites out there, but for Mac OS X keyboard shortcuts.

This project should train and test users to use the quicker keyboard shortcuts instead of a mouse and the GUI. The app gets more challenging as you progress through the commands.

Our goal for the backend project is to create a persistent app where users can sign in, practice with the app, and save their progress. That way, the next time they sign in, they can pick up where they left off rather than starting at the beginning.

Setting up Auth0 and creating an account

1. Create a free personal Auth0 account
2. Create a Regular Web Application
3. Run cp .env.example .env to create a .env file
4. From the settings page of your Auth0 web application fill in the environment variables, ensuring that the AUTH0_ISSUER_BASE_URL is the Domain URL starting with https://
5. The Allowed Callback URLs for local development should be http://localhost:3000/callback

Running the project

1. Run npm install to install all the packages.
2. Run npm start to start the server.
3. Navigate to http://localhost:3000 in your browser. Your project should be running at this point.

Contributing / Volunteering

Go to CONTRIBUTING.md.

Creative Commons Open-Source License

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

keyboard-shortcuts-practice's Issues

Spike: plan what kind of authentication makes sense

Spike: plan what kind of authentication makes sense

Make a plan regarding which type of Auth0 authentication to use:

• Password authentication
• Passwordless (via email link)
• Google sign-in

Detail your decision in the project ReadMe.md.

Force quit hotkeys don't not affect app

Force quit hotkeys don't not affect app, you just get the forcequit dialog.

Create an env file and share securely.

Create an env file and share securely.

1. Request Techtonica's login elephantsql.com database URL from Alina. She will email it to you.

2. Create a .env file with URL=<DB url/username/password> you received in the last step.

3. Create a .env.example file with the key and false value. Make a PR to the backend branch.

4. Send new .env to Alina.

5. Send a message to all Techtonica project teammates that you or Alina can email them the real values on request.

caps-lock toggles only every other time you press it, losing sync with actual lock

At least for me, pressing caps-lock for the first time changed the keyboard view to reflect it being enabled, but then pressing it again didn't show it as disabled... pressing a third time did. And now it seems to take every other press.

Add other Mac keyboard rows.

Display questions.

Display a prompt for an action, such as, "How do you copy something you've selected?" and go to the next prompt when the correct keys (Command + C for the example) are pressed. Cycle through all prompts this way.

Create an expert view that does not show blue hints until requested

Currently the blue hint keys are always shown. We'd like a toggle so you can hide the hints so users can test their expertise.

Design a toggle UI and implement it to allow the user to show or hide hints.

command hotkeys should be escaped instead of executed

cmd+t
cmd+n
cmd+shift+esc
cmd+space
cmd+tab
cmd+shift+~
cmd+shift+3

hotkeys should be escaped. Right now they are executed and interfere with the program.

potential solutions have been discussed in issue #32

Update: This was partially addressed in #118 , with these exceptions:

"Fixed for some key combinations; could not overwrite in Safari for command + n, command + m, command + t, command + w. I also tested in Chrome and at least command + n was still not working. Seems like it might be a browser issue with not allowing me to catch those events and override them. In my research I came across this library which may be able to help: https://craig.is/killing/mice."

Use a keycode JS library to handle keypress-related details

To be able to focus on the app's features, it makes sense to use a library like Keypress (https://dmauro.github.io/Keypress/) or Keymaster (https://github.com/madrobby/keymaster) that can run callback functions when key events happen.

Fix keyboard zoom bug

Zoom at 110%, 90%, 80% in chrome. Did not find the bug in Firefox.

To get started, follow the instructions in https://github.com/Techtonica/keyboard-shortcuts-practice/blob/backend/CONTRIBUTING.md

Originally reported by @IngridGdesigns

Spike: plan how to record user's progress

Note: make pull requests to techtonica/keyboard-shortcuts-practice's 'backend' branch.

Find out the best way to record a user savepoint in Techtonica/keyboard-shortcuts-practice.

Document your new dev plan + user journey for how to access the data for a savepoint at the bottom of the project's ReadMe.md.

People who pick this up are going to have to research how the practice app progresses through its stages of difficulty so that they know which data to save once we have a user database.

Detect pressing of fn and command.

Come up with list of commands for program to test.

Firefox not compatible with `command` shortcuts

My version of Firefox, 62.0.3, isn't working with command shortcuts. I think Chrome and Firefox use different keyCode.

Make input field turn red when the wrong keys are pressed.

GHC'19: add persistence layer so users can log in and save progress

Use our dedicated trello board for related issues: https://trello.com/invite/b/n0K4702v/bea90647f14eae2be2a1ac54e124d566/techtonica-keyboard-app-persistance-layer

Add UserAnswers model and DB schema to orm.js

A a new model in orm.js based on this definition

user_answers table / UserAnswers model

All of these columns are NOT NULL unless otherwise specified.

• id: primary key / integer sequence
• user_id: string (foreign key to users.id)
• question_number: integer
• is_correct: boolean
• elapsed_time_ms: integer
• created_at : timestamp (we don't need updated_at since this is immutable. this name can be configured in the sequelize model as we don't want the default camel case name)

Please use the sequelize docs

Move CSS and JavaScript into their own files and link to them in keyboard.html.

Add other technologies' shortcuts like GitHub and VS Code some day?

https://help.github.com/articles/using-keyboard-shortcuts/

Blue hint keys are difficult to read

Use different color style with more contrast

Create fake login/logout for local development

Auth0 is being integrated as part of #73 but we don't want to force all contributors to configure Auth0 just to work on the app so we'll have a simple auth setup for local development.

Feel free to suggest a better way to do this. This just one possible way among many.

• This should be the default way the app works unless Auth0 is setup - which will be done in #73
• Add the cookie-session package or your preferred cookie library
  • If you haven't worked directly with cookies before, read this background doc
• Implement a GET /login endpoint
  • It should set a cookie, userId which will just be the environment variable USER (your OS username) which has a lifetime of 1 hour
  • If no user record exists with that id, create it. Sequelize has a findOrCreate helper that makes this easy
  • The response to this endpoint should be a redirect to /
• Implement a GET /logout endpoint
  • It should unsets the cookie value
  • Response should be a redirect to /
• Update the /user/progress endpoint added in #66 so that the userId will be the logged-in user id if the cookie has the value set

If you have any question about cookies, Express, ping Bill D in Slack.

Create screen capture gifs that show the result of each command, as a hint

Create actions gifs based on wireframes at https://github.com/Techtonica/keyboard-shortcuts-practice/wiki

Disambiguate between mac keyboard shortcuts and shell shortcuts

I'd love to see some indication that the keyboard shortcut I'm on is for the mac operating system vs the shell.

Suggestion: add navigation between different sets of shortcuts, perhaps after we get shortcuts for more programs, #22

Add support for shortcuts with the Fn key

This ticket is to allow shortcuts to be specified that require the fn key on Mac.

For example, F2 in VSCode renames a symbol, which is a useful tool. Add this shortcut to the shortcuts.json and test to see if it will work.

Ideally, we would like to highlight the actual fn key on the displayed keyboard but that may or may not be possible. Please look into the link below and do your own search to see if that is possible.

To get started, follow the instructions in https://github.com/Techtonica/keyboard-shortcuts-practice/blob/backend/CONTRIBUTING.md

Note: Originally forked from #13 and #14. Command support was already implemented.

Highlight/accept the Command, Option, and Shift buttons on the right if the supporting keys are typed with the right hand.

For example, the Command button on the right should be used for copying, cutting, and pasting because C, X, and V are on the left of the keyboard and pressed with the left hand.

Certain questions cannot be answered because the cmd key is not override

When users answer the "hide the window" question with Cmd-H, it will actually close user's own window, thus the practice would not precede to the next question. The Cmd-h needs to be override somehow.

First DELETE request

First DELETE request

1. Create a working basic DELETE request for user: { username, id } based on the project's existing DB and ORM.

2. Add your endpoint and example request and response in the ReadMe.

Request the project .env from teammates.

Add fun success event when the user has finished all the questions

Currently when the user reaches the last question it just cycles back to the first one.

Let's help the user celebrate their accomplishment by showing a fun success message.

Also please add a button that will start the quiz over again if they want.

Try out the Keyboard Shortcut App: https://techtonica.github.io/keyboard-shortcuts-practice/

Save answer POST request

This depends on #72 so work on that first if you're interested and it isn't already assigned.

Add a new POST endpoint for the route: /user/answers/question/{questionNumber}

In the body of the request, include the necessary attributes (see #72) to save.

(Until auth is implemented, you can use guest as the user_id. Just make sure the record exists so the foreign key constraint isn't violated.)

In the main.js browser JavaScript, please submit an AJAX request (using fetch) to the above endpoint for any correct answer from the user. We can ignore incorrect answers for now.

This data will be retrieved in #96 if you're interested in working on that part.

Integrate Auth0 middleware into the server

You'll need to register your own free account with Auth0 to work on this issue.

• Create a new application in your Auth0 account
  • The type is Regular Web Application
• Follow the Auth0 tutorial for NodeJS / Express to integrate it into the app
  • Using the Auth0-endorsed express middleware, express-openid-connect
• Auth0 will provide a test to tell if the auth is working correctly
• To help others set it up in their environment, add environment variable names to the .env.example file. Do not put any of your own account/app's values here.
• Only configure the middleware if the Auth0 environment variable names you chose are present. If not, assume the app is running in local dev mode and will not need Auth0 integration. Local auth will be implemented in #74
• Please document in the README how someone can set up their own Auth0 (use links to official docs), such as copying the .env.example file

If you need help with Express or Auth0, ping Bill in Slack.

Add speed tracking

Come up with a way to give feedback to the user by measuring how fast they are getting correct answers. This way they can compare themselves to their previous score/rating.

Add a pause button

Add a pause button before a new prompt is shown (in place of the Next button).

Pause should keep the user on the same question. Once Paused, Pause button should change to Resume button. Once Resumed, display the next question.

If not Paused, then the next question is displayed automatically after 2-3 seconds.

update keyboard-shortcuts-practice README.md volunteer directions to more closely match the curriculum repo readme rules.

update keyboard-shortcuts-practice README.md volunteer directions to more closely match the curriculum repo readme rules.

there have been a few updates this year that need to be transferred. Use your judgement about which ones apply to this project.

Prevent default fn and command commands.

Maybe using this? https://www.w3schools.com/jsref/event_preventdefault.asp

Build JSON file with all keyboard shortcuts in the proper "schema"

This issue is a WIP (work in progress)

In order to have a in memory "database" to read keyboard shortcuts from, there will need to be a data source to pull in seed data (in this case, the keyboard shortcuts). For simplicity, it can be stored in a JSON file that can be read from the JS app and loaded into whatever in-memory data store is used.

Additionally, each keyboard shortcut object found in the JSON must conform to a standardized schema.

For now, that would mean each object must look like this:

{
  "title": "paste",
 "description": "This is how you paste text that is in your clipboard",
 "interactions": ["key-cmd", "key-v"],  //each element is the string-based id of a key (or click) definition,
 "importance": 100 // importance of knowing shortcut in a scale of 0-100 where 100 is as important as can be. multiple shortcuts can share the same values
}

Additionally, keys and/or clicks (or other interactions) should be defined in an "interactions" collection with each element having a type key of "key" or "mouse-action". that collection should look like:

{
  "interactions": {
    "key-cmd": {
       "type": "key",
      "value": "cmd"
    }
  }
}

Add Login/Logout button to the UI

Note: make pull requests to techtonica/keyboard-shortcuts-practice's 'backend' branch.

Design and implement a Login and Logout button. They should take the user to /login and /logout, respectively but those pages don't currently exist yet and will just show a 404.

Please design with either a navbar or just a button on the top of the page. It's up to you. There is currently no toolbar or header to the UI.

[meta] list of similar apps/tools to augment this one

After 5 minutes of googlin'....

• keycastr - mac program that doesn't teach directly but Bill used to use this pairing to rapidly learn my partner's key shortcuts without having to ask "Whoa how'd you do that?" every 2 seconds in an IDE
• EVE - mac-specific trainer that reminds you of shortcuts that exist whenever you do it the "slow" way. won't help with tech-only ones but could be a nice boost when starting out
• Shortcutfoo - seems similar to this in that it's a game-ified learning web app but there don't even seem to be free ones to try. maybe they will donate some licenses??

Finish ORM setup

Note: These steps may be partially done.

1. Connect the ORM in JS/orm.js to be used in keyboard-shortcuts-practice's main server file.

2. Create a basic model for a user: username and id. Export the user model.

3. Create a router file and import 'user' from your model file.

First GET request: /user/progress

Add new GET endpoint for the path /user/progress

This endpoint should return the following hardcoded response (since we don't yet know who the user is or their saved progress).

{ 
  "userId": null,
  "currentQuestionNumber": 1
}

Once the main.js loads, add an AJAX call (using fetch, not jQuery) to the above endpoint and set the current question to the returned currentQuestionNumber

First PUT request

First PUT request

For this task, you will be adding a column/field to the user: savepoint.

1. Create a working basic PUT request for user: { username, id, savepoint } based on the project's existing DB and ORM.
2. Add your endpoint and example request and response in the readme.

Dependencies:

• Savepoint strategy must be documented.
• Ask Techtonica teammates for the project .env .

Not required:
Actual saving functionality will be addressed in a future issue. The current issue only focuses on the functioning PUT request and the savepoint type.

[QA] Run through entire set of questions and create issues for any bugs seen

Run through the tests on the latest Mac versions of:

• Chrome
• Firefox

Use Sally's wireframes for layout and user flow.

Shortcuts Wireframes.pdf

Write user's progress PUT request

User story:
As a user, I want to have my savepoint automatically recorded as I progress. No "save" button should be required.

• The plan for creating a savepoint should be in the readme.

• Add your endpoint and example request and response in the readme, or update if it overrides an existing endpoint.

Dependencies:
P1(blue) & P2(green) Issues

Klicking the next button too fast will display all questions rotated through

If you klick the next button too fast (before the typewriter animation is finished), the script will just continue writing all the previous questions until it reaches the current question.

For example:
If I start at questionNo 1 and click really fast until questionNo 9 I'll get this in the text div:

e the contents of the clipboard into the current document or app?How do you undo the previous command?How do you redo to reverse the undo command?How do you select all items?How do you find items in a document or open a Find window?How do you find the next occurrence of the item previously found?How do you hide the windows of the front (active) app?

Fix the position of arrow keys in the keyboard.

Cosmetic issue

Visual Designs

Change designs like color etc to match wireframes and designer suggestions.

[Epic] Standardize app code and architecture including using React

This is more of an epic (and placeholder) but presumably we want the codebase to be easy for others to contribute to and be an educational environment for volunteers and students. Currently, this codebase wouldn't represent best practices for students to reference in interviews etc.

Here are some possible ideas in that vein:

• Switch the view to render via React components
  • All client state should move inside a root component or something like Redux
• Move active development back to master vs gh-pages using main for trunk dev
• Improve contributor readme docs
  • Slack or github contact info for who to talk to
  • How to build & test locally
  • Include suggestions for commit messages
  • Any desired coding style guide should be referenced and enforced via hooks Captured as #89
• ✅ Consume dependencies in a standard way using yarn or npm

Add link to list of commands.

For the MVP, we don't need a hint to show up when the wrong keys are pressed. Let's just have the input field turn red and supply a constant link to a list of commands people can refer to.

Keys "stick" on when switching tabs

If you use Cmd+Alt+Left/Right to change browser tabs, the Cmd key gets stuck orange on even when it's not pressed. Ideally we should reset keys when returning.

Alternatively we may not need to do this is we do #29 but that might not be a great UX.

To get started, follow the instructions in https://github.com/Techtonica/keyboard-shortcuts-practice/blob/backend/CONTRIBUTING.md

Put this repo onto GitHub pages.