DEV Community: Cory Rylan

Resilient CSS APIs and Design Systems

Cory Rylan — Wed, 11 Nov 2020 19:24:57 +0000

Design Systems and UI libraries help companies and product teams align visual design consistency and speed up UI development. As much as we hope to make our UIs pixel perfect, many aspects of the Web actively work against pixel perfection. Not only do we have to deal with browser inconsistencies but also other code running in the application unintentionally breaking or changing our expected visual output.

Many Design Systems and UI libraries use global CSS to apply the website’s desired look and feel. Global CSS can be good and bad in different use cases. Global styles can help easily make things consistent but also cause conflicts. Let’s walk through a seemingly simple scenario.

Our Design System needs consistent styles for our h1 headings. We define something like this in our code:

h1 {
  color: #2d2d2d;
  font-size: 24px;
}

Great, now every h1 heading will look the same. Quickly we run into issues at scale. What if we want to use an h1 style but can’t due to an h1 existing already on the page? Duplicate headings are bad for SEO and accessibility. Well, we could make an h1 class.

h1, .h1 {
  color: #2d2d2d;
  font-size: 24px;
}

This additional selector is a step in the right direction. We can now use any semantically correct element to style it like our system’s h1 style. But this is still at risk of other issues. First, if we are building a Design System to support multiple apps or teams, they may be already using another library to style their app. By applying styles to native element selectors, we have a high risk of causing style collisions.

.h1 {
  color: #2d2d2d;
  font-size: 24px;
}

So if we remove the native element selector, now we eliminate the risk of the Design System colliding with other styles. This now leaves the question of why call it an h1? Why not name it to something semantic that makes it easy to understand its purpose?

.heading {
  color: #2d2d2d;
  font-size: 24px;
}

That’s better, but the class name is a bit generic and still could be more specific. We can prefix with some standard name for our system.

.ds-heading {
  color: #2d2d2d;
  font-size: 24px;
}

The prefix could be a shorthand name for the product or company. Here I have ds for Design System. So now, we have a scoped isolated and consistent way to style headings in our design system. Something as simple as a class name can be more complicated than it seems. Thoughtful API design can save teams significant amounts of time when trying to adopt, use, or upgrade to your Design System/UI Library.

Often I think CSS selector types are often not used to their potential. While CSS class names are the most common style hook, we can use HTML attributes to provide a more expressive CSS API.

[ds-text*='heading'] {
  ...
}

[ds-text*='subheading'] {
  ...
}

[ds-text*='body'] {
  ...
}


<h2 ds-text="heading">A cool heading</h2>

<h2 ds-text="subheading">A cool subheading</h2>

<p ds-text="body">A cool paragraph</p>

By leveraging attribute selectors, we can may our CSS much more expressive. Not only is the style selector specific and scoped but also easily conveys its intent in the HTML.

CSS libraries and Design Systems can leverage more expressive selectors and Shadow DOM to create resilient CSS that works in more predictable and reliable ways. Check out the Clarity Design System Typography utilities, as well as blueprintcss.dev which both leverage similar attribute-based APIs.

Wrapping DOM Text Nodes with JavaScript

Cory Rylan — Wed, 30 Sep 2020 06:00:00 +0000

Sometimes when using CSS, we need certain DOM elements to exist to apply styles properly. An example is the use of text nodes and spacing. If we want to put space between text blocks, they must be wrapped in a span to apply margins properly.

In some cases where the content is out of your control, such as a CMS system, you may need to find and wrap these text nodes to style them properly. Let’s take a look at an example.

<section>
  <h1>A heading</h1>

  <p>a paragraph</p>

  some text

  <hr>

  some text
</section>

Our HTML here has two unwrapped text nodes, some text. A next node contains all text characters between two HTML elements, including whitespace. If my system needed to add margins between these elements, it would unfortunately not work.

To solve this, we need to query the child elements, find all text nodes with characters, and then wrap them with span elements. Our ideal output would be like the following:

<section>
  <h1>A heading</h1>

  <p>a paragraph</p>

  <span>some text</span>

  <hr>

  <span>some text</span>
</section>

To find and wrap all our text nodes, we must be careful to preserve the text node references. Instead of making a span and copying the text, we must move the text node into a newly created span. This is important as the text could be a text node that is being used somewhere else. Let’s look at this example:

<section>
  <h1>A heading</h1>

  <p>a paragraph</p>


  <hr>


</section>

Here we have a template using some framework template binding. This binding may update the text value over time. If we copy the text into a new span deleting the old text, we will break the text binding from being updated in the future.

To safely move our text node into a span element, we need to find all the text nodes we care about. This can vary slightly, but we want any text node with characters and no empty nodes in our use case.

const textNodes = getAllTextNodes(document.querySelector('section'));

function getAllTextNodes(element) {
  return Array.from(element.childNodes)
    .filter(node => node.nodeType === 3 && node.textContent.trim().length > 1);
}

