Forem: Open Web Components

Some things to know about Lit

Westbrook Johnson — Mon, 04 Oct 2021 03:04:18 +0000

When reviewing software with which you have little experience, it's pretty common to attempt to compare it to software you have used before. That can help you get a handle on the general ergonomics and decisions behind the two pieces of software in question. However, one thing that this approach is not particularly good at is comparing the new software in situ. You may have spent a good amount of time investigating, researching, and getting comfortable with the software you're already using in the context of your particular use case, so much so, that it may even be the best solution available in that context. Comparing a new software in that context (unless it, too, is purpose-built for that context) can do a disservice to the software under test, as well as to your ability to fully understand the benefits of that software.

This is what I keep coming back to when people say things like "X isn't as good as Y" when "X" is a way to build web components (of which there are many) and "Y" is a JS framework. Even before you fill actual names into either side of the equation the differences in usage of what you fill those in with is important:

JS frameworks often want to own most or all of a page, whereas a web component is a single custom element on an potentially large and diverse DOM tree.
Functional JS frameworks often hide much of that ownership from view to both the benefit (less code) and expense (less flexibility) of developers leveraging them.
JS Frameworks tend to be an abstraction above the DOM and in this way, their "components" can exist as both literal (DOM/UI elements) and figurative (data connectivity/translations to non-web contexts).
Web components being a DOM element can interact with their position in the DOM in the ways you'd otherwise need to bend over backward to do in a framework.
JS frameworks often ship a lot of JS down the wire that may not be required by your application or component(s) whether or not the framework author gives you the ability to manage how much of that code makes it into your production build.
Web components are portable to just about any context in which you'd build web UI, while JS frameworks require your components to run in an app built with the same framework (unless or course, they allow you to export web components).
and, many, many more.

Some or all of these points could be seen as being for or against either side of the conversation. Many of these could switch from pro to con depending on the particular use case. Too often, reviews that fail to take that into account lead to half-baked, often hypercritical takes.

With that in mind, I want to go over some concepts that support healthier decision-making when teams evaluate LitElement for their projects. This isn't really a "how-to", though I've got some (slightly) dated version of that available in my "Not Another To-Do App" series. This is more of a "good to know" guide, as these concepts aren't all exact ports from JS framework contexts. I hope the ability to judge the differences from a place of knowledge proves useful to you.

Default Values

There are a number of ways to define default values for a property on a LitElement, While some do require management across the entire element class, we'll ignore those today as there are a number of options that do not require such work.

First off, LitElement's render() method of a LitElement is (from the user's perspective) an almost 1 to 1 conversion from the functional definitions found in other offerings. In this way, you could treat render() as the only entry into your properties and define fallbacks at the top of your render function's body like so:

render() {
  const closeDelay = this.closeDelay ?? 300;
  return html`<x-dialog delay=${closeDelay}>Thank you!</x-dialog>`;
}

From here, you could get very close to copy and paste the rest of a functional UI component into a LitElement for an early test of its capabilities. Leveraging scoped variables like this, rather than class properties, does leave you in much the same place that functional alternatives to UI development do; needing additional tools for memoization of that scope. As using LitElement means you're already in a class context, we can use the capabilities of a class directly rather than synthesizing them with memoization.

A simpler approach to merging the two concepts is to set that fallback into the class property itself. Above I showed doing this in the render() lifecycle method, however, I find it much nicer to only have the template surfaced therein. Leveraging one of the earlier lifecycle methods for managing defaults, validation, sanitation, transformation, or derivation help to maintain that structure. In this case, we'll use willUpdate() which doesn't require a super call or a returned value, but will always be visited during each render lifecycle:

willUpdate(changedProperties: PropertyValues<this>): void {
  this.closeDelay = this.closeDelay ?? 300;
}

With this approach, you can most closely facilitate the single line defaulting that can be present when relying on a function to define a component. This does mean the shouldRender() method - the first method called in the render lifecycle - will not have your default value, and if that's an issue for your style of element development, you might want to move this fallback work there, but it also means that due to the fact the LitElement renders asynchronously there's technically a possibility that your local methods could as well. Due to this fact, you may want to leverage a slightly more complete approach to a default.

Here we see the property getter fallback to the value:

get closeDelay(): number {
  return this._closeDelay || 300;
}
set closeDelay(value: number) {
  const closeDelay = value;
  if (closeDelay === this.closeDelay) return;
  this.requestUpdate('closeDelay', this.closeDelay);
  this._closeDelay = closeDelay;
}
_closeDelay = 300;

This does eclipse the simplicity of a functional solution as we are choosing to apply the default by writing our own getter/setter pair on the property. At the same time, however, we've fallen into a possible trap of the functional fallback approach (and as the willUpdate() approach above), we're allowing our entire render lifecycle to be triggered for what might not be an actual change to our component state. Were this.closeDelay to already equal 300 and the application to change it to undefined, all of these approaches we've looked at so far would cause whatever could occur in your render lifecycle to occur needlessly.

By falling back in the setter as opposed to the getter you can leverage the capabilities of a class component to prevent the render lifecycle to be started altogether. In the following code, no matter how the value of this.closeDelay gets to 300 the call to this.requestUpdate() is gated as long as the final value doesn't change.

class MyThing extends LitElement {
  @property({type: Number})
  get closeDelay(): number {
    return this._closeDelay;
  }
  set closeDelay(value: number) {
    const closeDelay = value ?? 300;
    if (closeDelay === this.closeDelay) return;
    this.requestUpdate('closeDelay', this.closeDelay);
    this._closeDelay = closeDelay;
  }
  _closeDelay = 300;
...

Here you may still ask, "but, why it is so much more code?" and, in our ecosystem of "less is more", both from a DX as well as a UX/performance standpoint, it's a great question. It's more code because it is also a different level/type of capability. Here we get a default to our property, clear gating on the render lifecycle, and on top of that, we get a value that is held state-fully within a class that defines a DOM element. This means that not only can it take part in the render pipeline of the element that owns it, but that it is available for other elements that share its DOM tree to query as a container for that state. Not every application is architected with a want or need for this capability. Not every component is going to be leveraged at the scale where the checking is needed to confirm that the render lifecycle has no side effects in a way that benefits extra prevention of the lifecycle altogether. However, when you do, you might take a look at LitElement as a path towards attaining these capabilities.

So you like Typescript?

Typescript loves a good "Property is not definitely assigned in the constructor" warning, and if you like Typescript enough to use it a lot, you'll likely run into it at some point. It's telling you this, because in contrast to what you've been told Typescript is NOT smarter than you and it can't tell if something should always be available, only if it might not be available. You can set an initial value to a property, and it'll never yell:

class MyThing extends LitElement {
  myProperty = 'string'; // always available, always a string
}

If you're looking for that to have to be initialized to use your element, so you KNOW it's going to always have a value, but you want the consumer to initialize it, then you can tell Typescript that by using the ! operator once and be done with it:

class MyThing extends LitElement {
  myProperty!: string; // no initial value, but a string is required from the consumer
}

If you still want to be defensive, you can add some helper code in your lifecycle to support a consumer leveraging your custom element correctly:

class MyThing extends LitElement {
  shouldUpdate(changedProperties: PropertyValues<this>): boolean {
    // great location to make sure it's NEVER undefined;
    const canUpdate = this.myProperty ?? false;
    if (!canUpdate) console.warn('`myProperty` is unset');
    return canUpdate && super.shouldUpdate(changedProperties);
  }
  firstUpdated(changedProperties: PropertyValues<this>): void {
    // for one time availability confirmation
    super.firstUpdated(changedProperties);
    if (!this.myProperty) console.warn('`myProperty` is unset');
  }
}

Required properties

In this way, you can also manage required properties/attributes. No, it doesn't fall within the available management of a tool-based contract with the consumers of your component, however, a tool-based contract is not strictly enforceable. You as a component author can tell Typescript or a linter to error on certain things, but your consumer can tell them not to just as easily. Deciding to only leverage tooling for this sort of capability might mean less work for you, but it doesn't guarantee better outcomes for your consumers. Any component author will need to decide the risks they are willing to foist onto their consumers when publishing a component, and this is yet another item to manage on that list.

Event management

Event listeners added directly on this in a custom element do not need to be cleaned up when disconnected from the document. Once all references to the element are released, the same garbage collection that cleans up the element itself will clean up the events bound to it. What's more, when calling addEventListener on this, the method's this reference automatically reverts to the instance. You don't need to bind the method, so you can call a class method directly without any .bind(this) or class field arrow-functions.

@customElement('menu-trigger')
export class MenuTrigger extends LitElement {
  @property({type: String})
  trigger?: string;

  public willUpdate(changedProperties: PropertyValues<this>): void {
    if (changedProperties.has('trigger') {
      this.removeEventListener(changedProperties.get('trigger'), this.eventHandler);
      this.addEventListener(this.trigger, this.eventHandler);
    }
  }

  private eventHandler(): void {
    // do stuff.
  }
}

Events are even easier if you know the name of the event you're wanting to listen for will be the same throughout the lifecycle of your application. With that knowledge you can listen just once without needing to add/remove the listener based on even name changes over time:

@customElement('menu-trigger')
export class MenuTrigger extends LitElement {
  public constructor() {
    super();
    this.addEventListener('known-event-name', this.eventHandler);
  }

  private eventHandler(): void {
    // do stuff.
  }
}

Done and done!

styleMap usage

Lit's styleMap() directive helps when setting the style attribute on HTML elements from JavaScript. It accepts an object with css-property keys and string, undefined, or null values. This means you can prevent a CSS property from being added to the element by passing null or undefined as the value, e.g.:

import {styleMap} from 'lit/directives/style-map.js';
// ...

  render() {
    return html`
      <p
        style=${styleMap({
          border: '1px solid',
          width: '200px',
          float: undefined, // I don't show a type mismatch
          margin: 10, // I do show a type mismatch
        })}
      >Hello, world!</p>`;
  }

Check it out here.

The current version of Lit's styleMap excludes numbers as values. You might expect Lit to automatically convert numbers to px values, but on second thought that isn't actually what you'd want. In CSS, where px is just one of many units that a numeric CSS property could accept (%, vh, vwmax, pt, em, rem, pt, pc, ad infinitum), there's no way for Lit to know or even assume what kind of number you're using. On top of that, you might want to apply unit-less numbers directly to your styles:

class XL extends LitElement {
  static styles = css`
    div {
      width: 10px;
      height: 10px;
      background-color: hsl(var(--hue, 0) 50 100);
    }
  `;
  @property({ type: Number }) hue = 0;
  render() {
    const divStyles = styleMap({
      '--hue': this.hue.toString(),
    });

    return html`<div style="${divStyles}"></div>`;
  }
}

Thanks @bennypowers for the code sample here.

Defaulting numbers to px would be a foot-gun. Instead, Lit encourages you to be explicit with your CSS code. Doing so not only helps your consumers, but your teammates and future self as well when it comes time to maintain the components that you create.

One of the best things about lit-html, the renderer underlying LitElement, is that, if you want to live on that wild side, you could create your own directive that applied number typed properties as px and leverage it in your own work. Here are the docs for doing just that! If you're still not convinced, check out some directives with which I've experimented.

NOTE: the above article, "Doing a FLIP with lit-html@2.0", was written against an RC of lit@2.0 and may not be 100% current. I'll be looking to update it here, soon.

Conclusion

When you're learning a new piece of software, by all means, start by comparing it to something that you know. It's like a cheat code to getting started down the path of learning something new. Once you've done that, don't stop there, get into a real use case with it and learn what sort of capabilities or techniques it unlocks or supports. Only then can you really get into the question of why it's doing so and whether in the context that it is intended to be used (or the context that you might use it) it's the sort of tool you want to leverage for the job.

If you do get to building something with LitElement, come share it here and let's chat about the whats and whys of what you've done/are trying to do. I look forward to seeing it here in the comments, or hit me up on the Lit & Friends Slack!

Let's Build a Colour Picker Web Component

Benny Powers 🇮🇱🇨🇦 — Fri, 25 Jun 2021 09:55:14 +0000

Let's build a colour picker web component using HTML, CSS, and a little bit of JavaScript. In the end, we'll have a custom element that:

Displays a colour spectrum using CSS Gradients
Tracks the mouse position using a Reactive Controller
Updates it's Shadow DOM via a small class mixin
Fires a Custom Event when the user clicks or drags

Prerequisites
Setting Up
Defining our Element
Styling our Element
- Shadow CSS Q-and-A
- Color Picker Styles
Tracking the Mouse with a Reactive Controller
- Reusable, Composable Controllers
- Adding Controller Support to our Element
- Hooking up the Cursor
Firing Events
Accessibility
Using our Colour Picker
Next Steps
Footnotes

Prerequisites

To get the most out of this article, you should have a comfortable understanding of HTML, CSS, and JavaScript; including:

How to load resources with <link>
Basic CSS syntax
How to use the DOM API to query for elements
Object-oriented programming for web developers and the JavaScript class keyword
What a JavaScript module is

You don't need to be an expert, but you should have the basics covered. You should also be familiar with the concept of component-based UI design and have an idea of what a web component is. If you've ever written a component with one of the popular JS frameworks, you're good to go. To catch up on what web components are, check out my blog series:

Lets Build Web Components! Part 1: The Standards

Benny Powers 🇮🇱🇨🇦 ・ Sep 18 '18

#webcomponents #customelements #javascript #html

Setting Up

Before we define our component, let's set up a project folder to work in and spin up a quick dev server to reload the page when we save a file. Paste the following script into a BASH terminal on a computer that has nodejs and npm installed:

mkdir ~/color-picker
cd ~/color-picker
touch index.html
touch style.css
touch mouse-controller.js
touch color-picker.js
touch color-picker.css
npx @web/dev-server --open --watch

These commands create a working directory in your HOME folder with some empty files, then start an auto-reloading development server.
Next, open the newly created folder in your text editor of choice and edit the index.html file, adding this snippet:

<!doctype html>
<head>
  <link rel="stylesheet" href="style.css"/>
  <script type="module" src="color-picker.js"></script>
</head>
<body>
  <color-picker></color-picker>
</body>

And let's put some initial styles in style.css

color-picker {
  width: 400px;
  height: 400px;
}

We don't see anything on screen yet, since we haven't defined the <color-picker> element. Let's do that now.

Defining our Element

Web components (or custom elements) are HTML elements that we the users define. Let's define the <color-picker> element by extending from the HTMLElement class. Open color-picker.js and add this code:

const template = document.createElement('template');
      template.innerHTML = `
        <link rel="stylesheet" href="color-picker.css">
        <div id="loupe"></div>
      `;

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

customElements.define('color-picker', ColorPicker);

Let's take that file block-by-block.

We start by declaring a <template> element to hold our element's HTML. We'll add a link to our component's private CSS and two nested <div> elements that we'll use later on to enhance our component. By using a <template>, we make sure the browser does the work of parsing our HTML only one time, when the page loads. From then on, we can create as many <color-picker> elements as we want, but each one will stamp a clone of the existing HTML, which is much faster than parsing it again.

Next we declare our custom element class. In the constructor, we attach a ShadowRoot to our element, then stamp the contents of the template we created into it.

Last, we call customElements.define(), which assigns the HTML tag name <color-picker> to custom element class, and instructs the browser to upgrade the <color-picker> elements already present in the document.

If you save the file, the dev server will reload the page, but we still won't see any changes because our element's content is invisible. Let's change that by applying some good-old CSS.

Styling our Element

Open up color-picker.css and paste in the following.

:host {
  display: block;
  min-height: 100px;
  min-width: 100px;
  cursor: crosshair;
  background:
    linear-gradient(to bottom, transparent, hsl(0 0% 50%)),
    linear-gradient(
      to right,
      hsl(0 100% 50%) 0%,
      hsl(0.2turn 100% 50%) 20%,
      hsl(0.3turn 100% 50%) 30%,
      hsl(0.4turn 100% 50%) 40%,
      hsl(0.5turn 100% 50%) 50%,
      hsl(0.6turn 100% 50%) 60%,
      hsl(0.7turn 100% 50%) 70%,
      hsl(0.8turn 100% 50%) 80%,
      hsl(0.9turn 100% 50%) 90%,
      hsl(1turn 100% 50%) 100%
    );
}

#loupe {
  display: block;
  height: 40px;
  width: 40px;
  border: 3px solid black;
  border-radius: 100%;
  background: hsl(var(--hue, 0) var(--saturation, 100%) 50%);
  transform: translate(var(--x, 0), var(--y, 0));
  will-change: background, transform;
}

We'll get into the details of our CSS rules shortly (skip ahead). For now, save the file to see our changes on the page. That's more like it. Now our element looks like a colour picker!

Shadow CSS Q-and-A

If you're unfamiliar with web components, you might be asking yourself some questions at this point:

`:host`

What the heck is :host

The :host CSS selector gets the element that hosts the root containing the stylesheet. If that doesn't make any sense to you, don't worry, we'll explain more shortly. For now, all you need to know is that in this context, :host is synonymous with the color-picker element itself.

ID Selectors (e.g. `#loupe`)

ID selectors!? Aren't they a huge CSS no-no?

In the cascade, ID selectors have an extremely high specificity, which means they'll override rules with a lower specificity like classes or element selectors. In traditional (global) CSS, this can very quickly lead to unintended consequences.

Nov 26 '11 Comments: 9 Answers: 3

I was shocked by this line "Don't use ID selectors in CSS". Is it true? I found many posts have written this.

I think we can use the ID for the selectors.

I still want to clear this up.

Open Full Question

Our stylesheet isn't global though, since we <link> to it from within a ShadowRoot instead of from the document, the styles are strongly scoped to that root. The browser itself enforces that scoping, not some JavaScript library. All that means the styles we define in color-picker.css can't 'leak out' and affect styles elsewhere on the page, so the selectors we use can be very simple. We could even replace that #loupe selector with a bare div selector and it would work just the same.

The shadow root encapsulation also means that the element IDs we're using in our template HTML are private. Go ahead and try this in the browser console:

document.getElementById('loupe');

Without shadow DOM, we should see our <div id="loupe"></div> element in the console, but we don't. Shadow DOM puts us in complete^* control of our component's HTML and CSS, letting us put whatever HTML and CSS we want inside it without worrying about how they affect the rest of the page.

CSS-in-JS, BEM, etc.

If this is supposed to be a reusable component, won't those styles and IDs affect the page? Shouldn't we use BEM, or add JavaScript or a command-line tool to transform those IDs into unique random class names?

Now that we've learned a little more about Shadow DOM works, we can answer that question for ourselves: The Shadow DOM (supported in all browsers) removes the need for complicated css-in-js tooling or class naming conventions like BEM. We can finally write simple, à la carte selectors in CSS, scoping our work to the task at hand.

Color Picker Styles

Equipped with our knowledge of the Shadow DOM, let's dive into our element's styles.

The business-end of our element's :host styles is a pair of linear-gradient() calls, one which fades from transparent to grey, the other which turns 360 degrees around the colour wheel in 10% increments as it moves from the far left of our element to the far right. We also threw in a cross-hair cursor and some default dimensions for good measure.

Our #loupe rule gives our colour-picking loupe a pleasing circular shape, but - crucially - defines its background-color and position in terms of CSS Custom Properties also called CSS Variables. This is going to come in handy in the next step when we use JavaScript to animate the loupe element. We also nod to the browser, letting it know that the background and transform properties are likely to change.

Tracking the Mouse with a Reactive Controller

Every component needs HTML, CSS, and JavaScript to handle properties, events, and reactivity. We covered HTML and CSS with <template>, ShadowRoot, and :host. Now let's move on to reactivity, meaning to update our element's state-of-affairs in reaction to some input like user actions or changing properties.

Reusable, Composable Controllers

Oftentimes when writing components, we come across a bit of logic or behaviour that repeats itself in multiple places. Things like handling user input, or asynchronously fetching data over the network can end up in most if not all of the components in a given project. Instead of copy-pasting snippets into our element definitions, there are better ways to share code across elements.

JavaScript class mixins are a time-tested way to share code between components. For example you might have a component which fetches a file based on it's src attribute. A FetchSrcMixin would let you write that code in one place, then reuse it anywhere.

class JSONFetcher extends FetchSrcMixin(HTMLElement) {/*...*/}
class TextFetcher extends FetchSrcMixins(HTMLElement) {/*...*/}

<json-fetcher src="lemurs.json"></json-fetcher>
<text-fetcher src="othello.txt"></text-fetcher>

But mixins have a limitation - they have an 'is-a-*' relationship to their element class. Adding a mixin to a class means that the result is the combination of the base class and the mixin class. Since mixins are functions, we can compose them with function composition, but if one of the composed mixins overrides a class member (e.g. field, method, accessor), there could be trouble.

To solve this problem, the Lit team recently released a new "composition primitive" called Reactive Controllers, which represent a 'has-a-*' relationship. A controller is a JavaScript class that contains a reference to the host element, which must implement a certain set of methods called the ReactiveControllerHost interface.

In plain terms, that means you can write a controller class and add it to any element class that meets certain criteria. A controller host can have multiple independent or interdependent controllers, a controller instance can have one host, controllers can independently reference shared state.

If you're familiar with React hooks, you might recognize the pattern that controllers fit. The downside to hooks though is that you can only use them with React.

Similarly, the downside to controllers vs mixins is that they require their host element class to fulfill certain criteria, namely: the class must implement the ReactiveControllerHost interface.

