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.

Example:

<f-template name="my-custom-element">
    <template>
        <button @click="x.handleClick()" ?disabled="x.disabled">
            ${x.greeting}
        </button>
        <input
            :value="x.value"
        >
        <f-when condition="x.hasFriends()">
            <ul>
                <f-repeat items="x.friends">
                    <li>${x.friend}</li>
                </f-repeat>
            </ul>
        </f-when>
        <slot>
            <f-slotted :items="x.items"></f-slotted>
        </slot>
    </template>
</f-template>

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 function execution from the custom element, or access to attrs/properties.

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.

Pre-Hydration

Part of how the underlying hydration works is the assignment of unique ids for each function call inside an html tagged template. As this happens in a JS environment, we intend to require any BTR/SSR (Build Time Rendering/Server Side Rendering) to add comments which will then be updated during a pre-hydration step.

Example before pre-hydration:

<my-custom-element greeting="Hello world" disabled>
    <template shadowrootmode="open">
        <button disabled>
            <!--f-start-->Hello world<!--f-end-->
        </button>
        <input
            value="42"
        >
        <!--f-start-->
        <ul>
            <!--f-start--><li>First</li><!--f-end-->
            <!--f-start--><li>Second</li><!--f-end-->
        </ul>
        <!--f-end-->
        <slot>items 1</slot>
    </template>
</my-custom-element>

Example after pre-hydration:

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