With this function, given an HTML element, we can find all child nodes, which are nodeType value of 3 (text) and have at least one character in the node.

Now that we can get a list of text nodes, we can start moving them into new span elements.

textNodes.forEach(node => {
  const span = document.createElement('span');
  node.after(span);
  span.appendChild(node);
});

We iterate through each text node and create a span element appending it after the next node. Once the span is added, we use the existing text node and append it as a child of the span element. This allows us to preserve the text node without breaking any references. To test this, we can use a setInterval to change the text node value ever second.

const textNodes = Array.from(document.querySelector('section').childNodes)
  .filter(node => node.nodeType === 3 && node.textContent.trim().length > 1)

textNodes.forEach(node => {
  const span = document.createElement('span');
  node.after(span);
  span.appendChild(node);
});

setInterval(() =>
  textNodes.forEach(node => node.textContent = Math.random())
, 1000);

We can see how we can continue to refer to the text nodes even after moving them into our span wrappers. An alternative technique, if you want to add only space, is to use the CSS Flex Gap and Grid Gap properties, which will add space between elements, including text nodes.

Check out the full working demo below with the wrapper logic and CSS Gap alternative!

Understanding Slot Updates with Web Components

Cory Rylan — Mon, 31 Aug 2020 05:00:00 +0000

Web Components provide a component model to the Web. Web Components, instead of being a single spec, is a collection of several stand-alone Web technologies. Often Web Components will leverage the Shadow DOM feature. Shadow DOM is commonly used for CSS encapsulation. However, Shadow DOM has another useful feature called Slots.

The Slots API is a content projection API that allows HTML content from the host application to be rendered into your component template. Common examples of this are things like cards and modals.

Here is a minimal example of a Custom Element using the Slot API.



const template = document.createElement('template');
template.innerHTML = `
<div class="inner-template">
  <slot></slot>
</div>`;

class XComponent extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
  }
}

customElements.define('x-component', XComponent);


<x-component>
  <p>Some Content</p>
</x-component>

The tags content can be rendered into our template we defined and marked with the <slot> element. If we look at what the browser renders, we will see something like this:

The content is projected and rendered within the template of our component. Often there are use cases, whereas the component author we would like to know about any updates to the content provided by the slot element. We can achieve this by adding an event listener in our component for the slotchange event.



class XComponent extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));

    // get updates when content is updated in the slot
    this.shadowRoot.addEventListener('slotchange', event => console.log(event));
  }
}

This event will fire whenever any content has changed within the slot. To test this, we can use our component and dynamically update the content to see the event update.



<x-component></x-component>

<script>
setInterval(() => {
  // update text content
  document.querySelector('x-component').textContent = `${Math.random()}`;

  // change the DOM structure
  document.querySelector('x-component').innerHTML = `<span>${Math.random()}</span>`;
}, 1000);
</script>

In this example, every one second, we can set the textContent or the innerHTML of the component and see the slotchange event fire within the x-component.

We can easily render content into our component templates and list for content updates. But there is one interesting exception to this rule. While the event will happen whenever textContent or innerHTML is set, the event will not occur if a textNode reference is updated dynamically. Let’s take a look at an example.



<x-component></x-component>

<script>
const text = document.createTextNode(`${Math.random()}`);
document.querySelector('x-component').appendChild(text);
</script>

Instead of directly setting the textContent or innerHTML of our element we create a text node. While not an HTML element, the text node allows us to hold a reference in memory we can update at a later point. So if we go back to our interval, we will see the text change, but the event is no longer triggered.



<x-component></x-component>

<script>
const text = document.createTextNode(`${Math.random()}`);
document.querySelector('x-component').appendChild(text);

setInterval(() => {
  // update text node (no slotchange update)
  text.data = `${Math.random()}`;

  // update text content (triggers slotchange update)
  // document.querySelector('x-component').textContent = `${Math.random()}`;

  // change the DOM structure (triggers slotchange update)
  // document.querySelector('x-component').innerHTML = `<span>${Math.random()}</span>`;
}, 1000);
</script>

This behavior can be a bit unexpected at first. Many JavaScript frameworks will leverage text nodes to optimize for performance. The short rule to remember is slotchange only fires when the HTML DOM has changed either by a DOM/Text Node from being added or removed. Check out the full working example below!

https://stackblitz.com/edit/lit-element-example-wgxxgx

Don't Override CSS Outline Focus Styles

Cory Rylan — Mon, 20 Jul 2020 05:00:00 +0000

It’s common to see websites remove the focus outline of focusable items. Removing outline styles, however, causes problems for many users. To keep your websites and web apps accessible focusable items must have a focus outline. Users with mobility disabilities may only be able to use a keyboard or non-mouse interaction with your web app. By removing the outline, your web app can quickly become unusable.

button {
  outline: 0; /* don't do this! */
}

Many developers and designers do not like the default system focus most browsers provide and often override it with a custom outline style.

button:focus {
  outline: 4px solid blue;
}

