DEV Community: Westbrook Johnson

Testing with JS is like magic, but is it science?

Westbrook Johnson — Sat, 16 Sep 2023 15:34:55 +0000

If that title doesn't get you riled up, I know what will...

Last time on "Testing Web Components"

That's right, a recap!

If you haven't read the first installment of Testing Web Components with @web/test-runner, go do it now... I'll wait... If you just did, or you had previously, here are some fun things to have at the top of your mind before digging into today's episode:

you can quickly generate a new web component repo with Open-WC
the generator has a whole lot of options, but specifically, we're cooking with "Testing (web-test-runner)" and Typescript
the web component generated thereby is powered by Lit and leverages many of its decorators
by default, it tests a few things intrinsic to the generated element, but mostly you'll be replacing that functionality with your own

...and that's where we come in!

Testing with JS

I can hear you now:

What do you mean, all of my JS tests are in JS, what's so magic about it?

To which I'd respond, with a voice of disbelief, "You're testing JS with JS, what isn't magic about it?"

Then I'd remember that if you lived in my head already and knew all the jokes, you'd likely not be reading by this point. But, you're here, so I'll point out that I'm not talking about "magic"; that amazing, powerful stuff of lore that saves the heroine in your favorite story. I'm talking about "magic"; the thing that isn't real. Yes, testing your JS with JS isn't real. Or, it isn't real for at least half of your consumer types, which likely represent an overwhelmingly large percentage of your actual consumers. That is the consumers that actually visit the page or application that you are building.

To understand what I mean, let's revisit one of the tests that we've been bequeathed by the Open WC Generator.

it('increases the counter on button click', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);
  el.shadowRoot!.querySelector('button')!.click();

  expect(el.counter).to.equal(6);
});

In this test, we confirm that "clicking" the <button> within the shadow root of the <testing-components> element causes the counter property on our element to equal 6.

This is an extremely common approach to interacting with the UI at unit testing time with JS.

Interacting with the UI

.click() is a powerful part of the web API. It allows a developer to "simulate" the click segment of a pointer interaction (possibly the most common segment) from the JS context. In this way, it can be a great way to guarantee the developer API that you surface with code.

However, it's not real.

How do I know it's not real? Well, when was the last time you saw a visitor to your site or application type el.click() into the console of their browser's DevTools? You, me, and our developer friends at debug time don't count here!

This is a version of what's called "mocking". Mocking can be an important part of unit testing as it allows you to isolate the unit under test. This means that you can ignore inputs, side effects, and other realities applied to your unit by other contexts when testing that unit. When testing UI interactions, whether and how to mock the human that will be interacting with your UI will always be important to work out.

Some testing libraries look to mitigate this by more expansively mocking the interaction. You should definitely spend some time deciding whether the work going on here is something you think your testing needs, but, in a quick overview, some of the things being handled here are:

possibly moving the pointer
deciding whether the pointer should be released before starting a new interaction
pressing down the pointer on a new (or the last) position
possibly releasing the pointer again
managing interaction with the "carat", which I couldn't 100% tell you what is in this context

Luckily, this complexity is then hidden under helper methods because no one will remember to do all this every time they want to better mimic a .click().

Is there something better?
— exasperated unit tester

Well, @web/test-runner offers a Commands API that supports you making requests to the browser runner of your tests from the JS test context. At a high level, this means that you can ask the browser runner (e.g. Playwright, Selenium, etc.) that you leverage at test time to act on the test context as if it actually were a person interacting with the page. By doing so, you can trigger things like:

pointer interactions (hello, .click(), but better!)
keyboard interactions
interact with <select> menus (their default UI is outside of the browsing context)
resize the window
and, more!

For a .click(), this looks a bit like the following:

await sendMouse({ type: 'move', position: [x, y] });

Looks pretty awesome, right? Well, that's not what we're going to be diving into today, sorry. In the next couple of installments, we'll take deeper looks at a number of these commands, and how you can write your own!

For today, we're going to dive into the developer API that your newly generated custom element surfaces, and you're gonna like it.

Interacting with the developer API

As mentioned above, .click() is one way to surface interactions on your element to your developer consumers. In that way, this test could be 100% real, and actually magic (the amazing kind). In this context, however, it's not.

The offending code in this case is .shadowRoot!. While .click() can be a powerful API for consuming developers, if you're testing such an API on an element that a developer shouldn't have access to (any in the shadow DOM), then it's not real.

Using shadow DOM on an element encapsulates the contents of that shadow root from selectors from the parent application or component. This is why we can't use el.querySelector directly to access this button. Not being able to do so, means that a consuming developer will not be able to do so as well. So, while reaching through the .shadowRoot! may be a way to complete the coverage play of a component's unit tests, it's not something that actually guarantees actual API that any of your consumers would actually leverage.

With this in mind, our test development cycle might go one of a couple of different ways. You could:

say, "Output says the lines are covered, I'm going home", and you'd not be wrong.
leverage the commands from above and close over the API to external developers by only testing as a visitor and not as a developer consuming your component.
or, start a refactor party and look at what would be needed to make this API available to a developer.

Before you take the path of most resistance, ask yourself "As a developer would I want this capability to be surfaced in some way?". If the answer is "yes", then hopefully wanting it points you towards a path of how you'd want it surfaced, but if not, keep reading for some thoughts on what that might mean.

The developer API

Sometimes a developer API is already available on the surface of your custom element, you just have to hold it right. Let's revisit our test to see if that might be appropriate here:

it('increases the counter on button click', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);
  el.shadowRoot!.querySelector('button')!.click();

  expect(el.counter).to.equal(6);
});

What does "increases the counter on button click" mean, again:

we load the element
we find and click the button
the counter equals 6

Ignoring for the moment the lack of precision as to how much the counter is increased, or coverage of what the counter should be by default (that's technically addressed in a previous test in our generated code), the operative word here is that a button clicked increases the counter. This test is 100% for end consumers of your element. What might it be called if we were testing these capabilities for a developer consumer?

counter can be set?
counter can be increased?
element can be clicked?
something else?

Let's look at how we might build these tests and refactor our element to support them.

`counter` can be set

it('`counter` can be set', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);
  el.counter = 6;

  // This isn't really a test of the side effects of the counter being set, so wouldn't be my first choice.
  expect(el.counter).to.equal(6);
});

This test confirms that not only is counter a getable property as confirmed in 'has a default title "Hey there" and counter 5' and the original version of 'increases the counter on button click', but it is also settable. Being this property leverages the @property decorator from Lit, I can tell you for sure that it does have a setter, though our tests certainly hadn't guaranteed that previously. So, we'd be adding robustness to the generated code if we chose to add something like this. I would say that testing a setter with its getter might leave something to be desired. Once we get deep into them in subsequent articles, confirming that the new value of counter is leveraged by the rendered DOM via snapshot testing (not my favorite, I'll share more about that later) or actually rendered to the page via visual regression testing (key for UI libraries) would be a valuable extension of the test here.

`counter` can be increased

it('`counter` can be increased', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);
  // The API doesn't currently exist on the element but could be surface as a public method for developers and leveraged within the click callback.
  el.increaseCounter();

  expect(el.counter).to.equal(6);
});

"Increased" here is playing fast and loose with the context of the original test. "increases the counter", as the only spec for the element, implies (in a way that is played out in the definition of the custom element) that you can only increase the value of counter. If this were true, I might also suggest you cover over the setter of counter to prevent developer consumers from decreasing the value of counter. For now, we'll just go with increasing being the only thing we can do.

Based on this assumption, the right thing might be just to surface the internal __increment() method in a public manner. For brevities sake, we could rename it increaseCounter, as seen in the test:

-   __increment() {
+   increaseCounter() {

Then we'd refactor the click handler to leverage the same:

-       <button @click=${this.__increment}>increment</button>
+       <button @click=${this.increaseCounter}>increment</button>

And, then we'd be back to passing tests.

element can be clicked

Rather than requiring a consuming developer to find a specific element to click on, where you are sure that this was the only clickable functionality in your element, you might be better off by surfacing a custom click() method directly on your custom element. This can be tested as follows:

it('element can be clicked', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);
  // This API is also not currently available, but by abstracting the idea of what clicking the element does you may be setting down a path where it does many things.
  el.click();

  expect(el.counter).to.equal(6);
});

The refactor to make this possible is only a few steps in this case:

add the click() method
on, just one step, I guess

+   click() {
+     this.__increment();
+   }

Ship it!

This means that you are binding your custom element to a singular action at click time, so be sure this is what is actually intended for the functionality that you are shipping, but, if so, you're on your way to version 1.0!

something else

All of these, and more, could serve your developer consumers by ensuring the API contract that you surface to them at unit test time. Within each is a sea of nuance that can be navigated more appropriately with the deeper knowledge of your goals that only you can bring to the discussion.

Should your custom element support the https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md as a path to developer interaction?
Should a more proprietary state interface be surfaced? Web components and Lit pair quite nicely with popular projects like Mobx, Redux, XState, and on and on.
Should you devise a purpose-built custom events API for orchestrating imperative cross-DOM interactions? (Probably not..but, you could.)
Should a similar approach to increaseCounter() above be leveraged against a more specific method name clarifying the internal reaction to the state change?

Only you can answer these questions. However, what's great about code is that if you can imagine it then with the right amount of time you can code it, so go wild!

Being less "magic" and more "amazing"

Focusing your approach to testing on how the actual consumers of your code will interact with that code is an important part of ensuring that the work you do is less magic (the not real kind). The less magic in your tests, the more predictable your work will become. Contrary to popular belief shipping simple, dependable, well-tested features is much more amazing for you consumers than something that could disappear right in front of them.

Above we've learned about some refactoring strategies that our testing cycle can point us towards as we work to make our API contracts simpler, more dependable, and more likely to support our developer consumers to amazing results. Next time, we'll get back to our UI-first consumers and how we can better embody them at test time, as well. Specifically, we'll focus on the Commands API from @web/test-runner and ways to more accurately mock pointer interactions with your code. See you then!

Enter, it screams... I mean, it streams

Westbrook Johnson — Fri, 28 Jul 2023 14:31:12 +0000

Have you ever thought to write an event listener like the following?

const button = document.querySelector('button');

button.addEventListener(
    'click',
    () => {
        console.log('click');
    }
);

And then, gotten reports that the actual work that you listed (please don't ship console.log() statements to production) was happening way too often?

Maybe you wrote your listener like this, and got similar reports?

const button = document.querySelector('button');

button.addEventListener(
    'keydown',
    ({ code }) => {
        if (code === 'Enter') {
            console.log('Enter'));
        }
    }
);

If you've already caught the context, don't ruin the surprise...

Keyboard-based interactions

To mimic pointer interactions when navigating an application with the keyboard, when the Space key is pressed and a <button> element is in focus, the keyup event from that interaction is duplicated as a click event. Similarly, the keydown event (or keypress event, if you're into deprecated APIs) on the Enter key, in the same situation, will be duplicated as a click event.

However, the Enter key is special. The Enter key screams...I mean, streams its keydown event. That means as long as a visitor has their Enter key down the keydown event, which usually is tightly coupled to when the key goes down, will continue to fire. This means that our keydown listener AND the click listener in the above code sample will stream as well.

My own haunted house

I was recently surprised by this reality when a listener like this that I have bound threw focus into a different element that also had a listener like this bound, which subsequently through focus back into the first element and created a loop 😱

const button1 = document.querySelector('button.one');
const button2 = document.querySelector('button.two');

button1.addEventListener(
    'click',
    () => {
        button2.focus();
    }
);

button2.addEventListener(
    'click',
    () => {
        button1.focus();
    }
);

Normally, the event listeners worked exactly as planned, but then came the bumps in the night... luckily, I have great coworkers that helped catch this use case at code review time, before it went live to users. 😅

Enter at your own risk

Maybe yelling the event listener at your visitor is the right thing to do in the context of your application, but, if it is not, key this reality in mind to ensure that your application delivers the expected experience.

If you're interested in coalescing the interaction with the Enter key to a one-time event, you might be interested in the keyup event:

const button = document.querySelector('button');

button.addEventListener(
    'keyup',
    ({ code }) => {
        if (code === 'Enter') {
            console.log('Enter'));
        }
    }
);

