Inline Web Components

Inline components are not exactly a new thing. It's just a way for us to agree on a convention to declare a custom element, using what HTML already offers: HTMLTemplateElement template, JavaScript modules, ShadowDOM and CSSStyleSheet.

Different libraries/frameworks have tried to solve the same problem in multiple ways. We want to stop the special ways of doing things, and go back to simple and easy.

Take a few examples:

• VueJS uses single-file components with HTML syntax, but adds : and @ in attributes.
• Angular uses Classes and Decorators, and also adds special [], () and [()] attributes (or was it ([])?).
• React made JSX famous and added more specific syntax as well.
• Alpine and HTMX add very specific syntax to their mental model, which is not easy to remember.

OK, so how do we solve the syntax problem

Well... I don't think we can fully solve the custom syntax problem. But we can choose a predictable mental model instead, with as few additions as possible.

Let's agree on some principles:

• every component follows the same principle: props down and events up.
• the only way a component can change from the outside is with a change in properties
• any change inside a component is propagated up as an event.

With that in mind, let's pick a template convention for our principles: events start with on- and properties with bind-.

Now we can declare what we want:

<custom-element on-event="reaction()" bind-property="value"></custom-element>
Copy

But that's not enough, of course!

We still need to sprinkle some Javascript into our component to make it useful.

Let's look at other Web API's we can use to expand our components.

Web API's we can use today

We have quite a few things to put together before we can fully use the web platform. Here are some of the API's we can explore:

• Custom Elements Registry
• Templates and Slots
• ES Modules
• adopted CSS Stylesheets
• Import Maps
• Abort Controllers
• Shadow DOM and ElementInternals
• CSS parts selector

We will also build on top of concepts previously defined by projects like Angular, VueJS, SolidJS and React.

• Ref
• data binding
• props
• API Composition
• Functional components
• Redux/Store pattern

Narrow Down the Execution Context

Historically, a web page has a shared Javascript execution context, sometimes called "global scope", where all parts of a page must coexist. When pages were mostly text, with barely any Javascript, this was okay.

But the Web evolved, and with it, more complex structures started to emerge. It became harder and harder to maintain with a global context.

We need something in a page to create local variables, declare local event handlers, load modules and manage state. We should also compose with pieces of logic anda data without assigning values to the window object.

Another problem area is styling: we don't want global styles applied everywhere. Sometimes styles must be scoped to a single component.

Custom Elements are one of the building blocks we need to achieve just that. We declare a custom <any-name> tag and let the platform initialize it for us. Inside that context, we can import modules, load stylesheets and run our business completely isolated from the global state.

Declaring Components In HTML

The <template> element provides an API to include HTML in a webpage without rendering it.

This is very useful for us: we can load components just like any other HTML content, then read their content and "hydrate" the HTML with the help of Javascript, of course.

From a template element we use .contents.cloneNode() API to clone the entire template content without modifying the original nodes.

Another important aspect of templates is that scripts and styles are not activated either. We can include a <script> element inside a template and later use that source as a module.

Using <script setup> and <template component> attribute

Now that we know templates, let's expand on that API. A component can be authored in plain HTML, and even inserted into a webpage directly into the source.

Here's what we introduce on top of the standard API:

• add a component attribute to give the custom element a name

<template component="ui-card"></template>
Copy

• optionally, add shadow-dom attribute to specify Shadow DOM API options.

<template component="ui-card" shadow-dom="open"></template>
Copy

• create a <script setup> tag to write the component logic. Use import to load @li3/web and export a setup function:

<script setup>
  export default function () {
    /* */
  }
</script>
Copy

Let's put it all together in a ui-card component:

<template component="ui-card" shadow-dom="open">
  <div class="card">
    <span class="card-title">{{ title }}</span>
    <slot></slot>
  </div>
  <script setup>
    import { defineProp } from '@li3/web';
    export default function uiCard() {
      defineProp('title', '');
    }
  </script>
  <style>
    .card {
      padding: 1rem;
      margin: 1rem auto;
      border-radius: 0.5rem;
      border: 1px solid #ccc;
      background-color: white;
    }
    .card-title {
      color: #999;
      text-transform: uppercase;
      font-size: 0.75rem;
      display: inline-block;
      padding: 0 0 1rem 0;
    }
  </style>
</template>
Copy