Custom outlines can introduce a new set of usability problems that we will cover in this post. First, let’s look at a set of blue buttons for our demo.

These are native HTML buttons with some minor style changes for the background color. These buttons can have some issues when focused. The focus outline can blend into the button, making it difficult to see.

Chrome Focus Styles

This screenshot is an example running in Chrome. Each button is focused in the screenshot, and each looks slightly different. The first button is the default focus style in Chrome. We can see it blends in with the button. The second button shows a custom style that makes the outline larger but still blends in. We could change the color but will have to maintain multiple colors for each button color we may provide.

The last two buttons have native focus styles with some offset adjustments. As of Chrome 83 (announcement here), the focus styles have changed as well as the latest Edge. The new native focus style has two borders a light and dark that can be seen and altered by the browser-based on the background color. This feature is great to help ensure the focus is visible regardless of the surrounding colors.

But there is still a slight problem with this approach. The outline is directly next to our first button, making it difficult to see if the colors are similar. Some browsers mitigate this. For example, Safari adds an offset space between the button and the outline automatically.

Safari Focus Styles

As you can see, the offset Safari provides makes the focus much more visible. Unfortunately, Safari is currently the only browser that provides this default offset spacing. As we can see in Edge and Firefox, the first two buttons in each have no default offset.

Edge Focus Styles

Firefox Focus Styles

Even though only Safari provides an offset, we can still adjust the CSS outline offset ourselves.

button {
  outline-offset: 2px;
}

The outline-offset CSS property will add space between the element and the focus outline, making a visual distinction. But again, we run into some browser compatibility problems.

Offset Outline with Native Defaults

In Chrome and Edge, the outline-offset property does not work on the default outline style. The outline-offset will work only on custom outline styles. We don’t want to override the default outline since Chrome and Edge provide the helpful multi background outline support for accessibility.

So what can we do to improve this? We don’t want to override the native behavior as it provides the best accessibility support, but we cant apply the outline-offset needed. We can use a trick to create a pseudo-element around our focusable item that is slightly larger to create an offset space.

button {
  /* for browsers that support native offset without custom outline */
  outline-offset: 2px;
}

button:focus {
  position: relative;
}

button:focus::after {
  content: '';
  position: absolute;
  top: -2px;
  left: -2px;
  right: -2px;
  bottom: -2px;
  outline: 5px auto -webkit-focus-ring-color;
}

When the button is focused, we can create a pseudo-element and position it slightly larger, about two pixels, and around the focused button. To apply the native focus style to the pseudo-element, we use this CSS property:

outline: 5px auto -webkit-focus-ring-color;

This CSS line is the CSS that triggers the internal native outline style in Chrome and Edge, which will preserve the multi background color support. Looking back at our examples, the last two buttons have the space between the button and the outline. Since we did not override the native outline style, the outline is automatically visible on light and dark backgrounds.

Chrome Focus Styles

Accessibility can be tricky to get right across several browsers. Often browsers built-in defaults provide a solid foundation and are always improving. When adding custom overrides, we remove the browser’s chance to provide better defaults in the future. As Web Developers, we must find that balance between customization and using what is built-in. Check out the full demo code!

Using Web Components in AngularJS

Cory Rylan — Mon, 13 Jul 2020 05:00:00 +0000

AngularJS has been around for quite some time on the Web. Many legacy AngularJS apps need to be migrated or upgraded to the latest Angular or other UI frameworks like Vue or React. There are many challenges when upgrading or migrating an AngularJS application, as well as many different approaches. In this post, we will see how Web Components allow us to create a compatibility bridge between different Web technologies.

Web Components (Custom Elements) are a Web standard for defining custom HTML tags. Web Components work similarly to other component models allowing data to be passed in via Properties/Attributes and notify of changes to the host application through Custom Events.

We won’t dig deep into how to build Web Components but instead focus on integrating them into AngularJS. To get an introduction to Web Components, check out this post.

Setting Up

When using Web Components in AngularJS, your application must be on version 1.7.3 or higher. To start, we will set up a basic AngularJS app.

<!doctype html>
<html>
<head></head>

<body>
  <app-root></app-root>
</body>
<script src="./index.js"></script>
</html>

import angular from 'angular';

angular.module('app', []);
angular.element(document).ready(() => angular.bootstrap(document, ['app']));

angular.module('app').component('appRoot', {
  template: `
    hello world
  `,
  controller: function () { }
});

In our basic AngularJS app, we create a root app module as well as a single Angular component called appRoot. In this example, we will use a third party Web Component to demonstrate how Web Components integrate with AngularJS. Our Web Component for this example will come from the Clarity Design System, which provides an extensive UI Web Components suite. Web Components can be installed like any other NPM package.

npm install --save @clr/core

Once the package is installed, we can start importing the components we would like to use. The import path or registration step may vary between libraries, so be sure to check the latest documentation.

import angular from 'angular';
import '@clr/core/button/register';

angular.module('app', []);
angular.element(document).ready(() => angular.bootstrap(document, ['app']));