If you're actually working with a click event, you may want to do a more complex form of gating:

let enterKeydown = false;

const button = document.querySelector('button');

button.addEventListener(
    'keydown',
    (event) => {
        if (event.code === 'Enter') {
            if (enterKeydown) {
                event.preventDefault();
            }
            enterKeydown = true;
        }
    }
);

button.addEventListener(
    'keyup',
    (event) => {
        if (event.code === 'Enter') {
            enterKeydown = false;
        }
    }
);

button.addEventListener(
    'click',
    () => {
        console.log('click');
    }
);

Or, maybe you have an alternative way to not scare your visitors? If so, share it in the comments below! I'd love to hear what you've been doing to prevent the Enter key from screaming at anyone who has to listen to your application.

Testing Web Components with @web/test-runner

Westbrook Johnson — Thu, 16 Mar 2023 19:12:00 +0000

So, you write web components and you're interested in expanding the work you put into unit testing them? Well, you've come to the right place. This is just the beginning, but Testing Web Components: the Series is going to lay out for you how Open Web Components and Modern Web help you to do just that. We'll start with how the Open Web Components generator can get you up and running in no time with @web/test-runner right out of the box.

While the component and tests that come with the generator are a great place to get started, in future posts we'll dig even deeper into what it means to test your web components in real browsers. Along the way, we'll focus on several realities around unit testing web interfaces, like:

the capabilities (and limitations) of testing UI from the JS thread
how you can test more like a user will consume your component, whether that's with a mouse, a keyboard, or a little slower the normal JS execution time
what sort of accessibility guarantees you can test at unit time
and more...

Before we get started

To prepare, let's take a look at the component that comes with the Open Web Components generator and the tests that are already written for it. To get started run npm init @open-wc@latest in your terminal. Be aware that npm init has a pretty sticky cache. If you've run the command before, the inclusion of @latest will ensure you get the most current output. We'll be scaffolding a new project, in which we will build a web component, to which we'll want to add testing, all of which we'll do in Typescript, and will call our component testing-components. If you give the generator permission to write this content to disk and install dependencies with NPM, the terminal output should look like the following:

npm init @open-wc@latest
Need to install the following packages:
  @open-wc/create@0.38.69
Ok to proceed? (y) y

        _.,,,,,,,,,._
     .d''           ``b.       Open Web Components Recommendations
   .p'      Open       `q.
 .d'    Web Components  `b.    Start or upgrade your web component project with
 .d'                     `b.   ease. All our recommendations at your fingertips.
 ::   .................   ::
 `p.                     .q'
  `p.    open-wc.org    .q'
   `b.     @openWc     .d'
     `q..            ..,'      See more details at https://open-wc.org/init/
        '',,,,,,,,,,''


Note: you can exit any time with Ctrl+C or Esc
✔ What would you like to do today? › Scaffold a new project
✔ What would you like to scaffold? › Web Component
✔ What would you like to add? › Testing (web-test-runner)
✔ Would you like to use typescript? › Yes
✔ What is the tag name of your web component? … testing-components

./
├── testing-components/
│   ├── .vscode/
│   │   └── extensions.json
│   ├── demo/
│   │   └── index.html
│   ├── src/
│   │   ├── index.ts
│   │   ├── testing-components.ts
│   │   └── TestingComponents.ts
│   ├── test/
│   │   └── testing-components.test.ts
│   ├── .editorconfig
│   ├── .gitignore
│   ├── LICENSE
│   ├── package.json
│   ├── README.md
│   ├── tsconfig.json
│   ├── web-dev-server.config.mjs
│   └── web-test-runner.config.mjs

✔ Do you want to write this file structure to disk? › Yes
Writing..... done
✔ Do you want to install dependencies? › Yes, with npm

Now, if you run cd testing-components to get into the generated project, and open the directory in your editor of choice, we'll dive into what's been created for you.

The generated project

The first thing you'll notice are the choices from the Open Web Components generator that we didn't adopt; Linting (eslint & prettier) and Demoing (Storybook). As they aren't specifically germane to actually testing our web component, I've left them out of the repo as generated for this article, but that doesn't mean you have to do so. Whether you chose to include them now, or you choose to "Upgrade an existing project" later, these things won't specifically get in the way, but in a world where everything happens 90 miles a minute, it can be useful to start with some focus.

Then, you'll see what we did include:

the demo directory holds a very simple index.html that is served by @web/dev-server via the npm start command, if you'd like to check out the web component that comes stock with the generator in action
the dist directory holds the JS output from running tsc against our Typescript source, this command is included before almost all other scripts you may choose to run, so you shouldn't ever need to do so directly
the src directory holds our web component which is broken into an index.js re-exporting the class definition exported from TestingComponents.ts as well as testing-components.ts that specifically registers that same class as the testing-component custom element name
the test directory with one test file, testing-components.test.ts, that can be run via the npm test command

Don't let me stop you, now. I know you want to see for yourself, "will it blend?". Give npm start a run... you'll get something like:

The initial output of our `` element, saying "Hello owc World! Nr. 5!" with a button that says "Increment"

You can also give the tests a blend with the npm test command. If all things have gone as planned the output should be:

npm test

> testing-components@0.0.0 test
> tsc && wtr --coverage


dist/test/testing-components.test.js:

 🚧 Browser logs:
      Lit is in dev mode. Not recommended for production! See https://lit.dev/msg/dev-mode for more information.

Chrome: |██████████████████████████████| 1/1 test files | 4 passed, 0 failed

Code coverage: 100 %
View full coverage report at coverage/lcov-report/index.html

Finished running tests in 9s, all tests passed! 🎉

So, we've got a pretty minimal web component and four passing tests. Let's dig in a little further to see what have we gotten for our trouble and what is actually under test by default here.

The `<testing-components>` element

There's not much to our <testing-component> element, but here it is in all of its glory:

import { html, css, LitElement } from 'lit';
import { property } from 'lit/decorators.js';

export class TestingComponents extends LitElement {
  static styles = css`
    :host {
      display: block;
      padding: 25px;
      color: var(--testing-components-text-color, #000);
    }
  `;

  @property({ type: String }) header = 'Hey there';

  @property({ type: Number }) counter = 5;

  __increment() {
    this.counter += 1;
  }

  render() {
    return html`
      <h2>${this.header} Nr. ${this.counter}!</h2>
      <button @click=${this.__increment}>increment</button>
    `;
  }
}

The generated Typescript above heavily relies on Lit to keep your web component both fast and simple. Here are some important facts to take away from this code regarding the tests we'll investigate next:

the class definition leverages the LitElement base class, so check out lit.dev for more information about what that means when we get to adding new functionality in later installments
the property decorator is being leveraged to upgrade a couple of properties to be both reactive and bound to attributes on the element
the html template literal from is being leveraged to performantly render out template
the @ sigil is being leveraged to declaratively listen to events on elements within our template

The tests

In our tests, a web component defined by our TestingComponents class is ensured to have the following characteristics:

it has a default header "Hey there" and counter 5
it increases the counter on button clicks
it can override the header via attribute
it asses the a11y audit

Defaults, interactivity, customization, and accessibility, form a great baseline for testing most web UI, so let's look closer at how this is done for our <testing-components> element, and what else might be useful in these areas.

Defaults

As we saw above, the @property decorator is being leveraged to create reactive properties on our class definition. header is being decorated with type: string meaning when its value is accepted from the attribute header the value will be coerced to a string. Similarly, the counter is decorated with type: number, which means values applied to the counter attribute will be coerced to a number. A handful of these conversions are handled out of the box by Lit, but in case you have something more complex in mind, learn about custom converters to solve those use cases.

Numbers and strings being pretty de rigueur, the following test confirms that those values are actually applied to the custom element when attached to the DOM:

it('has a default header "Hey there" and counter 5', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);

  expect(el.header).to.equal('Hey there');
  expect(el.counter).to.equal(5);
});

Testing that a property equals its default value by default may feel a bit superfluous, but it ensures the baseline of your web component before you dig into anything else. Testing that a property equals a property may also look a little underwhelming, it doesn't actually test anything about the property, and you may be right. Depending on what such a property does in a more complete web component, it may be advantageous to confirm that those properties appear appropriately in a DOM snapshot or in a visual regression test. We'll get into these techniques, and more, in future installments.

Interactivity

When testing web UI it is important to think of your test inputs as a future visitor interacting with your web component or a future developer building with your web component. A visitor can interact with your code in many ways, including a mouse and a keyboard, and @web/test-runner offers some powerful ways to emulate those interactions that we will investigate, later. This generated test acts as a developer building with your web component; leveraging the fact that @web/test-runner exists on the JS thread of an actual browser to leverage element APIs like querySelector() and click() within your test code:

it('increases the counter on button click', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);
  el.shadowRoot!.querySelector('button')!.click();

  expect(el.counter).to.equal(6);
});

If you're wondering why someone building with your web component might reach into your element and manually click() something within your element, you're probably not the only one. However, at test time, doing this can sometimes be the only way to initiate interactions from the JS context. Other times, it can be a clear sign the API of your element hasn't fully considered the requirements of its public interface.

Is clicking this button something that a consuming application should be able to do without human intervention? The answer may be "no", as is the case in the generated code, but, if the answer is "yes", you may want to refactor your element to prevent consuming developers from having to reach into your web component in this way. Understanding the various techniques of testing a web component can help surface these questions, and their answers before your code ships to consumers.

Customization

By using the property decorator in our class definition we not only upgraded those properties to be reactive, but we also bound those properties to attributes on our custom element. In this way, both header and counter can be supplied new values via the attributes of the same name. The following test ensures that this relationship is maintained for the header attribute/property:

it('can override the header via attribute', async () => {
  const el = await fixture<TestingComponents>(
    html`<testing-components header="attribute header"></testing-components>`,
  );

  expect(el.header).to.equal('attribute header');
});

If you are one for being "complete", the same could be done for counter as well. This test specifically leverages the html template literal to create an instance of the <testing-components> element and applies the value attribute header as an attribute to that element. You could similarly apply that attribute manually by leveraging the element reference maintained in the el variable; this would be the equivalent imperative operation el.setAttribute('header', 'attribute header');, if you were one for being "complete"...

Accessibility (a11y)

Not only does the Open Web Components project provide the generator that we are basing our web component on in this conversation, but they also vend Chai A11y aXe which binds axe-core with Chai assertions for easy consumption in the @web/test-runner environment. This means that you can use the industry standard accessibility testing engine to confirm the accessibility of your web component at unit test time. This looks like the following:

it('passes the a11y audit', async () => {
  const el = await fixture<TestingComponents>(html`<testing-components></testing-components>`);

  await expect(el).shadowDom.to.be.accessible();
});

Important note: expect().to.be.accessible() is an asynchronous command. If you do not await this expectation you will get false positives in your test results.

But, when you do await it, ensuring the snapshot accessibility of your custom element is just that simple. I saw "snapshot" here in that .accessible() knows nothing about your web component other than the state from which you called it. That means if further interactions with the element change the accessibility model, you should be sure to add a test, or tests, that takes your web component into that state and confirms its accessibility in that context. In future articles, we'll take a close look at what that means, as well as the difference between a component possessing an accessible tree of DOM nodes and specifically delivering a unique accessibility tree to assistive technology.

What have we got?

Now you've got a pretty well-tested <testing-components> element that features a header and counter attribute that delivers a button to your consumers that allows them to increment the counter. What more could you want?

Oh... a lot?

That seems fair. There isn't a lot in the component we've generated, which is good because it means that were you actually starting a new project with actual requirements there wouldn't be much to take away to start focusing on those. When we come back together in the future, we'll start from right here where we've left off and go deeper into testing web components in the browser with @web/test-runner. Hopefully, you've got at least a rough handle on how things come together in this area and are excited to come along for the ride.

What's next...

Now we know how to get started with a new web component project leveraging Open Web Components generator and understand the basics of testing the defaults, interactivity, customization and accessibility of that element with @web/test-runner, but, in the long story of UI development and testing, we're just getting started. Throughout of future conversations, we'll be digging into more topics important to testing web components, like:

the capabilities (and limitations) of testing UI from the JS thread
how you can test more like a user will consume your component, whether that's with a mouse, a keyboard, or a little slower the normal JS execution time
what sort of accessibility guarantees you can test at unit time
testing with DOM snapshots
testing for visual regression
and more...

If you've got a sharp eye, you'll notice the list is already getting longer as we go. Help me find things that I've missed. Take to the comments below with any concepts you would like to see covered in future installments. I can't guarantee that I'll be able to cover them, but now that you've gotten started testing web components, maybe you'll be able to teach me all about your favorite facet of the work.

Testing Accessibility with Shadow Roots

Westbrook Johnson — Tue, 22 Feb 2022 13:16:49 +0000

Recently, I had the opportunity to discuss the difficulties, learnings, and victories or developing Spectrum Web Components together with fellow custom element developers from teams at IBM, ING, SAP, and Vaadin. If you missed the live stream, check out the recording! Fellow panelist, Ari Gilmore, made a great point that there is a lack of reading material for developers like ourselves to draw from when looking to build solid accessibility practices into the web components space. With that in mind, I thought it would be a good idea to take some of the abstract concepts we discussed in the panel and share some actual examples of working and testable code. Hopefully, this can better support the next developer(s) looking to bring a high-quality, accessible, design system to life for their team via web components.

To support this conversation, I'll be bringing to life an input element pattern featuring accessible labeling and help text. Taking the suggestion of Thomas Allmer and the team at ING, the first example will be a no shadow DOM implementation with associated testing. With a shared baseline on how both the HTML and the testing works, we'll explore some different examples of delivering the relationship an input element, label element, and help text element accessibly with custom elements and shadow DOM. We'll talk about ways that we can mix and match these approaches and how some of the approaches align with or support various in-development and draft specifications for making this process even less work.

Some particularly prescient subjects that we went over during the panel that I'll dive into in this article:

leveraging the axe-core accessibility testing engine
seeing and understanding the accessibility tree
using native keyboard interactions at testing time
how ID references do not pass through a shadow boundary
ways to mimic native element references

I'll also connect some dots between these techniques and the various web component libraries my fellow panelists have brought into the world that leverages them so you can follow up on what is needed to take those patterns into production.

Some subjects that I won't spend much time on in this article, but are of great importance when shipping high quality, production-ready implementations of these patterns, include:

content styling
form association
state management
validation

Each of these, and likely other topics omitted without reference, would easily fill their own article(s), and hopefully, the support you'll find here in getting a jump on making your shadow DOM-based content more accessible will free you up to share your approach to these realities, next.

Starting from HTML
What and how to test
- axe-core
- Accessibility tree
- Native keyboard events at test time
How should we build it?
- Factoring from raw HTML
- Wrapper
- Decorator
- Emitter
  - The Decorator Pattern Plus
  - Panelist projects leveraging this technique
- Outside-in
  - ID references DO NOT pass through shadow boundaries
  - Panelist projects leveraging this technique
- Snowflakes
  - Pretending to be a native element
    - Responding to the "for" attribute
    - Observing text content
  - Panelist projects leveraging this technique
In memoriam
In the next life...

Disclaimer
Before we get started, as I mentioned in the panel, I wouldn't call myself an accessibility specialist. I understand accessibility to be an important part of delivering products to people and strive for the tools I leverage to do so to be more and more accessible over time. In the community, I work with smart, caring people, like those that I joined on the panel, to find new and better ways to do things. At Adobe, while developing Spectrum Web Components, I work with a dedicated team of accessibility engineers, some of whom actually write the specs to which the entire web community develops software. Without their patience and support, I'd definitely not have gotten as far as I have in being able to bring accessible surfaces to the web. That certainly doesn't mean I get everything right. So, while I hope you find this article similarly useful, the only way for us all to get a little more accessible is for you to share in the comments in you find something I've missed, or a different way to achieve the same goals, or want to know something beyond what I'll be coving. We can all make the web a little better place, together!

Starting from HTML

Following the lead of the ING team who's solid work has brought up Lion, we'll start from the raw HTML pattern that delivers a labelled and described <input> element:

<div>
    <label for="input">Label</label>
    <input id="input" aria-describedby="description" />
    <div id="description">Description</div>
</div>

You can view a demo of this code or clone it from GitHub to look more closely into how it works. However, the crux of the functionality (all provided natively by HTML at this point) is ID reference.

Our <label> element accepts the for attribute which references an element by ID. The element it references, in this case, our <input> elements, will be the one that receives the content of the <label> as its "name" in the accessibility tree passed the screen reader. Locally, it will also pass the click and focus events triggered by clicking the <label> onto the referenced element as well. This is less important in an <input type="text"> element, however types like checkbox or radio will be toggled as appropriate when passing these events which can make both interactive with and styling your form content easier.

The <input> element in question is leveraging the aria-describedby attribute, which also references an element by ID. Here, the attribute points to our <div> element which holds our description. There is no default interactive functionality that this relationship provides, but it will supply the text content of the referenced element as the "description" of the <input> element in the accessibility tree.

What and how to test

All of this is a great start to delivering this pattern accessibly, but don't just take my word for it. Let's dig into how we can test these things to be true, and at the same time set the table for refactoring this pattern to leverage web component APIs like custom elements and shadow DOM.

axe-core

Thanks, @open-wc/testing!

The first stop in any accessibility testing (or possibly any UI testing) should be on tests you can get "for free". For our use case, that can be provided by the axe-core accessibility testing engine as packaged into Chai a11y Axe and delivered in @open-wc/testing. While you may have caught me quoting a woefully small percentage of issues that automated testing like this can catch, I am heartened to hear that Deque (makers of axe-core) have recently looked deeper into this situation and believe that 57.38% of accessibility issues can be discovered via automation, so this will be a big first step in affirming the accessibility of the patterns you deliver.

What's more, this big first step is actually a really small step in reality. Check out the code below for confirming the accessibility of a DOM fixture with axe-core via Chai a11y axe:

// Has the side effect of binding Chai A11y aXe to `expect`
import { fixture, expect } from '@open-wc/testing';

// ...

it('passes the aXe-core audit', async () => {
    const el = await fixture<HTMLDivElement>(`
<div>
    <label for="input">Label</label>
    <input id="input" aria-describedby="description" />
    <div id="description">Description</div>
</div>
`);

    // Asynchronously tests the accessibility of the supplied content
    await expect(el).to.be.accessible();
});

That's right, the guts of the test at await expect(el).to.be.accessible(); and you'll immediately start getting reports of the accessibility achieved by the DOM in your fixture. Visit the Rule Descriptions outlining all of the concepts that will be covered simply by adding the one test.

This one test is so important that many tools get out in front of you to ensure it is included from the start. npm init @open-wc will include this test by default when testing is added by the generator. At Spectrum Web Components, when generating a new package with our Plop templating, we have this test by default as well. However you are initializing your projects, I highly suggest you work to have this sort of test included by default.

With that out of the way, and as many as 57.38% of your accessibility issues already caught, we can take a look at some more nuanced contexts that can be useful to have covered.

Accessibility tree

Thanks, @web/test-runner!

The DOM tree, paired with various ID references and aria-* attributes is used by the browser to construct an accessibility tree that it represented to screen readers to support visitors experiencing and interacting with our content with their assistance. Leveraging WAI-ARIA Authoring Practices, along with the assurances that axe-core can set as a foundation, we can generally be sure of what the tree a browser might build from our content. However, it can beneficial to know for sure.

One path to this is to leverage full accessibility tree view in Chrome DevTools. Switch this on and you can manually confirm the tree to which your code is being converted by the browser. Many browsers surface the ability to see part of the accessibility tree via their developer tooling, which is very useful, but you often end up needing to rely on manual testing to confirm that the right content is being delivered to screen readers.

While manual testing should definitely be a part of your go to production strategy, knowing what's actually in that tree, not just the relations that get created but the actual content that is bound by those relationships, can be an important addition to our automated testing workflows. To support this, browser runners like Playwright surface APIs by which we can access the accessibility tree (as a snapshot thereof) directly.

@web/test-runner give you access to these APIs while unit testing via its commands interface. This allows you to snapshot the accessibility tree at any point during an interaction with your code at test time, and confirm that nodes and relations that you expect to exist are actually there.

import { a11ySnapshot, findAccessibilityNode } from '@web/test-runner-commands';

// ...

const label = 'Label';
const description = 'Description';

it(`is labelled "${label}" and described as "${description}"`, async () => {
    const el = await fixture<HTMLDivElement>(`
<div>
    <label for="input">${label}</label>
    <input id="input" aria-describedby="description" />
    <div id="description">${description}</div>
</div>
`);

    const snapshot = (await a11ySnapshot({})) as unknown as DescribedNode & {
        children: DescribedNode[];
    };

    const describedNode = findAccessibilityNode(
        snapshot,
        (node) =>
            node.name === label &&
            node.description === description
    );

    expect(describedNode, `node not in: ${JSON.stringify(snapshot, null, '  ')}`).to.not.be.null;
});

The above code actually builds our HTML implementation of the labeled and described input, appends it to the document, and then requests a snapshot of the accessibility tree. Then, using findAccessibilityNode helper confirms the presence of a node meeting the requirements supplied. You'll also note that I leverage the custom error message of the Chai expectation here to allow for seeing the stringified accessibility tree when a test fails. As the tree can have many edge cases, and unexpected results, I've found this an important part of understanding what I'm testing.

One way that the accessibility tree surprises me, in the case of this example, is that WebKit does not actively associate the description content with our <input> element. While manual testing does confirm that the description text is associated appropriately, the tree will not return a reality where these two elements are connected. With the cross-context manual testing to back up this relationship in a WebKit browser, I'm comfortable with expanding the test in this case to something that takes this deviation into account:

export const findDescribedNode = async (
    name: string,
    description: string
): Promise<void> => {
    await nextFrame();

    const isWebKit =
        /AppleWebKit/.test(window.navigator.userAgent) &&
        !/Chrome/.test(window.navigator.userAgent);

    const snapshot = (await a11ySnapshot({})) as unknown as DescribedNode & {
        children: DescribedNode[];
    };

    // WebKit doesn't currently associate the `aria-describedby` element to the attribute
    // host in the accessibility tree. Give it an escape hatch for now.
    const describedNode = findAccessibilityNode(
        snapshot,
        (node) =>
            node.name === name && (node.description === description || isWebKit)
    );

    expect(describedNode, `node not in: ${JSON.stringify(snapshot, null, '  ')}`).to.not.be.null;

    if (isWebKit) {
        // Retest WebKit without the escape hatch, expecting it to fail.
        // This way we get notified when the results are as expected, again.
        const iOSNode = findAccessibilityNode(
            snapshot,
            (node) => node.name === name && node.description === description
        );
        expect(iOSNode).to.be.null;
    }
};

You'll see that this test uses the user agent to compare for WebKit and then allows for the test to pass when the description isn't related to the <input> and the browser is WebKit. To support understanding when/if this reality were to change in the future, the test then runs the expectation in reverse for WebKit so that a failure would be raised in our test and the workaround can be removed.

In other testing scenarios, WebKit will associate description content without issue, so pay attention to your results and pair them with manual testing when setting the baselines from which you want to protect against regression. I've also seen these sorts of differences in cross-browser understandings of the role of certain patterns, so be aware of the tree your content is creating when deciding the appropriate testing pattern to apply.

Native keyboard events at test time

Thanks, Playwright!

Once you are comfortable with the experience you are delivering to screen reader users, another user segment to ensure you are accessibly supporting keyboard navigation users. Whether to guide the screen reader across your content, or in support of other situations, it is important to know that your content can be accessed via the keyboard in expected ways. This can often prove elusive as testing keyboard events at unit test time is much more complex than it may seem. However, once you've established a reliable path to do so, the techniques leveraged to test this can be useful in other areas, as well; for instance, in UIs that include things like <input> element, which would traditionally be interacted with via the keyboard by all users.