	Composable	Reusable	Stackable	Independent
Mixins	✅	⚠️	❌	✅
Controllers	✅	✅	✅	❌

Unlike React, though, controllers can be made to work with components from different frameworks or custom element classes other than LitElement. Controllers can work with React, Angular, Vue, Haunted, and others by virtue of some clever glue-code.

In my Apollo Elements project, I wrote some reactive controllers that do GraphQL operations like queries and mutations. I wanted to use those controllers in any custom element, so I decided to solve that problem with a class mixin called ControllerHostMixin. By applying it to an element's base class, it adds the bare-minimum required to host a reactive controller. If you apply it to a base class that already implements the ReactiveControllerHost interface, it defers to the superclass, so you could safely (if pointlessly) apply it to LitElement.

Adding Controller Support to our Element

Let's update (controller pun!) our element to accept controllers. Open color-picker.js and replace the contents with the following:

import { ControllerHostMixin } from 'https://unpkg.com/@apollo-elements/mixins@next/controller-host-mixin.js?module';

const template = document.createElement('template');
      template.innerHTML = `
        <link rel="stylesheet" href="color-picker.css">
        <div id="loupe"></div>
      `;

class ColorPicker extends ControllerHostMixin(HTMLElement) {
  constructor() {
    super()
    this
      .attachShadow({ mode: 'open' })
      .append(template.content.cloneNode(true));
  }

  update() {
    super.update();
  }
}

customElements.define('color-picker', ColorPicker);

Whoa what's that? We're loading the ControllerHostMixin over the internet from a CDN, no npm required!

This time, when you save the file and the page reloads, it will take a moment before you see the colour picker, while the page loads the necessary files from unpkg. Subsequent reloads should be faster, thanks to the browser cache. Go ahead and save colour-picker.js again to see what I mean.

Now that we're set up to host reactive controllers, let's add one which tracks the position and state of the mouse. Open mouse-controller.js and add the following content:

export class MouseController {
  down = false;

  pos = { x: 0, y: 0 };

  onMousemove = e => {
    this.pos = { x: e.clientX, y: e.clientY };
    this.host.requestUpdate();
  };

  onMousedown = e => {
    this.down = true;
    this.host.requestUpdate();
  };

  onMouseup = e => {
    this.down = false;
    this.host.requestUpdate();
  };

  constructor(host) {
    this.host = host;
    host.addController(this);
  }

  hostConnected() {
    window.addEventListener('mousemove', this.onMousemove);
    window.addEventListener('mousedown', this.onMousedown);
    window.addEventListener('mouseup', this.onMouseup);
  }

  hostDisconnected() {
    window.removeEventListener('mousemove', this.onMousemove);
    window.removeEventListener('mousedown', this.onMousedown);
    window.removeEventListener('mouseup', this.onMouseup);
  }
}

Notice how this module has no imports of its own. Controllers don't have to bundle any dependencies, they can be as simple as a single class in a single module, like we have here. Notice also where we reference the host element:

in the constructor by calling addController() to register this as one of the element's controllers
in hostConnected and hostDisconnected to run our setup and cleanup code
in our MouseEvent handlers, calling host.requestUpdate() to update the host element

That host.requestUpdate() call is especially important, it's how reactive controllers inform their hosts that they should re-render. Calling it kicks off an asynchronous pipeline which includes a call to the host's update() method. Read @thepassle 's formidable deep dive into the LitElement lifecycle for more details.

LitElement: A Deepdive Into Batched Updates

Pascal Schilp for Open Web Components ・ Dec 3 '20

#litelement #webcomponents #lithtml

Let's add the MouseController to our element and use console.log to observe updates. in color-picker.js, import the controller:

import { MouseController } from './mouse-controller.js';

Then add it to the element's class:

mouse = new MouseController(this);

update() {
  console.log(this.mouse.pos);
  super.update();
}

Full source

import { ControllerHostMixin } from 'https://unpkg.com/@apollo-elements/mixins@next/controller-host-mixin.js?module';

import { MouseController } from './mouse-controller.js';

const template = document.createElement('template');
      template.innerHTML = `
        <link rel="stylesheet" href="color-picker.css">
        <div id="loupe"></div>
      `;

class ColorPicker extends ControllerHostMixin(HTMLElement) {
  mouse = new MouseController(this);

  constructor() {
    super()
    this
      .attachShadow({ mode: 'open' })
      .append(template.content.cloneNode(true));
  }

  update() {
    console.log(this.mouse.pos);
    super.update();
  }
}

customElements.define('color-picker', ColorPicker);

After saving, when you move the mouse around the screen, you'll see the mouse' position logged to the console. We're now ready to integrate the MouseController's reactive properties into our host element.

Hooking up the Cursor

We'd like our #loupe element to move with the mouse cursor, and for it's background color to reflect the colour under the cursor. Edit the update() method of our element like so, making sure not to forget the super.update() call:

update() {
  const x = this.mouse.pos.x - this.clientLeft;
  const y = this.mouse.pos.y - this.clientTop;
  if (x > this.clientWidth || y > this.clientHeight) return;
  const hue = Math.floor((x / this.clientWidth) * 360);
  const saturation = 100 - Math.floor((y / this.clientHeight) * 100);
  this.style.setProperty('--x', `${x}px`);
  this.style.setProperty('--y', `${y}px`);
  this.style.setProperty('--hue', hue);
  this.style.setProperty('--saturation', `${saturation}%`);
  super.update();
}

In short, we get the mouse position from the controller, compare it to the element's bounding rectangle, and if the one is within the other, we set the --x, --y, --hue, and --saturation CSS custom properties, which if you recall, control the transform and background properties on our #loupe element. Save the file and enjoy the show.

Firing Events

Ok, we've done the lion's share of the work, all we have left to do is communicate with the outside world. We're going to use the browser's built-in message channel to do that. Let's start by defining a private #pick() method that fires a custom pick event, and we'll add a color property to our element to hold the most recently selected colour.

color = '';

#pick() {
  this.color = getComputedStyle(this.loupe).getPropertyValue('background-color');
  this.dispatchEvent(new CustomEvent('pick'));
}

Let's listen for click events in our element, and fire our pick event.

constructor() {
  super()
  this
    .attachShadow({ mode: 'open' })
    .append(template.content.cloneNode(true));
  this.addEventListener('click', () => this.#pick());
}

Add some user feedback by changing the loupe's border colour:

#loupe {
  /* ... */
  transition: border-color 0.1s ease-in-out;
}

Let's also let the user scrub around the picker with the mouse down, we'll add some conditions to our update function, right before the super call:

this.style.setProperty('--loupe-border-color', this.mouse.down ? 'white' : 'black');
if (this.mouse.down)
  this.#pick();

Full source

import { ControllerHostMixin } from 'https://unpkg.com/@apollo-elements/mixins@next/controller-host-mixin.js?module';

import { MouseController } from './mouse-controller.js';

const template = document.createElement('template');
      template.innerHTML = `
        <link rel="stylesheet" href="color-picker.css">
        <div id="loupe"></div>
      `;

class ColorPicker extends ControllerHostMixin(HTMLElement) {
  mouse = new MouseController(this);

  constructor() {
    super()
    this
      .attachShadow({ mode: 'open' })
      .append(template.content.cloneNode(true));
    this.addEventListener('click', () => this.#pick());
  }

  update() {
    const x = this.mouse.pos.x - this.clientLeft;
    const y = this.mouse.pos.y - this.clientTop;
    if (x > this.clientWidth || y > this.clientHeight) return;
    const hue = Math.floor((x / this.clientWidth) * 360);
    const saturation = 100 - Math.floor((y / this.clientHeight) * 100);
    this.style.setProperty('--x', `${x}px`);
    this.style.setProperty('--y', `${y}px`);
    this.style.setProperty('--hue', hue);
    this.style.setProperty('--saturation', `${saturation}%`);
    this.style.setProperty('--loupe-border-color', this.mouse.down ? 'white' : 'black');
    if (this.mouse.down)
      this.#pick();
    super.update();
  }

  #pick() {
    this.color = getComputedStyle(this.loupe).getPropertyValue('background-color');
    this.dispatchEvent(new CustomEvent('pick'));
  }
}

customElements.define('color-picker', ColorPicker);

Accessibility

We should take our social responsibility as engineers seriously. I'm ashamed to admit that I treated accessibility as an afterthought when originally drafting this post, but hopefully this section can do something to make it better.

Let's add screen reader accessibility to our element. We'll start by giving our loupe div a button role and an aria-label. We could use a <button> as well with visually hidden text content, but since we've already styled things the way we want, I think this is an acceptable use of role="button".

Let's also add a <div role="alert"> which we'll use to announce our chosen colour.

<link rel="stylesheet" href="color-picker.css">
<div id="loupe" role="button" aria-label="color picker"></div>
<div id="alert" role="alert" aria-hidden="true"></div>

Give the alert 'visually hidden' styles, since we'll be setting it's text content to announce our colour.

#alert {
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
  height: 1px;
  overflow: hidden;
  position: absolute;
  white-space: nowrap;
  width: 1px;
}

Last thing we need to do is set the alert's text when we pick the colour.

constructor() {
  // ...
  this.alert = this.shadowRoot.getElementById('alert');
}

#pick() {
  this.color = getComputedStyle(this.loupe).getPropertyValue('background-color');
  this.alert.textContent = this.color;
  this.alert.setAttribute("aria-hidden", "false");
  this.dispatchEvent(new CustomEvent('pick'));
}

And we're good, screen readers will now announce the chosen colour.

Using our Colour Picker

With our custom element finished, let's hook it up to the document by listening for the pick event. Edit index.html and add an <output> element to display our picked colour and an inline script to listen for the pick event. Let's also add some global styles in style.css:

<color-picker></color-picker>
<output></output>
<script>
  document
    .querySelector('color-picker')
    .addEventListener('pick', event => {
      document
        .querySelector('output')
        .style
        .setProperty('background-color', event.target.color);
    });
</script>

output {
  display: block;
  width: 400px;
  height: 120px;
  margin-top: 12px;
}

Next Steps

Well we're done! We've met all our goals from above with a few extras laid on top. You can play with a live example on Glitch:

You can also follow along with the steps by tracing the commit history on GitHub:

bennypowers / controller-host-color-picker

Color Picker Web Component With Reactive Controller

Let's build a colour picker web component using HTML, CSS, and a little bit of JavaScript. In the end, we'll have a custom element that:

Displays a colour spectrum using CSS Gradients
Tracks the mouse position using a Reactive Controller
Updates it's Shadow DOM via a small class mixin
Fires a Custom Event when the user clicks or drags

Tracking the Mouse with a Reactive Controller

Prerequisites

To get the most out of this article, you should have a comfortable understanding of HTML, CSS, and JavaScript; including:

How to load resources with <link>
Basic CSS syntax
How to use the DOM API to query for elements
Object-oriented programming for web developers…

View on GitHub

Can you improve on the design? Here are some ideas to get your gears turning:

Display the picked colour in HEX, HSL, or RGB
Use the picker in a popover menu
Add a lightness slider
Implement WCAG contrast checking
Use alternate colour spaces
Keep the loupe always within the colour picker area
Animate the cursor
Build a magnifying loupe element that wraps graphics elements
Optimize the runtime performance or bundle size
- How would you rewrite MouseController if you knew that an arbitrary multiple number of components in your app would use it?

Show us what you come up with in the comments. If you're looking for a production-ready colour picker element, check out @webpadawan's <vanilla-colorful>.

Footnotes

Inherited Styles

While Shadow DOM does provide strong encapsulation, inherited CSS properties are able to 'pierce' the shadow boundary, so things like color, font-family, and any CSS custom properties can reach down into our shadow roots and style our private shadow DOM.

Introducing: Custom Elements Manifest

Pascal Schilp — Thu, 17 Jun 2021 18:40:52 +0000

The idea for a web-components.json was first suggested in
this GitHub issue on the web components GitHub repository, by Pine from the VS Code team, with the initial goal for IDEs to be able to better support custom elements.

Developers tend to have many differing opinions, and standardization tends to... take time. More than 3 years later, we are happy to finally be able to share with you: Custom Elements Manifest 🎉

Custom Elements Manifest is a file format that describes the custom elements in your project. This format will allow tooling and IDEs to give rich information about the custom elements in a given project. A custom-elements.json contains metadata about the custom elements in your project; their properties, methods, attributes, inheritance, slots, CSS Shadow Parts, CSS custom properties, and a modules exports. If you're interested in following the specification of the schema, or contributing to it, you can find the repository here: webcomponents/custom-elements-manifest.

It's important to note that the Custom Elements Manifest schema is a community standard, discussion takes place in the open and is accessible to anyone. Discussions about the schema have included engineers from a wide variety of stakeholders like: Adobe, Stencil, Google, Open Web Components, ING, and more.

Example

Here's an example:

class MyElement extends HTMLElement {
  static get observedAttributes() {
    return ['disabled'];
  }

  set disabled(val) {
    this.__disabled = val;
  }
  get disabled() {
    return this.__disabled;
  }

  fire() {
    this.dispatchEvent(new Event('disabled-changed'));
  }
}

customElements.define('my-element', MyElement);

Will result in the following custom-elements.json:

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/my-element.js",
      "declarations": [
        {
          "kind": "class",
          "description": "",
          "name": "MyElement",
          "members": [
            {
              "kind": "field",
              "name": "disabled"
            },
            {
              "kind": "method",
              "name": "fire"
            }
          ],
          "events": [
            {
              "name": "disabled-changed",
              "type": {
                "text": "Event"
              }
            }
          ],
          "attributes": [
            {
              "name": "disabled"
            }
          ],
          "superclass": {
            "name": "HTMLElement"
          },
          "tagName": "my-element"
        }
      ],
      "exports": [
        {
          "kind": "custom-element-definition",
          "name": "my-element",
          "declaration": {
            "name": "MyElement",
            "module": "src/my-element.js"
          }
        }
      ]
    }
  ]
}

Potential Usecases

Why Custom Elements Manifest?

Documentation and demos

Documentation viewers should be able to display all the relevant information about a custom element, such as its tag name, attributes, properties, definition module, CSS variables and parts, etc.

api-viewer-element by Serhii Kulykov

Using a custom-elements.json file, it would be easy to generate or display demos for your component using tools such as api-viewer-element, or automatically generate Storybook knobs for your components. 11ty plugins could be created to automatically create your documentation sites for you.

Another great example is Apollo Elements by Benny Powers, which uses a Custom Elements Manifest to generate their documentation:

At the time of writing, we are also working on adding support for Custom Elements Manifest version 1.0.0 to Storybook. You can track the progress here: feat: support Custom Elements Manifest v1.

Framework Integration

React currently is the only major framework where custom elements require some special handling. React will pass all data to a custom element in the form of HTML attributes, and cannot listen for DOM events coming from Custom Elements without the use of a workaround.

The solution for this is to create a wrapper React component that handles these things. Using a custom-elements.json file, creation of these wrapper components could be automated.

Some component libraries like Fast or Shoelace provide specific instructions on how to integrate with certain frameworks. Automating this integration layer could make development easier for both authors of component libraries, but also for consumers of libraries.

Avoiding breaking API changes in minor or patch versions

Another interesting usecase, inspired by elm-package, is that tooling could be able to detect whether or not the public API of a custom element has changed, based on a snapshot of the current custom-elements.json file to decide the impact of an update, and potentially prevent breaking API change in patch or minor versions.

Linting

Linters will be able to give accurate contextual information about your custom element. Are you setting an attribute on a custom element that is not supported? Are you adding an event listener to a custom element that it doesn't fire? With the use of custom-elements.json, linters will be able to warn you, and catch mistakes early.

Cataloging

A major usecase of custom-elements.json is that it allows us to reliably detect NPM packages that for certain contain custom elements. These packages could be stored, and displayed on a custom elements catalog, effectively a potential reboot of webcomponents.org. This catalog would be able to show rich demos and documentation of the custom elements contained in a package, by importing its components from a CDN like unpkg, and its custom-elements.json file.

Much, much more!

We believe custom-elements.json will open the door for a lot, lot more new exciting ideas and tooling. Which usecases can you come up with? Do you have an idea, but are unsure where to start? Feel free to reach out to us on the Lit and Friends slack in the #open-wc channel, we're always happy to have a chat and help you get started.

How should I use a Custom Elements Manifest?

If you're publishing a component, or a library of components, we recommend people to create a Custom Elements Manifest and publish it alongside your components to NPM.

We recommend authors of components to add a "customElements": "./custom-elements.json" to your project's package.json. This allows tools to easily find whether or not a package contains a Custom Elements Manifest, and read its contents.

If your package makes use of Export Maps, make sure to also add your Custom Elements Manifest there under the "./customElements" key. This will allow consumers of your manifest to easily import it like so:

import cem from 'my-element/customElements' assert { type: 'json' };

🛠 The Tools

It's unlikely that developers will write their custom-elements.json file by hand. So at Open Web Components, we worked hard on a tool that does it for you!

`@custom-elements-manifest/analyzer`

@custom-elements-manifest/analyzer will scan the source files in your project, and generate a custom-elements.json for you.

Here's how you can use it today:

npx @custom-elements-manifest/analyzer analyze

✨ Or try it out in the online playground! ✨

@custom-elements-manifest/analyzer by default supports standard JavaScript, and vanilla web components. Dedicated web component libraries can be supported through the use of plugins. Currently, support for LitElement, Fast, Stencil and Catalyst is provided in this project via plugins. You can enable them by using the CLI flags --litelement, --fast, --stencil and --catalyst respectively, or loading the plugin via your custom-elements-manifest.config.js.

TL;DR:

JavaScript
TypeScript
LitElement (opt-in via CLI flag)
FASTElement (opt-in via CLI flag)
Stencil (opt-in via CLI flag)
Catalyst (opt-in via CLI flag)
Atomico (opt-in via community plugin)

Support for other web component libraries can be done via custom plugins, feel free to create your own for your favourite libraries.

Plugins

Different projects often have different requirements, and ways of documenting their components. Do you need to support custom JSDoc? Custom Decorators? Custom libraries? Custom anything? @custom-elements-manifest/analyzer has a rich plugin system that allows you to extend its functionality, and add whatever extra metadata you need to your custom-elements.json.

A plugin usually is a function that returns an object, and has several hooks you can opt in to:

collectPhase: First passthrough through the AST of all modules in a project, before continuing to the analyzePhase. Runs for each module, and gives access to a Context object that you can use for sharing data between phases, and gives access to the AST nodes of your source code. This is useful for collecting information you may need access to in a later phase.
analyzePhase: Runs for each module, and gives access to the current Module's moduleDoc, and gives access to the AST nodes of your source code. This is generally used for AST stuff.
moduleLinkPhase: Runs after a module is done analyzing, all information about your module should now be available. You can use this hook to stitch pieces of information together.
packageLinkPhase: Runs after all modules are done analyzing, and after post-processing. All information should now be available and linked together.

TIP: When writing custom plugins, ASTExplorer is your friend 🙂

Let's take a look at an example plugin:

Imagine we have some sourcecode, with a custom @foo JSDoc annotation and some information that we'd like to add to our custom-elements.json:

