Declarative HTML resolver

[janechu]

Introduction

Due to popular demand for BTR/SSR solutions, as an alternate approach to using the html tagged template literal this issue outlines the use of a declarative syntax template resolver.

Requires completion of #7036

Requirements

Declarative HTML Template Syntax

The resolver would require an async approach to resolving and attaching the template. This will require a few pieces, the first is the declarative HTML syntax. Once this has been declared on the page for the custom element, it will be added to the element's definition. This template syntax is meant to be able to be interpreted both by JavaScript in the browser, as well as by other languages during BTR/SSR, thus for applying values to create HTML from the template, where JavaScript is not applied we will use JSON and simple data structures.

Below will be an example, as you can see, for browser specific behavior we will keep a JavaScript-like syntax such as with the @click event.

Example HTML:

<f-template name="my-custom-element">
  <template>
      <button @click="{{ x.handleClick() }}" ?disabled="{{ x.disabled}} ">
          {{ x.greeting }}
      </button>
      <input
          :value="{{ x.value }}"
      >
      <f-when value="{{ x.hasFriends }}"><!--we assume the value passed to the condition is a boolean-->
          <ul>
              <f-repeat items="{{ friend in x.friends }}"><!--we assume the items is an array, in this case it might be ["brenda", "james"]-->
                  <li>{{ friend.firstname }} {{ friend.lastname }}</li><!--this now takes the a new context of the individual array item, so this might render as "brenda"-->
              </f-repeat>
          </ul>
      </f-when>
      <f-slotted items="{{ x.items }}">
          <slot></slot>
      </f-slotted>
  </template>
</f-template>

The reason that all directives are tags is because they should be made optional to allow for lighter bundles. If you don't use <f-when> (for example) you can choose not to include it.

html Tagged template version:

html`
    <template>
        <button @click="${x => x.handleClick()}" ?disabled="${x => x.disabled}">
            ${x => x.greeting}
        </button>
        <input
            :value="${x => x.value}"
        >
        ${when(
            x => x.hasFriends
            html`<ul>
                ${repeat(
                    x => x.friends,
                    html`<li>${x => x}</li>`
                )}
            </ul>`
        )}
        <slot ${slotted('items')}></slot>
    </template>
`;

Example JSON:

{
    "disabled": true,
    "greeting": "Hello World",
    "value": 42,
    "hasFriends": true,
    "friends": ["brenda", "james"]
}

This syntax is a close mirroring of how html template uses directives etc. so as not to confuse current consumers of html tagged template literal. We recognize that there are current efforts to create a standard for declarative HTML, but as they have not passed any meaningful stage at this time we will wait until the platforms proceed with a solution before we consider convergence.

One issue with declarative HTML is that we will not be interpreting any JavaScript, the developers will not be able to do anything like the following: <f-when condition="x.friends.length > 0">. This limitation means that we will only allow a variable that will be assumed to be a boolean.

Anything in the JSON data structure is assumed to be either an @attr or property of the custom element class. Therefore, hasFriends for example could be an observed property or a reflected attribute that is assigned in the constructor.

Aspected Attributes

Aspected attributes such as click events, property bindings, and boolean attributes can be represented in a 2 ways, either with a dataset attribute, or if XML 1.0 compliance is not required, with the same syntax as that offered by the html tag template literal. The "fe" identifies the dataset attribute as an event, likewise "fb" is for booleans, and "fp" is for properties.

dataset attribute:

<div data-fe_click="{{ handleClick() }}" data-fb_disabled="{{ disabled }}" data-fp_value="{{ value }}"></div>

html tag template syntax:

<div @click="{{ handleClick() }}" ?disabled="{{ disabled }}" :value="{{ value }}"></div>

Directives

Directives may be represented either with elements or as attributes on elements.

Elements:

<f-when value="{{ !disabled }}">
    <ul></ul>
</f-when>

Attributes:

<ul f-when="{{ !disabled }}"></ul>

Scoping

Scoping depending on configuration should either accept all values as the parent scope or should allow one scope up. Further scoping may be passed down by specific ID.

Current scope:

<button ?disabled="{{ disabled }}">
      {{ greeting }}
</button>

Parent scope:

<button ?disabled="{{ x.disabled }}">
      {{ x.greeting }}
</button>

Additional scoping is applied during f-repeat directives:

<f-repeat items="{{ item in items }}"></f-repeat>

Declarative HTML Template resolver

The second piece is the interpretation by a resolver to provide the ViewTemplate. This should be located on a different export path, per #7036 compose step example.

HTML Rendering

Fully documented examples with explanations will be provided to ensure processing of a Declarative HTML template is understood and can be resolved. FAST expects certain additions to the HTML for it to be hydratable, that includes comments etc.

Example rendering:

<my-custom-element greeting="Hello world" disabled>
    <template shadowrootmode="open">
        <button disabled>
            <!--fe-b$$start$$0$$QYOGJbAbyI$$fe-b-->Hello world<!--fe-b$$end$$0$$QYOGJbAbyI$$fe-b-->
        </button>
        <input
            value="42"
        >
        <!--fe-b$$start$$0$$QYOGJbAbym$$fe-b-->
        <ul>
            <!--fe-b$$start$$0$$QYOGJbAbyn$$fe-b--><li>First</li><!--fe-b$$end$$0$$QYOGJbAbyn$$fe-b-->
            <!--fe-b$$start$$0$$QYOGJbAbyo$$fe-b--><li>Second</li><!--fe-b$$end$$0$$QYOGJbAbyo$$fe-b-->
        </ul>
        <!--fe-b$$end$$0$$QYOGJbAbym$$fe-b-->
        <slot>items 1</slot>
    </template>
</my-custom-element>

What is the flow?

In a build/server environment the HTML generation should work as follows:

flowchart TD
    A[Declarative HTML Template]
    B[FAST BTR Rust Implementation]
    C[JSON state]
    D[HTML]
    E[Browser]
    A --> B
    C --> B
    B --> D
    D --> E

Loading

After the HTML has been loaded, the developer can choose when the <f-template> logic and HTML should be added, typically we would expect the following flow:

flowchart TD
    Z[The page including BTR HTML is recieved from the server]
    Y[TTVR complete]
    A[The declarative HTML template is included in the DOM]
    B[The <code>f-template</code> custom element is imported]
    C[The <code>f-template</code> custom element creates a <code>ViewTemplate</code>]
    D[The <code>ViewTemplate</code> is added as a template to existing FAST Custom Elements]
    E[The FAST Custom Elements with this template hydrates & becomes interactable]
    A --> C
    B --> C
    C --> D
    D --> E
    Y --> A
    Y --> B
    Z --> Y

Loading