Synthetic keyboard events can provide you with a decent entry into this area:

const keyboardEvent = (
    code: string,
    eventDetails = {},
    eventName = 'keydown'
): KeyboardEvent => {
    return new KeyboardEvent(eventName, {
        ...eventDetails,
        bubbles: true,
        composed: true,
        cancelable: true,
        code,
        key: code,
    });
};

Especially when the feature at test is also fully synthetic, e.g. something that you've added to your input element, they can take you a long way. When you're looking to test more complex keyboard interactions, including the various phases on a keypress, you might even turn to a testing library or framework to manage the complexities therein with success.

Once you move beyond testing your code directly, and into how your code should work in concert with the browser in which it is delivered synthetic events begin to show their shortcomings. This can be seen when attempting to use a synthetic event to alter the value of an <input> element. To fully mimic these interactions, more and more synthetic events need to be stacked on top of imperative commands to the to <input> until the whole process becomes quite brittle. Go one extra step and make expectations when a Tab key is pressed, and the approach falls apart altogether.

A native keyboard event doesn't just have all phases of a keypress that can be difficult to synthesize reliably, the browser itself recognizes the native keyboard interaction and responds with functionality beyond that which is found in your code. That means that the event has to originate with the browser itself. This is where tools like Playwright can step in and give you support for native keyboard interactions. Again, @web/test-runner gives you access to these APIs while unit testing via its commands interface. Leveraging this allows us to place <input> elements before and after the code we have under test and ensure that Tab and Shift + Tab interactions behave as expected. Code for doing so might look as follows:

import { sendKeys } from '@web/test-runner-commands';

// ...

it('is part of the tab order', async () => {
    const el = await fixture<HTMLDivElement>(`
<div>
    <label for="input">${label}</label>
    <input id="input" aria-describedby="description" />
    <div id="description">${description}</div>
</div>
`);
    const input = el.querySelector('input') as HTMLInputElement;
    const beforeInput = document.createElement('input');
    const afterInput = document.createElement('input');
    el.insertAdjacentElement('beforebegin', beforeInput);
    el.insertAdjacentElement('afterend', afterInput);
    beforeInput.focus();
    expect(document.activeElement === beforeInput, `activeElement: ${document.activeElement}`).to.be.true;
    await sendKeys({
      press: 'Tab',
    });
    expect(document.activeElement === input, `activeElement: ${document.activeElement}`).to.be.true;
    await sendKeys({
      press: 'Tab',
    });
    expect(document.activeElement === afterInput, `activeElement: ${document.activeElement}`).to.be.true;
    await sendKeys({
      press: 'Shift+Tab',
    });
    expect(document.activeElement === input, `activeElement: ${document.activeElement}`).to.be.true;
    await sendKeys({
      press: 'Shift+Tab',
    });
    expect(document.activeElement === beforeInput, `activeElement: ${document.activeElement}`).to.be.true;
    beforeInput.remove();
    afterInput.remove();
});

You'll see here that our test consists of three <input> elements and applies focus to the first before using Tab and Shift + Tab keyboard events to navigate through them. This may feel like testing code that isn't yours, and you might be right in this case of all native <input> elements in the same DOM tree. However, when shadow DOM boundaries come into play, it becomes more important to confirm how a keyboard user might come into contact with the elements you are building.

How should we build it?

There are a multitude of ways that we could structure this input experience with custom elements and shadow DOM. On top of each of those options is the ability to mix and match them across various contexts to make them work "just right" for your library or product. From here, let's dive into doing just that, while looking at some more "pure" implementations of the Wrapper, Decorator, Emitter, Outside-in, and Snowflakes techniques, as well as how the some of the panelist projects leverage them, or combinations thereof.

Factoring from raw HTML

We've already seen the raw HTML that we'll be working from, but here it is again as a reminder:

<div>
    <label for="input">Label</label>
    <input id="input" aria-describedby="description" />
    <div id="description">Description</div>
</div>

See the demo of webcomponents.dev.

Clone the code on GitHub.

Below, I've included five different ways to factor this raw HTML into custom elements, but they're just a small selection of the ways that you could do so accessibly. For each, we'll take a look at the custom elements that need to be created to leverage them, how those custom elements alter our usage in HTML, and what types of changes or additions might be needed to our test suite to support these decisions. I'll also link to examples of all or part of these techniques in work from my fellow panel members in the work on Carbon Web Components, Lion, SAP, and Vaadin, or in my own at Spectrum Web Components.

Wrapper

See the demo on webcomponents.dev.

Clone the code on GitHub.

This techniques is called "wrapper" because really, all that we're doing is wrapping our previously accessibly HTML with a custom element:

<testing-a11y>
    <label for="input">Label</label>
    <input id="input" aria-describedby="description" />
    <div id="description">Description</div>
</testing-a11y>

That's it, you're done. Ship it!

This <testing-a11y> element relies on the native accessibility of the raw HTML that we started with and then encapsulates the reusable functionality that you'd actually want to ship in a custom input element within the parent element wrapper. By itself, however, it places a lot of responsibility on a consuming developer to ensure that each usage fully completes the contract of accessibility promised by the raw HTML from which we started. I'd guess that this higher level requirement in their consumers lead other members on the panel not to use this technique as well, but you can always reach out to them and their teams for more information.

In the case that you like the flexibility of this pattern, but prefer to lighten the burden on your consumers, check out our next pattern.

Decorator

See the demo on webcomponents.dev.

Clone the code on GitHub.

<testing-a11y>
    <label>Label</label>
    <input />
    <div>Description</div>
</testing-a11y>

The decorator pattern takes the wrapper pattern, and, like its name would suggest, decorates the provided HTML with the required attributes in order to deliver the pattern accessibly. When decorating HTML that is slotted into your custom element from the outside, it is important to remember that the owner of that code (the application or component above) may have expectations as to the state of that DOM with which it is best not to interfere. In that way, our <testing-a11y> element, in this case, will only apply the IDs needed to complete our accessibility contract when IDs are not already available on the element(s) in question. With the possibility, too, that any required aria attributes might already have associations applied to them, the element "conditions" those attributes into the ID reference list of those attributes rather than setting them to the decorated IDs only. This is a useful pattern in a number of contexts, and can be achieved with the following helper methods:

export function conditionAttributeWithoutId(
    el: HTMLElement,
    attribute: string,
    ids: string[]
): void {
    const ariaDescribedby = el.getAttribute(attribute);
    let descriptors = ariaDescribedby ? ariaDescribedby.split(/\s+/) : [];
    descriptors = descriptors.filter(
        (descriptor) => !ids.find((id) => descriptor === id)
    );
    if (descriptors.length) {
        el.setAttribute(attribute, descriptors.join(' '));
    } else {
        el.removeAttribute(attribute);
    }
}

export function conditionAttributeWithId(
    el: HTMLElement,
    attribute: string,
    id: string | string[]
): () => void {
    const ids = Array.isArray(id) ? id : [id];
    const ariaDescribedby = el.getAttribute(attribute);
    const descriptors = ariaDescribedby ? ariaDescribedby.split(/\s+/) : [];
    const hadIds = ids.every((currentId) => descriptors.indexOf(currentId) > -1);
    if (hadIds) return function noop() {};
    descriptors.push(...ids);
    el.setAttribute(attribute, descriptors.join(' '));
    return () => conditionAttributeWithoutId(el, attribute, ids);
}

An element can conditionAttributeWithId and then cache the returned conditionAttributeWithoutId method to clean up at a later time, all without worrying about overwriting or removing values important to the parent context.

Beyond that, this is a rather naive example of decorating DOM in this way and assumes the first <input> that is slotted into it is the input should be decorating, and the same with the first <label> element. Any other non-<input> and non-<label> element that it is provided is there to describe the input. However, it does nothing to ensure those are the only <input> or <label> elements that it receives or that it displays. Those elements would deliver content into the accessibility tree that is currently unmanaged, and any production-ready implementation of this pattern would benefit from additional validation to ensure that didn't happen. If this level of flexibility and the validation required to manage it seem uncomfortable, take a look a how our next pattern locks down the content our custom element can deliver.

Emitter

See the demo on webcomponents.dev.

Clone the code on GitHub.

<testing-a11y
    label="Label"
    description="Description"
></testing-a11y>

Turn the decorator pattern up to 11 and you end up with the emitter pattern. As you see in the HTML sample above, the consuming developer no longer has to structure any of their own HTML to be slotted into the <testing-a11y> element. The emitter pattern relied on attributes to supply the accessible content that it will deliver and then renders the accessible HTML from that data. This approach very closely resembles patterns you may have seen in the JSX contexts of other approaches to componentizing UI. The main difference is that the accessible HTML will be rendered inside of the <testing-a11y> element as opposed to in the position marked by the call to a <TestingA11y> function in JSX.

The Decorator Pattern Plus

At the intersection of the emitter pattern and the decorator pattern is the decorator pattern plus, which I have written about before. It's crazy to think that it's more than three years old now, but it still does a great job of introducing what would otherwise be a sixth pattern to cover for this article. Pair the concepts therein with the concepts above, both in regards to testing and relating <input> elements to label and description content and you might find the accessibility pattern for your next custom input element!

Panelist projects leveraging this technique

Lion
The Lion library leverages a form of Decorator Pattern Plus in that it can either emit DOM based on the attributes or properties that it is provided or accept content for the various responsibilities slotted into its <lion-input> element from the outside.

<lion-input
    label="Label"
    help-text="Description"
></lion-input>

<!-- OR -->

<lion-input>
    <div slot="label">Label</div>
    <input slot="input" />
    <div slot="help-text">Description</div>
</lion-input>

This is powered by their FormControlMixin that makes the decoration or emission of light DOM content nice and uniform across their library.

Vaadin Web Components
Having mentioned as part of the panel that Lion had a lot of influence on their library, I'm unsurprised to see the Vaadin team also leveraging a form of Decorator Pattern Plus as well. Here, too, you can create a <vaadin-text-field> from attributes/properties or slotted content.

<vaadin-text-field
    label="Label"
    helper-text="Description"
></vaadin-text-field>

<!-- OR -->

<vaadin-text-field>
    <div slot="label">Label</div>
    <input slot="input" />
    <div slot="helper">Description</div>
</vaadin-text-field>

Here Vaadin leverages the reactive controller pattern popularized by the Lit team to manager various parts of this pattern. Label content, description content, as well as the <input> element itself are each managed in a way that is easily sharable across the library.

In both of these cases, you are also given the option to choose what things you want to supply and where, while still having them bound to the accessibility tree correctly. This can lend a nice level of freedom to developer consuming your custom form elements.

Outside-in

See the demo on webcomponents.dev.

Clone the code on GitHub.

<testing-a11y>
  <div slot="label">Label</div>
  <div slot="description">Description</div>
</testing-a11y>

In this approach, there is content important to the accessibility story of the element on both the outside and the inside of our <testing-a11y> element. Inside, by default, consumers of this element are provided an <input> element, and from the outside content is addressed to label and description slots for their content to be associated with said <input> appropriately. Much like we saw with the emitter approach above, this allows a consuming developer to focus directly on providing the content they would like to deliver while the <testing-a11y> element manages all of the accessible relations. This pattern goes one step further in not altering DOM contexts that it does not own, which can ensure eager rendering technologies employed at the parent application or element level will not interfere with the UI our custom element delivers.

ID references DO NOT pass through shadow boundaries

This is the first technique we've looked at together where there is content important to delivering the accessibility of the pattern separated by shadow boundaries. In association with that, you'll notice that we are no longer supplying IDs directly on the element containing the label and description text content. This is because the ID reference created by the for attribute on a <label> element and the aria-describedby attribute on an <input> DO NOT pass through shadow boundaries. To avoid this reality, we've wrapped the <slot> elements onto which we are projecting this content from the light DOM into our shadow DOM in elements that hold these references. Content projected into a custom element in this way will be attributed to those wrapping elements when the browser constructs the accessibility tree from this DOM to pass to the screen reader clearly delivering the content of this UI to the users they support.

Panelist projects leveraging this technique

