DEV Community: Gary Großgarten

Create Keyboard Shortcuts with RxJS

Gary Großgarten — Mon, 08 Jun 2020 19:41:53 +0000

I recently tried to add some keyboard shortcuts to my Angular app. 🤯 But don't worry , the solution is quite simple. At least Brent Rambo approves.

In this Quick Tip, I'll show you what I came up with, using RxJS.This demonstration is done in an Angular Workspace scaffolded with the Angular CLI.

Implementation

The shortcut function below can be used to effortlessly create Observables for any keyboard shortcut. A keyboard shortcut is an array of keycodes (event.code), each representing a key of your keyboard. Grab the KeyCode Enum here.

See the comments in the code for explanation:

export const shortcut = (shortcut: KeyCode[]): Observable<KeyboardEvent[]> => {
  // Observables for all keydown and keyup events
  const keyDown$ = fromEvent<KeyboardEvent>(document, 'keydown');
  const keyUp$ = fromEvent<KeyboardEvent>(document, 'keyup');

  // All KeyboardEvents - emitted only when KeyboardEvent changes (key or type)
  const keyEvents$ = merge(keyDown$, keyUp$).pipe(
    distinctUntilChanged((a, b) => a.code === b.code && a.type === b.type),
    share()
  );

  // Create KeyboardEvent Observable for specified KeyCode
  const createKeyPressStream = (charCode: KeyCode) =>
    keyEvents$.pipe(filter((event) => event.code === charCode.valueOf()));

  // Create Event Stream for every KeyCode in shortcut
  const keyCodeEvents$ = shortcut.map((s) => createKeyPressStream(s));

  // Emit when specified keys are pressed (keydown).
  // Emit only when all specified keys are pressed at the same time.
  // More on combineLatest below
  return combineLatest(keyCodeEvents$).pipe(
    filter<KeyboardEvent[]>((arr) => arr.every((a) => a.type === 'keydown'))
  );
};

combineLatest: Whenever any input Observable emits, combineLatest will compute and emit all the latest values of all inputs. However, combineLatest will wait for all input Observables to emit at least once, before it starts emitting results.

Usage

Usage is simple. Just call the shortcut function with your desired KeyCode combination. Then subscribe to the result and handle the keyboard shortcut. More examples can be found in the repo.

const commaDot$ = shortcut([KeyCode.Comma, KeyCode.Period]);

const ctrlO$ = merge(
  shortcut([KeyCode.ControlLeft, KeyCode.KeyO]),
  shortcut([KeyCode.ControlRight, KeyCode.KeyO])
);

commaDot$.pipe(tap(() => doSomething())).subscribe();

Bonus

The shortcut function emits whenever the specified keys are pressed simultaneously, no matter in which order they were pressed. If the sequence of the key presses is also important to you, you can use the pipeable operator below.

export function sequence() {
  return (source: Observable<KeyboardEvent[]>) => {
    return source.pipe(
      filter((arr) => {
        const sorted = [...arr]
          .sort((a, b) => (a.timeStamp < b.timeStamp ? -1 : 1))
          .map((a) => a.code)
          .join();
        const seq = arr.map((a) => a.code).join();
        return sorted === seq;
      })
    );
  };
}

Then use it like this

const abc$ = shortcut([KeyCode.KeyA, KeyCode.KeyB, KeyCode.KeyC]).pipe(
  sequence()
);

Now the abc$ Observable will only emit when the keys are pressed sequentially (a->b->c).

Limitations

Beware that keyboard shortcuts could collide with global shortcuts specified by your OS or Browser (e.g. Spotlight on Mac for Cmd+Space). Also there are cases where keyup events will be skipped when certain keys are pressed down. This is particularly the case with the cmd key (KeyCode.MetaRight and KeyCode.MetaLeft) on mac.

If you have further questions on the article or just want to say hi, feel free to slide into my twitter dms.🐦

Angular Elements: Create a Component Library for Angular and the Web

Gary Großgarten — Wed, 25 Mar 2020 15:41:02 +0000

Reuse your Angular components almost everywhere - with Angular Elements.

In this guide you'll learn how to

Scaffold a reusable component library.
Export the library for Angular and as Web Components.
Publish everything to npm.

Let's get started. ⬇

Create the project

This guide uses the Angular CLI 9.0.7 to scaffold most of the project structure and configuration for your reusable UI Library.

First, initialize a new Angular application with ng new APP_NAME. Feel free to use routing and your favorite stylesheet format when prompted.

Open the newly created project in your favorite IDE.

Next, run:

ng g library components

This step will generate a new library under ./projects/components and add an example component. The library is ready to be shared and used in all of your Angular applications without further configuration. 💆

Perform an initial build of the component library by running:

ng build components

Currently, Angular Elements only supports projects of type application to create Custom Elements. This means you need to generate an additional application. The sole purpose of the application is to import your angular components and output them as Custom Elements.

To generate the elements application run:

ng g application elements

Additionally, run the @angular/elements schematic:

ng add @angular/elements --project elements

This will create a new app in the subfolder ./projects/elements and install all the necessary dependencies and polyfills needed to set up Angular Elements.

If you want to publish your components as Custom Elements cd into ./projects/elements and create a package.json using

npm init

Then, add the following to the newly created package.json :

{
  ...
  "files": ["elements.js", "styles.css"],
  ...
}

Your project should now look something like this:

Configure Angular Elements

In the elements application delete all files in ./projects/elements/src/app except app.module.ts.

You need to define your own bootstrapping method for the elements application.Do some changes to your elements app.module.ts:

Remove the bootstrap array from NgModule declaration.
Import ComponentsModule and ComponentsComponent from the components library.
Add ngDoBootstrap hook.
For every component create an element using the createCustomElement function from @angular/elements. Then define the element using web's native customElemments.define function, specifying a selector.

import { BrowserModule } from '@angular/platform-browser';
import { NgModule, Injector } from '@angular/core';
import { createCustomElement } from '@angular/elements';
import { ComponentsModule, ComponentsComponent } from 'components';

@NgModule({
  imports: [
    BrowserModule,
    ComponentsModule
  ],
  providers: []
})
export class AppModule {

  constructor(private injector: Injector){}

  ngDoBootstrap(){
    const element = createCustomElement(ComponentsComponent, { injector: this.injector })
    customElements.define("lib-components", element);
  }

 }

Remove zone.js (optional):

Removing zone.js is probably a good idea. Read more about it in this great article. Just keep in mind that you need to handle change detection yourself.

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic()
  .bootstrapModule(AppModule, { ngZone: 'noop' })
  .catch(err => console.error(err));

Time to build ⚙

In your root package.json add the following scripts:

{
  "scripts": {
    ...
    "build:elements": "ng build --prod --project elements --output-hashing none && npm run pack:elements && cp projects/elements/package.json dist/elements",
    "pack:elements": "cat ./dist/elements/{runtime,polyfills,main}-es5.js > dist/elements/elements.js && ls -lah dist/elements/elements.js",
    "build:components": "ng build --prod --project components",
    ...
  },
  ...

}

To build the elements application run:

npm run build:elements

The script exports your Angular components as Custom Elements during the build process. Also it will run the pack:elements script and copy the previously created package.json to ./dist/elements.

The pack:elements script is optional yet very useful because it will bundle the js build outputs into a single elements.js file. This makes it easier to include your library in other applications.

Try it out

Use your Angular components by including them in the root Angular application:

In app.module.ts:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';
import { ComponentsModule } from 'components';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    ComponentsModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

In app.component.html:

<h1>angular component</h1>
<lib-components></lib-components>

Run the root application with ng s.

Using your Custom Elements is simple. Create an index.html in the root of your project and add following code snippet:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Document</title>
    <link rel="stylesheet" href="dist/elements/styles.css">
    <script src="dist/elements/elements.js"></script>
</head>
<body>

    <h1>Web Component (Costum Elements)</h1>
    <lib-components></lib-components>
</body>
</html>

To test, serve it on a http server and open the index.html. I'm using serve.

serve .

Publish to npm

The only thing left to do is to publish your components and Custom Elements to npm.This is fairly easy. Either run npm publish dist/components or npm publish dist/elements.

Reminder: Before releasing, you probably want to update ./projects/components/package.json and ./projects/elements/package.json to include your libraries' name and version. A way to name your libraries could be ngx-<NAME> for angular and wc-<NAME> for the Custom Elements.

✨ Congratulations! You successfully created and published a custom Angular component library that can be used almost everywhere!

If you have further questions on the topic, feedback on the article or just want to say hi you can hit me up on twitter

Build and publish your first GitHub Action

Gary Großgarten — Wed, 18 Mar 2020 21:07:41 +0000

If you are using GitHub you most likely already heard about GitHub Actions. With GitHub Actions you can fulfill all of your CI/CD dreams right where your code lives. You do this by defining jobs that run a series of Actions - The building blocks of your repository workflows. This enables you to stay productive even when managing multiple projects at once. 👨‍💻

In this short guide you will learn how to create your first GitHub Action and publish it on the GitHub Marketplace! 💙

Quickstart

To get started quickly, you can initialize your own Action repository by generating it from GitHub Action Template. For the sake of simplicity this repository is a minimized version of the official typescript action template. You are free to choose which starter you want to use. The steps to build and release your Action will essentially remain the same.

