@microsoft/fast-html 1.0.0-alpha.11 → 1.0.0-alpha.13

package/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).
+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.

package/dist/dts/components/element.d.ts

@@ -0,0 +1,6 @@
+import { FASTElement } from "@microsoft/fast-element";
+export declare abstract class RenderableFASTElement extends FASTElement {
+    deferHydration: boolean;
+    needsHydration: boolean;
+    constructor();
+}

package/dist/dts/components/index.d.ts

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

package/dist/dts/components/template.d.ts

@@ -1,11 +1,13 @@
 import { FASTElement, ShadowRootOptions } from "@microsoft/fast-element";
+import "@microsoft/fast-element/install-hydratable-view-templates.js";
+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;
 }
 /**
  * The <f-template> custom element that will provide view logic to the element
@@ -18,9 +20,16 @@ declare class TemplateElement extends FASTElement {
     /**
      * A dictionary of custom element options
      */
-    static elementOptions: ElementOptions;
+    static elementOptions: ElementOptionsDictionary;
     private partials;
-    static options(elementOptions?: ElementOptions): typeof TemplateElement;
+    private static defaultElementOptions;
+    static options(elementOptions?: ElementOptionsDictionary): typeof TemplateElement;
+    constructor();
+    /**
+     * Set options for a custom element
+     * @param name - The name of the custom element to set options for.
+     */
+    private static setOptions;
     connectedCallback(): void;
     /**
      * Resolve strings and values from an innerHTML string

package/dist/dts/index.d.ts

@@ -1 +1 @@
-export { TemplateElement } from "./components/index.js";
+export { RenderableFASTElement, TemplateElement } from "./components/index.js";

package/dist/esm/components/element.js

@@ -0,0 +1,25 @@
+import { __decorate, __metadata } from "tslib";
+import { attr, FASTElement, Observable } from "@microsoft/fast-element";
+export class RenderableFASTElement extends FASTElement {
+    constructor() {
+        super();
+        this.deferHydration = true;
+        this.needsHydration = true;
+        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");
+    }
+}
+__decorate([
+    attr({ mode: "boolean", attribute: "defer-hydration" }),
+    __metadata("design:type", Boolean)
+], RenderableFASTElement.prototype, "deferHydration", void 0);
+__decorate([
+    attr({ mode: "boolean", attribute: "needs-hydration" }),
+    __metadata("design:type", Boolean)
+], RenderableFASTElement.prototype, "needsHydration", void 0);

package/dist/esm/components/index.js

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

package/dist/esm/components/template.js

@@ -1,5 +1,6 @@
 import { __awaiter, __decorate, __metadata } from "tslib";
-import { attr, DOMAspect, FAST, FASTElement, fastElementRegistry, ViewTemplate, } from "@microsoft/fast-element";
+import { attr, DOMAspect, FAST, FASTElement, fastElementRegistry, HydratableElementController, ViewTemplate, } from "@microsoft/fast-element";
+import "@microsoft/fast-element/install-hydratable-view-templates.js";
 import { DOMPolicy } from "@microsoft/fast-element/dom-policy.js";
 import { getAllPartials, getExpressionChain, getNextBehavior, pathResolver, resolveWhen, transformInnerHTML, } from "./utilities.js";
 function allow(tagName, aspect, aspectName, sink) {
@@ -11,13 +12,34 @@ function allow(tagName, aspect, aspectName, sink) {
  * The <f-template> custom element that will provide view logic to the element
  */
 class TemplateElement extends FASTElement {
+    static options(elementOptions = {}) {
+        var _a;
+        const result = {};
+        for (const key in elementOptions) {
+            const value = elementOptions[key];
+            result[key] = {
+                shadowOptions: (_a = value.shadowOptions) !== null && _a !== void 0 ? _a : TemplateElement.defaultElementOptions.shadowOptions,
+            };
+        }
+        this.elementOptions = result;
+        HydratableElementController.install();
+        return this;
+    }
     constructor() {
-        super(...arguments);
+        super();
         this.partials = {};
+        if (!!TemplateElement.elementOptions) {
+            TemplateElement.options();
+        }
     }
-    static options(elementOptions = {}) {
-        this.elementOptions = elementOptions;
-        return this;
+    /**
+     * Set options for a custom element
+     * @param name - The name of the custom element to set options for.
+     */
+    static setOptions(name) {
+        if (!!!TemplateElement.elementOptions[name]) {
+            TemplateElement.elementOptions[name] = TemplateElement.defaultElementOptions;
+        }
     }
     connectedCallback() {
         super.connectedCallback();
@@ -25,7 +47,10 @@ class TemplateElement extends FASTElement {
             this.$fastController.definition.registry
                 .whenDefined(this.name)
                 .then((value) => __awaiter(this, void 0, void 0, function* () {
-                var _a;
+                var _a, _b;
+                if (this.name && !!!((_a = TemplateElement.elementOptions) === null || _a === void 0 ? void 0 : _a[this.name])) {
+                    TemplateElement.setOptions(this.name);
+                }
                 const registeredFastElement = fastElementRegistry.getByType(value);
                 const template = this.getElementsByTagName("template").item(0);
                 if (template) {
@@ -38,7 +63,7 @@ class TemplateElement extends FASTElement {
                             this.resolveTemplateOrBehavior(strings, values);
                         // set shadow options as defined by the f-template
                         registeredFastElement.shadowOptions =
-                            (_a = TemplateElement.elementOptions[this.name]) === null || _a === void 0 ? void 0 : _a.shadowOptions;
+                            (_b = TemplateElement.elementOptions[this.name]) === null || _b === void 0 ? void 0 : _b.shadowOptions;
                     }
                 }
                 else {
@@ -92,7 +117,7 @@ class TemplateElement extends FASTElement {
             switch (behaviorConfig.name) {
                 case "when":
                     {
-                        const { strings, values } = yield this.resolveStringsAndValues(innerHTML.slice(behaviorConfig.openingTagEndIndex, behaviorConfig.closingTagStartIndex));
+                        const { strings, values } = yield this.resolveStringsAndValues(innerHTML.slice(behaviorConfig.openingTagEndIndex, behaviorConfig.closingTagStartIndex), self);
                         const { when } = yield import("@microsoft/fast-element");
                         const expressionChain = getExpressionChain(behaviorConfig.value);
                         const whenLogic = resolveWhen(self, expressionChain);
@@ -182,7 +207,7 @@ class TemplateElement extends FASTElement {
                             (closingParenthesis - openingParenthesis) -
                             1);
                         const arg = bindingHTML.slice(openingParenthesis + 1, closingParenthesis);
-                        const binding = (x, c) => pathResolver(propName, self)(x, c)(...(arg === "e" ? [c.event] : []), ...(arg !== "e" && arg !== ""
+                        const binding = (x, c) => pathResolver(propName, self)(x, c).bind(x)(...(arg === "e" ? [c.event] : []), ...(arg !== "e" && arg !== ""
                             ? [pathResolver(arg)(x, c)]
                             : []));
                         values.push(binding);
@@ -252,6 +277,11 @@ class TemplateElement extends FASTElement {
  * A dictionary of custom element options
  */
 TemplateElement.elementOptions = {};
+TemplateElement.defaultElementOptions = {
+    shadowOptions: {
+        mode: "open",
+    },
+};
 __decorate([
     attr,
     __metadata("design:type", String)

package/dist/esm/fixtures/attribute/main.js

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

package/dist/esm/fixtures/binding/main.js

@@ -1,7 +1,7 @@
 import { __decorate, __metadata } from "tslib";
-import { TemplateElement } from "@microsoft/fast-html";
-import { attr, FASTElement } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { attr } from "@microsoft/fast-element";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.text = "Hello";
@@ -13,8 +13,9 @@ __decorate([
 ], TestElement.prototype, "text", void 0);
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-class TestElementUnescaped extends FASTElement {
+class TestElementUnescaped extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.html = `<p>Hello world</p>`;
@@ -24,17 +25,6 @@ TestElementUnescaped.define({
     name: "test-element-unescaped",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-    "test-element-unescaped": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/children/main.js

@@ -1,7 +1,7 @@
 import { __decorate, __metadata } from "tslib";
-import { TemplateElement } from "@microsoft/fast-html";
-import { FASTElement, observable } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { observable } from "@microsoft/fast-element";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.listItems = [];
@@ -20,12 +20,6 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/dot-syntax/main.js

@@ -1,6 +1,5 @@
-import { TemplateElement } from "@microsoft/fast-html";
-import { FASTElement } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.object = {
@@ -12,12 +11,6 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/event/event.spec.js

@@ -25,4 +25,11 @@ test.describe("f-template", () => __awaiter(void 0, void 0, void 0, function* ()
         yield customElement.locator("button").nth(2).click();
         expect(message).toEqual("bar");
     }));
+    test("should properly bind events with `this`", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/event");
+        const customElement = yield page.locator("test-element");
+        yield expect(customElement).toHaveJSProperty("foo", "bar");
+        yield customElement.locator("button").nth(3).click();
+        yield expect(customElement).toHaveJSProperty("foo", "modified-by-click");
+    }));
 }));

package/dist/esm/fixtures/event/main.js

@@ -1,7 +1,7 @@
 import { __decorate, __metadata } from "tslib";
-import { TemplateElement } from "@microsoft/fast-html";
-import { attr, FASTElement } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { attr } from "@microsoft/fast-element";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.foo = "";
@@ -15,6 +15,9 @@ class TestElement extends FASTElement {
             console.log(foo);
         };
     }
+    handleModifyAttributeClick() {
+        this.foo = "modified-by-click";
+    }
 }
 __decorate([
     attr,
@@ -24,12 +27,6 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/partial/main.js

@@ -27,12 +27,6 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/ref/main.js

@@ -1,6 +1,5 @@
-import { TemplateElement } from "@microsoft/fast-html";
-import { FASTElement } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.video = null;
@@ -10,12 +9,6 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/repeat/main.js

@@ -1,7 +1,7 @@
 import { __decorate, __metadata } from "tslib";
-import { TemplateElement } from "@microsoft/fast-html";
-import { FASTElement, observable } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { observable } from "@microsoft/fast-element";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.list = ["Foo", "Bar"];
@@ -16,12 +16,29 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+class TestElementInnerWhen extends RenderableFASTElement {
+    constructor() {
+        super(...arguments);
+        this.list = [
+            {
+                show: true,
+                text: "Foo",
+            },
+            {
+                show: false,
+                text: "Bar",
+            },
+        ];
+    }
+}
+__decorate([
+    observable,
+    __metadata("design:type", Array)
+], TestElementInnerWhen.prototype, "list", void 0);
+TestElementInnerWhen.define({
+    name: "test-element-inner-when",
+    shadowOptions: null,
+});
+TemplateElement.define({
     name: "f-template",
 });

package/dist/esm/fixtures/repeat/repeat.spec.js

@@ -26,4 +26,11 @@ test.describe("f-template", () => __awaiter(void 0, void 0, void 0, function* ()
         expect(yield customElementListItems.nth(1).textContent()).toEqual("B - Bat");
         expect(yield customElementListItems.nth(2).textContent()).toEqual("C - Bat");
     }));
+    test("create a repeat directive with an inner when", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/repeat");
+        const customElement = yield page.locator("test-element-inner-when");
+        let customElementListItems = yield customElement.locator("li");
+        expect(yield customElementListItems.count()).toEqual(1);
+        expect(yield customElementListItems.nth(0).textContent()).toEqual("Foo");
+    }));
 }));

package/dist/esm/fixtures/slotted/main.js

@@ -1,7 +1,7 @@
 import { __decorate, __metadata } from "tslib";
-import { TemplateElement } from "@microsoft/fast-html";
-import { FASTElement, observable } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { observable } from "@microsoft/fast-element";
+class TestElement extends RenderableFASTElement {
     constructor() {
         super(...arguments);
         this.slottedNodes = [];
@@ -18,12 +18,6 @@ TestElement.define({
     name: "test-element",
     shadowOptions: null,
 });
-TemplateElement.options({
-    "test-element": {
-        shadowOptions: {
-            mode: "closed",
-        },
-    },
-}).define({
+TemplateElement.define({
     name: "f-template",
 });