Carbon Web Components
We can see a full investment into the outside-in pattern in Carbon Web Components' <bx-input> element, including some additional slots for content beyond that covered herein.

<bx-input>
  <div slot="label-text">Label</div>
  <div slot="helper-text">Description</div>
</bx-input>

This allows the <bx-input> to fully leverage the accessibility relationship created by the outside-in pattern for the label-text content. However, when taking a closer look, you'll see that the helper-text and validity-message content is not currently associated with the <input> element.

Spectrum Web Components
In order to attach description content to form elements, including the <sp-textfield> element in the Spectrum Web Components library, a help-text slot is surfaced.

<sp-textfield>
  <div slot="help-text">Description</div>
</sp-textfield>

This leverages the pattern outlined above very closely and expands to with a technique called Stacked Slots that allows you to easily manage multiple pieces of description content based on the validity of the <sp-textfield> element. Even after all this time, I find that the patterns made available around slotted content and ensuring the accessibility of content leveraging shadow roots has much exploration to be had!

UI5 Web Components
In conjunction with a visual design decision that delivers extra content about the <input> element in a "popover", the <ui5-input> element from UI5 Web Components leverages a valueStateMessage slot similar to this pattern. Notice that the value-state attribute must be set for content supplied in this manner to be displayed. This attribute accepts Error, Information, and Warning in order to display this content at various visual severity levels.

<ui5-input value-state="Information">
  <div slot="valueStateMessage">Description</div>
</ui5-input>

However, to achieve the delivery of the content via a popover, there is some additional machinery that goes into this implementation. By default, the text content applied to the valueStateMessage text is duplicated into the shadow root of the <ui5-input> element and associated to the <input> via a computed aria-describedby attribute for screen readers. When the <ui5-input> element is focused, any content supplied to the valueStateMessage slot will then be copied just in time into a popover for visual delivery.

Snowflakes

See the demo on webcomponents.dev.

Clone the code on GitHub.

<div>
    <testing-a11y-label for="input">Label</testing-a11y-label>
    <testing-a11y-input id="input"></testing-a11y-input>
    <testing-a11y-help-text for="input">Description</testing-a11y-help-text>
</div>

Everyone wants to be different, everyone wants to be unique, and sometimes custom elements feel this same way, too. To support them in this endeavor, here we outline what it might look like to make a fully custom implementation of each of the elements found in the raw HTML.

<testing-a11y-label> replaces the native <label> element and take on the responsibility of both the focus forwarding that we confirmed in our test code, but also features its own for attribute that must be powered by custom JS.
<testing-a11y-input> replaces the native <input> element and adds some simplicity by not requiring the aria-describedby attribute any longer.
<testing-a11y-help-text> helps clarify the anonymous nature of the <div> we had previously leveraged for this content and also features its own for attribute. We'll investigate how the lack of an aria-description attribute in the platform makes managing this for attribute different than the one on our <testing-a11y-label> element below.

Pretending to be a native element

One of the key characteristics of the snowflake pattern is that you are making custom elements that mimic the native behavior of existing HTML elements rather than leveraging them directly, decorating them, or extending (not likely ever possibly without polyfilling in Safari) then. This means you'll need to be conscious of the capabilities you were otherwise getting "for free" in those native elements. One should be apparent by the use of the for attribute in our custom label and help text elements above. Both <testing-a11y-label> and <testing-a11y-help-text> will need to duplicate the ID reference established in native <label> elements by this attribute. In this pattern, the for attribute points to an element that could be an actual form field, and you'll see code to support that possibility, but knowing that our <testing-a11y-input> encapsulated its form element within its shadow DOM, we'll also need to prepare a path to keep the content relationship between two elements separated by a shadow boundary live.

Responding to the "for" attribute

Part of the power that custom elements surface for developers in the lifecycle methods with which they can hook into browser native changes in our elements. Two of these are observedAttributes and attributeChangedCallback which allow us to observe attribute changed. With them we can easily react to changes in the for attribute on our custom label and help text elements to ensure that those elements are appropriately associated to the element referenced thereby. Take a closer look at how we do that in <testing-a11y-label>:

async resolveForElement() {
    // House keeping for when the value of `for` changes from one ID to another.
    if (this.conditionLabel) this.conditionLabel();
    if (this.conditionLabelledby) this.conditionLabelledby();
    if (!this.for) {
        delete this.forElement;
        return;
    }
    // [1] Resolution of the element referenced by the ID provided as `for`. This resolution happens in the DOM tree in which the `<testing-a11y-label>` element exists, so the referenced element will need to exist there as well.
    const parent = this.getRootNode() as HTMLElement;
    const target = parent.querySelector(`#${this.for}`) as LitElement & { focusElement: HTMLElement };
    if (!target) {
        return;
    }
    if (target.localName.search('-') > 0) {
        await customElements.whenDefined(target.localName);
    }
    if (typeof target.updateComplete !== 'undefined') {
        await target.updateComplete;
    }
    // [2] Noralization of the referenced element as the referenced host or an element available via the `focusElement` property on that host (for cross shadow boundary referencing).
    this.forElement = target.focusElement || target;
    if (this.forElement) {
        const targetParent = this.forElement.getRootNode() as HTMLElement;
        if (targetParent === parent) {
            // [3a] Application of `aria-labelledby` for elements in the same DOM tree.
            this.conditionLabelledby = conditionAttributeWithId(this.forElement, 'aria-labelledby', this.id);
        } else {
            // [3b] Application of `aria-label` for elements separated by shadow boundaries.
            this.forElement.setAttribute('aria-label', this.labelText);
            this.conditionLabel = () => this.forElement?.removeAttribute('aria-label');
        }
    }
}

Looking specifically at the numbered comments above:

For performance reasons this code requires that referenced elements live in the same DOM tree. If based on the requirements of your application this might be something you could relax. As seen in 5b, there is already support for associating content across shadow boundaries, so whether you step up through the various tree to the document or choose to resolve the forElement via alternate means (possibly accepting an actual element reference in the JS scope) you should be fully prepared to label that element with this code.
The choice to resolve target.focusElement || target for the forElement likely restricts this approach to native form elements and custom form elements that have bought into this technique, which could be seen as unfortunate. However, it does closely mimic the Cross-root Aria Delegation specification that is currently under development and widely agreed to across the various browser vendors.
Here we gate between supporting elements in the same DOM tree and those separated by shadow boundaries. This ensures that our accessibility story continues to be delivered on even though native ID references are not able to bridge this divide themselves.

When attempting to apply this same pattern to <testing-a11y-help-text> you'll quickly discover that there is not aria-description attribute. Because of this, associating our help text across shadow boundaries is a little more complex:

const proxy = document.createElement('span');
proxy.id = 'complex-non-reusable-id';
proxy.hidden = true;
proxy.textContent = this.labelText;
this.forElement.insertAdjacentElement('afterend', proxy);
const conditionDescribedby = conditionAttributeWithId(this.forElement, 'aria-describedby', 'complex-non-reusable-id');
this.conditionDescribedby = () => {
    proxy.remove();
    conditionDescribedby();
}

Here we create a proxy element to inject into the DOM tree on the other side of the shadow boundary with which to associate the help text provided to our form element. This does mean that our <testing-a11y-help-text> will be injecting DOM into a rendering scope that is does not own and it is important to keep in mind the limitations and dangers of doing so when choosing your path forward in this area. However, even when separated by this shadow boundary if you (or the same developer/library) own the elements on both sides of the divide these realities can be easily handled and the accessibility tree shaped from your content should be both stable and reliable.

Observing text content

When reaching across shadow boundaries to manage these label or description relationships, one added responsibility is insuring that the text content applied to the form element across the shadow boundary is kept up-to-date. Our elements will meed to observer their mutations in order to do this.

public connectedCallback(): void {
    super.connectedCallback();
    if (!this.observer) {
        this.observer = new MutationObserver(() => this.resolveForElement());
    }
    this.observer.observe(this, { characterData: true, subtree: true, childList: true });
}

public disconnectedCallback(): void {
    this.observer.disconnect();
    super.disconnectedCallback();
}

private observer!: MutationObserver;

The config of { characterData: true, subtree: true, childList: true } ensures that the observer will trigger on all changes to the value of el.textContent. When that content changes it needs to be pushed over the shadow boundary into the other DOM tree so that the accessibility tree can be built with the expected relationships.

Panelist projects leveraging this technique

Spectrum Web Components
This pattern is leveraged specifically for the <sp-field-label> element in Spectrum Web Components to deliver label content to <sp-textfield> elements when finishing the <input> interface we've explored herein.

<div>
    <sp-field-label for="input">Label</sp-field-label>
    <sp-textfield id="input"></sp-textfield>
</div>

In the Spectrum Web Components library the <sp-field-label> element uses almost line for line the approaches outlined above so that it can be leveraged in partnership with other native form elements or custom form element surfacing a focusElement property to provide intentional access to specific children in the elements shadow DOM.

UI5 Web Components
Similarly, the <ui5-label> element in UI5 Web Components also leverages this technique to a degree.

<div>
    <ui5-label id="label" for="input">Label</ui5-label>
    <ui5-input id="input" accessible-name-ref="label"></ui5-input>
</div>

Here they've baked for attribute management into the <ui5-label> element and resolution from the form element to the label element via the accessible-name-ref attribute as part of their AriaLabelHelper utility. Yet another example as to how we're really only scratching the surface as to how you could ship accessible UI with shadow roots by looking at the handful of techniques included in this article.

In memoriam

If you hitherto thought that it was not possible to make shadow DOM accessible, thanks for sticking around this far to have that misunderstanding cleared up.

If you understood how shadow DOM could be accessible, thanks for sticking around this far to hear about ways that I understand to do so.

Hopefully everyone has a couple of extra tools for making their next web component, or one they're already shipping, even more accessible. But, remember, this is just a couple of the possibilities! If you've got other techniques that you know, use, or love, please, please share them in the comments so that whether it's me, or the next developer, the community at large can put them in their tool belt as well.

Or even better, if you see something I missed, something I did wrong, or something you're want to know more about, get that conversation going. The only way we can all get better at delivering accessible UIs is by making it central to the conversation of delivering UIs. Sharing what we know, asking questions about what we don't, and pushing the envelope in every direction is a big part of that. I look forward to seeing it below!

In the next life...

Like I mentioned at the start, there are MANY concepts around shipping a complete web component that we have not covered in this conversation. Including:

content styling
form association
state management
validation

Each and every one of these topics and more would make a great follow up article expanding on these above patterns in any one of those directions. I can't make any promises, but I'll do my best...if you're interested in it, I'd love to partner, support, cheer you on as it comes together!

On top of that, there are some more varied and complex patterns for accessibility with web component that could be useful to dig into, as well. In particular, the Vaadin panel touched on the super useful combobox patterns currently begin shipped by various products from other panelists which is currently raising up the backlog of Spectrum Web Components. Sharing thoughts on how to bring that experience to the web with custom elements and shadow DOM might be just the nudge needed to actually get development of that pattern finished.

Let's keep talking about accessibility. Let's keep making our UIs and components accessible. Let's find new and better patterns for doing it, together. See you next time.

Who doesn't love some ``s?

Westbrook Johnson — Wed, 24 Nov 2021 01:59:07 +0000

It does seem like I enjoy a good <slot></slot>. I mean, look, I wrote about them all the way back in 2018 in <slot/>ing in Some Tips, and then in 2020, I spoke about Stacked Slots at a virtual Web Components SF meetup (see the associated slides), before sharing a proof of concept for Light DOM as Model. And, as if that weren't enough, here we are again, and I'm writing to you, friend, about <slot>s. Today, we're going to get out of the theoretical and into the practical as we start on the path towards actual usage of Stacked Slots that I'm excited to bring to life as part of Adobe's Spectrum Web Components to support the delivery of Spectrum design's Help Text pattern.

Help text

Spectrum’s help text pattern:

provides either an informative description or an error message that gives more context about what a user needs to input. It’s commonly used in forms.

Clearly, help text isn’t much use on its own. There needs to be some way to associate help text with the element it describes. Traditionally, that might look like:



  <input aria-describedby="help-text" />
  <div id="help-text">
    The above input is described by this help text.
  </div>