Visit GitHub Action Template and click on Use this template.

Fill out the form and click on Create repository from template.

Next clone your newly created repository and open it with your favorite IDE.

git clone git@github.com:<USERNAME/ORG>/<REPOSITORY>.git

Install all dependencies by running npm i.

Great! Everything is set up! 🚀 In the next section of this guide you'll get an overview of the most important files.

Template Overview

First, inspect index.ts:

The template Action is a simple script that receives an input string and outputs a hello world like greeting. (E.g. input World ➡ output Hello World). See how the actions/core api is being used to receive the value of the my_input input and to set the resulting string as an output. Also, setFailed can be called to set the running workflow as failed and stop the execution. API Documentation

Most toolkit and CI/CD operations involve async operations so your run function will most likely be async.

import * as core from '@actions/core';

async function run() {
  try {
    await asyncFunction();
  } catch (err) {
    core.setFailed(err.message);
  }
}

run();

Second, see action.yml in the root of your project.

name: 'GitHub Action Template'
description: 'simple typescript template for building GitHub Actions'
author: 'notiz.dev'
inputs:
  my_input:
    description: 'input description here'
    default: 'World'
runs:
  using: 'node12'
  main: 'dist/index.js'
branding:
  color: 'yellow'
  icon: 'bell'

The action.yml file defines some metadata that is mandatory to run and publish your Action on GitHub. Besides general information like name, description and author, you'll want to define all the necessary inputs for your Action. The entrypoint of the Action is set to run dist/index.js using version 12 of node. This file will be created once you build and pack the project.

To publish the Action, you additionally need to define a branding for how your Action appears on the GitHub Marketplace. For more information on the configuration of your Action see Metadata syntax for GitHub Actions.

Lastly, you'll find a workflow file under .github/workflows/test.yml.

name: 'test'
on: # rebuild any PRs and main branch changes
  pull_request:
  push:
    branches:
      - master
      - 'releases/*'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v1
    - name: run action
      id: run_action
      uses: ./
      with: 
        my_input: 'World'

    - name: log action output
      run: echo ${{steps.run_action.outputs.my_output}}

Essentially, this will start a workflow testing your Action on every push to master/release or on PRs. The test job will checkout and run your Action, defining World as the input value for my_input.

Finally, the log action output step of your job will echo the output set by your GitHub Action. Note the id that is defined in the run action step and later used to retrieve the output value.

By creating your repository from the template earlier, the workflow already got invoked once:

As you can see in the image above, the log action output step successfully echoed Hello World to the console.

Implement the Action

Next, the fun part! 🙋

Implement your own Typescript code in src/index.ts. Just remember to update the action.yml and the test workflow .github/workflows/test.yml before pushing your changes. You can obviously do everything you want here. Feel free to install other libraries via npm.

To build changes to your Typescript code run:

npm run build

This will compile your Typescript to a lib folder.

Next, run:

npm run pack

This script will bundle your lib together with the required production node_modules. The bundled package can now be found in the dist folder containing the index.js that's been declared as the entrypoint in your action.yml.

See JSON Property GitHub Action for another example.

Publish to GitHub Marketplace

After you built and packed the Action you are ready to commit and push your changes to the GitHub Repository. You should definitely add a README with instructions on how to use your Action.

Check if your test workflow is working as expected. If you are happy with the results, you are ready to finally publish your Action to the Marketplace.

Hit the release tab of your repository to create a new version of your Action.

Click on Create a new release and select Publish this Action to the GitHub Marketplace.

Check if all requirements are checked and proceed to file the release.

Enter a tag and release title. Optionally specify a release description before clicking Publish release.

To make it easy for users to always use the latest release of your Action you can tag the newly created version with a release tag. Next time you release a version you can move the release tag from the previous to the latest version.

Using your Action

By now you should have a published version of your Action on the GitHub Marketplace.

You should see the Marketplace banner on your repository page:

Inspect the Action entry in GitHub Marketplace:

Use your Action by creating a workflow file in a repository of your choice. In case you tagged the version with the release tag, include your Action as follows:

...

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - name: run action
      id: run_action
      uses: <USERNAME/ORG>/<REPOSITORY>@release
      with: 
        my_input: 'World'

    - name: log action output
      run: echo ${{steps.run_action.outputs.my_output}} 

...

Please replace <USERNAME/ORG> and <REPOSITORY> with your repository details.

Conclusion

Awesome, you made it to the end of this guide. 🎉

As you could see, building and publishing your first GitHub Action is fairly straightforward. To not double the efforts of building certain Actions you should check the Marketplace and this awesome list.

If you have further questions on the topic, feedback on the article or just want to say hi you can hit me up on twitter.