my-element.js:

export class MyElement extends HTMLElement {
  /**
   * @foo Some custom information!
   */ 
  message = ''
}

In a custom plugin, we have full access to our source code's AST, and we can easily loop through any members of a class, and see if it has a JSDoc tag with the name foo. If it does, we add the description to our custom-elements.json:

custom-elements-manifest.config.js:

export default {
  plugins: [
    {
      name: 'foo-plugin',
      analyzePhase({ts, node, moduleDoc, context}){
        switch (node.kind) {
          case ts.SyntaxKind.ClassDeclaration:
            /* If the current AST node is a class, get the class's name */
            const className = node.name.getText();

            /* We loop through all the members of the class */
            node.members?.forEach(member => {
              const memberName = member.name.getText();

              /* If a member has JSDoc notations, we loop through them */
              member?.jsDoc?.forEach(jsDoc => {
                jsDoc?.tags?.forEach(tag => {
                  /* If we find a `@foo` JSDoc tag, we want to extract the comment */
                  if(tag.tagName.getText() === 'foo') {
                    const description = tag.comment;

                    /* We then find the current class from the `moduleDoc` */
                    const classDeclaration = moduleDoc.declarations.find(declaration => declaration.name === className);
                    /* And then we find the current field from the class */
                    const messageField = classDeclaration.members.find(member => member.name === memberName);

                    /* And we mutate the field with the information we got from the `@foo` JSDoc annotation */
                    messageField.foo = description
                  }
                });
              });
            });
        }
      }
    }
  ]  
}

And the output custom-elements.json will look like this:

{
  "schemaVersion": "1.0.0",
  "readme": "",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/bar.js",
      "declarations": [
        {
          "kind": "class",
          "description": "",
          "name": "MyElement",
          "members": [
            {
              "kind": "field",
              "name": "message",
              "default": "",
+             "foo": "Some custom information!"
            }
          ],
          "superclass": {
            "name": "HTMLElement"
          },
          "customElement": true
        }
      ],
      "exports": [
        {
          "kind": "js",
          "name": "MyElement",
          "declaration": {
            "name": "MyElement",
            "module": "src/bar.js"
          }
        }
      ]
    }
  ]
}

To get started developing custom plugins, take a look at the cem-plugin-template repository to quickly get you up and running, and take a look at the Authoring Plugins documentation for more in depth information.

Concluding

We're excited and look forward to see what sorts of tooling you'll build with the Custom Elements Manifest. Do you have a cool idea for tooling, or do you want to add support for your library, but are you unsure how to get started? Drop by the Lit and Friends slack in the #open-wc channel!

Doing a FLIP with lit-html@2.0

Westbrook Johnson — Tue, 29 Dec 2020 16:45:00 +0000

UPDATE: (20 March 2021) Add support for window.matchMedia('(prefers-reduced-motion: no-preference)').

UPDATE: (23 February 2021) Use lit-html@2.0.0-pre.6 and lit-element@3.0.0-pre.3 and their associated API changes.

There's nothing like a good vacation to get the desire to try out a new piece of technology to grow like a weed in my mind. Especially if it promises to make my work not only easier, but faster and more fun at the same time. Enter the upcoming releases of lit-html and LitElement; a powerfully light renderer and a productively simple custom elements base class, respectively. These fine products from the Polymer team at Google have been an important part of my work for going on 3 or so years now, along with many other offerings from the team in the years before that, so my interest was piqued when they released their first preview build of both earlier this year. These initial looks into the new code structure of the two libraries didn't offer much in new features, but each pointed to a powerful new future that the Polymer team had been laying out for itself. So, when a second round of previews was dropped, just before the holiday break, this time supporting both new APIs and features, I couldn't wait to jump in and take a look around.

First off, if you're interested in the nitty-gritty, I suggest you start by taking a look at the README's for the latest releases of lit-html and LitElement to get right into all the things that have been or will be changed before a stable release early 2021. There are a lot of cool things, not least of which is the desire to cause as few breaks as possible when moving our use of lit-html@1.0 and LitElement@2.0 to the new versions. The biggest break looks to be in the change from a functional to a class-based API for the directive functionality offered by lit-html. While I use directives a good amount in my work, I've mainly worked with the ones built-in to lit-html by default. I'd only really built my own directives once or twice, and being I use these tools to work with custom elements (which are themselves class-based), I agree that this change is for the better of the ecosystem these tools serve. With this simplification of context, I thought directives would be a great place to take a look at what's going to be possible in the near future.

My directives to date

I've recently started working with a "streaming listener" directive in my work with Adobe's Spectrum Web Components for a number of in-development patterns, to nice success. The Open Web Components team and I vend a series of lit-helpers, one of which is a spread directive for lit-html@1.0 that simplifies spreading multiple attributes/event listeners/properties/etc. onto an element. Before getting into really new features, I took a pass at updating these.

Spreading it on thick

If you've worked with virtual DOM in the past you might be used to the ability to do something like <Component {...props} />, which is a powerful way to get an unknown number of properties applied to a component. A lot of talk around how and why to support this functionality when into this issue and what came out allows you to do the following:

import { html, render } from 'lit-html';
import { spread } from '@open-wc/lit-helpers';

render(
  html`
    <div
      ...=${spread({
        'my-attribute': 'foo',
        '?my-boolean-attribute': true,
        '.myProperty': { foo: 'bar' },
        '@my-event': () => console.log('my-event fired'),
      })}
    ></div>
  `,
  document.body,
);

I'll admit to being a little reticent about the need to include sigils demarcating which type of value is being spread onto the element, but once you've been working with lit-html for a while it starts to feel a little more normal.

What's particularly at question here is the use of the ... "attribute" to bind the directive to the element. What is the ... attribute? Is it a property named ..? (Note the . sigil demarcates a bound value should be applied as a property.) Is it magic syntax? No, it's a requirement of the v1.0 parser when binding directives to an element that something be used to ensure associate to the elements and ... representing spread/destructuring in JS, it was included here in a question inducing way. Enter element expressions in the new releases and this is no longer needed.

import { LitElement, html, css } from 'lit-element@next-major';
import { spread } from './spread.js';

class MyElement extends LitElement {
  render() {
    return html`
      <button
        ${spread({
          'my-attribute': 'foo',
          '?my-boolean-attribute': true,
          '.myProperty': { foo: 'bar' },
          '@my-event': () => console.log('my-event fired'),
          '@click': event => event.target.dispatchEvent(new Event('my-event')),
        })}
      >
        This button has a bunch of things spread on it.
      </button>
    `;
  }
}

customElements.define('my-element', MyElement);

Beyond the ease of not needing a binding sigil, there isn't a whole lot of change in the usage here. Even in the implementation, there's not a whole lot of change to go from the functional to the class based code structure. You can see this running live in the browser/in code, here: https://webcomponents.dev/edit/XugyS6YAQnEQXcS7YVKk. You can also take a closer look at the difference between the v1.0 and v2.0 implementations.

You'll see some of the cleanliness that class syntax brings to event listening generally. For instance, the ability to use the eventHandler pattern to more simply distribute the events to appropriately bound methods. Look closer and you'll see the addition of the connected and disconnected methods to the AsyncDirective base class leveraged therein. This allows the directive to clean up work that it's done while the part it relates to is not attached to the DOM. In this instance this allows us to add and remove event listeners when they are not needed.

The endless stream of time

Some DOM events are built for a streaming form of listening by default (e.g. pointerdown outlines the beginning of a stream of pointermove events that end with a pointerup) and make it really clear what the boundaries at both ends of the stream are. Some DOM events are not built this way (e.g. input starts a stream of input events that end of a change) and need a little something extra to ensure they are consumed appropriately.

In fact, streaming is so fun that you can say that again.

Some DOM events are built for a steaming form of listening by default (e.g. a change event marks the end of a stream of input events that don't fire again until a new stream starts) and make it really clear what the boundaries at both ends of a stream are. Some DOM events are not built this way (e.g. pointermove streams regardless of which side of a pointerdown or pointerup event you're on) and need a little something extra to ensure they are consumed appropriately.

Whichever side of my mind I might be in agreement with in any given moment, I created the streaming listener directive to better support this reality. On top of maintaining the stateful progression of a stream, a streaming listener allows for binding fewer events at runtime by using the current state of the stream to determine what binding to do which can improve performance as well. Take a look at how this might be leveraged:

import { streamingListener } from "./streaming-listener";

// ...

<input
  type="range"
  min="0"
  max="100"
  @manage=${streamingListener(
    { type: "input", fn: this.start },
    { type: "input", fn: this.stream },
    { type: "change", fn: this.end }
  )}
/>

Here the directive supports the ability to bind input events to both this.start and this.stream depending on the state of the stream. This allows for only a single event to be bound to the <input> at any one time without you needing to manage this (or any other state in regards to your event listening) locally increasing performance and reducing the chances of copy/paste centric bugs when leveraged across multiple contexts.

While I've made some feature additions and API changes when going between the v1.0 and v2.0 implementations, the biggest benefit of the class syntax that I see is the ability to more directly keep the state necessary to empower the directive. Previously this was done through the use of the following WeakMaps:

const previousValues = new WeakMap<
  Part,
  {
    start: { type: string; fn: (event) => void };
    stream: { type: string; fn: (event) => void };
    end: { type: string; fn: (event) => void };
    removeEventListeners: () => void;
  }
>();

const stateMap = new WeakMap<Part, boolean>();

With these hanging around in the module scope, we are able to take advantage of the idea that the Part representing the location of the directive in the template is an object that keeps identity across multiple renders, which allows us access to stored state on subsequent render passes. However, this can feel a little magic... why is this Part always the same? Can I really rely on that? Why did I make previousValues and stateMap separate? Oh, wait, that's not about magic, that's just me code reviewing myself...

In the lit-html@2.0 version, we can avoid these questions altogether by leveraging the class syntax to do exactly what classes are meant to do, keep state. We also leverage some nice defaults in our directive arguments to make it easy to apply the directive not only for events streaming between a "start" and "stop" event but also as an on/off listener for enter/leave style events as well as to stream events (like pointermove) on on the outside (or between "stop" and "start") of our stream:

<canvas
  ${streamingListener({
    start: ["pointerdown", this.start ],
    streamInside: [ "pointermove", this.streamInside ],
    end: [ "pointerup", this.end ],
    streamOutside: [ "pointermove", this.streamOutside ]
  })}
></canvas>

This really takes the streaming listener directive to a whole other level, all with only the smallest amount of additional code, and a clearer API both internally and externally.

Seeing what it looks like to update places I've been, I was even more excited to see where these new APIs might be able to take us with new possibilities.

Element expressions

In both of the above examples, we were able to remove extraneous binding locations thanks to "element expressions" that allow you to bind a directive directly to the element that it is applied to, rather than a specific part that you've outlined with an "attribute". For the spread directing that reduced <div ...=${spread({...})></div> to <div ${spread({...})></div> and <div @manage=${streamingListener({...},{...},{...})}></div> to <div ${streamingListener({...})}></div>, a win for brevity and clarity. Using this feature, the ref() directive was added to the lit-html built-ins giving us the ability to cache a reference to an element as it is rendered:

import { render, html } from 'lit-html';
import { createRef, ref } from 'lit-html/directives/ref.js';

const inputRef = createRef();
render(html`<input ${ref(inputRef)} />`, container);
inputRef.value.focus();

This greatly reduces the work need to get a reference to an element when using lit-html alone, and, whether using lit-html directly or as part of LitElement, prevents the need to query the element again after rendering. Take a test drive of the ref() directive in this lit-html only demo. I see this as a great feature for leveraging lit-html in something like StorybookJS where you will be working with pre-built custom elements and no wanting to make a new wrapping element or strange workaround to have access to elements post-render. But, what element expressions really make available are things like:

🤯 https://t.co/Ty1x9FkSpT
— Westbrook (@WestbrookJ) December 23, 2020

Let's do a FLIP

First, what is FLIP? Paul Lewis says it best, so definitely check out his blog, but the short story is:

set the (F)irst frame of your animation and cache the values you're looking to animate
set the (L)ast frame of your animation and cache the target values again
apply the (I)nverted values of those properties to the end frame
and then (P)lay the animation by removing them with a transition applied

This works best with things that can be applied as transforms or opacity, as they can be rendered on the GPU for maximum performance.

Generally, the tricky parts are doing the work between the first and last frames (but this is simplified by a multi-pass render as the first frame will simply be the previous render and the last frame will be the current render) and then calculating the inverted values on the element. In the example that we are about to borrow from the Svelte documentation we'll be focusing specifically on position properties which will allow us to keep that math a little more contained.

Or, rather, a `${flip()}`

The ${flip()} loosely referenced by Justin Fagnani in the above tweet theorized a list of items that when rearranged uses a "FLIP" algorithm to ensure that the motion between one place in the list and the next is smoothly animated. In the Svelte example, not only are there two lists, but you can remove items from those lists, which is where the real fun starts. (disclaimer: maybe we have different definitions of "fun"...)

Before we get deeper into how it works, take a look at the code in practice. Like most to-do apps (and I've made a few...haven't we all?), you're able to add an item, mark the item as "done" (or not), and delete the item. Adding will automatically append the item to the "todo" list. Clicking an item will toggle it between "todo" and "done", which will cause it to animate between the to lists and the remaining items in its original list to animate to fill the space the toggled item previously took up. Using the "delete" button will fade the item into the background while the remaining items smoothly fill up the previously used space. Try it out, do weird stuff, report bugs!

How's it work?

Taking the code pretty straight out of the above Tweet:

${repeat(
  this.items,
  i => i.id,
  i => html` <li ${flip()}>${i.name}</li> `,
)}

The repeat() directive built-in to lit-html allows you to loop over an array of items and then the optional id argument is passed (here we see it as i => i.id) the directive will maintain a single template instance for each item. This means that the instance of the flip() directive in each item will be the same regardless of where the item appears in the array order and we'll be able to cache the position of the item in the page from one render to the next. You'll see this in the code where we save the value returned by getBoundingClientRect() on the boundingRect property of the directive class. This way we can easily use that cached value to determine our "first" frame. We then wait for the Promise.resolve().then() timing (the timing on which LitElement batches its updates) to capture the "last" frame of our animation. We then take the delta so we can "invert" the values before "playing" the animation via the CSS transition property.

flip(
  firstStyleMap: {[property: string]: string},
  lastStyleMap: {[property: string]: string},
  listener: (event?: any) => void = () => {},
  removing?: boolean,
) {
  const previous = this.boundingRect;
  this.boundingRect = this.element.getBoundingClientRect();
  const deltaX = previous.x - this.boundingRect.x;
  const deltaY = previous.y - this.boundingRect.y;
  if (!deltaX && !deltaY && !removing) {
    return;
  }
  const filteredListener = (event: TransitionEvent) => {
    if (event.target === this.element) {
      listener(event);
      this.element.removeEventListener('transitionend', filteredListener);
    }
  }
  this.element.addEventListener('transitionend', filteredListener);
  const translate = `translate(${deltaX}px, ${deltaY}px)`;
  this.applyStyles({
    ...firstStyleMap,
    transform: `${translate} ${firstStyleMap.transform ?? ''}`,
  });
  requestAnimationFrame(() => {
    const transition =
      `transform ${this.options.duration}ms ${this.options.timingFunction} ${this.options.delay}ms`;
    this.applyStyles({
      ...lastStyleMap,
      transition,
      transform: `${removing ? `${translate} ` : ''}${lastStyleMap.transform ?? ''}`,
    });
  });
}

With that, all of the repositioning within a single list works like a dream. But, you may remember that in the Svelte demo we're recreating there actually are two different lists that elements animate between, as well as an animation that occurs when an element is removed from all lists, and if you do you may already be seeing where things need to get tricky.

When items are the same but not the same...

While the repeat() directive is great for associating an item to a DOM template within a single instance, it doesn't currently do this across multiple instances. This means that the DOM for a "todo" item and a "done" item with the same ID will not actually be the same and, what's worse, nor will the flip() directive that manages that DOM. To support this context, we will be needing a manage a little bit of state outside of our directive class and to do so you'll see const disconnectedRects = new Map();, where we will cache the position values of elements from directives that have been disconnected from the DOM. To power this approach, we'll also add an optional id to our directive's properties.

${repeat(
  this.todos.filter(t => !t.done),
  todo => todo.id,
  (todo) => html`
    <label ${flip({id: todo.id})}>
      <input
        type=checkbox
        ?checked=${todo.done}
        @change=${() => this.mark(todo, true)}
      >
      ${todo.id}: ${todo.description}
      <button
        @click=${() => this.delete(todo)}
        class="button"
      >remove</button>
    </label>
  `)
}

With this id cached on to our directive class and the disconnected() that we learned about above, we'll be able to store the position of our element in a place where the next directive of the same id can find it. Here you'll see how a directive without a value for boundingRect will first check to see if there was a rect for its id before generating a new one:

this.boundingRect = disconnectedRects.has(this.id)
  ? disconnectedRects.get(this.id)
  : this.element.getBoundingClientRect();
disconnectedRects.delete(this.id);

This allows the "new" instance of that directive to use the last position of the "old" instance for the "first" frame of its ensuing animation, which makes it appear as if the item is animating from one list to the next. Here we also denote that the item is no longer "disconnected" by removing its rect from the disconnectedRects cache.

When are the items not there at all?

Our items now animate with a list and between lists, but when an item is deleted, it's gone. What do we do then? This is where is good to know about your Tasks, microtasks, queues and Schedules in javascript. Go ahead and get your read on, I'll wait.

In LitElement, as we learned earlier, updates are batched in Promise.resolve().then() (or microtask, at the end of the current task) time. In a standard animation, particularly one that FLIPs, you'll do work in requestAnimationFrame() (rAF()) time (or just before the next frame). We can use this to empower our "delete" animation.

Above we learned about some housekeeping that we were doing in microtask time: disconnectedRects.delete(this.id). This is run when a directive is new and has possibly just pulled this rect out of the cache for use in a subsequent animation. However, when an item is deleted there will be no new items with the same id, and this cache will not be cleaned up. This means that in rAF() time this rect will still be in the cache and we can add the following to our disconnected():

requestAnimationFrame(() => {
  if (disconnectedRects.has(this.id)) {
    this.remove();
  }
});

This means that the position data saved in the directive can serve as the "first" frame of our "delete" animation and by appending the cached element (which is no longer on the DOM due to the previously completed render pass) to the previously cached parent, we can trigger the "delete" animation as follows:

remove() {
  this.parent.append(this.element);
  this.flip(
    { zIndex: '-1' },
      {
        transform: 'scale(0.5)',
        opacity: '0.5',
      },
      () => {
        this.element.remove();
        disconnectedRects.delete(this.id);
      },
      true
  );
}

And then, we have our complete animated todo list with the single addition of a ${flip({id})}.

When your users aren't ready to do a `${flip()}`

Recently, we've seen a rise in user preference media queries on the web. You may be taking advantage of one right now; @media (prefers-color-scheme: dark) gets a lot of play in the development community. However, there is a growing number of prefers-* media queries to take advantage of in the development of our products, and doing so can be not just that extra polish on the work we're doing, but the difference between certain visitors being able to enjoy your work or not. On top of prefers-color-scheme, prefers-contrast can mark the difference between whether someone with visual disabilities can consume your content. In locations of connectivity or high data cost, prefers-reduced-data can increase the amount of your content someone might be able to consume. In the case of content featuring motion, or rather content that ${flip()}s, the prefers-reduced-motion query can support preparing your content to take into account its effect on your audiences health. Tatiana Mac goes into great detail on how you can bring prefers-reduced-motion into the conversation as part of the development of our products and proposes "Taking a no-motion-first approach to animations". I think she's outlined an excellent path forward for our application of animation in a product, so I've made it a default of the ${flip()} directive as follows.

In javascript, we can access the current state of a media query via window.matchMedia(queryGoesHereAsAString).matches. In the case of a no-motion-first animation, we can cache a single match media object as follows:

const hasNoMotionPreference = window.matchMedia('(prefers-reduced-motion: no-preference)')

From there we can leverage whether or not the query matches to gate the initiation of animation in our experience. Currently, we do this in both the update() and disconnected() lifecycle methods. For disconnected(), we can simply gate all of the functionality therein, like so:

disconnected() {
    if (!hasNoMotionPreference.matches) {
        return;
    }
    // ... animation work done when there is `no-preference`
}

In updated() we don't want to be so blunt. This is to prepare for the possibility that the preference changes over the course of the experience. To do so we want to complete all the administrative work of caching and measuring the elements in question, which serves to prepare them to animate at any later time, and then gate the actual initiation of the current animation. In this way only the call to prepareToFlip() should be gated:

update(part, [{id = undefined, options = {}} = {}]: Parameters<this['render']>) {
    // ... administrative work of caching the element
    if (!hasNoMotionPreference.matches) {
        // exit early when there is `no-preference`
        return;
    }
    Promise.resolve().then(() => this.prepareToFlip());
}

And now, our elements only ${flip()} when a browser can make known the no-preference state of this preference, which means we're both delivering this experience as a no-motion-first animation.

What else does it do?

You'll notice that the settings for flip() also takes an options parameter. This surfaces the ability to customize the transitions via the following Options type:

type Options = {
  delay?: number,
  duration?: number,
  timingFunction?: string,
};

Playing with this I discovered that there's a step() function available in the CSS transition-timing-function which is super cool. The only problem is that step(6, end) causes the animation to look like it's running at about two frames per second (e.g. not buttery smooth) if you aren't prepared for it.

What else could it do?

While I noticed that my LitElement implementation of this interface came in right around the same number of lines of code as the notoriously terse Svelte did (give or take some TS definitions), I do realize that the original version leverages the ability to customize the "delete" animation from the outside. My example does not currently do this. It doesn't currently allow for any special customization of any of the animations. However, these animations are powered is pseudo styleMap objects and as such could be passed additional properties to animate. This would allow consumers to even more finely tune the animation you get between renders and could open some really fun paths in the future. It's important to remember (as we salivate over the possibility) which CSS properties can be performantly animated. In this way, maybe the right level of power would be to and options for opacity and scale (possibly as an opt-in that worked with width/height from the rect internally) so as to ensure users ship high-quality experiences.

One pattern that I've enjoyed recently that could be built onto this is the surface the sizing deltas a CSS Custom Properties to be consumed across a number of CSS properties via calc(). I originally discovered this technique in this great Keyframers tutorial and then later expanded on it with the help of Hounini's CSS.registerProperty currently available in Blink based browsers to be even more buttery smooth by helping it even more correctly handle the scaling of animating surfaces with rounded corners. I'll save this sort of advanced application for after the lit-* releases go stable, however.

What do you think?

Is this a cool evolution of the lit-html and LitElement ecosystem? Does it make you excited for the pending stable release? Can you already imagine the great things you'd like to build with it?

Tell me all about it!

Building for the web is all that much more exciting when we're doing it together, so I hope you'll share your thoughts on these new APIs and how I've leveraged them for good or naught I know it helps me make better code, and hopefully, it does the same for you (or there next reader that visits).

Photo by Austin Neill on Unsplash

LitElement: A Deepdive Into Batched Updates

Pascal Schilp — Thu, 03 Dec 2020 09:33:02 +0000

Introduction

LitElement is a base class for developing web components. It's very small, efficient at updating, and takes a lot of the heavy lifting of writing web components out of the developers hands, by being lazy (or: efficient).

Some questions that I often get during workshops, or from new colleagues who have just started working with LitElement are:

How exactly does LitElement achieve its efficient updates?
What does asynchronous rendering mean?
How does LitElement pick up property changes?

So I figured, it's blog time!

Lets start by taking a look at the following code example:

class MyElement extends LitElement {
  foo() {
    this.myPropertyA = 1;
  }
}

LitElement is reactive and observes your properties to kick off what is known as its "render pipeline". What this means is that whenever we change a property in our component, it'll update and re-render the component. This is nice, because it means we don't have to do anything manually. In the code example above, just the act of setting a new value to this.myPropertyA will cause our component to re-render.

Now consider another example:

class MyElement extends LitElement {
  foo() {
    this.myPropertyA = 1;
    this.myPropertyB = 2;
  }
}

Hrm. Looks like we're in a bit of a pickle here. When should we re-render? Should we re-render after myPropertyA has been set? That would mean we might do a bunch of unnecessary work and rendering, because we also want our component to update when we set myPropertyB, so we'll end up with two renders, where one would have been sufficient. That doesn't sound very efficient. This would get out of hand really quickly if we'd have a lot more properties to set in a method.

Fortunately, LitElement is smart and lazy, and uses a clever technique to batch these updates, and only re-render once. In order to understand how all this works, we're going to take a look at some popular batching patterns, dive into the event loop, and the internals of LitElement. Finally, we'll write a naive implementation of a batching web component base class.

Batching

Before we get started, lets make clear what we actually mean when we talk about batching work, and go over a couple techniques to demonstrate how we can achieve batching behavior in JavaScript.

Batching is basically limiting the amount of work we need to do, and is often implemented as a performance measure. A popular usecase for batching, or limiting work, is limiting API calls that may get fired in quick succession for example. We don't want to put any unnecessary load on the API, and do a bunch of wasteful requests. Or in the case of LitElement; efficiently limiting re-renders of our components. Remember; the goal is to avoid any unnecessary work in order to be performant.

A popular pattern for batching is using a debounce function. As mentioned above, debouncers are often used for batching API calls. Imagine we have a search input, that every time a new search keyword is entered, fetches some search results from a server. It would put a pretty heavy load on the API if we would fire a request for every single input change or every new character, and that can be pretty wasteful. Instead, we can debounce the API calls, to only actually fire a request on the last input change.

Consider the following example:

/* This is generally what a debounce function looks like, it takes a function to execute, and optionally a delay */
function debounce(func, delay = 0) {

  /* We create a variable to store a reference to the last `setTimeout` */
  let timeoutId;

  /* And then we return a new function, that whenever called, clears the latest timeout, essentially cancelling it, and schedules a new timeout */
  return function() {

    /* Because this function closes over the outer function, we'll still have access to the `timeoutId` declared above. This is useful on subsequent calls to the 'inner' function. */
    clearTimeout(timeoutId);

    /* We then schedule a new timeout, that calls the function that we'd like to execute */
    timeoutId = setTimeout(() => {
      func.apply(this, arguments);
    }, delay);
  }
};

function search() {
  /* Do some API call to get more search results */
}

/* We create a new variable that stores the _returned_ function from the debounce function */
const debouncedSearch = debounce(search, 500);
input.addEventListener("input", debouncedSearch);

If the user types the search keyword "javascript" in the input, instead of firing 10 API requests (one request for every character in the word "javascript"), we only fire one request; when the user has finished typing.

If you're interested in reading more about debouncing, here's a great blog on css-tricks.com

However, and I’m sorry to disappoint, this is not how LitElement does things but important to illustrate the point of "batching". Before we go deeper into that, we’re going to require some knowledge about...

THE EVENT LOOP!

The event loop... can be a pretty elusive subject to understand. I'll try to keep it brief here with a basic example, but if you're interested in learning more about how the event loop works, here are some incredible resources that I cannot recommend enough:

Fortunately, where we're headed, we don't need to understand all the ins and outs of the event loop, we're really only interested in microtasks for our case. Consider the following piece of code (... that often does the rounds on Twitter polls, and has confused many a developer before). What do you think is the order the console.log statements are called?

console.log(1);

Promise.resolve().then(() => {
  console.log(2);
});

console.log(3);

Here's the answer, the order of the resulting console logs of this code is:

// 1
// 3
// 2

We'll have Jake Archibald explain to us why exactly this happens:

The microtask queue is processed after callbacks as long as no other JavaScript is mid-execution, and at the end of each task. Any additional microtasks queued during microtasks are added to the end of the queue and also processed.

If we go back to our code snippet, we can see that the following happens:

console.log(1); is called, and logged to the console
We schedule a new microtask with Promise.resolve().then(() => {}), but at this point in time, JavaScript has not finished executing; it's not time to actually process microtasks just yet
JavaScript continues executing code, because we're not done yet
console.log(3); is called, and logged to the console
JavaScript has finished executing! The browser can now process any microtasks we may have
console.log(2); is called, and logged to the console.

So why is this important? How does this allow us to use microtasks to batch work? Let's take a look at a practical example:

class Batching {
  /* We declare and initialize a variable to keep track of whether or not an update has already been requested */
  updateRequested = false;

  scheduleUpdate() {
    /** 
     * In here, we need a check to see if an update is already previously requested.
     * If an update already is requested, we don't want to do any unnecessary work!
     */
    if(!this.updateRequested) {

      /* If no update has yet been requested, we set the `updateRequested` flag to `true` */
      this.updateRequested = true;

      /** 
       * Since we now know that microtasks run after JavaScript has finished
       * executing, we can use this knowledge to our advantage, and only set 
       * the `updateRequested` flag back to `false` again once all the tasks 
       * have run, essentially delaying, or _batching_ the update!
       */
      Promise.resolve().then(() => {
        this.updateRequested = false;
        this.update();
      });
    }
  }

  /* This is our `update` method that we only want to be called once */
  update() {
    console.log('updating!');
  }
}

const batching = new Batching();

/* We call scheduleUpdate in quick succession */
batching.scheduleUpdate();
batching.scheduleUpdate();
batching.scheduleUpdate();

/* 🎉 The result: */

// "updating!" 

/* `update` only ran once! */

Essentially, scheduleUpdate guards the update function against multiple incoming calls with its if statement. This cleverly uses our newfound knowledge of microtasks to our advantage to process any other incoming calls first. update only gets called once JavaScript has finished executing and microtask processing begins.

As a fun tidbit of knowledge, we can also write the scheduleUpdate method like so:

class Batching {
  // ...

  async scheduleUpdate() {
    if(!this.updateRequested) {
      this.updateRequested = true;
      this.updateRequested = await false;
      this.update();
    }
  }

  // ...
}

Since, from MDN:

If the value of the expression following the await operator is not a Promise, it's converted to a resolved Promise.

In other words, once we set updateRequested, we don't immediately unset it, the await keyword ensures that we only schedule it to be unset.

In fact, Justin Fagnani, one of the authors of LitElement, once told me on twitter that the pre-LitElement version did exactly this:

Deferring promises

Alright, we're almost ready to explain how LitElement achieves its efficient updates. But before we go there, there's one final concept we need to explore, and that's deferring resolving of Promises, which will provide us with a handy utility later on in this blog post.

Take a look at the following code:

/* We declare a new variable */
let resolveFn;

/** 
 * We declare a new promise, but we _dont_ resolve it! 
 * Instead, we assign the `resolve` function to the
 * `resolveFn` that we declared above
 */
const myPromise = new Promise((resolve) => {
  resolveFn = resolve;
});

/** 
 * `myPromise` now is just a pending promise, waiting to be resolved,
 * and we can do that whenever we please with our `resolveFn`
 */
myPromise; // Promise {<pending>}

/* For example, we could do a whole bunch of other work in between */

/* And finally, whenever we're ready, we can call the `resolveFn` to resolve `myPromise` */
resolveFn(); // Resolves `myPromise`

/* Aaand `myPromise` is now fulfilled! */
myPromise; // Promise {<fulfilled>: undefined} ! 🎉

This pattern is often used in cases (like unit tests) where you have to await a specific amount of time before continuing.

function sleep(delay) {
  return new Promise(resolve => {
    setTimeout(resolve, delay)
  });
}

(async () => {
  await sleep(1000); // Awaits one second for the timeout to execute before continuing
})()

In this example, the sleep function returns a new Promise. Inside the promise, we set a timeout, but we only resolve the promise once the setTimeout callback is executed. So by awaiting the sleep function, we essentially force to wait until setTimeout callback has executed.

Be aware, however, that JavaScript is single-threaded, and blocking the main thread is generally considered a bad practice.

Back to LitElement

🧙‍♂️ Automagically requested updates

LitElement is reactive. What this means is that, like many other modern frontend libraries, we dont have to worry as much about manually rendering or re-rendering the contents of our component. All we have to do as a user of LitElement is declare our properties, LitElement will then observe these properties for us, and when a property has changed LitElement takes care of updating our component for us. Nice. I like not doing work.

Simple counter element, courtesy of the lovely folks over at webcomponents.dev

Imagine we have a simple counter element that has a count property. All thats needed for LitElement to rerender, is set a new value to the count property like so: this.count = 1;. This will automagically cause LitElement to request an update.

But... how? How does LitElement know that the count property was set? How does it observe our properties?

LitElement requires users to declare the properties of their component in a static properties getter. This static properties getter is very, very useful, because it takes a lot of boilerplate out of the developers hands, it takes care of attributes for us, handles attribute reflection, allows us to react to changes, but more importantly: It creates getters and setters for us. This is nice, because this means that our components dont get littered with getters and setters all over the place, but it also requests updates for us!

Consider the following example:

class MyCounter extends LitElement {
  static get properties() {
    return {
      count: { type: Number }
    }
  }
}

Under the hood, LitElement essentialy turns this into the following getters/setters:

class MyCounter extends LitElement {
  set count(value) {
    this.__count = value;
    this.requestUpdate(); // ❗️ (metal-gear-solid-alert.mp3)
  }

  get count() {
    return this.__count;
  }
}

Note: this is pseudocode for illustration purposes, the actual source code of LitElement looks a little bit different, but the general concept still applies. If you're interested in reading the source code, you can find it here.

What this means is that whenever we assign a new value to a property like so: this.count = 1;, the setter for count is called, which then calls requestUpdate(). So by simply setting a property, an update is requested for us!

Objects and arrays

We'll take a small aside here to explain another common occurence when using LitElement, that I often see people get confused about. We now know that we can trigger updates simply by setting a new value to a property, but... what about objects and arrays?

Imagine we have a component with a user property that looks something like this:

{
  name: "Mark",
  age: 30
}

People often expect that setting, for example, the name property on the user object should trigger a rerender, like so: this.user.name = "Nick";, and are surprised to find that it doesn't. The reason for this is that by setting the name property of the user object, we don't actually change the user object itself, we changed a property of the user object, and as such, the this.requestUpdate() method is never called!

An easy fix for this is to just call this.requestUpdate() manually, or alternatively replace the entire object to make sure the setter does get called:

this.user = {
  ...this.user,
  name: "Mark"
}

The same is true for arrays. Imagine we have a users property on our element, that contains a list of users similar to the object we used in the example above. The following code will not schedule an update:

this.users.push({name: 'Nick', age: 30});

Because we only mutate the already existing array, and as such don't trigger the setter for the users property itself.

Back to batching updates

Alright, we now know what batching means, how microtasks work, how we can defer resolving promises, and how setting properties in LitElement schedules an update. We have all the required knowledge to figure out how LitElement actually uses this to batch its updates.

To do so, we're going to write a very naive implementation of this behavior. We're going to start with a very simple JavaScript class that efficiently calls an update method when our properties change. Follow along:

/* We create a new class ... */
class Batching {

  /* ... that has a `requestUpdate` method */
  async requestUpdate() {

    /** 
     * In here, we need a check to see if an update has already previously been requested.
     * If an update is already requested, we don't want to do any unnecessary work!
     */
    if (!this.updateRequested) {

      /**
       * If no update was previously requested, we set this
       * flag to `true` to avoid doing unnecessary work in
       * case `requestUpdate` might get called another (or several) times
       */
      this.updateRequested = true;

      /** 
       * ... and _this_ is where the magic happens;
       * This schedules a microtask that executes once JavaScript has
       * finished executing, and since we guard against any other
       * incoming calls for `requestUpdate`, we only do work once
       */
      this.updateRequested = await false;

      /* Finally, we call our `update` method, which can then render some DOM, or do whatever */
      this.update();
    }
  }

  update() {
    console.log("updating!");
  }

  /**
   * For demonstration purposes we add some setters here,
   * that when given a new value, will request an update
   */
  set a(val) {
    this.__a = val;
    this.requestUpdate();
  }

  set b(val) {
    this.__b = val;
    this.requestUpdate();
  }
}

/* We instantiate a new instance of our class */
const batching = new Batching();

/* And we set multiple properties */
batching.a = 1;
batching.b = 2;

/* 🎉 The result: */

// "updating!"

You can see a live demo of this in your browser here

Taking things a step further

Neat! We now have a simple implementation of batching updates. We can now take things even further and provide some kind of API so users can await updates, like LitElement's updateComplete property. Take a look at the following code:

class Batching {
  constructor() {

    /** 
     * We initialize an `updateComplete` property with a new 
     * Promise that we'll only resolve once `this.update()`
     * has been called
     */
    this.updateComplete = this.__createDeferredPromise();
  }

  async requestUpdate() {
    if (!this.updateRequested) {
      this.updateRequested = true;
      this.updateRequested = await false;
      this.update();

      /* When our update is, in fact, complete we resolve the Promise that was assigned to the `updateComplete` property ... */
      this.__resolve();

      /* ... And we assign a new promise to updateComplete for the next update */
      this.updateComplete = this.__createDeferredPromise();
    }
  }

  update() {
    console.log("updating!");
  }

  /** 
   * Creates a new deferred promise that we can await, 
   * and assign the `resolve` function to `this.__resolve`, 
   * so we can resolve the promise after we call `this.update()`
   */
  __createDeferredPromise() {
    return new Promise((resolve) => {
      this.__resolve = resolve;
    });
  }

  set a(val) {
    this.__a = val;
    this.requestUpdate();
  }

  set b(val) {
    this.__b = val;
    this.requestUpdate();
  }
}

/* We use an Async IIFE (Immediately Invoked Function Expression), because top-level await is not a thing yet 😑 */
(async () => {
  /* We instantiate a new instance of our class */
  const batching = new Batching();

  /* Set multiple properties in a row */
  batching.a = 1;
  batching.b = 2;

  /* And this is where we `await` an update */
  await batching.updateComplete;

  /* We then assign another property */
  batching.b = 3;

  /* 🎉 The result: */

  // "updating!"
  // "updating!"
})();

You can see a live demo of this in your browser here

Back to web components land

Sweet, now that we have a solid understanding of using microtasks to our advantage to batch work, let's go back to web components land, and see how we could implement this as a simple base class for web components.

/* We create a new class that extends from the native HTMLElement */
class BatchingElement extends HTMLElement {
  constructor() {

    /* We now have to call `super` to make sure our element gets set up correctly */
    super();
    this.updateComplete = this.__createDeferredPromise();
  }

  async requestUpdate() {
    if (!this.updateRequested) {
      this.updateRequested = true;
      this.updateRequested = await false;
      this.update();
      this.__resolve();
      this.updateComplete = this.__createDeferredPromise();
    }
  }

  update() {}

  __createDeferredPromise() {
    return new Promise((resolve) => {
      this.__resolve = resolve;
    });
  }
}

Again, this code is a simplified example of the technique LitElement uses for illustration purposes, if you're interested in seeing how LitElement achieves this exactly, you can find the source code here.

And, well, that's it. Not much has changed here really, other than the fact that we now extend from HTMLElement, and have to call super() in the constructor. Let's see how we can actually use it in a component:

/* We create a new class, MyElement, that extends from our BatchingElement base class */
class MyElement extends BatchingElement {

  constructor() {
    super();

    /* We attach a shadowRoot to our component for good measure */
    this.attachShadow({ mode: "open" });
  }

  connectedCallback() {
    /* And we call an initial render when our component gets connected to the DOM */
    this.update();
  }

  /**
   * This is our `update` function that will get triggered by the
   * `requestUpdate` method.
   * 
   * Any time we set a property on this element, we'll also
   * trigger an update.
   */
  update() {
    console.log('updating!');
    this.shadowRoot.innerHTML = `
      <div>value of a: ${this.a}</div>
      <div>value of b: ${this.b}</div>
    `;
  }

  /**
   * And finally, we need some getters and setters to
   * actually be able to trigger updates 🙃
   * 
   * Notice how much boilerplate this is, and how nice
   * LitElement makes this for us instead? 😩
   */
  set a(val) {
    this.__a = val;
    this.requestUpdate();
  }
  get a(){
    return this.__a;
  }

  set b(val) {
    this.__b = val;
    this.requestUpdate();
  }
  get b(){
    return this.__b;
  }
}

customElements.define("my-element", MyElement);

Neat! We've now implemented our BatchingElement base class in a real life web component. Whenever we change multiple properties in a row, we'll only call our update method once. Consider the following example:

/* We get a reference to our component, so we can call methods on it */
const myElement = document.querySelector('my-element');

/**
 * We assign multiple properties in quick succession,
 * but our component will still only call `update` once!
 */
myElement.a = 'foo';
myElement.b = 'bar';

/* 🎉 The result: */

// "updating!" -> called in the `connectedCallback` to do an initial render
// "updating!" -> trigger by setting two properties

You can see a live demo of this in your browser here.

If you're interested in seeing another real world example that implements this pattern, you can take a look at @generic-components, where I use the same pattern to batch calls for the slotchange event. The implementation is slightly different, but the same concepts apply.

And thats how LitElement efficiently batches updates and avoids doing unnecessary work. Combine that with lit-html to do efficient DOM updates, and you have a really efficient and powerful combination of libraries at your disposal.

Thanks for reading!

Introducing mdjs - interactive demos everywhere

Thomas Allmer — Wed, 15 Apr 2020 12:26:09 +0000

All shared code should have written documentation to show what it can be used for and what the idea behind it is.
Users should at least be able to get a high level understanding of what they are using, what they're using it for, and why.

On the web, we have many many different ways of writing documentation.
However, one thing almost all of them have in common is that they rely on Markdown or some kind of variation of it.

And it's no surprise, because Markdown is supported practically everywhere (vscode, atom, github, gitlab, dev.to, npmjs, ...)

For tools that do not run in the browser

In this case, you will mostly share code snippets that people will need to run in their own projects in which case traditional static site generators like Docusaurus, VuePress, Gatsby, et al work great. All of them have full support for Markdown and allow you to easily create beautiful documentation pages with code snippets/highlighting, and more.

And frankly, if that is your use case almost everything you need should be possible with those tools as long as you feel comfortable with the ecosystem/framework.

For (visual) components that do run in the browser

In this context, users probably do expect a live demo to see all the different options of your component in action. So pure Markdown is usually not enough as we now want to actually execute code and "insert" our working component in our documentation somehow. This would require specialized handling for each framework.

Vue

For Vue, as an example, you can use VuePress which auto registers all Vue components in a certain folder and then you can use as normal html tags since Markdown supports html

.
└─ .vuepress
  └─ components
      ├─ demo-1.vue

<demo-1 />

supports vue components and has "magical" import for them
no support for generic javascript or passing properties to components

React

For React you can use Mdx which extends Markdown with JSX support. Mdx is available via multiple tools like Gatsby, docz, storybook, etc.

import { Chart } from '../components/chart'

# Here’s a chart

The chart is rendered inside our MDX document.
<Chart />

supports import/export JavaScript
passes everything through JSX
Doesn't look great on github, requires special tools in editors to get highlighting

Limitations

What all these specialized tools have in common is that they require a specific build tooling setup to work.
For web components, none of that is actually needed. Markdown already allows for HTML. The only missing piece is how to load a web component through JavaScript?

Introducing Markdown with JavaScript (mdjs)

The primary goals are

minimal complexity
follows progressive enhancement
stick close to valid markdown syntax
code highlighting in editors without additional tools
looks good on github/gitlab/any source code management tool

The fundamental idea seems almost too simple to be true. We "enhance" a code fence block with additional meta data js script.

```js script
import './my-component.js';
```

# This is my component
<my-component></my-component>

And that's it! 😄

Alright, enough talk, you can see it live here:

==> Link to editable demo <==

How does it work

Mdjs hooks into remark and extracts all those tagged js blocks.
In the end, html and js is separately available.

{
  html: '<h1>This is my component</h1><my-component></my-component>',
  jsCode: "import './my-component.js';"
}

It can then be combined/processed by any tool to create an actual documentation page.

The process looks like this:

Extract js script and separate it from md
Render md
Provide html & js

Link to animation as slides

This already is powerful enough to directly include JavaScript and render web components with attributes.

Enhancing mdjs with demo format

Now that we can execute JavaScript within our Markdown this opens the door for more advanced features.

Our first step is to create another enhanced js code block, namely; js story.
From this code block you can export a function to be executed on demand:

```js script
import './my-component.js';
```

# This is my component

```js preview-story
export const demo = () => `<my-component header="from attribute"></my-component>`
```

if you want to add a border around and a button to show/hide the actual source code you can use js preview-story

What you get looks something like this

{
  html: '<h1>This is my component</h1><my-component></my-component>',
  jsCode: "import './my-component.js';",
  stories: [
    key: 'demo',
    name: 'demo',
    code: 'export const demo = () => `<my-component header="from attribute"></my-component>`',
  ]
}

Under the hood, this adds an extra step to the processing:

Extract js script and separate from md
Extract js story and js preview-story and separate from md
Put a placeholder <mdjs-story mdjs-story-name="demo"></mdjs-story> or mdjs-preview at it's place
Render markdown
Provide html, javascript, and stories

This is all the information we need to create full javascript and demo capable pages purely from markdown.

By default Mdjs takes it a small step further by supporting an actual template system - namely lit-html.

```js script
import './demo-wc-card.js';
import { html } from 'lit-html';
```

# This is my component

```js story
export const demo = () => html`
  <demo-wc-card header="HEADER"></demo-wc-card>
`;
```

Link to animation as slides

Here another playground mimicking a full documentation page.

==> Link to editable demo <==

mdjs default docs page

Once all this meta-information is available you can render a specific docs page.

It basically comes down to generating this code which assigns the demo function to the actual web component.

const stories = [{ key: 'demo', story: demo, code: demo }];
for (const story of stories) {
  const storyEl = rootNode.querySelector(`[mdjs-story-name="${story.key}"]`);
  storyEl.story = story.story;
  storyEl.code = story.code;
}

All of this happens under the hood for you 🤗

Where can you use mdjs?

You can use it locally via es-dev-server

Here i'll show you how you can create a github like markdown view for all your local markdown files including live demos.

Install es-dev-server as a dependency by running npm i -D es-dev-server
Add the following script to your package.json:

  "scripts": {
    "start": "es-dev-server",
  }

Create a es-dev-server.config.js in the root of your repo.

  const { mdjsTransformer } = require('@mdjs/core');

  module.exports = {
    nodeResolve: true,
    open: 'README.md',
    watch: true,
    responseTransformers: [mdjsTransformer],
  };

After executing npm run start you can happily browse your live documentation via http://localhost:8000/README.md.

You can see an example setup in the demo-wc-card repo.

You can use it via Storybook

If you want to work on individual components or get a list of all demos you can use Storybook.

Install dependency npm i -D @open-wc/demoing-storybook
Add to your package.json:

  "scripts": {
    "storybook": "start-storybook",
  }

Adjust your .storybook/main.js to load markdown files

  module.exports = {
    stories: ['../README.md', '../docs/**/*.md'],
    esDevServer: {
      nodeResolve: true,
      watch: true,
      open: true,
    },
  };

Add to every markdown file that should be in storybook a name via

  export default {
    title: 'My Group/My Awesome Component',
  };

And just like that, you are good to go.
No additional changes to any files are needed; a plugin will take care of everything by converting your markdown files to the support Storybook's mdx format.

For more detailed information please see https://open-wc.org/demoing-storybook/.

Show it on github

Since Github supports markdown out of the box, we can take things even further by using Mdjs.

As it's not supported by github directly you will need a chrome extension called mdjs-viewer.

Do you want to see a demo without opening a different page? mdjs-viewer!
Do you want to show a live example of the issue you are having? mdjs-viewer!

Almost looks like black magic, huh?
All you did was install a Chrome extension and suddenly Github got superpowers.

All that you need is to have some Markdown files with the correct code fence blocks, and have your code up and running on unpkg.com.

How does it actually work?

The extension detects which Github page you are on.
If it actually finds a markdown file or an issue with mdjs code then it adds a "show demo" button to activate it.
Only if you click the button it will start gathering all the needed info.

find the nearest package.json
read the actual markdown file/issue content
replace all bare import with unpkg.com imports
replace all relative imports with unpkg.com and the name of the package.json + relative path for it
create a secured iframe
position the iframe absolute as an overlays
put the javascript and html code inside the iframe
the button becomes a toggle to show/hide the iframe

Some of the tasks are more complicated and require some extra work to make it secure but in essence, that's it.

With that, you can put documentation with live examples on github.
Even issues with demos showing the actual error in the code are possible.

That sure sounds like a hell of a tool to improve your documentation an issue reproduction, doesn't it?
Especially as the readme and issue content still remain useful even without the extension.

For more detailed information please see https://github.com/open-wc/mdjs-viewer.

Supported on webcomponents.dev

Fully supported by this awesome online editor.

You can directly edit your documentation, demos and code directly in the browser.

You can start directly with documentation as in the screenshot above, or even better you can use it in every Markdown file or README.md 💪

Give it a go and document your components in all its glory.

All the demo links are actually from webcomponents.dev.

Be sure to check it out.

How you can add support for mdjs

Please check the official documentation page at https://rocket.modern-web.dev/docs/markdown-javascript/overview/.

Resume

There you have it - mdjs is a format that can be shown in many different ways.
It is your single source of truth for good looking documentation everywhere.
Be it locally, a published storybook, on github or npmjs it always looks good even if there is no direct support for it, but when possible it will become interactive demos through progressive enhancement.

Now go out there and write good documentation for your components!

Future

Have a separate github repo (potentially group as well).
Have a dedicated homepage
The default story preview frame should look a little nicer
Support multiple renderers - discussion in issue
Highlighting of code snippets
More helpers to be used within stories
... (feel free to open issues within the corresponding projects)

Acknowledgements

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Pascal for feedback and helping turn my scribbles to a followable story.

Photo by Aaron Burden on Unsplash

The evolution of Open-wc scoped-elements

Manuel Martín — Mon, 06 Apr 2020 06:11:09 +0000

In this blog post I'm going to talk about the evolution of @open-wc/scoped-elements package. If you want to know the context behind it and why we created it, you might want to read my previous blog post first.

A few months ago we shipped the first experiment about scoping web component definitions, @open-wc/scoped-elements, allowing us to use in our apps different versions of the same components. Since then, we learned and improved some things about using scoped elements that I would like to share with you in this post.

First, we improved our development experience. From using the createScopedHtml function we have gone to using a Mixin for our LitElement components, so now the use of scoped-elements looks like this:

import { LitElement, html, css } from 'lit-element';
import { ScopedElementsMixin } from '@open-wc/scoped-elements';
import { FeatureA } from 'feature-a';
import { FeatureB } from 'feature-b';

export class PageA extends ScopedElementsMixin(LitElement) {
  static get scopedElements() {
    return {
      'feature-a': FeatureA,
      'feature-b': FeatureB,
    }
  }

  static get styles() {
    return css`
      :host {
        display: block;
        padding: 10px;
        border: 2px solid #ccc;
      }
    `;
  }

  render() {
    return html`
      <h3>I am page A</h3>
      <feature-a></feature-a>
      <feature-b></feature-b>
    `;
  }
}

As developers, we can now apply the ScopedElementsMixin to our component and add the static scopedElements method, with the elements that we want to scope. So far so good!

But, what happens if we don't know which element we want to use at the moment of the scoped elements definition? It could happen, for example, that we may want to lazy-load some components. To cover this use-case the mixin has a method named defineScopedElement(tagName, element) that allows us to define scoped elements at any time. Let's see an example:

import { LitElement } from 'lit-element';
import { ScopedElementsMixin } from '@open-wc/scoped-elements';
import { MyPanel } from './MyPanel.js';

export class MyElement extends ScopedElementsMixin(LitElement) {
  static get scopedElements() {
    return {
      'my-panel': MyPanel,
    };
  }

  connectedCallback() {
    super.connectedCallback();

    import('./MyButton.js').then(({ MyButton }) =>
      this.defineScopedElement('my-button', MyButton));
  }

  render() {
    return html`
      <my-panel class="panel">
        <my-button>${this.text}</my-button>
      </my-panel>
    `;
  }
}

In the previous example, my-button is not registered as a scoped element in the static scopedElements method because it is loaded lazily, and once loaded it is defined through the definedScopedElement function, which causes the tag my-button to be upgraded to the actual component.

Last but not least, it could also happen that in an awesome feature you are implementing you need to get a scoped tag name for any other reason or perhaps you want to create the element through document.createElement 🤷‍♂️.

Static method getScopedTagName to the rescue! This method returns the scoped tag name used by your component for a specific tag name. Even if the component that uses that tag name is not yet defined! (remember, lazy components 😉).

import { LitElement } from 'lit-element';
import { ScopedElementsMixin } from '@open-wc/scoped-elements';
import { MyPanel } from './MyPanel.js';

export class MyElement extends ScopedElementsMixin(LitElement) {
  static get scopedElements() {
    return {
      'my-panel': MyPanel,
    };
  }

  constructor() {
    super();

    const scopedTagName = this.constructor.getScopedTagName('my-panel');

    // do whatever you need with the scopedTagName
  }

  // ...
}

But those are not the only improvements made by the use of the mixin. Another important point is that this type of use will probably allow us to upgrade our mixin to use scoped custom element registries behind the scenes once they are a reality, so our applications will not need to be migrated whenever this happens. Great, isn't it? 🤗

Finally, scoped-elements has been very useful in my company because we have a large shared component library that recently released a major version, and scoped-elements allows us to migrate our apps seamlessly without doing a big bang.

You can find more information about scoped-elements in Open-wc website.

Mind the `document.activeElement`!

Westbrook Johnson — Wed, 19 Feb 2020 00:35:51 +0000

The element that currently has focus in your HTML at any point in time can be accessed as document.activeElement. If you don't know, now you know!

What's more, while it can be difficult to capture the value of this property while debugging, at least without changing it, you can leverage browsers that allow you to "watch live expressions" to keep the current value of this property available at all times, 😱. No, really, go check it out right now!

There are lots of ways you can leverage this in your work, whether in functional code, unit tests or debugging, but I'm not looking to walk you through all the things that should be, can be, or will be in this area. However, if you're already using this value, I'd love to hear more about it in the comments. My usage can definitely be super-powered by hearing great workflows from others, so I look forward to hearing what you've got up your sleeves.

We are gathered here, today, to go a little bit deeper on what document means and when the document isn't the “document”0 you're looking for and what to do in that case.

Out of the shadows a new `document` rises...

Do you find yourself using code like the following to attach a shadow root to elements in your application?



el.attachShadow({mode: 'open'});

Do you find yourself attaching that shadow root to custom elements that you've defined?



class CustomElement extends HTMLElement {}
customElement.define('custom-element', CustomElement);

Then you're already using web components.

If not, I highly recommend them in many and varied use cases! The benefits I've gained from working with custom elements and shadow DOM from well before both APIs were even supported by two browsers, let alone all of them, are all positive, and the full possibilities of this sometimes wholely different paradigm of client-side development are still only beginning to be fully explored.

// Detect dark theme var iframe = document.getElementById('tweet-1217578939456970754-367'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1217578939456970754&theme=dark" }

If you're ready to start exploring them too, check out Web Components: from zero to hero, an amazing introduction to these technologies by Pascal Schilp, and you'll be well on the way.

When creating your own custom element with their own shadow roots, you're getting a "DOM subtree that is rendered separately from a document's main DOM tree". A subtree that is separate from the document: a document to itself. Inside of that subtree, you get encapsulation for whatever DOM lives therein from external selectors, a special HTML slot API for composing DOM from the outside of the element, and much more. However, when minding the document.activeElement, it is important to look a little deeper at the specific cost that we pay to get these new capabilities.

document.activeElement points to the element in the document that currently has focus, but what happens when that element isn't actually in the document? If your shadow DOM has focusable elements internal to it, and one of those elements currently has focus, document.activeElement (like all other selectors) will not be able to point directly to it. What it will point to is the first element in the document that includes a shadow DOM. So, taking the following tree into account:



<document>
  <body>
    <h1>Title</h1>
    <custom-element>
      #shadow-root
        <h2>Sub-title</h2>
        <other-custom-element>
          #shadow-root
            <a href="#">This is a link</a> <!-- The link _has_ focus -->

When the <a> element above is focused and document.activeElement is referenced, the value returned will point to the <custom-element> just below the <h1>; not the <a>, not the <other-custom-element> that is its parent, and likely, not what you expected.

A brave new world

Oh no, shadow DOM broke the internet!
- alarmist JS (framework) user

Well, in a word, "no".

With more nuance... shadow DOM has broken the assumption that the specifics of focus in any one component will bleed into all other components, so yes the fragile, fly by night, shoot from the hip internet that was previously the only option available to use is broken if you choose to use shadow DOM and the shadow boundaries that they create. However, if you choose to use shadow DOM and the shadow boundaries that they create, you now have access to a more nuanced, controllable, and refined DOM than ever before. Yes, some things that you may have taken for granted in the past may be a little different than you remember, but you also have access to capabilities that were previously impossible or prohibitively complex.

But... if I can't see what the currently focused element is, what will I do?

While inside a shadow root, document.activeElement will not allow you to see if any other elements in the subtree are currently focused, yes. However, from the root of a subtree, we now have shadowRoot.activeElement available to us when we desire to find the focused element in our current subtree. This means that instead of having to worry about the entire document (both above and below your current component), you can take into consideration only the DOM belonging to the subtree related to the current component.

OK, how do I leverage this?

I feel you start to think, "ok, that sounds like I could find a way to process this as being cool after ruminating on it for a while, but how do I figure out what shadow root I'm in?", and that's a great question! The answer is in the getRootNode() method that has been added to Element as part of the introduction of shadow DOM. With this method, you will be given the root of the DOM tree in which the element you called getRootNode() on lives. Whether what is returned is the actual document or an individual shadowRoot its member property activeElement will allow you to know what element in that tree is currently focused.

Let's revisit our sample document from above to better understand what this means...



<document>
  <body>
    <h1>Title</h1>
    <custom-element>
      #shadow-root
        <h2>Sub-title</h2>
        <other-custom-element>
          #shadow-root
            <a href="#">This is a link</a> <!-- The link _has_ focus -->

When you have a reference to the <a> element therein:



const root = a.getRootNode();
console.log(root);             // otherCustomElement#shadowRoot
const activeElement = root.activeElement;
console.log(activeElement);    // <a href="#"></a>

When you have a reference to the <h2> element therein:



const root = h2.getRootNode();
console.log(root);             // customElement#shadowRoot
const activeElement = root.activeElement;
console.log(activeElement);    // <other-custom-element></other-custom-element>

And, when you have a reference to the <body> element therein:



const root = body.getRootNode();
console.log(root);             // document
const activeElement = root.activeElement;
console.log(activeElement);    // <custom-element></custom-element>

But, a component should have some control of its children, right?

I completely agree! But, in the context of a free and single document "some" control becomes complete and total control.

In the case of shadow DOM encapsulated subtrees, the control that a parent has over its children is only the control that said child offers in the form of its public API. If you don't want to cede any control to a parent element implementing your custom element, you do not have to. Much like the first night you stayed out past curfew, this will surprise most parents accustomed to a level of control they maybe never should have had.

Will they get the number to your new cell phone?
Will you pick up when they call?
Will you still come home for dinner on Sunday nights?

All these questions and more are yours to answer via the attributes, properties, and methods that your elements surface to the public. Take care to respect your parents, but don't think that you have to become a doctor/lawyer/the President just because your mother said you should.

The components are alright

In this way, we might address the following simplification of the DOM we've reviewed through much of this article:



<document>
  <body>
    <h1>Title</h1>
    <other-custom-element>
      #shadow-root
        <a href="#">This is a link</a> <!-- The link _has_ focus -->

When accessing document.activeElement from the outside, again we will be returned other-custom-element in reverence of the constrained control we now have over our once singular document. In this context, we may want to forward a click event into our focused element, however not having direct access to the anchor tag through the shadow boundary, we'd be calling click() on other-custom-element. By default, this type of interaction on the shadow DOM of other-custom-element would be prevented. In the case that we wanted this sort of thing to be possible, we could build the following extension of the click() method into our other-custom-element element to pass the click into its child:



click() {
  this.shadowRoot.querySelector('a').click();
}

But what about the case where there are more than one anchor tags inside of an other-custom-element?



<other-custom-element>
  #shadow-root
    <a href="#">This is a link</a>
    <a href="#">This is also a link</a> <!-- The link _has_ focus -->