However, we are gathered here today to celebrate the awesomeness that are <slot>s, so we have to be talking about shadow DOM (required to leverage browser native <slot> elements and their various capabilities), and are likely talking about custom elements (because they all get along so well). With these two APIs together, it's not uncommon to see a form element writ into a custom element as follows:



  <custom-form-element></custom-form-element>

From here, you're likely to see many APIs structured in a "component as function with properties" pattern that is common in various javascript frameworks and surface help-text as an attribute of the <custom-form-element>:



  <custom-form-element
    help-text="An input inside of this element is described by this help text."
  ></custom-form-element>

You might then see such an API expanded for help text across various states:



  <custom-form-element
    help-text="An input inside of this element is described by this help text."
    help-text-invalid="An input inside of this element is described by this help text when invalid."
  ></custom-form-element>

Possibly, ad infinitum:



  <custom-form-element
    help-text="An input inside of this element is described by this help text."
    help-text-valid="An input inside of this element is described by this help text when valid."
    help-text-invalid="An input inside of this element is described by this help text when invalid."
    help-text-when-you-appear-stuck="An input inside of this element is described by this help text when you appear stuck."
    help-text-etc="An input inside of this element is described by this help text, etc."
  ></custom-form-element>

This API had only just started to talk about the <custom-form-element> and already it is quite thick (imagine it with actual API for customizing the associated form element). This could certainly weigh on your consuming developers. What's more, while this is going to look (and work) great when javascript is on, or look great (though possibly not work) when delivered in a browser with Declarative Shadow DOM, it has no chance of looking good with neither (unless generally not seeing something counts as it looking good, which is true... sometimes), and it certainly doesn't use any <slot>s!

To be clear, none of the notes above are inherently bad. Each of these could align with the desired philosophy of an element, a library of elements, or an application that leverages elements. I call them out here as a way to get to the point I'd like to make about <slot>s. If your use case doesn't direct you towards an HTML-like API for your custom elements, more power to you. However, supplying this content as HTML allows us to:

customize the DOM element that wraps your help text content
deliver DOM in that content (e.g. anchor tags, icons, etc.)
encapsulate any default functionality or styles belonging to help text content
separate the concerns of delivering a form element from those of delivering help text content
style help text content directly from the outside

To support all these things, I'd like to propose the following API.



  <custom-form-element>
    <custom-help-text slot="help-text">
      An input inside of this element is described by this help text.
    </custom-help-text>
    <custom-help-text slot="negative-help-text">
      An input inside of this element is described by this help text when invalid.
    </custom-help-text>
  </custom-form-element>

The above makes the presence and the customization of content beyond the initial help message easy to manage regardless of the context from which you're delivering it. You've got a custom form element; you slot in the default and negative help text messages and automatically they are correctly associated with the appropriate element within the parent's shadow DOM and hidden/shown based on the validity of the said parent. Similarly, you can slot in a single piece of help text, and it can be fully controlled from the JS scope in which is delivered:



  <custom-form-element>
    <custom-help-text slot="help-text">
      An input inside of this element is described by this help text.
    </custom-help-text>
  </custom-form-element>

Let's look at how we can bring all of this into being.

<slot/>ing in some help text

For this last example, a single slot named help-text is all you need to get started. Here's what that could look like in a no dependency custom element where we're taking nothing else into account except slotting in this one piece of content:



const template = document.createElement("template");
template.innerHTML = /*html*/`
  <input />
  <slot name="help-text"></slot>
`;

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

customElements.define("custom-form-element", CustomFormElement);

If this already has you excited to code, hop on over to webcomponents.dev and fork the project from this point.

What we've got here is relatively simple to start, so we've got lots of growing to do. Before we dive into supporting the help-text AND negative-help-text slots, where we can really dig into the concept of Stacked Slots, let's be sure that the content in this slot can be appropriately associated with the <input /> element that we're basing our <custom-form-element> around for the time being.

All form controls need to be supplied with a label (something we are actively omitting at this time) to be accessible. Labels can be associated with a form control as follows:

the form control can supply this content itself via the aria-label attribute
a secondary element can be referenced by ID in the form control's aria-labelledby attribute, or
the form control itself can be referenced by ID in a <label> element's for attribute

Content associated in this way will be read as part of the primary description of the form control. Help text content doesn't require this level of priority in the element's description, so we will associate it by leveraging the form control's aria-describedby attribute to reference this content by ID.

When referencing content by ID, it is important to remember that the elements on either side of the reference need to share a DOM tree for the reference can be completed. With our form control (the <input />) being within our shadow root and our <custom-help-text> element being slotted from the outside we can't simply add an ID on one and point to it from the other. Instead, we'll place our <slot> element into a <div> itself and give that <div> the ID to reference from our form control. In this way, the <div> can adopt the help text content projected onto the <slot> element and make it available to the form control to reference via ID with its aria-describedby attribute.



template.innerHTML = /*html*/`
  <input aria-describedby="help-text" />
  <div id="help-text">
    <slot name="help-text"></slot>
  </div>
`;

See it in living color, fork it, share it, and when you're done, come right back, so we can dig even deeper.

Now for the superpowers

That's right, custom elements allow you to give your HTML superpowers. A consumer of our element could already take what we've made, leverage the bubbling and composed events out of the <input /> element, and manage the text that is supplied to the <custom-help-text> element from the outside, and we'll see what that looks like shortly. However, we can save most consumers a lot of work by baking some basic management directly into our custom element. This is exactly what is outlined in the code example above:



  <custom-form-element>
    <custom-help-text slot="help-text">
      Describe interests you would like to explore.
    </custom-help-text>
    <custom-help-text slot="negative-help-text">
      Enter at least one interest.
    </custom-help-text>
  </custom-form-element>

While there is much that can be done about managing when something deserves "negative help text", for our demo we'll only track whether our <input /> has content or not. To do so, and rather naively at that, we'll add the required attribute. This will allow us to leverage the checkValidity() method on the <input /> element to confirm whether any content has been supplied.

To support this, we'll expand our constructor to bind a listener for the input event to our host element:



constructor() {
  super();
  this.attachShadow({ mode: "open" });
  this.shadowRoot.appendChild(template.content.cloneNode(true));
  this.addEventListener('input', this.handleInput);
}

Adding the listener to this, even though the input occurs within our shadow DOM, is useful to ensure that the handleInput() callback is bound to our host element, and not the child <input />. In our example, we'll be keeping the held state to an absolute minimum, but having this reference the host element not only allows us to directly query selectors within our element, were we to hold state on our element we'd have access to that as well. In the handleInput() callback we can examine the event's composedPath() to reacquire the <input /> element and call checkValidity() on it:



handleInput(event) {
  // ...
  const target = event.composedPath()[0];
  const showNegative = !target.checkValidity();
  // ...
}

We'll leverage the showNegative variable to tell our element to show the negative help text. showNegative as a variable name is very specific to our help text use case, and that shouldn't be an issue with it scoped to our handleInput() method. In larger scopes of work, we should look at making this attribute more semantic to our <custom-form-element>. This might be managing it as invalid, or similar, that would make sense to surface via the element's public API.

While we're here, we will also surface a getter/setter pair to manage the value of our <input /> from the outside:



  get value() {
    return this.shadowRoot.querySelector('input').value;
  }

  set value(value) {
    this.shadowRoot.querySelector('input').value = value;
  }

Next we'll get into what we actually do with these values.

All the slots

So far, we've discussed the consumption of two different slots: help-text and negative-help-text. Why?

Well, some consumers want all the control. In this use case, we surface the help-text slot so that absolutely anything can be put into it, whenever the parent application would like. Want to cheer your visitor on for every keystroke they make, this is the slot for that.



  <custom-form-element
    oninput="
      const modiferElement = this.querySelector('#modifier');
      const countElement = this.querySelector('#count');
      const multipleElement = this.querySelector('#multiple');
      const length = this.value.length;
      multipleElement.textContent = length === 1
        ? ''
        : 's';
      countElement.textContent = length;
      let modiferText = '';
      if (length > 10) {
        modiferText = 'Wow!';
      } else if (length > 5) {
        modiferText = 'Nice.';
      } else if (length > 0) {
        modiferText = 'Keep going.';
      }
      modiferElement.textContent = modiferText;
    "
  >
    <custom-help-text slot="help-text">
      <span id="modifier"></span> You've typed <span id="count">0</span> character<span id="multiple">s</span>.
    </custom-help-text>
  </custom-form-element>

Really, with the help-text slot, access to the form control's value, and experience with which to interact with it from the outside, there's no end to how you could leverage the content you might supply. However, in more cases than not, swapping between "this is what you should do" and "this is how you get out of the problem you've gotten yourself in" text will likely support the goals of our consumers. In some cases, we might just be turning on the "this is how you get out of the problem you've gotten yourself in" text. Pairing the help-text slot with a negative-help-text slot, we can make the process of doing these things something they'll almost never have to think about.

So, where are we actually inserting these slots into our element's shadow DOM? We might start by positioning them next to each other, as siblings:



template.innerHTML = /*html*/`
  <input aria-describedby="help-text" />
  <div id="help-text">
    <slot name="help-text"></slot>
    <slot name="negative-help-text"></slot>
  </div>
`;

From here we could leverage the showNegative variable we've already derived in our handleInput() method to do something like add the hidden attribute (ignoring that [hidden] is a lie) to the <slot> elements conditionally. Then we can show the negative-help-text slot when !!showNegative. When !showNegative, we can show the help-text slot. And, we're done.

Except, what happens when content is only addressed to the help-text slot?

Toggling hidden directly on both <slot> elements in response to showNegative would mean that the content addressed to the help-text slot would be hidden when showNegative, regardless of whether there was content to display in the negative-help-text slot at that time. We could only toggle hidden on the negative-help-text slot, but that would mean that there are times that our <custom-from-element> would receive two pieces of help text. Some component authors might want to deliver exactly this functionality to their users, in which case, they'll be ready to go with the above. For those of you that would agree, here's your off ramp.

For those of you who, like me, see more than one type of help text as something to prevent, there are a couple of options available. One would be to leverage the slotchange event, and the assignedElements() API on the negative-help-text slot to decide whether it has content, and when it does use that state in concert with showNegative to decide when to hide the help-text slot. One more event listener, one more callback method, one quick question about slotchange timing and whether you should hold state instead, and you'd be ready to go! But, what if I told you that the browser already had this functionality built directly into it?

Well, it does.

Stacked slots

A <slot> element doesn't just act as a marker for where content can be projected into your element from the outside. The <slot> element can also supply default content to be delivered when there is nothing projected onto it, as well. What's more, that content can be additional <slot> elements. In this way, we can stack our slots and give the earliest ancestor <slot> in the stack precedence over those that descend from it. For our help text slots, that could look like:



template.innerHTML = /*html*/`
  <input aria-describedby="help-text" />
  <div id="help-text">
    <slot name="negative-help-text">
      <slot name="help-text"></slot>
    </slot>
  </div>
`;

This allows any content addressed to the negative-help-text slot to "win" and be the content that is shown when it is available. When that is absent, content addressed to the help-text slot will always be available for users to manage directly from the outside. That means that when HTML like the following is used, only the "This field is required!" content that is addressed to the negative-help-text slot will be displayed on the rendered page.



  <custom-form-element>
    <custom-help-text slot="help-text">Please type something here.</custom-help-text>
    <custom-help-text slot="negative-help-text">This field is required!</custom-help-text>
  </custom-form-element>

This isn't exactly what we were looking for, so we need to add a little something more. We want our parent <slot> to pass through to our child <slot> when the form control's value is valid. To do this, instead of relying on hidden to show or hide the element, we can use a nonsensical name to ensure content can't be addressed to the slot.



template.innerHTML = /*html*/`
  <input aria-describedby="help-text" />
  <div id="help-text">
    <slot
      name="pass-through-help-text-${Math.random()}"
      id="negative-help-text"
    >
      <slot name="help-text"></slot>
    </slot>
  </div>
`;

