10 Things You Are Doing Wrong in your Web Components

import {ZephComponents} from "./Zeph.js";
import {html,css,attribute,property,bind,onCreate,onEvent} from "./zeph.min.js";
ZephComponents.define("my-button",()=>{
html("./my-button.html");
css("./my-button.css");
attribute("icon","");
attribute("icon-placement","left");
attribute("disabled",undefined);

property("clickCount",0);

bind("@icon","button > img","@src");
bind("@disabled","button");

onCreate((element)=>{
    console.log("Element '"+element.getAttribute("name")+"' created!",element);
});

onEvent("click",(event,element)=>{
    element.clickCount += 1;

    console.log("Button '"+element.getAttribute("name")+"' clicked "+element.clickCount+" times.");
});

});

ZephComponents.define("my-widget",()=>{
html(<input type="text"></input>);

// sets tabindex attribute for this component
attribute("tabindex","0");

// forward focus from the component to the internal contents
// input element.
onEvent("focus",(event,element,content)=>{
    let next = content.querySelector("input");
    next.focus();
});

});

The difference between any old Web Component and a professional Web Component often lies in localization. Localization is the ability of a component (or any software for that matter) to be delivered to users of different languages. A Web Component that has some text within it is only localizable if that text can be changed.

For example, say one has a Yes/No component where users can choose between the Yes state and the No state. Here's a simple example in ZephJS:

ZephComponents.define("my-yesno-chooser",()=>{
html(<div class="question"></div> <div class="chooser"> <span class="yes">Yes</span> or <span class="no">No</span> </div>);

attribute("question","");
attribute("value","");

bind("@question",".question","$");

onEventAt(".yes","click",(event,selected,element,content)=>{
    element.setAttribute("value","yes");
});
onEventAt(".no","click",(event,selected,element,content)=>{
    element.setAttribute("value","no");
});

});

In this example, both the "Yes" and the "No" text is not localizable because there is no way for the component user to change it. Also, the separator text of "or" is not localizable. That means if a component user wanted to change "Yes" to "Oui" for his French users they could not without some fancy javascript.

A better solution would be to allow a component attribute to drive what the Yes (or No) text is. Like this:

ZephComponents.define("my-yesno-chooser",()=>{
html(<div class="question"></div> <div class="chooser"> <span class="yes"></span><span class="separator"></span><span class="no"></span> </div>);

attribute("question","");
attribute("yesText","Yes");
attribute("noText","No");
attribute("separator"," or ");
attribute("value","");

bind("@question",".question","$");
bind("@yesText",".yes","$");
bind("@noText",".no","$");
bind("@separator",".separator","$");

onEventAt(".yes","click",(event,selected,element,content)=>{
    element.setAttribute("value","yes");
});
onEventAt(".no","click",(event,selected,element,content)=>{
    element.setAttribute("value","no");
});

});

Notice in this example that one can use that "yesText", "noText", and "separator" attributes to set the text of the component. If these attributes are ommitted, the component falls back to the default english. (One might consider making the default a "1" or "0" to make the component even more localization friendly.)/p><h3><a href="https://gist.github.com/arei/216b7cbfc7cf3557768daaedd27a2349#6-forgetting-about-accessibility"6). Forgetting About Accessibility

Accessibility centers around the ability of users with disabilities to interact with a Web Component. And modern web browser standards have made incredible strides at giving web developers tools to easily add accessibility into their pages. The ARIA work in particular is very useful and compelling.

Yet for some reason, like localization, most Web Component authors spend zero effort on accessibility and this is extremely problematic. If a component does not have the necessary accessibility information and affordances it is ignoring an entire class of users (and even potentially opening themselves up to legal liabilty). And because ARIA is chiefly achieved through element markup and Web Components are not addressable externally, users of a Web Component cannot add accessibility after the fact.

Good Web Component design takes accessibility into account from the start. ARIA attributes are librally used and applied. Keyboard navigation is provided instead of relying solely on mouse navigation. Components are tested against screen readers to ensure that they flow correctly. Indicators are provided not just by color but by other means as well. Also, keep in mind the localization points from above; when using ARIA attributes make sure that they can be localized as well.

You can learn more about Accessibility Best Practices here: https://www.webaccessibility.com/best_practices.php