In this case, we can take advantage of the activeElement accessor on a shadow root and target the correct anchor tag as follows to make an even more flexible custom element implementation:



click() {
  this.shadowRoot.activeElement.click();
}

From here, there are any number of next steps that you can take to produce your own powerful custom elements that leverage the encapsulation offered by the shadow DOM to structure more nuanced, yet eminently powerful APIs to surface to users of your components. As you find patterns that work well for you, I'd love to hear about them in the comments below. If you're interested in uses of the activeElement property in the wild, I invite you to checkout Spectrum Web Components where we are actively reviewing the use of this and many other practices to power our growing web component implementation of the Spectrum, Abode's design system.

Using JavaScript Mixins The Good Parts

Thomas Allmer — Tue, 18 Feb 2020 12:12:50 +0000

Before we can start using something we need to understand what it is and what we can achieve with it.

What is a Mixin?

A mixin is an abstract subclass; i.e. a subclass definition that may be applied to different superclasses to create a related family of modified classes.

Gilad Bracha and William Cook, Mixin-based Inheritance

Let's take for example Logging. Imagine you have 3 Pages

Red
Green
Blue

              +----------+
              |   Page   |
              +----------+
                |  |  |
     +----------+  |  +-----------+
     |             |              |
+---------+ +-----------+ +----------+
| PageRed | | PageGreen | | PageBlue |
+----+----+ +-----------+ +----------+

class Page {}
class PageRed extends Page {}
class PageGreen extends Page {}
class PageBlue extends Page {}

Now we want to log whenever someone goes on Page Red.
To achieve that we extend Page Red and make a Logged Page Red.

              +----------+
              |   Page   |
              +-+--+--+--+
                |  |  |
     +----------+  |  +-----------+
     |             |              |
+----+----+  +-----+-----+  +-----+----+
| PageRed |  | PageGreen |  | PageBlue |
+----+----+  +-----------+  +----------+
     |
+----+----+
| Logged  |
| PageRed |
+---------+

class Page {}
class PageRed extends Page {}
class PageGreen extends Page {}
class PageBlue extends Page {}
class LoggedPagRed extends PageRed {}

If we want to start logging for PageGreen we have an issue:

we can't put the logic in Page as Blue should not be logged
we can't reuse the logic in Logged PageGreen as we can not extend from 2 sources (even if we could it would mean conflicting info in Red and Green)

What we can do is put it in an "external" place and write it so it can be "mixed in".

               +----------+                +----------+
               |   Page   |                | Logging* |
               +-+--+--+--+                +----------+
                 |  |  |
      +----------+  |  +-----------+
      |             |              |
+-----+----+  +-----+-----+  +-----+----+
| PageRed  |  | PageGreen |  | PageBlue |
|  with    |  |   with    |  +----------+
| Logging* |  |  Logging* |
+----------+  +-----------+

// defining the Mixin
export const LoggingMixin = superclass =>
  class LoggingMixin extends superclass {
    // logging logic
  };

class Page {}
// applying a Mixin
class PageRed extends LoggingMixin(Page) {}
class PageGreen extends LoggingMixin(Page) {}
class PageBlue extends Page {}

With that approach we can extract logic into a separate code piece we can use where needed.

For a more in-depth technical explanation please read Real Mixins with JavaScript Classes.

Why is Deduping of Mixins Necessary?

We now want all logging to the Red, Green, and Blue pages.
Easy enough - as we can now apply the LoggingMixin on the Page itself.

               +----------+               +----------+
               |   Page   |               | Logging* |
               |   with   |               +----------+
               | Logging* |
               +-+--+--+--+
                 |  |  |
      +----------+  |  +-----------+
      |             |              |
+-----+----+  +-----+-----+  +-----+----+
| PageRed  |  | PageGreen |  | PageBlue |
+----------+  |   with    |  +----------+
              |  Logging* |
              +-----------+

However, Team Green was eager to launch, so they already applied LoggingMixin to their Page class. When we apply it to the base Page class, Mixin is now applied twice 😱
Suddenly, the Green page will print each log twice - not what we originally had in mind.

What we need to do is make sure that each Mixin is attached only once even if we try to apply it multiple times.

Generally, the more generic a mixin is, the higher the chance becomes that is gets applied more than once. As a mixin author, you can't control how it is used, and can't always predict it. So as a safety measure it is always recommended to create deduping mixins.

npm i @open-wc/dedupe-mixin

import { dedupeMixin } from '@open-wc/dedupe-mixin';

export const MyMixin = dedupeMixin(
  superclass =>
    class MyMixin extends superclass {
      // your mixin code goes here
    },
);

You can see exactly this situation in the demo.

By applying dedupeMixin to the mixin function, before we export it, we can be sure that our mixin class will only take effect once, even if it is mixed into multiple base classes in the inheritance chain.

no-dedupe "fails" by logging Green two times
with-dedupe "succeeds" by logging Green one time as well

You can check the source code for both on github.

Nested examples

You may think that the above example is too simple and can be solved by aligning on when to do changes.
However, in most real-life scenarios the situation is much more complicated 🙈
Mixins can be extended and just because you import a class it does not mean that this class has some Mixins pre-applied.

Consider this example:

               +----------+               +----------+      +----------+
               |   Page   |               | Logging* |      | Feature  |
               |   with   |               +----+-----+      |   with   |
               | Logging* |                    |            | Metrics* |
               +-+--+--+--+               +----+-----+      +----+--+--+
                 |  |  |                  | Metrics* |           |  |
      +----------+  |  +-----------+      +----------+           |  +------
      |             |              |                             |
+-----+----+  +-----+-----+  +-----+----+                 +------+-------+
| PageRed  |  | PageGreen |  | PageBlue |                 | WaterFeature |
+----------+  +-----------+  |   with   |                 +--------------+
                             | Metrics* |
                             +----------+

Pages generally only need Logging
There is however also more advanced Metrics System which extends Logging
Metrics was separately developed for Features
When we now want to get the same Metrics on Page Blue we get duplicate logging without consciously applying logging even once (we do class PageBlue extends MetricsMixin(Page) {})
Only deduping can help in these scenarios

When NOT to use a Mixin

You may think now "dam that is powerful" and you are right. Should we use it now for everything? Hell, no.

Only use it if you absolutely need access to the instance itself. Here are some bad examples when NOT to use a Mixin.

I want to do `if (this.isIE11()) { // ... }`

For any "pure" function it is better to keep it outside of the class/prototype. e.g. better write it like so

import { isIE11 } from './helpers.js';

if (isIE11()) {}

I want to have a special `this.addEventListener()`

Firstly overriding built-in functions can be really dangerous. When inside your class and when you need to make a very specific use-case happen then it might be ok. However, if that magically happens while using a Mixin it can be very confusing.

Better to have these as an extra function which can pass on this. That way people can opt these special features without "polluting" their prototype chain.

import { specialAddEventListener } from './helpers.js';

specialAddEventListener(this, 'click', () => console.log('clicked'));

Secondly all properties/methods are global to the class/prototype. That means if two mixins use the same name it will clash. Therefore make sure to definitely use specific names for private/protected methods and make sure if you use common names that it is clear from the mixin name/docs.

When to use a Mixin

If you need to have access to the class instance itself. Meaning if every instance may have a different setting.

A valid example could be for example a LocalizeMixin which enables you to set myEl.locale = 'de-DE';. In this case, the Mixin needs to provide and react to this property.

import { dedupeMixin } from '@open-wc/dedupe-mixin';

export const LocalizeMixin = dedupeMixin(
  superclass =>
    class LocalizeMixin extends superclass {
      // this assumes a Mixin for LitElement
      static get properties() {
        return {
          locale: { type: String }
        };
      }

      updated(changedProperties) {
        super.updated(changedProperties);
        if (changedProperties.has('locale')) {
          // react to locale change
        }
      }
    },
);

What we have learned

With Mixins you can bring shared logic into multiple classes. It is a very powerful tool - and with that power comes responsibility. Be sure to use it responsibly and to dedupe your mixins.

Notes

Ascii Graphics made with AsciiFlow
Photo by Vania Shows on Unsplash

Open-wc scoped-elements

Manuel Martín — Thu, 23 Jan 2020 14:39:30 +0000

"Good frontend development is hard. Scaling frontend development so that many teams can work simultaneously on a large and complex product is even harder." (martinfowler.com - micro frontends)

Micro-frontends, as well as micro-services, are gaining popularity. Many organizations are adopting those architectures allowing multiple autonomous teams to work on the same applications without the limitations of large monoliths.

To have visual consistency across micro-frontends, one common approach is to have a shared library of reusable UI components, but basing this library on web components could be a problem in certain situations. We are going to create some dumb components to emulate it, analyze the problem, and see how to fix it.

The context

Imagine we have the first version of a shared component library, containing two components:

feature-a
feature-b

In addition, two pages use those components contained in our shared library. Imagine that each page has been developed by autonomous teams.

Finally, we have the shell app that contains the pages. Once the app is built we will obtain the following node_modules tree.

├─ node_modules
│  ├─ feature-a@1.0.0
│  │  ├─ feature-a.js
│  │  └─ index.js
│  ├─ feature-b@1.0.0
│  │  ├─ feature-b.js
│  │  └─ index.js
│  ├─ page-a@1.0.0
│  │  ├─ page-a.js
│  │  └─ index.js
│  └─ page-b@1.0.0
│     ├─ page-b.js
│     └─ index.js
├─ demo-app.js
└─ index.html

So far so good. Everything is up and running and you can check the application online [see the code here].

The problem

Imagine now the requirement of release a breaking change on feature-a to fulfill new business requirements. A new major version of feature-a would be released.

The team in charge of page A has enough time and budget to update their page and implement the required changes using the latest release of feature-a, but unfortunately, the team in charge of page B has other business priorities before adapting their code to the new version.

As they are independent teams, each one releases their new page versions and the app is built obtaining the following node_modules tree.

├─ node_modules
│  ├─ feature-a@2.0.0
│  │  ├─ feature-a.js
│  │  └─ index.js
│  ├─ feature-b@1.0.0
│  │  ├─ feature-b.js
│  │  └─ index.js
│  ├─ page-a@1.1.0
│  │  ├─ page-a.js
│  │  └─ index.js
│  └─ page-b@1.1.0
│     ├─ mode_modules
│     │  └─ feature-a@1.0.0
│     │     ├─ feature-a.js
│     │     └─ index.js
│     ├─ page-b.js
│     └─ index.js
├─ demo-app.js
└─ index.html

As the user tries to execute the application he/she will find the following error.

Looking at the web console we can read the following message

NotSupportedError: 'feature-a' has already been defined as a custom element

The problem here is that the custom element registry doesn't allow multiple versions of the same element to be registered and we are trying to register two versions of the feature-a component with the same name.

customElements.define('feature-a', FeatureA);

but why is this happening?

ES modules are only executed once per URL so

import 'feature-b/feature-b.js';

in both, page-a/index.js and page-b/index.js, resolves to node_modules/feature-b/feature-b.js so it's going to be executed only once. However, doing

import 'feature-a/feature-a.js'

in page-a/index.js resolves to node_modules/feature-a/feature-a.js
while in page-b/index.js it resolves to node_modules/page-b/node_modules/feature-a/feature-a.js therefore these are separate URLs and feature-a definition will be executed both times.

If you want to dig deeper into how node resolution works you can read this article which explains it very well.

The solution

There are two possible solutions:

Synchronizing updates of shared dependencies across teams. e.g. make sure all teams always use the same version upon release. This can be a viable solution but it comes with high organizational overhead and is hard to scale. I would discard this option because I want to provide value to the user as soon as possible and this option requires extra work from the teams.
Temporarily (!) allow to ship similar source code (most breaking releases are not a total rewrite) and scope them via @open-wc/scoped-elements.

@open-wc/scoped-elements

Recently Open-wc released scoped-elements as an experiment, allowing us to use different versions of the same web-component in a single document. Let's see how we can use it to fix our sample application.

First of all, we have to install @open-wc/scoped-elements.

npm i --save @open-wc/scoped-elements

Once installed, we have to modify our page's components to use it.

// page-a/index.js
import { render/*, html */ } from 'lit-html'; // (1)
import { createScopedHtml } from '@open-wc/scoped-elements'; // (2)
// import 'feature-a/feature-a.js'; (3)
// import 'feature-b/feature-b.js'; (3)
import { FeatureA } from 'feature-a/index.js'; // (4)
import { FeatureB } from 'feature-b/index.js'; // (4)

const html = createScopedHtml({ // (5)
  'feature-a': FeatureA,
  'feature-b': FeatureB,
});

export class PageA extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    render(html`
      <style>:host { display: block; padding: 10px; border: 2px solid #ccc; }</style>
      <h3>I am page A</h3>
      <feature-a></feature-a>
      <feature-b></feature-b>
    `, this.shadowRoot);
  }
}

Let´s see what we did here:

Remove the html function from lit-html because we must use the createScopedHtml provided one instead.
Import the function createScopedHtml from scoped-elements.
Remove the imports that contain the self-definition of the components that we are going to use.
Import the component classes that we want to use inside our component. This is an important step because now FeatureA and FeatureB components are not self-defined anymore.
Use createScopedHtml to indicate how to use FeatureA and FeatureB components inside our component HTML. This function returns another html function that transforms a template literal into a new one replacing the tags used by the developer with the ones defined by the custom elements. Finally, the transformed template literal is going to be processed by lit-html returning a TemplateResult.

We can see that the final result [see the code here] works as expected using two different versions of the same component.

Limitations

But it's not all fun and games. There are some limitations using scoped-elements that are important to understand:

Imported components should not be self-registering.
Every component that contains subcomponents must use `scoped-elements´.
Imported components need to be fully side effect free.
Currently, only lit-html rendering engine is supported.
You can not use tag selectors in CSS, but you could use an id, a class name or even a property instead.
You can not use tag names using javascript querySelectors, but you could use an id, a class name or even a property instead.
You can not use document.createElement to create a scoped element, but there is an open issue to discuss how to improve the API and support it.
Using scoped-elements may result in performance degradation of up to 8%.

As a good practice, loading of duplicate/similar source code (most breaking releases are not a total rewrite) should always be a temporary solution. However, temporary solutions tend to become more permanent, so be sure to focus on keeping the lifecycle of nested dependencies short.

In a nutshell, it is all about stopping components from self-registering and telling them how they should be used. The concept is similar to how Scoped Custom Element Registries is going to work in the future.

Join the conversation

If you like this feature please feel free to join the conversation for feedback, criticism, concerns, or questions.

Disclaimer

scoped-elements is an experimental feature, so use it at your own risk and be sure to understand the previous limitations.

Storybook for web components on steroids

Thomas Allmer — Thu, 28 Nov 2019 20:13:42 +0000

Building a web application is quite a big and challenging task.
As with many big tasks, it makes sense to break them into smaller pieces.
For applications, this usually means splitting your application into multiple separate components.

Once you start doing that you will notice that you have a lot of individual pieces in your hands, and that it can be tough to keep an overview of all these moving parts.

To solve this we have been recommending storybook since quite some time.

The support for web components has always been good (via @storybook/polymer), and it got even better with the recently added @storybook/web-components.

There are however some parts in storybook which are not fine-tuned for developing web components (the open-wc way).

Let's look at some of those points and how we can improve them.

You can follow along in the accompanying github repo

After a typical storybook setup it looks like this

$ start-storybook
info @storybook/web-components v5.3.0-alpha.40
info
info => Loading presets
info => Loading presets
info => Loading custom manager config.
info => Using default Webpack setup.
webpack built b6c5b0bf4e5f02d4df8c in 7853ms
╭───────────────────────────────────────────────────╮
│                                                   │
│   Storybook 5.3.0-alpha.40 started                │
│   8.99 s for manager and 8.53 s for preview       │
│                                                   │
│    Local:            http://localhost:52796/      │
│    On your network:  http://192.168.1.5:52796/    │
│                                                   │
╰───────────────────────────────────────────────────╯
# browser opens

When we compare this to starting a project with npm init @open-wc

$ npm run start
es-dev-server started on http://localhost:8000
  Serving files from '/my-demo'.
  Opening browser on '/my-demo/'
  Using history API fallback, redirecting non-file requests to '/my-demo/index.html'
# browser opens

The most obvious difference is that in one case we have 2 builds of ~8 seconds and in the other, we don't have any.

So why there are 2 builds?

To get an idea about why this might be needed we first need to understand some of the requirements of a universal demo system like storybook.

Excursion universal demo system

Let's assume we are a startup and we are creating a new app.
Our choice of technology is Vue.js. We happily start building our app and soon we see the need of having a demo system to show and work on all these individual components. Go forth they said and we built a demo system for vue.

It could look something like this

just some example code - don't read this as good vue code 😅

<template>
  <div class="hello">
    <h1>{{ msg }}</h1>
    <ul>
      <li v-for="demo in demos" v-on:click="showDemo(demo.name)">{{demo.name}}</li>
    </ul>

    <div v-html="demo"></div>
  </div>
</template>

<script>
  export default {
    name: 'HelloWorld',
    props: {
      msg: {
        type: String,
        default: 'My Demo System',
      },
      demos: {
        type: Array,
        default: () => [
          { name: 'Demo One', content: '<h1>Hey there from demo one</h1>' },
          { name: 'Demo Two', content: '<h1>I am demo two</h1>' },
        ],
      },
    },
    methods: {
      showDemo: function(name) {
        this.demoIndex = this.demos.findIndex(el => el.name === name);
      },
    },
    data() {
      return {
        demoIndex: -1,
      };
    },
    computed: {
      demo() {
        if (this.demoIndex >= 0) {
          return this.demos[this.demoIndex].content;
        }
        return '<h1>Please select a demo by clicking in the menu</h1>';
      },
    },
  };
</script>

The code here shows only the most relevant information
For a demo and more details look in the vue-demo-system folder
You can start it via npm i && npm run serve

Everything works, everyone is happy - life is good.

Fast forward 12 months and we got a new CIO. A new wind is blowing and with it a prosperous opportunity to work on a second app. The breeze, however, demands that this time it is written in Angular. No, problem - we are professionals and off we go working on the new app.
Pretty early we see a similar pattern as before - components everywhere and we need a way to work and demo them individually.
Ah we think that's easy we already have a system for that 😬

We give our best - but the angular components just don't wanna work well together with the vue demo app 😭.

What can we do? Do we really need to recreate the demo system for Angular now?

It seems our issue is that having the demo UI and the component demo on the same page has the unwanted side effect that we can only use the UI system within our demos.
Not very universal that is 😅
Could we split the UI and the demo?

How about using iframes and only communicate via postMessage?
Would that mean each window can do what they want? 🤞

Let's make a simple POC (proof of concept) with

a ul/li list as a menu
an iframe to show the demo

What we need:

We start with an empty menu
We listen to post messages of demos
The iframe gets loaded and the demos inside fires post messages
We then create menu items for each demo
On click on the menu item, we change the iframe url
If the iframe gets a demo to show it updates the html

Here is the index.html

<ul id="menu"></ul>
<iframe id="iframe" src="./iframe.html"></iframe>

<script>
  window.addEventListener('message', ev => {
    const li = document.createElement('li');
    li.addEventListener('click', ev => {
      iframe.src = `./iframe.html?slug=${slug}`;
    });
    menu.appendChild(li);
  });
</script>

Here is the iframe.html

<body>
  <h1>Please select a demo by clicking in the menu</h1>
</body>

<script>
  // Demo One
  if (window.location.href.indexOf('demo-one') !== -1) {
    document.body.innerHTML = '<h1>Hey there from demo two</h1>';
  }
  // Demo Two
  if (window.location.href.indexOf('demo-two') !== -1) {
    document.body.innerHTML = '<h1>I am demo two</h1>';
  }

  // register demos when not currently showing a demo
  if (window.location.href.indexOf('slug') === -1) {
    parent.postMessage({ name: 'Demo One', slug: 'demo-one' });
    parent.postMessage({ name: 'Demo Two', slug: 'demo-two' });
  }
</script>

The code here shows only the most relevant information
For a demo and more details look in the postMessage folder
You can start it via npm i && npm run start

Now imagine that the UI is way more than just a ul/li list and that the demo follows a certain demo format?
Could this be a system which allows the UI and the demo to be written in completely different technologies?

The answer is YES 💪

The only means of communication is done via postMessages.
Therefore the preview only needs to know which postMessage format to use.
Also, postMessage is a native function so every framework or system can use them.

Two builds (continued)

The above concept is what is used by storybook - which means that there are actually 2 applications being run.
One is the storybook UI (called manager) and one is your actual demo (called preview).
Knowing that it makes sense that there are 2 separate builds.

But why is there a build step at all? Why would storybook have such setup?

Let's see what is needed to allow for some code to be run and worked on in multiple browsers.

Excursion shipping code based on browser capabilities

Let's have a small example where we are using private class fields.
This feature is currently at stage 3 and only available in Chrome.

// index.js
import { MyClass } from './MyClass.js';

const inst = new MyClass();
inst.publicMethod();

// MyClass.js
export class MyClass {
  #privateField = 'My Class with a private field';

  publicMethod() {
    document.body.innerHTML = this.#privateField;
    debugger;
  }
}

We deliberately put a debugger breakpoint in there to see the actual code the browser is executing.

Let's see how webpack with a few babel plugins handles it. (see full config)

__webpack_require__.r(__webpack_exports__);
/* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "MyClass", function() { return MyClass; });
function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
function _defineProperties(target, props) {
// ... more helper functions

var MyClass =
/*#__PURE__*/
function () {
  function MyClass() {
    _classCallCheck(this, MyClass);

    _privateField.set(this, {
      writable: true,
      value: 'My Class with a private field'
    });
  }

  _createClass(MyClass, [{
    key: "publicMethod",
    value: function publicMethod() {
      document.body.innerHTML = _classPrivateFieldGet(this, _privateField);
      debugger;
    }
  }]);

  return MyClass;
}();

var _privateField = new WeakMap();

Wow that is quite some code 🙈 and it does not really look like the code written 😱

Note: in most cases you will not see this because of source maps

What happened? in a typical webpack & babel setup your code gets compiled down to es5 in order to be able to run the code also on older browser like IE11.

However, you may ask how often do I actually run my app in an older browser?

A typical developer should probably develop ~90% on a modern browser and ~10% on older browsers to make sure everything still works in order.
At least we hope you have such a nice workflow 🤗

So the question is why compile, ship, debug and work with this "strange" code 100% of the time if it's only needed for 10%?
Could we do better?

Let's see how es-dev-server handles it by opening the same file on chrome.

export class MyClass {
  #privateField = 'My Class with a private field';

  publicMethod() {
    document.body.innerHTML = this.#privateField;
    debugger;
  }
}

It looks exactly as the original code - because it is. The code as is was fully capable of running in chrome without any adjustments.
And that's what is happening it ships the source as is.

However, we are using private class fields which is an unsupported feature for example on Firefox.
What happens if we open it there?

it fails 😭

SyntaxError: private fields are not currently supported

ok, it's our fault as we are using a stage 3 feature and are not doing any compilation now.

Let's try it with es-dev-server --babel which in turn will use the same .babelrc as webpack.

The following code will be generated.

function _classPrivateFieldGet(receiver, privateMap) {
  var descriptor = privateMap.get(receiver);
  if (!descriptor) {
    throw new TypeError('attempted to get private field on non-instance');
  }
  if (descriptor.get) {
    return descriptor.get.call(receiver);
  }
  return descriptor.value;
}

export class MyClass {
  constructor() {
    _privateField.set(this, {
      writable: true,
      value: 'My Class with a private field',
    });
  }

  publicMethod() {
    document.body.innerHTML = _classPrivateFieldGet(this, _privateField);
    debugger;
  }
}

var _privateField = new WeakMap();

And it works 💪
It only compiles the private fields and not everything 👌

However, if you now go back to chrome you will see that it is now compiled there as well.
The reason for it is that once you start going through babel it just does it's thing based on @babel/preset-env and babel is always on the conservative side.

The real magic ✨ happens when you open it on an older browser like IE11.
As then it will compile it down to systemjs, a polyfill for es modules.

It will look something like this

System.register([], function(_export, _context)) {
  "use strict";

  var MyClass, _privateField;

  function _classCallback(instance, Constructor) {
// ...

It will behave exactly like real es modules, so that your code will work just fine on browsers which don't support them 💪

If you are concerned about speed it is best to only rely on stage 4 features and to not use babel at all.
You can if really needed use 2 start commands

"start": "es-dev-server --open",
"start:babel": "es-dev-server --babel --open",

So what es-dev-server auto mode enables is that you don't need to think about it.
It will be instant on modern browsers and will even work in these moments where you have a need to test in older browsers.

To summarize in order to be able to work with and debug code in all the browser we want to support we basically have 2 options.

Compile down to the lowest denominator
Serve code base on browser capabilities

And as always please don't go crazy with new features.
Use what is currently stable and available on your development browser.
You will have the best experience when you do not use a custom babel config.

The code here shows only the most relevant information
For a demo and more details look in the EsDevServer-vs-WebpackDevServer folder
You can start it via npm run start, npm run start:babel and npm run webpack

Source maps

Luckily in most cases, even when working with compiled code you will see the source code.
How is that possible? It's all thanks to Sourcemaps.
They are a way to map the original code to the compiled code and browser are smart enough to link them together and only show you what you are interested in.
As long as the option "Enable JavaScript source maps" is checked in your dev tools.

It is really awesome that it justs works. It is however yet another moving part that may break or you need to know about it at least.

Opportunity

So looking at compilation and shipping of modern code we see a window of opportunity.
We want to have the features of storybook but we also want to have the ease of use of not relying on webpack.

In short, the idea is to marry storybook ui with es-dev-server.

Let's get started 💪

Here is the master plan

Prebuild storybook ui (so we are not forced to use webpack)
Replace webpack magic like require.context
Mimic how the preview communicates with the manager
Use rollup to build a static version of storybook

Storybook on steroids

Prebuild storybook

In order to get an es module version of the storybook preview, it needs to go through webpack & rollup.
Yes, it is a little black magic but that was the only way that worked.
It seems storybook is not yet optimized to have a fully separated manager/preview.
But hey it works and we will collaborate with storybook to make this even better 💪

You can find the source on github and the output is published on npm as @open-wc/storybook-prebuilt.

Prebuilt has the following benefits:

fast
preview can be independent of storybooks build setup

Prebuilt has the following downsides:

you can not change the addons of a prebuilt
you can, however, create your own prebuilt

Replace webpack magic

In the current storybook require.context is used in preview.js to define which stories are loaded.
This is, however, a feature only available in webpack which basically means it is a lock in to a specific build tool.
We would like to free ourself to choose whatever we want so this needs to be replaced.

We opted for a command-line argument.

In short instead of defining where to look for stories in your js you now do it on the command line via

start-storybook --stories 'path/to/stories/*.stories.{js,mdx}'

Doing so allows exposing this value to various tools like koa-middlewares and rollup.

Mimic how the preview communicates with the manager

Now that we can "include/use" the storybook UI (manager) independent it's time to spin up es-dev-server.

For the manager, we create an index.html which boils down to a single import

<script src="path/to/node_modules/@open-wc/storybook-prebuilt/dist/manager.js"></script>

We do some special caching to make sure your browser only ever loads the storybook manager once.

For the preview, it is a little more as we need to load/register all the individual stories as shown in the postMessage example.
The list of stories we will get via the command line argument.

The important bits which end up being used by the browser is a dynamic import of all story files and then calling storybooks configure which will trigger a postMessage.

import { configure } from './node_modules/@open-wc/demoing-storybook/index.js';

Promise.all([
  import('/stories/demo-wc-card.stories.mdx'),
  // here an import to every story file will created
]).then(stories => {
  configure(() => stories, {});
});

Extra mdx support

The upcoming storybook 5.3.x (currently in beta) will introduce docs mode.
A special mode which allows writing markdown together with stories in a single file and it will be displayed on a single page.
You can think of it as Markdown but on steroids 😬

The format is called mdx and allows to write markdown but also to import javascript and write jsx.

We recommend it as the primary way to write documentation about your components.

In order to support such a feature es-dev-server needs to understand how to handle an mdx file.

For that, we added a koa middleware which converts requests to *.mdx files into the CSF (Component Story Format).

It basically means when you request http://localhost:8001/stories/demo-wc-card.stories.mdx and the file look like this on the file system:

###### Header

<Story name="Custom Header">
  {html`
    <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>
  `}
</Story>

it will server this to your browser

// ...
mdx('h6', null, `Header`);
// ...
export const customHeader = () => html`
  <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>
`;
customHeader.story = {};
customHeader.story.name = 'Custom Header';
customHeader.story.parameters = {
  mdxSource:
    'html`\n    <demo-wc-card header="Harry Potter">A character that is part of a book series...</demo-wc-card>\n  `',
};

You can just open your Network Panel and look at the response 💪

Use rollup to build a static storybook

In most cases, you will also want to publish your storybook somewhere on a static server.
For that, we pre-setup a rollup configuration and which does all of the above and outputs 2 versions.

for modern browsers who support es modules and
for all other browsers we ship an es5 version with all polyfills

For more details on how the different versions are shipped from a static server please see the open-wc rollup recommendation.

The code here shows only the most relevant information
For a full demo see the storybookOnSteroids folder
You can start it via npm i && npm run storybook
For the actual source code see @open-wc/demoing-storybook

Verdict

We did it 💪

A fully-featured demo system that

is buildless on modern browsers
starts up lightning-fast
has a prebuilt UI
serves preview code based on browser capabilities
uses es-dev-server under the hood so you can use all its features

And above all, it's just wonderful to see how a completely separate server can power storybook.
The storybook setup is really worth it 👍

You can check it out in the open-wc repo
See a live example at https://open-wc.org/demoing-storybook/
And read the documentation documentation

PS: it's not all roses and rainbows but with that step, we now know that it is possible - further improvements like a smaller preview bundle or separate packages for the mdx transformation will happen at some point 🤗

Future

We hope that this can be a starting point so storybook can directly support other framework servers as well 👍
Even non JavaScript servers could be possible - Ruby, PHP are you ready? 🤗

If you are interested in supporting your frameworks server and you need help/guidance be sure to let us know.

Acknowledgements

Follow us on Twitter, or follow me on my personal Twitter.
Make sure to check out our other tools and recommendations at open-wc.org.

Thanks to Benny and Lars for feedback and helping turn my scribbles to a followable story.

Cover Photo by Nong Vang on Unsplash

`composed: true` considered harmful?

Westbrook Johnson — Thu, 07 Nov 2019 20:05:01 +0000

Disclaimer: it was brought to my attention that in my desire to strike a very click-bait-like pose in reference to a wide field of "considered harmful" articles, that it might too directly call to mind a seminal post in this regard that takes a clear stance in opposition to its subject. While it is absolutely my goal to trick you onto this page with such a title, I won't pretend to have THE definitive stance on almost any subject, let alone on one as rich and varied as event handling. I do hope to strike up a good dialog if you'll join me in one, and find that a shared foundation of knowledge is the best place to get started on one. So, let's begin!

Photo by Toa Heftiba on Unsplash

First of all, what even is composed: true, and when might you use it?

Event.composed outlines whether a DOM event will cross between the shadow DOM in which the event is dispatched into the light DOM in which the element that the shadow root is attached to exists. As you'll find in the MDN article on the subject, "all UA-dispatched UI events are composed" by default, but when you work with manually dispatched events you have the opportunity to set the value for this property as you see fit. So the "what" of composed: true at its simplest is "a way to manage the encapsulation of your event transmission", and the "when" is namely "while working with shadow DOM", a practice that is not exclusive to but has become somewhat synonymous to working with web components; shadow DOM, custom elements, ES6 modules, and the <template> element. Next, we'll review some important concepts before we try to come to a decision about composed: true:

Native DOM events and how they work
Manually dispatched events and their configurations/extensions
The details on Custom Events
The world of events within a shadow root
Composed Events

At that point, we'll all be specialists and we can get into some practices and patterns with DOM events that might be useful in your applications. I'll share some ideas that I've had or used, and I hope you'll do the same in the comments below. Ready to go?

Native DOM Events

Native HTML elements communicate up the DOM tree using DOM events. You might be used to seeing this with elements like <input /> which publish events like change and input or with the <button /> element, where it's common to rely on the click event that it publishes. It might not be immediately clear you are relying on these things, but when applying onclick (native) or onChange (virtual DOM) properties, it is these DOM events on which you are relying under the hood. Knowing that these events are dispatch along the DOM tree, we can choose locations (either explicit or general) at which to listen for them via the addEventListener(type, listener[, options/useCapture]) method that is present on any HTMLElement based DOM node.

These events have two phases; the "capture" phase and the "bubble" phase. During the capture phase, the event travels from the top of the DOM down towards the dispatching element and can be listened for on each of the elements that it passes through in this phase by setting the third argument of addEventListener() to true, or by explicitly including capture: true in an options object passed as the third argument. For example the steps of the "capture" phase of a click event on the <button> in the following DOM structure:

<body>
    <header>
        <nav>
            <button>Click me!</button>
        </nav>
    </header>
</body>

Would be as follows:

<body>
<header>
<nav>
<button>

Then, being a click event, bubbles: true is set by default, so the event would enter the "bubble" phase and travel back up the DOM passing through the above DOM in the following order:

<button>
<nav>
<header>
<body>

At any point in either phase that you are listening for this event, you will have access to the preventDefault(), stopPropagation(), and stopImmediatePropagation() methods that give you powerful control over the events that travel across your application. preventDefault() can most clearly be felt when listening to a click event on an <a href="..."> tag. In this context, it will prevent the anchor link from being activated and prevent the page from navigating. In a way, this is the event asking for permission to do an action, and we'll look at this more closely in conjunction with manually dispatched events. stopPropagation() prevents the event in question from continuing along the DOM tree and triggering subsequent listeners along that path, a sort of escape valve for the event when certain parameters are met. This can be taken one step further via stopImmediatePropagation() which also prevents the event from completing the current step of the phase it is in. This means that no later bound listeners on that same DOM element for the event in question will be called. Returning to the <button> element in the example above, when a click event is dispatched, you could imagine the following completely trivial listeners:

const body = document.querySelector('body');
const header = document.querySelector('header');
const button = document.querySelector('button');
// You can hear the `click` event during the "capture" phase on the `<body>` element.
body.addEventListener('click', () => {
    console.log('heard on `body` during "capture"');
}, true);
// You cannot hear the `click` event during the "bubble" phase on the `<body>` element.
body.addEventListener('click', () => {
    console.log('not heard `body` during "bubble"');
});
// You can hear the `click` event during the "bubble" phase on the `<header>` element.
header.addEventListener('click', (e) => {
    console.log('heard on `header` via listener 1 during "bubble"');
    e.stopPropagation();
});
// You can hear the `click` event during the "bubble" phase on the `<header>` element.
header.addEventListener('click', (e) => {
    console.log('heard on `header` via listener 2 during "bubble"');
    e.stopImmediatePropagation();
});
// You cannot hear to the `click` event during the "bubble" phase on the `<header>`
// element being it is bound later than the previous listener and its use of the
// `stopImmediatePropagation()` method.
header.addEventListener('click', (e) => {
    console.log('not heard on `header` via listener 3 during "bubble"');
});
// You can hear the `click` event during the "capture" phase on the `<button>` element.
button.addEventListener('click', () => {
    coonsole.log('heard on `button` during "capture"');
}, true);

button.click();
// heard on `body` during "capture"
// heard on `button` during "capture"
// heard on `header` via listener 1 during "bubble"
// heard on `header` via listener 2 during "bubble"

The majority of values for bubbles, cancelable (needed to empower preventDefault()), and composed are the same across native DOM events, and in many of those cases the value of composed is true, so it's possible that the browser is already refuting the idea that it could "harmful". However, when working with native DOM events the values for these three properties are also not configurable. To access the power, and responsibility, that comes with being able to do so, you'll need to enter the world of manually dispatched events.

`dispatchEvent()`

So far we've mainly talked about the click event as automatically dispatched by the browser. There is, of course, a whole family of UA-dispatched UI events that can be addressed in the same manner (e.g. animationend/copy/keydown/mouseover/paste/touch, etc.). However, the real fun starts when you take that power into your own hands and start dispatching events on your own creation. For this, the browser supplies us with the dispatchEvent() method that hangs off of anything extended from EventTarget, which includes all of the HTMLElement based collection of DOM elements. For this to do its magic we need to supply it an event to dispatch. We're given a number of events classes to create our new event from (e.g. new Event(), new MouseEvent(), new InputEvent(), etc.), but event just new Event(typeArg[, initDict]) gives us very a wide range of possibilities.

Now, we're ready to dispatch an event.

el.dispatchEvent(new Event('test-event'));

Event dispatched!

The event has a type of test-event, so a listener set directly on the dispatching element will be able to hear it:

el.addEventListener('test-event', (e) => console.log(e.type));
// test-event

You can also listen for this event during the "capture" phase:

const body = document.querySelector('body');
body.addEventListener('test-event', (e) => console.log(e.type), true);
// test-event

But, you won't be hearing it in the "bubble" phase:

const body = document.querySelector('body');
body.addEventListener('test-event', (e) => console.log(e.type));
// ... ... Bueller?

This is because by default a new Event() (as well as all derivative event constructors) have bubbles, cancelable, and composed set to false by default. This is where the optional initDict argument of our event constructor comes into play. When you want to customize the values of these, you'll create your event like so:

const event = new Event('test-event', {
    bubbles: true,
    cancelable: true,
    composed: true,
};

Or however best supports (or least harms? 😉) the use case in question. That means that if you only want your event to be available in the "capture" phase (which literally means it takes half the time for it to run synchronously through your application than if it were to also make a pass through the "bubble" phase) you can leave that out. Don't have an action that you'd like permission to do? You can leave out cancelable, too. Don't have shadow DOM? Decided definitively that composed: true is harmful? It's your rodeo, leave it out!

Preventing Default

Being able to prevent default on a manually dispatched event is awesome. It allows you to structure the actions you dispatch across your application as permission gates. Your event is essentially asking "do I have permission to do this thing?", and whether the answer to that question can be found nearby or far you'll be able to respond to that information as you see fit. Returning to our completely trivial sample DOM:

<body>
    <header>
        <nav>
            <button>Click me!</button>
        </nav>
    </header>
</body>

Our button might want to dispatch a hover event with cancelable: true to ensure that in the current viewing context (as managed in a more central location) is an acceptable one for displaying hover content or making hover related visuals, like maybe certain mobile browsers aught to do so we don't have to tap twice to get the actual link action to work... In this case, the application manager attached to the <body> element will not grant permission to continue with this action:

body.addEventListener('hover', e => e.preventDefault());
const event = new Event('hover', {
    bubbles: true,
    cancelable: true
});
const applyDefault = button.dispatchEvent(event);
console.log(applyDefault);
// false
console.log(event.defaultPrevented);
// true

Not only do we see this pattern in the native anchor tag, but you'll likely have noticed it in the various keyboard events, amongst many others. With cancelable: true you can choose how closely to follow the patterns and practices applied natively by the browser.

The `detail`s on Custom Events

The ability for an event to outline that something did (or is about to) happen is a superpower in and of itself. However, there are cases when we want to know more than can be communicated via access to e.target (a reference to the dispatching element), we want to know it more clearly, or we want the dispatching element to receive access to information only available to the listening element. For this, the off-the-shelf event constructors for native UI events won't be enough. Luckily, we have two really great options to work with when this is the case: new CustomEvent() and class MyEvent extends Event {}.

CustomEvent

new CustomEvent(typeArg[, initDict]) can be used in your application exactly like any of the previous constructors we've discussed and is sometimes discussed as "the" interface by which to create manually dispatched events for its clever naming as a "custom" event. However, the real power that this constructor gives you is the inclusion of the detail property on the initDict. While detail isn't directly writable after you have created the event, it can be set to an object or an array that won't lose identity when being mutated by the listener. This means that not only can you append data to it when dispatching an event, you can also append/edit data in it at the listener, allowing you to use events to resolve the value of data managed higher in your application. Get ready for another trivial example by imagining the following HTML:

<body>
    <header> ... </header>
    <main>
        <section>
            <h1>Resolving title...</h1>
            <h2>Resolving title...</h2>
        </section>
    </main>
</body>

From here text for our <h1> could be resolved a la:

body.addEventListener('title', e => e.detail.tile = 'Hello, World!');
const event = new CustomEvent('title', {
    bubbles: true,
    detail: {
        title: 'Failed to find a title.'
    }
});

h1.dispatchEvent(event);
h1.innerText = event.detail.title;

This all comes to pass thanks to the availability of the detail property on the initDict for new CustomEvent() and the reality that DOM events are synchronous (meaning that by the time the line directly after dispatchEvent() is run, the event will have already traveled every DOM node that its settings and listeners will allow), which can be super powerful.

Extending Event

A very similar, and much more in-depth, form of customization can be had from extending the Event base class. Immediately, this approach allows you to access data that you would hang off of the event without the intervening detail. On top of that, the ability to use instanceof is where this approach really differentiates itself. Returning to the HTML in the example above, let's now resolve the values for both of the headline elements:

class H1Title extends Event {
    constructor(title = 'Failed to find a title.') {
        super('title', {
            bubbles: true
        });
        this.title = title;
    }
}
class H2Title extends Event {
    constructor(title = 'Failed to find a title.') {
        super('title', {
            bubbles: true
        });
        this.title = title;
    }
}
body.addEventListener('title', e => {
    if (e instanceof H1Title) {
        e.title = 'Hello, World!';
    } else if (e instanceof H2Title) {
        e.title = 'We're going places.';
    }
});

const h1Title = new H1Title();
const h2Title = new H2Title();

h1.dispatchEvent(h1Title);
h1.innerText = h1Title.title;

h2.dispatchEvent(h2Title);
h2.innerText = h2Title.title;

Whichever approach you take, using DOM events to pass actual data around your application can be very powerful. It's not a huge step from the trivial example above to a more complete Context API or a DOM bound Redux implementation. Versions of this approach can also serve as an orchestrator for asynchronous actions across your application. For more information on leveraging events in this way, check out this very informative talk by Justin Fagnani:

Side note: all of the events in the above video apply `composed: true`...

Events from the Shadow Root

Up to this point, every event that we have discussed has been dispatched in a document without any shadow roots. Because of this, there have been no extenuating encapsulations to take into consideration meaning unless you were to leverage stopPropagation() or stopImmediatePropagation() on one of those events the "capture" phase would span the entire DOM tree from document to the dispatching element, and when bubbles: true the "bubble" phase would do the same in reverse. When attached to an element, a shadow root creates a sub-tree of DOM that is encapsulated from the main documents DOM tree. As discussed before, the majority of UA-dispatched UI events have composed: true by default and will pass between the sub-tree to the main tree at will. Now that we know how to manually dispatch events, we get to choose whether that is true about the events we create.

Event Retargeting

Before we do that, let's take a look at what happens when an event with composed: true is dispatched within a shadow root, being it will happen a lot (UA-dispatched UI events and all). Take, for example, a click event (which also has bubbles: true by default) as triggered by the <button> in the following DOM tree:

<document>
    <body>
        <div>
            <shadow-root-el>
                #shadow-root
                    <div>
                        <button>
                            Click here!
                        </button> <!-- click happens here -->
                    </div>
            </shadow-root-el>
        </div>
    </body>
</document>

As with an event in the light DOM, the click event here will begin its "capture" phase at the <document>. However, it's here that the first difference between light DOM and shadow DOM events will become clear, the target of this event will not be the <button> element. As the shadow root on <shadow-root-el> is designed to do, it will have encapsulated the DOM inside of its sub-tree and hidden it away from the implementing document. In doing so, it will have retargeted the event in question to the <shadow-root-el> instead.

<document> <!-- event: `click`, phase: "capture", target: `shadow-root-el` -->
    <body>
        <div>
            <shadow-root-el>
                #shadow-root
                    <div>
                        <button>
                            Click here!
                        </button> <!-- click happens here -->
                    </div>
            </shadow-root-el>
        </div>
    </body>
</document>

The event will capture down the DOM tree with these settings until it enters the shadow root where we'll experience the next difference between light DOM and shadow DOM events. The shadow root is the first node in our sub-tree that encapsulates the internals of <shadow-root-el> meaning we are inside of the encapsulated DOM and the internals are no longer obfuscated from us. Here the target will be the <button> element on which the click event explicitly occurred.

<document>
    <body>
        <div>
            <shadow-root-el>
                #shadow-root <!-- event: `click`, phase: "capture", target: `button` -->
                    <div>
                        <button>
                            Click here!
                        </button> <!-- click happens here -->
                    </div>
            </shadow-root-el>
        </div>
    </body>
</document>

From here, the event, still being in its "capture" phase, will continue to travel down the DOM until it reaches its target the <button>. Here it will be available in the "capture" phase. It will also be available as the first step of the "bubble" phase before traveling back up the DOM.

<document>
    <body>
        <div>
            <shadow-root-el>
                #shadow-root
                    <div>
                        <button>
                            <!-- event: `click`, phase: "capture", target: `button` -->
                            <!-- event: `click`, phase: "bubble", target: `button` -->
                            Click here!
                        </button> <!-- click happens here -->
                    </div>
            </shadow-root-el>
        </div>
    </body>
</document>

During the "bubble" phase the same effect of encapsulation that the event experienced in the "capture" phase will be in play. While the target as the event passes the shadow root will be the <button> element, starting at the <shadow-root-el>, the event will be retargeted to that element before continuing to bubble up the DOM.

<document>
    <body>
        <div>
            <shadow-root-el> <!-- event: `click`, phase: "bubble", target: `shadow-root-el` -->
                #shadow-root <!-- event: `click`, phase: "bubble", target: `button` -->
                    <div>
                        <button>
                            Click here!
                        </button> <!-- click happens here -->
                    </div>
            </shadow-root-el>
        </div>
    </body>
</document>

Extended Retargeting

When working with nested shadow roots (e.g. custom elements with custom elements inside of them) this event retargeting will happen at each shadow boundary that the event encounters. That means that if there are three shadow roots that the event passed through the target will change three times:

<body> <-- target: parent-el -->
    <parent-el> <-- target: parent-el -->
        #shadow-root <-- target: child-el -->
            <child-el> <-- target: child-el -->
                #shadow-root <-- target: grandchild-el -->
                    <grandchild-el> <-- target: grandchild-el -->
                        #shadow-root <-- target: button -->
                            <button> <-- target: button -->
                                Click here!
                            </button> <!-- click happens here -->
                    <grandchild-el>
            <child-el>
    <parent-el>
</body>

This is, of course, one of the benefits of the encapsulation that a shadow root can provide, what happens in the shadow root stays in the shadow root, or at least appears that way.

The Composed Path Less Traveled

There are times when we need a look into that dirty laundry to get a peek at just where that event came from, be it <button>, <div>, <a>, or something else (it's hopefully a <button> or <a>...a11y, people!), and for those times we've got the composedPath() method on our events. At any point in the event's lifecycle, calling composedPath() on that event will give you an array of all the DOM elements on which it can be heard. The array is listed in "bubble" order (even when bubbles: false), so the zeroeth item will be the dispatching element and the last item will be the last element through which the event will pass. That means you can always use the following code to ascertain the original dispatching element and outline the path along which the event will trave, assuming the previous example HTML:

const composedPath = e.composedPath()
const originalDispatchingElement = composedPath[0];
console.log(composedPath);
// [
    button,
    document-fragment,
    grandchild-el,
    document-fragment,
    child-el,
    document-fragment,
    parent-el,
    body, html,
    document,
    window
]

It's here in composedPath() that the effects of composed: true are most clearly felt. When an event has composed: true that path will start from the original dispatching element all the way to the window that holds the entire document, but when an event has composed: false that path will end at the shadow root that contains the dispatching element.

Decomposing an Event

As we've seen so far, what composed: true does for an event is make it act as much like a native DOM event as possible by allowing its "capture" phase to start at the very root of the document (as well as across intervening shadow boundaries) and travel into the shadow DOM sub-tree where the original dispatching element lives before allowing the "bubble" phase to do the same in reverse. Along that path, the event will be further affected by the shadow roots that it passes through by having itself retargeted to the element on which that shadow root is attached. There is one more place where a composed: true event in a shadow root will perform differently than when not in one. composed: true allowing that event to cross the shadow root, it will fire (as if in the "bubble" phase, but without traveling up the DOM) on the element to which the shadow root is attached. That means (referencing the DOM below) that while a composed: true, bubbles: false event that was dispatched on <event-dispatching-element> would pass through all of the elements in the following code during the "capture", only the <shadow-root-el> would experience that event during the "bubble" phase.

<div>
    <shadow-root-el>
        #shadow-root
            <section>
                <div>
                    <event-dispatching-element>

So, it's really composed: false that gives us new and interesting functionality.

When an event is dispatched with composed: false then that event will be contained within the shadow root in which it is fired. Right off, for the speed-obsessed developers reading this, that means your events will go faster! Whereas {bubbles: false} can double the speed of an event by completely cutting off the "bubble" phase (read half of the traveling required of an event), {composed: false} could cut that distance all the way down to two stops, the dispatching element and the shadow root that contains it, assuming such a simplified DOM tree. Code speed is likely not the concern here, even if it is worth noting. What's really of most interest is access. When an event is dispatched with composed: false only the ancestor elements encapsulated in the same shadow root have access to it.

Yes, not only does shadow DOM allow you to encapsulate your CSS, DOM, and javascript, it will contain your events for you as well essentially making the element a closed application ecosystem. Within your sub-tree you could dispatch any number of events, with as simple (as affords the contained scope) or complex (as affords their lack of being public) event names as you'd like, process them as needed internally, and then only when needed (or ready) dispatch a new, clearly documented, and explicitly packaged event into the parent scope. That parent scope could also be a shadow tree, and it can then do the same with the various events dispatched there. Turtle this approach all the way up and it becomes very clear how shadow DOM really empowers the reuse of components through this encapsulation. composed: false is the private fields of DOM events.

The Responsibility Part

So, what are we to make of all this power? And, what sort of trouble can it get us in? After all, the premise behind such a broad assertion as "composed: true is harmful" is that it will, after a turn, get us in trouble.

My path towards examining this danger started with a conversation around the minutia that marks the difference between handing events via a passed callback and doing so via a listener. With a passed callback, you know that there is work that you need to do:

const doWork = () => console.log('Do work.');

And you pass it into the element that needs to do that work.

const primaryButton = ({onClick}) => html`
    <button @click=${onClick}>Primary Button</button>