angular.module('app').component('appRoot', {
  template: `
    <cds-button>hello there</cds-button>
  `,
  controller: function () { }
});

Here we added a simple button Web Component from the Clarity Design System. If we look at our running app, we will see the following:

Properties and Attributes

Web Components can accept data in a few different ways. Web Components can receive projected content between its element tags and values passed via attributes and properties.

When passing data to a Web Component, its important to understand the differences between attributes and properties. Attributes can be set via HTML and are always string values.

<cds-alert-group status="danger"></cds-alert-group>

However, if we wanted to pass an Object or Array to the component, it would not work as attributes are always strings in HTML. To set complex values, we have to set the property.

const component = document.querySelector('my-custom-element');
component.someProperty = { greeting: 'hello there' };

For Angular, however, we don’t need to use document.querySelector. Instead, we can use the ng-prop directive. This directive allows us to set the JavaScript property on an element instead of using attributes. Let’s add an alert component to display a message and update its status via our Controller properties.

import angular from 'angular';
import '@clr/core/alert/register';
import '@clr/core/button/register';

angular.module('app', []);
angular.element(document).ready(() => angular.bootstrap(document, ['app']));

angular.module('app').component('appRoot', {
  template: `
    <cds-button status="primary">hello there</cds-button>

    <cds-alert-group ng-prop-status="$ctrl.status">
      <cds-alert>
        General Kenobi. You are a bold one.
      </cds-alert>
    </cds-alert-group>
  `,
  controller: function () {
    this.status = 'danger';
  }
});

In the example above, we can see we use the status attribute to set the button’s status but use ng-prop to bind the JavaScript property of our controller to the corresponding JavaScript status property on the alert component. Both are valid, but ng-prop will work with all value types.

Custom Events

Web Components can be used like any other component and have event listeners. Let’s add a click event and show the alert message when the button is clicked.

import angular from 'angular';
import '@clr/core/alert/register';
import '@clr/core/button/register';
import './style.css';

angular.module('app', []);
angular.element(document).ready(() => angular.bootstrap(document, ['app']));

angular.module('app').component('appRoot', {
  template: `
    <cds-button ng-click="$ctrl.showAlert = true">hello there</cds-button>

    <cds-alert-group ng-if="$ctrl.showAlert" ng-prop-status="$ctrl.status">
      <cds-alert>
        General Kenobi. You are a bold one.
      </cds-alert>
    </cds-alert-group>
  `,
  controller: function () {
    this.status = 'danger';
    this.showAlert = false;
  }
});

On our Angular controller, we use a boolean to show the alert when the button is clicked.

The Alert Web Component has a closable feature and can emit an event when the user has clicked the close button. We can use the Custom Event to hide the alert in our Angular template. To listen to Custom Events, we use the ng-on directive.

import angular from 'angular';
import '@clr/core/alert/register';
import '@clr/core/button/register';
import './style.css';

angular.module('app', []);
angular.element(document).ready(() => angular.bootstrap(document, ['app']));

angular.module('app').component('appRoot', {
  template: `
    <cds-button ng-click="$ctrl.showAlert = true">hello there</cds-button>

    <cds-alert-group ng-if="$ctrl.showAlert" ng-prop-status="$ctrl.status">
      <cds-alert ng-on-close_change="$ctrl.showAlert = false" closable>
        General Kenobi. You are a bold one.
      </cds-alert>
    </cds-alert-group>
  `,
  controller: function () {
    this.status = 'danger';
    this.showAlert = false;
  }
});

With the ng-on directive, we add the event’s name to the end of the directive and an Angular expression on the right-hand assignment. Note since our template is HTML, we lose case-sensitivity; however, Custom Events are case sensitive. Because of this, upper case letters need to have a _ prefix.

The alert component emits a closeChange custom event so our template would be ng-on-close_change="". Now we can listen for the close event on our alert.

With Web Components, we can pass data, listen for events, and share logic between different UI setups. Web Components are a great way to encapsulate UI into a standard component model. To learn more about Web Components, check out a few of these tutorials. The working demo can be found below!

Measuring Angular Performance with Source Map Explorer

Cory Rylan — Tue, 30 Jun 2020 05:00:00 +0000

Web Performance is becoming more and more demanding as Web applicationscontinue to grow in size and complexity. One of the biggest culprits of Web Performance issues is JavaScript. JavaScript can be slow to download but also slow to execute depending on the network and device capabilities.

To keep Angular performance fast we can use lazy loading and dynamic imports to load code as needed on demand. This can greatly reduce the amount of JavaScript required to load and run on the client. However, even when following best practices, sometimes a single third party dependency can break all performance progress.

In this post, we will see how we can better understand what JavaScript we are sending down to the client within our Angular applications.

Angular CLI

To understand our Angular application’s performance characteristics, we will need to build our app with the production flag to ensure we are testing with what our prod environment will be using.

In the root of the Angular CLI project, we can execute the following:

ng build --prod --source-map

This command will build our Angular application with all the optimization the Angular CLI uses and produce source map files of the output code. The source maps allow the compiled final output to be mapped to its original code before compilation.

With the source maps, we can use a tool like source-map-explorer to inspect and show precisely what code is being sent to the client. To use Source Map Explorer, you will need to install via NPM.

npm install source-map-explorer

Once installed, we can add it as an NPM stript to the package.json in our Angular application.

{
  "bundle:report": "source-map-explorer dist/demo-app/**/*.js"
}

When we run our script npm run bundle:report, we will get the output in the browser.

Here we can see the output of the ng-pokedex project. We can see all the JavaScript and dependencies within each JavaScript bundle. This visualization makes it easy to identify what code is being loaded.

While the Angular CLI uses Webpack for some of its bundling, it also makes additional optimizations on top of Webpack. Because of these optimizations, it’s important to use the source-map-explorer to test the final output and not the webpack-bundle-analyzer that is commonly used with Webpack based applications.

You can find the demo application on Github!

Using Event Decorators with lit-element and Web Components

Cory Rylan — Mon, 22 Jun 2020 05:00:00 +0000

When Web Components need to communicate state changes to the application, it uses Custom Events, just like native events built into the browser. Let’s take a look at a simple example of a component emitting a custom event.

const template = document.createElement('template');
template.innerHTML = `<button>Emit Event!</button>`;

export class Widget extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
    this.shadowRoot.appendChild(template.content.cloneNode(true));

    this.shadowRoot.querySelector('button').addEventListener('click', () => {
      this.dispatchEvent(new CustomEvent('myCustomEvent', { detail: 'hello there' }));
    });
  }
}

customElements.define('my-widget', Widget);

Our widget is a basic custom element containing a single button. With our widget, we can listen to the click event from the component template to trigger a custom event.

this.dispatchEvent(new CustomEvent('myCustomEvent', { detail: 'hello there' }));

With custom events, we pass an event name and a configuration object. This configuration object allows us to pass a value using the detail property. Once we have the event setup, we can listen to our new custom event.

<my-widget></my-widget>

import './widget';

const widget = document.querySelector('my-widget');

widget.addEventListener('myCustomEvent', (event) => {
  alert(`myCustomEvent:, ${event.detail}`);
});

Just like any other DOM event, we can create an event listener to get notified when our event is triggered. We can improve the reliability of our custom events by using TypeScript decorators to create a custom @event decorator.

Example Alert Web Component

For our example, we will be making a simple alert component to show messages to the user. This component will have a single property to determine if the alert can be dismissed and a single event to notify the application when the user has clicked the dismiss button.

Our Web Component is using lit-element. Lit Element is a lightweight library for making it easy to build Web Components. Lit Element and its templating library lit-html provide an easy way to bind data and render HTML within our components. Here is our example component:

import { LitElement, html, css, property } from 'lit-element';
import { event, EventEmitter } from './event';

class Alert extends LitElement {
  @property() dismiss = true;

  render() {
    return html`
      <slot></slot>
      ${this.dismissible
        ? html`<button aria-label="dismiss" @click=${() => this.dismissAlert()}>&times;</button>`
        : ''}
    `;
  }

  dismissAlert() {
    this.dispatchEvent(new CustomEvent('dismissChange', { detail: 'are you sure?' }));
  }
}

customElements.define('app-alert', Alert);

Our alert component can show or hide a dismiss button. When a user clicks the dismiss button, we emit a custom event dismissChange.

this.dispatchEvent(new CustomEvent('dismissChange', { detail: 'are you sure?' }));

By using TypeScript, we can improve handling our custom events. Custom events are dynamic, so it’s possible to make a mistake emitting different types on the same event.

this.dispatchEvent(new CustomEvent('dismissChange', { detail: 'are you sure?' }));

this.dispatchEvent(new CustomEvent('dismissChange', { detail: 100 }));

I can emit a string or any other value and make the event type value inconsistent. This will make it hard to use the component in our application. By creating a custom decorator, we can catch some of these errors at build time.

TypeScript Decorator and Custom Events

Let’s take a look at what our custom decorator looks like in our alert Web Component.

import { LitElement, html, css, property } from 'lit-element';
import { event, EventEmitter } from './event';

class Alert extends LitElement {
  @property() dismiss = true;

  @event() dismissChange: EventEmitter<string>;

  render() {
    return html`
      <slot></slot>
      ${this.dismiss
        ? html`<button aria-label="dismiss" @click=${() => this.dismissAlert()}>&times;</button>`
        : ''}
    `;
  }

  dismissAlert() {
    this.dismissChange.emit('are you sure?');
  }
}

customElements.define('app-alert', Alert);

Using the TypeScript decorator syntax, we can create a property in our class, which will contain an event emitter to manage our components events. The @event decorator is a custom decorator that will allow us to emit events with type safety easily.

We leverage TypeScript Generic Types to describe what type we expect to emit. In this use case, we will be emitting string values.