This will be our default, allowing the help-text slot to take precedence. While handling the input event we can then use the value of showNegative to toggle the name attribute to something addressable.




handleInput(event) {
  // ...
  const target = event.composedPath()[0];
  const showNegative = !target.checkValidity();
  const slot = this.shadowRoot.querySelector('#negative-help-text');
  slot.name = showNegative
    ? 'negative-help-text
    : `pass-through-help-text-${Math.random()}`;
}

This will give our content addressed to negative-help-text a slot onto which to be projected when our form control becomes showNegative without preventing content addressed to the help-text slot from being displayed when negative-help-text content is absent. It's a bit like API validation in HTML.

With all of this together, we'll be imbuing our <custom-form-element> with the following super powers:

accessible help text content
a help-text slot to act as default and receive updates from the outside while displaying in all validity states
a conditional negative-help-text slots for overriding that content with content meant only for when the form control should showNegative

It is a neat little custom element who's definition looks about like:



const template = document.createElement("template");
template.innerHTML = /*html*/`
  <input
    aria-describedby="help-text"
    required
  />
  <div id="help-text">
    <slot
      id="contextual-help-text"
      name="pass-through-help-text-${Math.random()}"
    >
      <slot name="help-text"></slot>
    </slot>
  </div>
`;

class CustomFormElement extends HTMLElement {
  get value() {
    return this.shadowRoot.querySelector('input').value;
  }

  set value(value) {
    this.shadowRoot.querySelector('input').value = value;
  }

  constructor() {
    super();
    this.attachShadow({ mode: "open" });
    this.shadowRoot.appendChild(template.content.cloneNode(true));
    this.addEventListener('input', this.handleInput);
  }

  handleInput(event) {
    const contextualHelpTextSlot =
      this.shadowRoot.querySelector('#contextual-help-text');
    const target = event.composedPath()[0];
    const showNegative = !target.checkValidity();
    contextualHelpTextSlot.name = showNegative
      ? 'negative-help-text'
      : `pass-through-help-text-${Math.random()}`;
  }
}

customElements.define("custom-form-element", CustomFormElement);

Check it out more closely, as well as demos for working with the help-text and negative-help-text slots to varying levels of complexity.

What's missing?

Before we wrap up, let's visit a (not so short) list of things that were consciously omitted from the conversation in this article. If you find any that I've unconsciously missed, or if one of these is of particular interest to you, please let me know in the comments below as I'd want to get it added when missing or take your interest as a nice push towards any sequel posts with which I might follow this.

The first to come to mind is giving a definition to our <custom-help-text> element that is features throughout our demos but until this point has no superpowers of its own.

Revisiting our screenshot of what help text could look like, we've clearly skipped:

labeling our form element
supporting API like required (see the * mark) on <custom-form-element>
styling content that we build this way. Yes, I noticed that the visuals in that image are much more appealing than our demos to date

Thinking about the validity and value piping that we added:

what other APIs (beyond value) of our form element should be passed through to our <custom-form-element>?
what other forms of validity (beyond required) should be available and how can we surface them?
how can we make this validity and value a part of a parent <form> element's form data? (Yes, the shadow DOM boundary effectively hides the <input /> from participating in our custom element's current form.)

Looking at how we related our help text to our form control, we might also be interested in:

supporting form controls that are outside of our shadow root
abstracting this relationship into a reusable form that could empower many custom form control elements, rather than just one
the benefits of simplifying this code with the help of a declarative templating system

Clearly, there is a lot that we could do to continue to expand on what we've started here together. Some might even involve more learning and praise around <slot> elements, but most spread across the breadth of APIs and capabilities that are available in the browser today as web components.

But, just because there is a lot to do, doesn't mean we haven't already achieved a lot together.

How far we've come

At press time, our demo features:

a reusable <custom-form-element> element
a single required <input /> element on which we track validity
piping for seeing the value of the <input /> from the outside
the <input /> is accessibly related to "help text" content that can be supplied from the outside as HTML
a default <slot> (help-text) surfaces a wide array of from the outside customizations around the delivery of the help text
an override <slot> (negative-help-text) that is available when the <custom-from-element> is showNegative

To do so we've learned about:

building a custom element from scratch
how amazing webcomponents.dev is
ways to manage property/attribute bloat
accessibly relating content from the outside of a custom element to content with that element's shadow DOM
bind events to custom elements
some basics around boolean attributes
making state on elements encapsulated within our shadow root public
<slot> elements and their default content
stacking <slot> elements

Hopefully, you've found it interesting and educational. Feel free to share anything I could be more clear about in the comments below so that this content can be even more useful for our readers.

After that, you can visit a more advanced version of this technique where it is being leveraged in Spectrum Web Components. There you'll see this functionality delivered as a class factory mixin into custom elements based on the lit library and its LitElement base class, great fodder for follow up conversations around lending declarative templating and reactivity to our <custom-form-element>.

Additional editing by @HunterLoftis, who wished after the fact that I had asked him to read this before I asked him to review a PR based on these ideas.

Photo by Aarón González on Unsplash

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!

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

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.

Things We did for the First Time in 2019...

Westbrook Johnson — Tue, 31 Dec 2019 02:34:11 +0000

Hi, I'm Westbrook and I'm a front-end engineer.

👋🏼

I've been doing this CSS/HTML/JS thing for more than 12 years now, and I'm always amazed by all of the interesting technologies that come and go in our industry. Some things have been with us forever, others have just joined the party but seem destined to be with us for a while, and many more enter and leave the picture as fast as you can turn your head to learn what they are. Often this only really comes clear to me by way of trending topics on Twitter or the blogosphere. Particularly, in the way that my career has worked out, my work with the web fits into a couple of neat little epochs: 3 or 4 years of predominately CSS/HTML development, 3 or 4 years of working with jQuery/Backbone.js derivatives, and 5 or 6 years of building component/design systems and applications with web components. However, this year was a little different. While working to discover the right team with which to continue to develop my career, I ended up changing jobs twice, and across those three different teams, I encountered a lot of things that might not be new to the world of front-end engineering but were certainly new to me.

While reviewing them for myself, I was surprised how many things I had seen in the community for years but only just this year ended up working with myself. In that it surprised me, I thought it might surprise or be of interest to others, especially those of us that find it hard to keep up with all of the great concepts and technologies that are consistently making their way around the front-end engineering community. This will also be a good chance for me to hear what some of the rest of your might have done for the first time this year in your work as well! I'm sure there be lots of things I find there that end up being firsts for me in 2020...

I'll get started in no particular order here, you share yours in the comments below!

worked at three different companies
had a job interview in San Francisco
published on dev.to
handed over management of an entire product in just 2 weeks
realized that no amount of documentation is enough
worked full-time with teammates in other countries
worked in an office that wasn't the "main" location of my team
built a mono-repo with Lerna
developed React for production
shipped an application built with webpack
wrote Jest tests
shipped CSS Grid-based UIs to production
managed state with Redux
joined an open-source project as a maintainer
published packages to public and private NPM registries
worked with a mono-repo built with Rush
used Artifactory
managed state with finite state machines
used StackBlitz
used WebComponents.dev
developed in Vue.js
open-sourced work I'd done for my company

There's likely more that I've missed, but this is already a pretty long list of firsts! I'm going to take it as a good sign that no matter how experienced we become in our fields that there's always value in keeping an open mind and experimenting with new and different techniques...

What's your list look like?