`;

render(primaryButton({onClick: doWork}), document.body);

In this way you can pass this callback from a great distance if you need:

const doWork = () => console.log('Do work.');

class PrimaryButton extend LitElement {
    static get properties() {
        return {
            onClick: { type: Function, attribute: false}
        };
    }
    render() {
        return html`
            <button @click=${this.onClick}>Primary Button</button>
        `;
    }
}

customElements.define('primary-button', PrimaryButton);

class Card extend LitElement {
    static get properties() {
        return {
            doWork: { type: Function, attribute: false}
        };
    }
    render() {
        return html`
            <div class="card">
                <h1>Something</h1>
                <p>Some stuff...</p>
                <primary-button .onClick=${this.doWork}></primary-button>
            </div>
        `;
    }
}

customElements.define('custom-card', Card);

class Section extend LitElement {
    static get properties() {
        return {
            doWork: { type: Function, attribute: false}
        };
    }
    render() {
        return html`
            <section>
                <custom-card .doWork=${this.doWork}></custom-card>
            </section>
        `;
    }
}

customElements.define('custom-section', section);

render(html`<custom-section .doWork=${doWork}></custom-section>`, document.body);

But, in the end, the work is done AT the site of the event. In this way, even if you know work might need to be done high up in your application, you use a templating system (in the above example lit-html via LitElement, but attainable via myriad virtual DOM systems as well) to pass that action down to the event site. This approach works perfectly with composed: false because with the callback passed into the <primary-button> element only the <button> element therein really needs to know about the event that is being dispatched. However, we've just learned the click events (and most other default UI-events) are dispatched with composed: true, so that means we could also do the following:

const doWork = () => console.log('Do work.');

class PrimaryButton extend LitElement {
    render() {
        return html`
            <button>Primary Button</button>
        `;
    }
}

customElements.define('primary-button', PrimaryButton);

class Card extend LitElement {
    render() {
        return html`
            <div class="card">
                <h1>Something</h1>
                <p>Some stuff...</p>
                <primary-button></primary-button>
            </div>
        `;
    }
}

customElements.define('custom-card', Card);

class Section extend LitElement {
    render() {
        return html`
            <section>
                <custom-card></custom-card>
            </section>
        `;
    }
}

customElements.define('custom-section', section);

render(html`<custom-section @click=${doWork}></custom-section>`, document.body);

In the above example, we listen for the event, which is possible because the click event has composed: true by default. In theory, both samples of code output the same user experience, but that isn't true. While the passed callback example will ONLY call doWork when the <button> element in the <primary-button> element is clicked, the listening example will do so AS WELL AS calling doWork when any other part of the <custom-section> element is clicked: the <p>, the <h1>, the <div>, etc. Here is the source of "composed: true considered harmful". While the composed: true event allows you to listen more easily to the event in question, it also hears a lot more than you might be expecting when opting into the practice. Via the passed callback approach you could also go one step further with your callback, leverage the stopPropagation() method we discussed and prevent DOM elements that would naturally be later in the event lifecycle from hearing the event:

const doWork = (e) => {
    e.stopPropagation();
    console.log('Do work.');
}

We're feeling safe now, aren't we!?

Non-standard Events

A click event, and generally all MouseEvents, is pretty powerful in this way: they can happen everywhere. Without passing a callback, you would be forced to rely on event delegation to contain the effects of such broadly felt/originated events. While this may seem powerful (and is leveraged in a very popular synthetic event system), it inherently breaks the encapsulation provided by the shadow DOM boundaries outlined by our custom elements. That is to say, if you have to know that <custom-section> has a <custom-card> child that subsequently has a <primary-button> child that then has a <button> child, in order to respond to a click then why have encapsulation, to begin with? So, composed: true is harmful, after all? I want to hear your thoughts below, but let's also take the following into account. When we manually dispatch events, we get to decide what those events are called.

Our non-standard events, whether they're made via new Event('custom-name') or new CustomEvent('custom-name') or class CustomNamedEvent extends Event { constructor() { super('custom-name'); } }, are completely under our control. This means we no longer have to worry about the generic nature of the click event and can use a custom naming system to dispatch more specific (e.g. importing-thing-you-care-about) event names. By this approach, we get back a good amount of control over our response to an event:

render(html`<custom-section @importing-thing-you-care-about=${doWork}></custom-section>`, document.body);

In this context, we can be fairly certain that nothing but what we expect to dispatch the importing-thing-you-care-about event will be doing so. By this approach, we can listen from a distance, and be sure that only the element that we expect to dispatch an event is doing so, without having to resort to techniques like event delegation. Maybe that means we've been confusing composed: true for "event delegation" this whole time... Does it make the use of composed: true in this case safe? This starts to come down to the specific needs of your application.

Recap

DOM events are very powerful (even when only looking at the bubbles, cancelable, and composed settings as we have today) and can be leveraged for any number of things in an application.
- bubbles controls whether the event enters the second half or "bubble" phase of its lifecycle
- cancelable allows for preventDefault() to send an approval signal back to the dispatching element
- composed decides how the event relates to shadow DOM boundaries
If you've worked with these events before (whether in shadow DOM or not) you're likely accustomed to the way that almost all of them include composed: true by default.
composed: true opens the event to being listened for at a distance, so the naming of that event becomes more important.
When passing a callback into a component for an event, composed: false can give fine-grained control over an application's ability to react to that event.

`composed: true` considered harmful?

With all this new knowledge, what do you think, should composed: true be considered harmful? Is the browser killing us with a thousand cuts by setting all UA-dispatched UI events to composed: true by default? It may be that composed: true is for "apps" and composed: false is for "components"...but, where do we draw the line? While I've used both values of composed in my own manually dispatched events, I'd say that I've fallen on the side of composed: true more often than not, though namely through lack of introspection than through a presence of planning. After walking through all of the above, it's hard to say one is specifically better/more dangerous than the other. If you've taken the time to watch the very informative video above, you'll have seen a plethora of quality use cases for composed: true when building for the web. Maybe composed: true isn't harmful after all? One thing I am sure of is, like most technical decisions, the value you set for composed should be decided based on the specific needs of your application and/or the offending component in question. However, my experience is just that, my experience. I'd love to hear about yours! Please hop into the comments below and share whether you've been harmed by composed: true and how.

Want to do more research?

Still wrapping your brain around what all this looks like? I've put together an event playground where you can test the various settings and realities we've discussed so far:

While the design therein could certainly be considered harmful, hopefully, it'll give you a more clear understanding of the settings that can be applied to events and how that affects the way those events travel around the DOM. Take note that each DOM element that hears an event will say so, along with the phase during which it heard the event, what step in the path of the event it passed through that element and the target element at that point next to the original dispatching element. I use manually dispatched events pretty liberally across my applications and shadow DOM-based components, and putting this little ditty together went a long way to cementing my knowledge of DOM events (and surprised me in a couple of spots, too), so hopefully, it helps you too. As you get deeper into your studies, if you remix the project to help outline your thoughts on composed: true, please share them with us all in the comments below.

Epilogue: originally this post had a reading time of 3 minutes, I swear! I thought, get in, get out, get people talking about important things. Cooler heads pointed out that DOM events are not a simple subject and the knowledge base of even seasoned users (myself included) can be bumpy, so I expanded. That being so, there is a lot of information here, so if you think I've missed something somewhere, please let me know! I intend to smooth out the bump knowledge, not make it worse, and your help in that endeavor would be much appreciated. I'd also like to thanks the Open Web Components team for being those cooler heads and putting some hard-fought editing into this article.

Forem: Open Web Components

Some things to know about Lit

Default Values

So you like Typescript?

Required properties

Event management

styleMap usage

Conclusion

Let's Build a Colour Picker Web Component

Contents

Prerequisites

Lets Build Web Components! Part 1: The Standards

Benny Powers 🇮🇱🇨🇦 ・ Sep 18 '18

Setting Up

Defining our Element

Styling our Element

Shadow CSS Q-and-A

:host

ID Selectors (e.g. #loupe)

CSS-in-JS, BEM, etc.

Color Picker Styles

Tracking the Mouse with a Reactive Controller

Reusable, Composable Controllers

Adding Controller Support to our Element

LitElement: A Deepdive Into Batched Updates

Pascal Schilp for Open Web Components ・ Dec 3 '20

Hooking up the Cursor

Firing Events

Accessibility

Using our Colour Picker

Next Steps

bennypowers / controller-host-color-picker

Color Picker Web Component With Reactive Controller

Contents

Prerequisites

Footnotes

Inherited Styles

Introducing: Custom Elements Manifest

Example

Potential Usecases

Documentation and demos

Framework Integration

Avoiding breaking API changes in minor or patch versions

Linting

Cataloging

Much, much more!

How should I use a Custom Elements Manifest?

🛠 The Tools

@custom-elements-manifest/analyzer

Plugins

Concluding

Doing a FLIP with lit-html@2.0

My directives to date

Spreading it on thick

The endless stream of time

Element expressions

Let's do a FLIP

Or, rather, a ${flip()}

How's it work?

When items are the same but not the same...

When are the items not there at all?

When your users aren't ready to do a ${flip()}

What else does it do?

What else could it do?

What do you think?

LitElement: A Deepdive Into Batched Updates

Introduction

Batching

THE EVENT LOOP!

Deferring promises

Back to LitElement

🧙‍♂️ Automagically requested updates

Objects and arrays

Back to batching updates

Taking things a step further

Back to web components land

Introducing mdjs - interactive demos everywhere

For tools that do not run in the browser

For (visual) components that do run in the browser

Vue

`:host`

ID Selectors (e.g. `#loupe`)

`@custom-elements-manifest/analyzer`

Or, rather, a `${flip()}`

When your users aren't ready to do a `${flip()}`

Out of the shadows a new `document` rises...

I want to do `if (this.isIE11()) { // ... }`

I want to have a special `this.addEventListener()`

`dispatchEvent()`

The `detail`s on Custom Events

`composed: true` considered harmful?