Provide examples of using web components with bindings

[alexeyraspopov]

This PR implements a bunch of integration specs that can serve as an example of using custom elements with our bindings library. This suppose to be the path of least resistance to get into component-based UI development wherever the complexity requires, still without switching to full fledged UI framework. Keeping things lightweight and using the platform as far as we can feasibly do.

Framework component vs web component

A framework's component (React, Vue) is not the same as Web component. A framework component mainly about separating knowledge/structure based on application domain. Web component is a set of different technologies that allow building reusable custom elements. Custom elements by themselves is also another particular API in the web platform that allows defining HTML elements with custom behavior. Dynamic behavior can be based on user events, changing attributes, etc. It can be anything inside of it, but the application of custom elements remains the same, anywhere. This is the important part of web components, comparing to a framework components.

We are going to use custom elements, Shadow DOM, and inertial to define what a custom component is. It is going to be a structure, a pattern we can follow to build isolated components based on our domain (e.g. smaller reusable parts of a large complex form).

Custom component and its lifecycle

Here's briefly the structure I've used in this PR:

import { ObservableScope } from "inertial";
import { applyBindings, html } from "./bindings";

// Using custom elements, we define custom component as a class that extends HTMLElement
// On the inside, it behaves just like another class
// Custom elements provide certain methods that can be defined to react on host events: element attached/detached, attributes changed
class CustomComponent extends HTMLElement {
  // Each instance of a custom component going to have its own scope for reactive values so they don't interfere
  os = ObservableScope();
  
  // Using the scope, we define internal state in the same way we define a View Model
  internalState = this.os.signal(/* initial state */);

  // The parent scope needs a way to pass data down to a custom component
  // Here we use property setters so any kind of data can be passed, unlike attributes that only handle strings
  // Following setter triggers when you do `element.someValue = ...` 
  //   which is what happens when you bind `data-prop-some-value="..."`
  set someValue(value) {
    // Triggering changes in internal state is how we update the component based on what the parent scope needs
    this.internalState(value);
  }

  // Since the class context is being used as View Model for its own template bindings,
  // we can define custom methods to describe certain behaviors outside of the template
  someMethod() {
    // We can use custom events to trigger reaction in the parent scope
    //   that can bind to the event e.g. `data-on-something="this.handle(event.detail)"`
    this.dispatchEvent(new CustomEvent("something", { detail: info }));
  }

  // To make it easier to navigate, I defined the component's template as a separate property
  // It uses JS template strings for convenient multiline editing 
  // `html` tag (imported from bindings module) does nothing in runtime, but can enable HTML syntax highlight
  template = html`
    <p data-text="this.internalState()"></p>
    <button data-on-click="this.someMethod()"></button>
  `

  // This part is what makes everything work
  // This method is triggered by the browser when the custom element is attached to the page
  connectedCallback() {
    // Here we hide the internal template from the parent scope, so parent bindings don't see internal template
    const shadow = this.attachShadow({ mode: "open" });
    // The shadow DOM of an element receives the template defined earlier
    shadow.innerHTML = this.template;
    // And gets bindings applied, using the instance of the class as view model
    applyBindings(shadow, this.os, this);
  }
}

// Here we register the class we implement as a custom HTML element so it can be used in a parent template
customElements.define("custom-component", CustomComponent);

HTML in JS syntax highlight

Now that we put HTML template directly in JS/TS file and it's not JSX, it becomes harder to work with the code, since it is just a template string in terms of JS. In this PR I tagged the templates with html so that it can trigger certain setups and IDEs to treat the contents of following string as HTML. It also works on GitHub! Not sure if vscode suppose to support this by default, but if not, you can use es6-string-html vscode extension to enable this feature.

[noeldevelops]

🫧