To give you an example of how bad developers are at accessibility it should be pointed out that not once in any of the examples were there any accessibility examples. We, as a comunity of developers, must strive to do better./p><h3><a href="https://gist.github.com/arei/216b7cbfc7cf3557768daaedd27a2349#7-not-using-slots"7). Not Using Slots

One of the underlying Standards for Web Components is HTML Templates API. Templates enable a key parts of Web Components: slots. Slots allow a Web Componnet to identify a space for the innerHTML of the component to be projected into.

Say we have a Web Component called <my-button>. And using it we write the following HTML:

ZephComponents.define("my-button",()=>{
html(<button></button>);
});

<my-button>
<img src="./my-button-icon.jpg" />
<span>Click Here!</span>
</my-button>

The innerHTML of the <my-button>, the <img> and the <span>, will be lost unless the Web Component specifically offers a <slot> to project into the Web Component. Instead the Web Component should look like this:

ZephComponents.define("my-button",()=>{
html(<button> <slot></slot> </button>);
});

The <slot> element identifies where the innerHTML content is projected. One could bury the <slot> element in fifteen nested <div> tags and that is where the content would be projected. There's a little more to <slot> such as named slots which allow one to project specific parts to specific slots, but that is a topic for some self reading./p><h3><a href="https://gist.github.com/arei/216b7cbfc7cf3557768daaedd27a2349#8-over-engineering"8). Over Engineering

It is easy to envision building a Web Component that does all the amazing things you want it to do. Resist this urge. The more complexity one builds into a component, the more likely it is to be unusable by others.

Instead, consider building simple components and building them well. Makw sure they are localized and accessible, make sure they are flexible and styles cascade into them. Keep them simple.

If the end goal needs a more complicated solution, consider building a set of lower level components and then wrapping them up into the higher component. For example, if one is building a Tab container, build out several components like a Tab Heading, a Tab Body, a Tab Header, and a Tab Page, and bind them altogether into a single Tab component.

Simple components are more testable, more accessible, and better for the end users./p><h3><a href="https://gist.github.com/arei/216b7cbfc7cf3557768daaedd27a2349#9-zip-files"9). Zip Files

Since a primary reason to build a Web Component is to share it with the world, one needs a means to do so. The most common approach for doing this is to put all the files into a Zip File and then tell users how and where to extract it. This usually involves complicated instruction on where the files need to be placed, a bunch of <script> and <link> style loading tags to be inserted, and a whole lot of trail and error by the user to get it all working.

This is messy and cumbersome for Web Developers and often costs them the one resource they dont have enough of: time. Instead, consider some of the techniques one can use in a component (or component library) to get everything down to just one file:

• Inline HTML in the Web Component: This is usually the default case, but in some systems the HTML content can be separated out. This is preferred because it is cleaner, but it also makes it harder on users.

• Inline CSS or just Style In JavaScript: The same goes for CSS. Inline is better for the end users, but harder for the developers. Another common recommendation here is to have an external style sheet and then use an @import inside of the Web Component to do the styling. Do not do this (yet). as it can cause performance and memory degredations in a site. There is a proposal for this in the W3C that is working its way forward, but its still a long way off.

• Inline Assets: Putting assets (images, audio files, videos, etc) directly into a Web Component JS can be done using data: urls, or for images one could use SVGs instead of image files. Either will allow one to put the asset data directly into the component definition thus keeping everything all together.

The ultimate goal is to ship just one file that contains everything for a component or component library. This means there is one import that needs to be done and no complicate directory layouts that need to be managed. It's just plain simple.

Of note, ZephJS, has a nice bundle utility that is built on a href="https://github.com/rollup/rollup"rollup and a href="https://github.com/acornjs/acorn"acorn that does all of this. So one can keep the HTML, CSS, and assets all as separate files and then using the ZephJS bundle utility bundle it all up into a single JS file for distribution. Worth considering./p><h3><a href="https://gist.github.com/arei/216b7cbfc7cf3557768daaedd27a2349#10-not-publically-releasing"10). Not Publically Releasing

Finally, the last mistake most Web Component authors are making is just not releasing their work. One of the entire points of Web Components is reuse. Reuse in web pages and apps and also reuse by others. And this only happens by putting them out there. Please, publish components to npm and get the word out. Share them on webcomponents.org.

Of course this article would be remiss if it did not reiterate everything it just said. So share, but make sure the components are ready to be shared. Make sure they are well design, simple, not overly styled, flexible, localizable, accessable, and small. And then share them with the world.