`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.

Not Another To-Do App: Part 10

Westbrook Johnson — Tue, 01 Oct 2019 20:28:07 +0000

Getting your hands dirty and feet wet with Open Web Component Recommendations...sort of.

This a cross-post of a Feb 26, 2019 article from Medium that takes advantage of my recent decision to use Grammarly in my writing (so, small edits have been made here and there), thanks for looking again if you saw it there 🙇🏽‍♂️ and if this is your first time reading, welcome!

Welcome to “Not Another To-Do App”, an overly lengthy review of making one of the smallest applications every developer ends up writing at some point or another. If you’re here to read up on a specific technique to writing apps or have made your way from a previous installation, then likely you are in the right place and should read on! If not, it’s possible you want to start from the beginning so you too can know all of our characters’ backstories...

If you’ve made it this far, why quit now?

Reusable and Scaleable Data Management

Photo by Francesco Ungaro on Unsplash

You know what’s kind of popular right now? Functional programming. You know what’s a great way to deliver features build to take advantage of functional programming concepts? ES Modules. You know what’s a great way to manage logic trees without relying on switch or if/else statements? The strategies pattern. What do you get when you mix them all together? Reusable and Scaleable Data Management. Or, at least I certainly hope so (yes, that’s another good one to take down to the comments)...here’s how I did it.

Reuse

On the reusable end of the spectrum, let’s start with the functional interface by which we interact with the lifecycle of our list of to-dos (creating it, adding to-dos to it, and completing to-dos on it). Access to this can be gained via import { newToDos, addToDo, completeToDo } from './to-do-manager';. Here we get functional controls to initialize a new set of to-dos (i.e. return []), add a to-do (i.e. return [...todos, newTodo]), and remove a todo (i.e. return [...todos.filter(todo => todo.id !== completedId)]. Across each of these, we establish and maintain the identity of our individual to-dos while generating a new identity for the resulting list of to-dos, which will trigger the render pipeline in our LitElement based application. Further, their being exports allows them to be used and reused across our application and tests while being prepared for being made an external dependency if at some point this data became useful across multiple applications. If you want to use them in your To-Do application, fork me on GitHub!

Scale

On the scaleable side of the spectrum, we’ll be looking at the rest of the code in [src/to-do-manger.js](https://github.com/Westbrook/to-do-app/blob/master/src/to-do-manager.js) which covers the ability to deliver work level customized suggestions for the user via the workLevelMessage(todos) export. While this data is also structured for use across the application and possible externalization as well, what’s really nice about it is how it is structured to scale.

function workLevelMeter(todos) {
    const workLevelCounts = Object.keys(workLevelByTodoCount);
    const count = workLevelCounts
        .find(todoCount => todos.length <= todoCount);
    return typeof count !== 'undefined'
        ? workLevelByTodoCount[count]
        : workLevelCounts.length;
}

export function workLevelMessage(todos) {
    return workLevelMessages[workLevelMeter(todos)];
}

Notice how rather than attempting to structure an extended if/then tree or switch statement to outline which the message to return from [workLevelMessage](https://github.com/Westbrook/to-do-app/blob/master/src/to-do-manager.js#L52) the [workLevelMeter](https://github.com/Westbrook/to-do-app/blob/master/src/to-do-manager.js#L44) method relies on a series of object and array methods (thanks to our previous commit linting experience) to resolve the appropriate message. This means that regardless of whether to the current five levels of workloads and their associated messages, to a single one, or to fifty levels, this same logic will apply. We don’t need to go about adjusting what could easily become an awkward logic tree when you choose to make additions to the messages delivered or alterations to the levels at which their delivered, we just add the associated information to the data structure:

export const workLevelMessages = {
  0: 'Looks like you don\'t have anything to do right now. Take a break!',
  1: 'Looks like you\'re almost done. Keep it up!',
  2: 'Still a little more work to do. Don\'t loose focus!',
  3: 'It\'s a tough job, but somebody\'s got to do it.',
  4: 'This may look like a lot, but I know you can do it!',
  5: 'Maybe it\'s time to take a vacation? I won\'t judge.',
  /* New message */ 6: 'There\'s a new message in town!',
};

export const workLevelByTodoCount = {
  0: 0,
  3: 1,
  6: 2,
  9: 3,
  14: 4,
  /* New work level */ 50: 5,
};

The above additions will immediately be available to uses with 50 or more to-dos, no logic alterations needed. And, even better, with the additional export of [workLevelMessages](workLevelMessages) and [workLevelByTodoCount](https://github.com/Westbrook/to-do-app/blob/master/src/to-do-manager.js#L36) those additions are also immediately added to the testing process.

And, in the end...

If you are sure I’m wrong, want to celebrate how right I am, or teach me ways I can be even crazier/insightful/progressive/right/et al. about anything you’ve read this far, I hope you know the refrain...the comments you take, and equal to the comments you make. Or at least I heard (something like) that somewhere.

As is noted above, the code shared throughout our conversation to date has not always been what ended up as final in my application. In case you’ve not gotten a chance to see what did, feel free to read the whole codebase on GitHub.

Westbrook / to-do-app

An open-wc powered To Do application

Open-wc Starter App

Quickstart

To get started:

git clone https://github.com/open-wc/open-wc-starter-app.git
cd open-wc-starter-app

npm install
npm start

Live demo on Netlify.

Scripts

start runs your app with auto reload for development, it only works on browsers which support modules for faster builds
start:es5 runs your app for development, it only works on browsers that don't support modules (IE11)
build builds your app for production and outputs it in the /dist folder
start:build runs your built app using a plain web server, to prove it works without magic 😃
build:stats creates an analysis report of your app bundle to be consumed by Webpack Visualizer and Analyser
test runs your test suite
lint runs the linter for your project

View on GitHub

You can also see the current final application on Netlify. It’s tied to the GitHub repo above, so by current...I really mean it. It’s putting all of the ideas we’ve discussed in action live on the internet, and I hope the conversations we’ve shared about the development of it have proved useful to you in some way.

To bring us back to where we started, here’s a little refresher on the concepts that I wanted to find their way into my little To-Do app:

component-based code architecture
custom property based style API
event-based state management
style sharing
unit testing
web component-based UI

Over the course of some tightly related and others wildly tangential approaches, I hope you agree that I did a decent job of making a pass at each and every one of them. Some of these techniques are enabled by the team behind Open Web Components and their brand new Starter App. Some of them are rooted deeply in the tools recommended therein. And, others are flights of fancy that I’ve cooked up or heard over the course of years working with applications on the web.

If I haven’t said it yet, or in some cases if you hadn’t heard it yet, I’m not planting a stake in the ground to say that any of them are bar none the best in their class, and even less so am I trying to say that any of them would apply to projects of any size or holotype. What I do hope is that maybe like yet another set of interesting voices I follow in the field the subjects covered so far spark, not joy, but an interesting conversation between you and your other self, you and your team, you and me, or possibly even any small part of the larger javascript community. The more we get together to talk about our techniques and fret out the edge cases and the exactitudes that make them up, the happier we’ll be. (Oh, look, maybe I did mean for it to spark joy...) So, take the discussion to the comments below, the @ messages on Twitter, your favorite Slack, or this one were working with the web platform, web components, LitElement, and Open Web Components are all trending (at least most of the time), and I’ll see you there!

Fin.

The Short Game

As voted on by a plurality of people with opinions on such topics that are both forced to see my tweets in their Twitter feed and had a free minute this last week, a 9000+ word article is a no, no.

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

So, it is with the deepest reverence to you my dear reader that I’ve broken the upcoming conversations into a measly ten sections. Congratulations, you’re nearing the end of the first! If you’ve enjoyed yourself so far, or are one of those people that give a new sitcom a couple of episodes to hit its stride, here’s a list of the others for you to put on your Netflix queue:

Not Another To-Do App
Getting Started
Test Early, Test Often
Measure Twice, Lint Once (I, for one, welcome our robot overlords. Maybe they’ll do the writing every time I have an idea to deliver a crazy long series of articles like this...)
Make it a Component
Make it a Reusable Part
Does Your Component Really Need to Know That?
Separate Things Early, Often, and Only as Needed
Some Abstractions Aren’t (Just) For Your App
Reusable and Scaleable Data Management/And, in the end... (you are here)
See the app in action

Special thanks to the team at Open Web Components for the great set of tools and recommendations that they’ve been putting together to support the ever-growing community of engineers and companies bringing high-quality web components into the industry. Visit them on GitHub and create an issue, submit a PR, or fork a repo to get in on the action!

Not Another To-Do App: Part 9

Westbrook Johnson — Wed, 18 Sep 2019 13:03:51 +0000

Getting your hands dirty and feet wet with Open Web Component Recommendations...sort of.

This a cross-post of a Feb 26, 2019 article from Medium that takes advantage of my recent decision to use Grammarly in my writing (so, small edits have been made here and there), thanks for looking again if you saw it there 🙇🏽‍♂️ and if this is your first time reading, welcome!

If you’ve made it this far, why quit now?

Some Abstractions Aren’t (Just) For Your App

Photo by Kira auf der Heide on Unsplash

Often times we find ourselves staring the benefits of a quality abstraction in the eyes. For instance, if you realize that you are baking certain functionality into every component that you make, it’s probably a good idea to create an intermediary base class, or a mixin, or module export to abstract that repetition, centralize that functionality, and generally enable you to DRY (don’t repeat yourself) up your code. Other times, the benefits of making a solid abstraction are less clear. If something is really only used once in your application, it might be hard to fully sell the benefits of an abstraction (even to yourself, especially after I spent a lot of time telling you to be lazy and separate things only when you need to in previous installations of this glorious adventure we’ve embarked on together), and in these cases it can be useful to think not only about where your application might be making use of this functionality, but where your tests might, as well. (I’ll leave the argument as to whether your tests are part of your app or not to my self-conscious desire to judge every statement in this series. Or, the comments, I still love comments!)

As a refresher, let’s take a look at some testing code that we’ve already spent some time with:

it('adds a to do in response to a `todo-new` event', async () => {
    const newTodo = 'New To Do';
    const el = await fixture(html`<open-wc-app></open-wc-app>`);
    expect(el.shadowRoot.querySelectorAll('to-do').length)
        .to.equal(0);
    el.dispatchEvent(new CustomEvent('todo-new', {
        detail: newTodo,
        bubbles: true,
        composed: true
    }));
    await nextFrame();
    expect(el.todos.length).to.equal(1);
    expect(el.todos[0]).to.equal(newTodo);
    expect(el.shadowRoot.querySelectorAll('to-do').length)
        .to.equal(1);    
    expect(el.shadowRoot.querySelectorAll('to-do')[0].textContent)
        .to.equal(newTodo);
});

In isolation, not that crazy; create a fixture, do a test, create/dispatch a Custom Event, wait a bit, do some more tests. Now, to add context, let’s look at some code from src/to-do-write.js:

newToDo() {
    if (!this.todo) return;
    this.dispatchEvent(new CustomEvent('todo-new', {
        detail: this.todo,
        bubbles: true,
        composed: true
    }));
    this.todo = '';
}

In isolation, also not crazy: check to see if a to-do has been supplied, create/dispatch a Custom Event, clean up the to do. Even side by side you could easily rely on the rule of three as an excuse for not thinking too hard about this. There’s, of course, more...context. Take a look at the listener in src/open-wc-app.js:

this.addEventListener(
    'todo-new',
    (e) => this.addToDo(e.detail)
);

this.addEventListener(
    'todo-complete',
    (e) => this.completeToDo(e.detail)
);

No, this is not a third instance of the code above, but an eagle eye might have spotted the magic string that now resides across all three pieces of code. Tangentially in the land of context, you may also have noticed this code in src/to-do.js:

completeToDo() {
    this.dispatchEvent(new CustomEvent('todo-complete', {
        detail: this.todoId,
        bubbles: true,
        composed: true
    }));
}

As well as this somewhat matching test in test/to-do.test.js:

it('removes a to do in response to a `todo-complete` event', async () => {
    const completeToDo = 'New To Do';
    const el = await fixture(
        html`<open-wc-app
            todos='["${completeToDo}"]'
        ></open-wc-app>`
    );
    expect(el.shadowRoot.querySelectorAll('to-do').length))
        .to.equal(1);
    expect(el.shadowRoot.querySelectorAll('to-do')[0])
        .to.equal(completeToDo);
    expect(el.todos[0]).to.equal(completeToDo);
    el.dispatchEvent(new CustomEvent('todo-complete', {
        detail: completeToDo,
        bubbles: true,
        composed: true
    }));
    await nextFrame();
    expect(el.shadowRoot.querySelectorAll('to-do').length))
        .to.equal(0);
});

So far we’ve seen the emergence of some magic strings that might have been acceptable in the isolation of the application code. However, when they are placed next to their associated tests, and the somewhat magic Custom Events that the strings are found in, our “abstraction needed” bells should be going off. You, your application, and its tests are a little family, and while it certainly took me longer to realize that than it should have, abstractions aren’t for any one part of the family alone! Take a look at how we can abstract some of this away via src/to-do-events.js:

const eventOptions = {
  bubbles: true,
  composed: true,
}

export const toDoEventNames = {
  NEW: 'todo-new',
  COMPLETE: 'todo-complete',
}

const toDoEvent = (todo, event) => {
  return new CustomEvent(event, {
    ...eventOptions,
    detail: todo
  });
}

export const eventCompleteToDo = (todo) => {
  return toDoEvent(todo, toDoEventNames.COMPLETE);
}

export const eventNewToDo = (todo) => {
  return toDoEvent(todo, toDoEventNames.NEW);
}

Now we have those pesky magic strings enumerated via toDoEventNames.COMPLETE, and toDoEventNames.NEW, and our Custom Event creation is sharing most of the operable parts of the process while exposing a helper to for each event to leverage that code. That means a good amount of complexity can be removed from the samples above and we get code like:

newToDo() {
    if (!this.todo) return;
    this.dispatchEvent(eventNewToDo(this.todo));
    this.todo = '';
}

And:

completeToDo() {
    this.dispatchEvent(eventCompleteToDo(this.todoId));
}

Bubbling up to:

this.addEventListener(
    toDoEventNames.NEW,
    (e) => this.addToDo(e.detail)
);

this.addEventListener(
    toDoEventNames.COMPLETE,
    (e) => this.completeToDo(e.detail)
);

Along the way we’ve also reduced maintenance costs, in the case we need to refactor, and future development cost, in the case we add new Custom Events for extended data interactions in the future.

Speaking of data and managing it...you might be interested in checking out the next and last entry in our long-running telenovela.

The Short Game

As voted on by a plurality of people with opinions on such topics that are both forced to see my tweets in their Twitter feed and had a free minute this last week, a 9000+ word article is a no, no.

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

Not Another To-Do App
Getting Started
Test Early, Test Often
Measure Twice, Lint Once
Make it a Component (The intro/outro relationship on these articles could use some componentization...just apply bad joke via the Light DOM.)
Make it a Reusable Part
Does Your Component Really Need to Know That?
Separate Things Early, Often, and Only as Needed
Some Abstractions Aren’t (Just) For Your App (you are here)
Reusable and Scaleable Data Management/And, in the end... (Coming Soon to dev.to)
See the app in action

DEV Community: Westbrook Johnson

Testing with JS is like magic, but is it science?

Last time on "Testing Web Components"

Testing with JS

Interacting with the UI

Interacting with the developer API

The developer API

counter can be set

counter can be increased

element can be clicked

something else

Being less "magic" and more "amazing"

Enter, it screams... I mean, it streams

Keyboard-based interactions

My own haunted house

Enter at your own risk

Testing Web Components with @web/test-runner

Before we get started

The generated project

The <testing-components> element

The tests

Defaults

Interactivity

Customization

Accessibility (a11y)

What have we got?

What's next...

Testing Accessibility with Shadow Roots

Table of contents

Starting from HTML

What and how to test

axe-core

Accessibility tree

Native keyboard events at test time

How should we build it?

Factoring from raw HTML

Wrapper

Decorator

Emitter

The Decorator Pattern Plus

Panelist projects leveraging this technique

Outside-in

ID references DO NOT pass through shadow boundaries

Panelist projects leveraging this technique

Snowflakes

Pretending to be a native element

Responding to the "for" attribute

Observing text content

Panelist projects leveraging this technique

In memoriam

In the next life...

Who doesn't love some ``s?

Help text

<slot/>ing in some help text

Now for the superpowers

All the slots

Stacked slots

What's missing?

How far we've come

Some things to know about Lit

Default Values

So you like Typescript?

Required properties

Event management

styleMap usage

Conclusion

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?

`counter` can be set

`counter` can be increased

The `<testing-components>` element

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

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

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

`dispatchEvent()`

The `detail`s on Custom Events

`composed: true` considered harmful?