@event() dismissChange: EventEmitter<string>;

...

dismissAlert() {
  this.dismissChange.emit('are you sure?');

  this.dismissChange.emit(100); // error: Argument of type '100' is not assignable to parameter of type 'string'
}

So let’s take a look at how we make a @event decorator. First, we are going to make a small EventEmitter class.

export class EventEmitter<T> {
  constructor(private target: HTMLElement, private eventName: string) {}

  emit(value: T, options?: EventOptions) {
    this.target.dispatchEvent(
      new CustomEvent<T>(this.eventName, { detail: value, ...options })
    );
  }
}

Our EventEmitter class defines a generic type <T> so we can ensure we always provide a consistent value type when emitting our event. Our decorator will create an instance of the EventEmitter and assign it to the decorated property. Because decorators are not yet standardized in JavaScript, we have to check if the decorator is being used by TypeScript or Babel. If you are not writing a library but an application, this check may not be necessary.

export function event() {
  return (protoOrDescriptor: any, name: string): any => {
    const descriptor = {
      get(this: HTMLElement) {
        return new EventEmitter(this, name !== undefined ? name : protoOrDescriptor.key);
      },
      enumerable: true,
      configurable: true,
    };

    if (name !== undefined) {
      // legacy TS decorator
      return Object.defineProperty(protoOrDescriptor, name, descriptor);
    } else {
      // TC39 Decorators proposal
      return {
        kind: 'method',
        placement: 'prototype',
        key: protoOrDescriptor.key,
        descriptor,
      };
    }
  };
}

Decorators are just JavaScript functions that can append behavior to and existing property or class. Here we create an instance of our EventEmitter service and can start using it in our alert.

import { LitElement, html, css, property } from 'lit-element';
import { event, EventEmitter } from './event';

class Alert extends LitElement {
  @property() dismiss = true;

  @event() dismissChange: EventEmitter<string>;

  render() {
    return html`
      <slot></slot>
      ${this.dismiss
        ? html`<button aria-label="dismiss" @click=${() => this.dismissAlert()}>&times;</button>`
        : ''}
    `;
  }

  dismissAlert() {
    // type safe event decorator, try adding a non string value to see the type check
    this.dismissChange.emit('are you sure?');
  }
}

customElements.define('app-alert', Alert);

If you want an in-depth tutorial about TypeScript property decorators, check out Introduction to TypeScript Property Decorators. The full working demo can be found here https://stackblitz.com/edit/typescript-xuydzd

Faster NPM installs with NPM CI

Cory Rylan — Sun, 31 May 2020 05:00:00 +0000

When developing NodeJS applications or using NodeJS for Web Development, we often have to install and reinstall dependencies via NPM. Depending on the number of dependencies, this can get slow and tedious to wait on. When we install a single dependency, we typically will run something like:

npm install some-package

When we run this command, NPM will add it to the package.json if not already there and install the package to the node_modules directory. When using NPM locally, we will also get a package.lock file that will track all dependencies and transitive dependencies used.

Typically it is best practice to not source control our node_modules but only the package.json and package-lock.json files. When another developer clones the repository, they will run npm install to install the same listed dependencies.

In theory, this workflow is ideal, but often this is not the case. Many times we need to delete and reinstall packages that may be corrupt or our of date. We often see a command like the following used:

rm -rf node_modules && npm install

This command works but is a bit of a brute force way to update and reinstall dependencies. Instead, we can use npm ci. When we have an existing project using NPM and Node. To install or reinstall dependencies, we can run the following:

npm ci

NPM CI is a command designed for installing dependencies in an automated CI environment. It will delete the node_modules directory automatically and reinstall all of our dependencies. NPM CI typically is faster than npm install. NPM CI requires an existing package-lock.json file. Instead of resolving the dependencies in the package.json it uses the lock file directly, which speeds up the install time. Here is an example of the install time differences:

// example repo: https://github.com/vmware/clarity/tree/master/packages/core

npm install - 42.116s

npm ci - 24.629s

If npm ci finds a difference between the listed dependencies between the package.json and the package-lock.json it will exit with an error. The standard npm install will however update the package-lock.json file if a difference is found. Using npm ci helps ensure that the packages installed are the same every time, providing consistency between installs and CI builds.

Using npm ci is useful if you need to simply install or reinstall your node_modules. If you need to add an individual dependency, you will still need to use npm install. For my day to day workflows, I have found that using npm ci works well for most of the time, I use NPM and Node.

Introduction to TypeScript Property Decorators

Cory Rylan — Mon, 18 May 2020 05:00:00 +0000

Decorators are a language construct that allows us to add additional behavior to a Class. Decorators are in many languages, and in this post, we will learn how to create and use a custom Class Property Decorators in TypeScript.

TypeScript supports various kinds of decorators, including Class, Method, and Property Decorators. Decorators are a language feature proposal for JavaScript, which you can find in the TC39 Documentation. Decorators use the @ character to signify a decorator call.

