Add a RenderableFASTElement and default shadow options (#7126)

# Pull Request

## 📖 Description

This change:
- Requires that using `@microsoft/fast-html` rendered markup include hydratable markup.
- Adds default shadowOptions so they do not need to be passed
- Adds a `RenderableFASTElement` export which will automatically add and remove the `defer-hydration` attributes

## ✅ Checklist

### General

<!--- Review the list and put an x in the boxes that apply. -->

- [x] I have included a change request file using `$ npm run change`
- [ ] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.
- [x] I have read the [CONTRIBUTING](https://github.com/microsoft/fast/blob/main/CONTRIBUTING.md) documentation and followed the [standards](https://github.com/microsoft/fast/blob/main/CODE_OF_CONDUCT.md#our-standards) for this project.

Author: janechu

change/@microsoft-fast-html-f2182c6e-460a-4b78-9b2d-32177d0d098e.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Add a RenderableFASTElement and default shadow options",
+  "packageName": "@microsoft/fast-html",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

packages/web-components/fast-html/README.md

@@ -30,20 +30,14 @@ MyCustomElement.define({
     shadowOptions: null,
 });
 
-TemplateElement.options({
-    "my-custom-element": {
-        shadowOptions: {
-            mode: "closed",
-        }
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });
 ```
 
 This will include the `<f-template>` custom element and all logic for interpreting the declarative HTML syntax for a FAST web component as well as the `shadowOptions` for any element an `<f-template>` has been used to define.
 
-It is necessary to set the initial `shadowOptions` of your custom elements to `null` otherwise a shadowRoot will be attached and cause a FOUC (Flash Of Unstyled Content). For more information about how this affects hydration, check out our [document](./RENDERING.md#setting-shadow-options) on rendering DOM from non-browser.
+It is necessary to set the initial `shadowOptions` of your custom elements to `null` otherwise a shadowRoot will be attached and cause a FOUC (Flash Of Unstyled Content). For more information about how this affects hydration, check out our [document](./RENDERING.md#setting-shadow-options) on rendering DOM from a non-browser environment.
 
 The template must be wrapped in `<f-template name="[custom-element-name]"><template>[template logic]</template></f-template>` with a `name` attribute for the custom elements name, and the template logic inside.
 
@@ -59,6 +53,50 @@ Example:
 </f-template>
 ```
 
+#### Non-browser HTML rendering
+
+One of the benefits of FAST declarative HTML templates is that the server can be stack agnostic as JavaScript does not need to be interpreted. By default `@microsoft/fast-html` will expect hydratable content and uses comments and datasets for tracking the binding logic. For more information on what that markup should look like, as well as an example of how initial state may be applied, read our [documentation](./RENDERING.md) to understand what markup should be generated for a hydratable experience. For the sake of brevity hydratable markup will be excluded from the README.
+
+#### Adding shadowOptions
+
+By default `shadowOptions` via the `TemplateElement` will be with `"mode": "open"` once the template has been set. To set each components `shadowOptions` you can pass an `options` object.
+
+Example:
+
+```typescript
+TemplateElement.options({
+    "my-custom-element": {
+        shadowOptions: {
+            mode: "closed",
+        }
+    },
+}).define({
+    name: "f-template",
+});
+```
+
+#### Using the RenderableFASTElement
+
+The exported abstract class `RenderableFASTElement` is available for automatic addition and removal of `defer-hydration` and `needs-hydration`. If you use `FASTElement` you will need to add `defer-hydration` and `needs-hydration` attributes to your rendered markup and remove them via your component.
+
+Example:
+```typescript
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+
+class MyCustomElement extends RenderableFASTElement {
+    // component logic
+}
+
+MyCustomElement.define({
+    name: "my-custom-element",
+    shadowOptions: null,
+});
+
+TemplateElement.define({
+    name: "f-template",
+});
+```
+
 ### Syntax
 
 All bindings use a handlebars-like syntax.
@@ -217,10 +255,6 @@ If your template includes JavaScript specific logic that does not conform to tho
 - `@microsoft/fast-html/rules/member-expression.yml`
 - `@microsoft/fast-html/rules/tag-function-to-template-literal.yml`
 
-### Non-browser HTML rendering
-
-One of the benefits of FAST declarative HTML templates is that the server can be stack agnostic as JavaScript does not need to be interpreted. FASTElement will expect hydratable content however and uses comments and datasets for tracking the binding logic. For more information on what that markup should look like, as well as an example of how initial state may be applied, read our [documentation](./RENDERING.md) to understand what markup should be generated for a hydratable experience.
-
 ## Acknowledgements
 
 This project has been heavily inspired by [Handlebars](https://handlebarsjs.com/) and [Vue.js](https://vuejs.org/).

packages/web-components/fast-html/RENDERING.md

@@ -160,13 +160,7 @@ TemplateElement.options({
 
 ## Hydration Comments and Datasets
 
-When hydrating the HTML FAST uses the `HydratableElementController` which can be included in your bundle like so:
-
-```typescript
-import "@microsoft/fast-element/install-element-hydration.js";
-```
-
-The `HydratableElementController` will take over from the `ElementController` to use hydration "markers" such as comments and dataset attributes to rationalize bindings with existing HTML.
+When hydrating the HTML, FAST uses the `HydratableElementController` which will take over from the `ElementController` to use hydration "markers" such as comments and dataset attributes to rationalize bindings with existing HTML. By default the `@microsoft/fast-html` package will assume that component hydration will occur so rendering hydratable markup is required.
 
 ### Bindings
 

packages/web-components/fast-html/docs/api-report.api.md

@@ -7,15 +7,25 @@
 import { FASTElement } from '@microsoft/fast-element';
 import { ShadowRootOptions } from '@microsoft/fast-element';
 
+// @public (undocumented)
+export abstract class RenderableFASTElement extends FASTElement {
+    constructor();
+    // (undocumented)
+    deferHydration: boolean;
+    // (undocumented)
+    needsHydration: boolean;
+}
+
 // @public
 export class TemplateElement extends FASTElement {
+    constructor();
     // (undocumented)
     connectedCallback(): void;
-    // Warning: (ae-forgotten-export) The symbol "ElementOptions" needs to be exported by the entry point index.d.ts
-    static elementOptions: ElementOptions;
+    // Warning: (ae-forgotten-export) The symbol "ElementOptionsDictionary" needs to be exported by the entry point index.d.ts
+    static elementOptions: ElementOptionsDictionary;
     name?: string;
     // (undocumented)
-    static options(elementOptions?: ElementOptions): typeof TemplateElement;
+    static options(elementOptions?: ElementOptionsDictionary): typeof TemplateElement;
 }
 
 // (No @packageDocumentation comment for this package)

packages/web-components/fast-html/src/components/element.ts

@@ -0,0 +1,27 @@
+import { attr, FASTElement, Observable } from "@microsoft/fast-element";
+
+export abstract class RenderableFASTElement extends FASTElement {
+    @attr({ mode: "boolean", attribute: "defer-hydration" })
+    deferHydration: boolean = true;
+
+    @attr({ mode: "boolean", attribute: "needs-hydration" })
+    needsHydration: boolean = true;
+
+    constructor() {
+        super();
+
+        this.setAttribute("defer-hydration", "");
+        this.setAttribute("needs-hydration", "");
+
+        Observable.defineProperty(this.$fastController.definition, "shadowOptions");
+
+        Observable.getNotifier(this.$fastController.definition).subscribe(
+            {
+                handleChange: () => {
+                    this.deferHydration = false;
+                },
+            },
+            "shadowOptions"
+        );
+    }
+}

packages/web-components/fast-html/src/components/index.ts

@@ -1 +1,2 @@
 export { TemplateElement } from "./template.js";
+export { RenderableFASTElement } from "./element.js";

packages/web-components/fast-html/src/components/template.ts

@@ -6,9 +6,11 @@ import {
     FASTElement,
     FASTElementDefinition,
     fastElementRegistry,
+    HydratableElementController,
     ShadowRootOptions,
     ViewTemplate,
 } from "@microsoft/fast-element";
+import "@microsoft/fast-element/install-hydratable-view-templates.js";
 import { DOMPolicy } from "@microsoft/fast-element/dom-policy.js";
 import { Message } from "../interfaces.js";
 import {
@@ -40,13 +42,15 @@ function allow(
     };
 }
 
+export interface ElementOptions {
+    shadowOptions?: ShadowRootOptions | undefined;
+}
+
 /**
  * A dictionary of element options the TemplateElement will use to update the registered element
  */
-interface ElementOptions {
-    [key: string]: {
-        shadowOptions: ShadowRootOptions | undefined;
-    };
+export interface ElementOptionsDictionary<ElementOptionsType = ElementOptions> {
+    [key: string]: ElementOptionsType;
 }
 
 /**
@@ -62,23 +66,64 @@ class TemplateElement extends FASTElement {
     /**
      * A dictionary of custom element options
      */
-    public static elementOptions: ElementOptions = {};
+    public static elementOptions: ElementOptionsDictionary = {};
 
     private partials: { [key: string]: ViewTemplate } = {};
 
-    public static options(elementOptions: ElementOptions = {}) {
-        this.elementOptions = elementOptions;
+    private static defaultElementOptions: ElementOptions = {
+        shadowOptions: {
+            mode: "open",
+        },
+    };
+
+    public static options(elementOptions: ElementOptionsDictionary = {}) {
+        const result: ElementOptionsDictionary = {};
+
+        for (const key in elementOptions) {
+            const value = elementOptions[key];
+            result[key] = {
+                shadowOptions:
+                    value.shadowOptions ??
+                    TemplateElement.defaultElementOptions.shadowOptions,
+            };
+        }
+
+        this.elementOptions = result;
+
+        HydratableElementController.install();
 
         return this;
     }
 
+    constructor() {
+        super();
+
+        if (!!TemplateElement.elementOptions) {
+            TemplateElement.options();
+        }
+    }
+
+    /**
+     * Set options for a custom element
+     * @param name - The name of the custom element to set options for.
+     */
+    private static setOptions(name: string): void {
+        if (!!!TemplateElement.elementOptions[name]) {
+            TemplateElement.elementOptions[name] = TemplateElement.defaultElementOptions;
+        }
+    }
+
     connectedCallback(): void {
         super.connectedCallback();
 
         if (this.name) {
             this.$fastController.definition.registry
                 .whenDefined(this.name)
                 .then(async value => {
+                    if (this.name && !!!TemplateElement.elementOptions?.[this.name]) {
+                        TemplateElement.setOptions(this.name);
+                    }
+
                     const registeredFastElement: FASTElementDefinition | undefined =
                         fastElementRegistry.getByType(value);
                     const template = this.getElementsByTagName("template").item(0);

packages/web-components/fast-html/src/fixtures/attribute/attribute.fixture.html

@@ -6,7 +6,9 @@
     </head>
     <body>
         <test-element type="checkbox">
-            <template shadowrootmode="open"><input type="checkbox" disabled></template>
+            <template shadowrootmode="open">
+                <input disabled data-fe-b-0 type="checkbox">
+            </template>
         </test-element>
         <f-template name="test-element">
             <template><input type="{{type}}" disabled></template>

packages/web-components/fast-html/src/fixtures/attribute/main.ts

@@ -1,7 +1,7 @@
-import { TemplateElement } from "@microsoft/fast-html";
-import { attr, FASTElement } from "@microsoft/fast-element";
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { attr } from "@microsoft/fast-element";
 
-class TestElement extends FASTElement {
+class TestElement extends RenderableFASTElement {
     @attr
     type: string = "radio";
 }
@@ -10,12 +10,6 @@ TestElement.define({
     shadowOptions: null,
 });
 
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

packages/web-components/fast-html/src/fixtures/binding/binding.fixture.html

@@ -6,10 +6,14 @@
     </head>
     <body>
         <test-element text="Hello world">
-            <template shadowrootmode="open">Hello world</template>
+            <template shadowrootmode="open">
+                <!--fe-b$$start$$0$$ZJEYduCZlM$$fe-b-->Hello world<!--fe-b$$end$$0$$ZJEYduCZlM$$fe-b-->
+            </template>
         </test-element>
         <test-element-unescaped>
-            <template shadowrootmode="open"><p>Hello world</p></template>
+            <template shadowrootmode="open">
+                <div><p><!--fe-b$$start$$0$$ZJEYduCZlM$$fe-b-->Hello world<!--fe-b$$end$$0$$ZJEYduCZlM$$fe-b--></p></div>
+            </template>
         </test-element-unescaped>
         <f-template name="test-element">
             <template>{{text}}</template>