import { id } from './id.decorator';

export class Component {
  @id() instanceId: string;

  log() {
    console.log('id', this.instanceId);
  }
}

In this example, we have created a @id decorator that will create a simple random id that we can use in my components. Decorators are JavaScript functions that are executed once for the class definition and not per the instance.

First, for our @id decorator, we need to create a function to generate the ID values for us. To correctly make truly unique IDs, we would need to use a library or use the newer browser crypto APIs. For simplicity of the demo, we will generate using a function that will be unique enough for our client-side use cases.

// Read more about the UUID proposal here https://github.com/tc39/proposal-uuid
export function createId() {
  return Math.random().toString(36).substr(2, 9);
}

Decorators are JavaScript functions. Decorators can also have parameters by returning an inner function. When a Property Decorator is executed at runtime, the prototype is passed as a target reference. A second parameter is passed as the name of the property that the Decorator is placed on.

export function id() {
  return (target: {} | any, name?: PropertyKey): any => {
    const descriptor = {
      get(this: any) { },
      set(value: any) { },
      enumerable: true,
      configurable: true,
    };

    Object.defineProperty(target, name, descriptor);
  };
}

With the target, we can define a descriptor. The descriptor allows us to define a new getter and setter for the Decorator. With our custom getter and setter, we can apply our custom logic for our Decorator.

export function id() {
  return (target: {} | any, name: PropertyKey): any => {
    const descriptor = {
      get(this: any) {
        const propertyName = `__${String(name)}`;

        if (!this[propertyName]) {
          this[propertyName] = createId();
        }

        return this[propertyName];
      },
      enumerable: true,
      configurable: true,
    };

    Object.defineProperty(target, name, descriptor);
  };
}

When the getter is called, we receive a reference to the Class instance. With this reference, we can create a backing field to hold the unique ID for when the next time the getter is called. We prefix the backing field with a double underscore (dunder) so that we don’t cause a collision with any existing fields/properties.

Now with our Decorator we can create IDs for components.

export class Component {
  @id() instanceId: string;

  @id() secondaryId: string;

  log() {
    console.log(this.instanceId, this.secondaryId);
  }
}

const component = new Component();
const component2 = new Component();

// Each instance is unique and each property within the instance is also unique
component.log(); // _115fl2ygf _jwlv4b9dc
component2.log(); // _ql8hudynl _7eqg80p64

Decorators in Libraries

With Decorators still in the proposal stage, we have to add a bit more work if wewant to ship the decorators as part of a library. If a consumer of our Decorator were to use Babel or eventually the native implementation, we will need to make sure we follow the appropriate API.

When the Decorator is executed, we need to handle the different signatures.

export function id() {
  return (protoOrDescriptor: {} | any, name?: PropertyKey): any => {
    const descriptor = {
      get(this: any) {
        const propertyName = name !== undefined ? `__${String(name)}` : `__${protoOrDescriptor.key}`;

        if (!this[propertyName]) {
          this[propertyName] = createId();
        }

        return this[propertyName];
      },
      enumerable: true,
      configurable: true,
    };

    // if there is no name then this is a TypeScript runtime else its the current native TC39 proposal
    return name !== undefined
      ? legacyId(descriptor, protoOrDescriptor as {}, name)
      : standardId(descriptor, protoOrDescriptor as any);
  };
}

// Current TS API
const legacyId = (descriptor: PropertyDescriptor, proto: {}, name: PropertyKey) => {
  Object.defineProperty(proto, name, descriptor);
};

// TC39 Decorators proposal
const standardId = (descriptor: PropertyDescriptor, element: any) => ({
  kind: 'property',
  placement: 'prototype',
  key: element.key,
  descriptor,
});

Decorators in TypeScript have been around for a while, but if you are using plain JavaScript, be aware the Decorators proposal is still not 100% standardized, so it is subject to change or never be implemented. If you are developing an application, this may not be an issue using Decorators with TypeScript or Babel. However, if you are a library author, be cautious of shipping decorators as part of the public API.

Check out the full working demo!

Faster Web Pages with the Picture Element and WebP

Cory Rylan — Mon, 04 May 2020 05:00:00 +0000

Images can be a significant contributor to page slow down on the Web. Using just a couple of APIs, we can drastically improve the load and render time of a Web page. In this post, we will be using the HTML Picture Element and WebP image compression to better optimize image loading.

WebP Image Format

Images on the Web are typically loaded as png, svg, and jpeg formats. With the WebP image format, we can send high-quality images with significant data savings. On average lossless images are about 25% smaller and lossy images upwards of 34% smaller.

Browser support for WebP is relatively good. While Safari does not yet support WebP, we can still use WebP with the combination of the Picture Element we will cover in the next section.

Picture Element Support

The easiest way to get started with WebP is to use the cwebp encoder command-line tool. You can find the various installation options here WebP Installation (developers.google.com). Once you have cwebp installed, converting jpg and jpg images is straightforward.

We can pass in an argument of the image we want to convert and the out-file path. Optionally we can control the output quality with the -q flag. By lowering the quality, we compress the image even further.

cwebp -q 90 my-image.jpg -o my-image.webp

Picture Element

Now that we can convert our images to a better compression algorithm, how do we support browsers that don’t yet support WebP? Using the HTML picture element, we can use fallback image types as well as provide high-resolution images whilepreserving performance.

With the picture element, we provide an image tag with an image source that has the most substantial amount of browser support. In this case, it would be a jpg. With the picture tag, we can provide alternative source tags that tell the browser where it can download various formats of the same image. This feature allows the browser to choose what image is ideal base on its capabilities.

<picture>
  <source srcset="/my-image.webp" type="image/webp" />
  <img src="/my-image.jpg" alt="My Cool Image" loading="lazy" />
</picture>

With the picture element, we can also use the srcset attribute to define high-density images for both our default image and alternative image sources.

<picture>
  <source srcset="/my-image.webp" type="image/webp" />
  <source srcset="/my-image.webp 2x" type="image/webp" />
  <img src="/my-image.jpg" srcset="/my-image.jpg 2x" alt="My Cool Image" loading="lazy"/>
</picture>

In this example, we can give the browser the source of where to find a 2x resolution version of our image. This feature allows the browser to download whichever image is best for the user based on the device and network capabilities. For example, a high-end laptop on wifi can download the 2x image resources while a mobile device can download the standard resolution.

WebP Support

The browser support for picture is good and due to the syntax browsers that don’t support the picture tag ignore the unknown element and load the regular image jpg. Check out the demo!

CSS Gap Space with Flexbox

Cory Rylan — Sat, 25 Apr 2020 02:38:07 +0000

CSS Flexbox and CSS Grid are fantastic tools available for managing layout on the Web. Flexbox handles single-dimensional layouts very well while CSS Grid handles two-dimensional layouts with columns and rows. Often we want to add space between the items within our layout. This post will show how to do this using the CSS gap property in Flexbox and the necessary workarounds for reasonable browser support.

Inline Flex

To demonstrate CSS Gap, we will use Flexbox. CSS Gap works in CSS Grid, but there are many cases where we have inline lists that need space without a defined grid.



<div class="flex-gap">
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
  <div>6</div>
</div>



.flex-gap {
  display: inline-flex;
  flex-wrap: wrap;
}

We use inline-flex so we can have flex items but display our parent element as an inline element instead of a block element. The flex-wrap: wrap property will allow our items to wrap as the parent container shrinks or is constrained.

If we want to add space between each item, we could use margin on each item.



.flex-gap {
  display: inline-flex;
  flex-wrap: wrap;
}

.flex-gap > div {
  margin: 6px;
}

Margins works but is not the same behavior as CSS Gap space. Notice the extra space surrounding the boxes. With gap spacing, we only want space applied between the items. Using CSS Gap, we can achieve this.



.flex-gap {
  display: inline-flex;
  flex-wrap: wrap;
  gap: 12px;
}

CSS Gap is a feature of the CSS Grid spec and Flexbox; however, currently, only Firefox is the only major browser that supports gap on flex items.

Because of the lack of browser support, to achieve the same effect we will need to use some CSS hacks with margins.



<div class="emulated-flex-gap">
  <div>1</div>
  <div>2</div>
  <div>3</div>
  <div>4</div>
  <div>5</div>
  <div>6</div>
</div>



.emulated-flex-gap > * {
  margin: 12px 0 0 12px;
}

.emulated-flex-gap {
  display: inline-flex;
  flex-wrap: wrap;
  margin: -12px 0 0 -12px;
  width: calc(100% + 12px);
}

We can set margin space on the top and left of each item. On the flex parent element, we can use negative margins to counter the excess margin on the outer elements to get a similar effect to CSS gap space.

We can clean up the CSS a bit by using CSS Custom Properties so it is easierto change the margin spacing.



.emulated-flex-gap {
  --gap: 12px;
  display: inline-flex;
  flex-wrap: wrap;
  margin: calc(-1 * var(--gap)) 0 0 calc(-1 * var(--gap));
  width: calc(100% + var(--gap));
}

.emulated-flex-gap > * {
  margin: var(--gap) 0 0 var(--gap);
}

With this workaround, we can get something close to CSS Gap space in all browsers. I hope to soon see improved browser support for CSS gap as it enhances managing layouts with CSS. With CSS Gap spacing, we can remove a lot of white space complexities in CSS when using margins. Check out the full working demo!

CSS Custom Properties - Video Tutorial

Cory Rylan — Sun, 12 Apr 2020 05:07:44 +0000

This is a sample video from my Video Course Web Component Essentials.In this video you will learn the basics of how to use CSS Custom Properties.To get the written blog tutorial check out this post, “Build CSS Themes with CSS Custom Properties and Sass”

If what you watched was helpful checkout the full Video Course and EBook at webcomponent.dev!