@microsoft/fast-html 1.0.0-alpha.7 → 1.0.0-alpha.9

package/README.md

@@ -23,13 +23,27 @@ In your JS bundle you will need to include the `@microsoft/fast-html` package:
 
 ```typescript
 import { TemplateElement } from "@microsoft/fast-html";
+import { MyCustomElement } from "./my-custom-element";
 
-TemplateElement.define({
+MyCustomElement.define({
+    name: "my-custom-element",
+    shadowOptions: null,
+});
+
+TemplateElement.options({
+    "my-custom-element": {
+        shadowOptions: {
+            mode: "closed",
+        }
+    },
+}).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.
+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).
 
 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.
 
@@ -162,10 +176,47 @@ Where the right operand can be either a reference to a value (string e.g. `{{foo
     <f-apply partial="test" value="{{items}}"></f-apply>
     ```
 
+#### Unescaped HTML
+
+You can add unescaped HTML using triple braces, this will create an additional `div` element as the HTML needs an element to bind to. Where possible it is advisable to not use unescaped HTML and instead use other binding techniques as well as partials.
+
+Example:
+```html
+{{{html}}}
+```
+
 ### Writing Components
 
 When writing components with the intention of using the declarative HTML syntax, it is imperative that components are written with styling and rendering of the component to be less reliant on any JavaScript state management. An example of this is relying on `elementInterals` state to style a component.
 
+### Converting Components
+
+FAST Components written using the `html` tag template literal can be partially converted via the supplied `.yml` rules made for use with [ast-grep](https://ast-grep.github.io/).
+
+Example:
+
+```ts
+// before
+export const template = html`
+    <slot ${slotted("slottedNodes")}></slot>
+`;
+// after
+export const template = `
+    <slot f-slotted="{slottedNodes}"></slot>
+`;
+```
+
+Which creates a starting point for converting the tag template literals to the declarative HTML syntax.
+
+If your template includes JavaScript specific logic that does not conform to those rules, the fix may not be applied or may apply incorrectly. It is therefore suggested that complex logic instead leverages the custom elements JavaScript class.
+
+#### Available Rules
+
+- `@microsoft/fast-html/rules/attribute-directive.yml`
+- `@microsoft/fast-html/rules/call-expression-with-event-argument.yml`
+- `@microsoft/fast-html/rules/member-expression.yml`
+- `@microsoft/fast-html/rules/tag-function-to-template-literal.yml`
+
 ## Acknowledgements
 
 This project has been heavily inspired by [Handlebars](https://handlebarsjs.com/) and [Vue.js](https://vuejs.org/).

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

@@ -1,4 +1,12 @@
-import { FASTElement } from "@microsoft/fast-element";
+import { FASTElement, ShadowRootOptions } from "@microsoft/fast-element";
+/**
+ * A dictionary of element options the TemplateElement will use to update the registered element
+ */
+interface ElementOptions {
+    [key: string]: {
+        shadowOptions: ShadowRootOptions | undefined;
+    };
+}
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
@@ -7,7 +15,12 @@ declare class TemplateElement extends FASTElement {
      * The name of the custom element this template will be applied to
      */
     name?: string;
+    /**
+     * A dictionary of custom element options
+     */
+    static elementOptions: ElementOptions;
     private partials;
+    static options(elementOptions?: ElementOptions): typeof TemplateElement;
     connectedCallback(): void;
     /**
      * Resolve strings and values from an innerHTML string

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

@@ -101,4 +101,11 @@ interface OperatorConfig {
  * @returns Operator
  */
 export declare function getOperator(value: string): OperatorConfig;
+/**
+ * This is the transform utility for rationalizing declarative HTML syntax
+ * with bindings in the ViewTemplate
+ * @param innerHTML The innerHTML to transform
+ * @param index The index to start the current slice of HTML to evaluate
+ */
+export declare function transformInnerHTML(innerHTML: string, index?: number): string;
 export {};

package/dist/esm/components/template.js

@@ -1,7 +1,12 @@
 import { __awaiter, __decorate, __metadata } from "tslib";
-import { attr, FAST, FASTElement, fastElementRegistry, ViewTemplate, } from "@microsoft/fast-element";
+import { attr, DOMAspect, FAST, FASTElement, fastElementRegistry, ViewTemplate, } from "@microsoft/fast-element";
 import { DOMPolicy } from "@microsoft/fast-element/dom-policy.js";
-import { getAllPartials, getNextBehavior, getOperator, pathResolver, } from "./utilities.js";
+import { getAllPartials, getNextBehavior, getOperator, pathResolver, transformInnerHTML, } from "./utilities.js";
+function allow(tagName, aspect, aspectName, sink) {
+    return (target, name, value, ...rest) => {
+        sink(target, name, value, ...rest);
+    };
+}
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
@@ -10,21 +15,30 @@ class TemplateElement extends FASTElement {
         super(...arguments);
         this.partials = {};
     }
+    static options(elementOptions = {}) {
+        this.elementOptions = elementOptions;
+        return this;
+    }
     connectedCallback() {
         super.connectedCallback();
         if (this.name) {
             this.$fastController.definition.registry
                 .whenDefined(this.name)
                 .then((value) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
                 const registeredFastElement = fastElementRegistry.getByType(value);
                 const template = this.getElementsByTagName("template").item(0);
                 if (template) {
-                    yield this.resolveAllPartials(this.innerHTML);
-                    const { strings, values } = yield this.resolveStringsAndValues(this.innerHTML);
+                    const innerHTML = yield transformInnerHTML(this.innerHTML);
+                    yield this.resolveAllPartials(innerHTML);
+                    const { strings, values } = yield this.resolveStringsAndValues(innerHTML);
                     if (registeredFastElement) {
                         // all new elements will get the updated template
                         registeredFastElement.template =
                             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;
                     }
                 }
                 else {
@@ -56,7 +70,15 @@ class TemplateElement extends FASTElement {
      * @param values - The interpreted values.
      */
     resolveTemplateOrBehavior(strings, values) {
-        return ViewTemplate.create(strings, values, DOMPolicy.create());
+        return ViewTemplate.create(strings, values, DOMPolicy.create({
+            guards: {
+                aspects: {
+                    [DOMAspect.property]: {
+                        innerHTML: allow,
+                    },
+                },
+            },
+        }));
     }
     /**
      * Resolve a template directive
@@ -280,6 +302,10 @@ class TemplateElement extends FASTElement {
         });
     }
 }
+/**
+ * A dictionary of custom element options
+ */
+TemplateElement.elementOptions = {};
 __decorate([
     attr,
     __metadata("design:type", String)

package/dist/esm/components/utilities.js

@@ -8,6 +8,10 @@ const openTagStart = "<f-";
 const tagEnd = ">";
 const closeTagStart = "</f-";
 const attributeDirectivePrefix = "f-";
+const startInnerHTMLDiv = `<div :innerHTML="{{`;
+const startInnerHTMLDivLength = startInnerHTMLDiv.length;
+const endInnerHTMLDiv = `}}"></div>`;
+const endInnerHTMLDivLength = endInnerHTMLDiv.length;
 /**
  * Get the index of the next matching tag
  * @param openingTagStartSlice - The slice starting from the opening tag
@@ -335,3 +339,32 @@ export function getOperator(value) {
         rightIsValue: null,
     };
 }
+/**
+ * This is the transform utility for rationalizing declarative HTML syntax
+ * with bindings in the ViewTemplate
+ * @param innerHTML The innerHTML to transform
+ * @param index The index to start the current slice of HTML to evaluate
+ */
+export function transformInnerHTML(innerHTML, index = 0) {
+    const sliceToEvaluate = innerHTML.slice(index);
+    const nextBinding = getNextBehavior(sliceToEvaluate);
+    let transformedInnerHTML = innerHTML;
+    if (nextBinding && nextBinding.type === "dataBinding") {
+        if (nextBinding.bindingType === "unescaped") {
+            transformedInnerHTML = `${innerHTML.slice(0, index)}${sliceToEvaluate.slice(0, nextBinding.openingStartIndex)}${startInnerHTMLDiv}${sliceToEvaluate.slice(nextBinding.openingStartIndex + 3, nextBinding.closingStartIndex)}${endInnerHTMLDiv}${sliceToEvaluate.slice(nextBinding.closingStartIndex + 3)}`;
+            return transformInnerHTML(transformedInnerHTML, index +
+                startInnerHTMLDivLength +
+                endInnerHTMLDivLength +
+                nextBinding.closingStartIndex -
+                3);
+        }
+        else if (nextBinding.bindingType === "client") {
+            return transformInnerHTML(transformedInnerHTML, index + nextBinding.closingEndIndex);
+        }
+        return transformInnerHTML(transformedInnerHTML, index + nextBinding.closingStartIndex - 2);
+    }
+    else if (nextBinding) {
+        return transformInnerHTML(transformedInnerHTML, index + nextBinding.closingTagEndIndex);
+    }
+    return transformedInnerHTML;
+}

package/dist/esm/components/utilities.spec.js

@@ -1,6 +1,6 @@
 import { __awaiter } from "tslib";
 import { expect, test } from "@playwright/test";
-import { getNextBehavior, getAllPartials, getIndexOfNextMatchingTag, pathResolver } from "./utilities.js";
+import { getNextBehavior, getAllPartials, getIndexOfNextMatchingTag, pathResolver, transformInnerHTML } from "./utilities.js";
 test.describe("utilities", () => __awaiter(void 0, void 0, void 0, function* () {
     test.describe("content", () => __awaiter(void 0, void 0, void 0, function* () {
         test("get the next content binding", () => __awaiter(void 0, void 0, void 0, function* () {
@@ -166,4 +166,21 @@ test.describe("utilities", () => __awaiter(void 0, void 0, void 0, function* ()
             expect(pathResolver("../foo")({}, { parent: { foo: "bar" } })).toEqual("bar");
         }));
     }));
+    test.describe("transformInnerHTML", () => __awaiter(void 0, void 0, void 0, function* () {
+        test("should resolve a single unescaped data binding", () => __awaiter(void 0, void 0, void 0, function* () {
+            expect(transformInnerHTML(`{{{html}}}`)).toEqual(`<div :innerHTML="{{html}}"></div>`);
+        }));
+        test("should resolve multiple unescaped data bindings", () => __awaiter(void 0, void 0, void 0, function* () {
+            expect(transformInnerHTML(`{{{foo}}}{{{bar}}}`)).toEqual(`<div :innerHTML="{{foo}}"></div><div :innerHTML="{{bar}}"></div>`);
+        }));
+        test("should resolve a unescaped data bindings in a mix of other data content bindings", () => __awaiter(void 0, void 0, void 0, function* () {
+            expect(transformInnerHTML(`{{text1}}{{{foo}}}{{text2}}{{{bar}}}{{text3}}`)).toEqual(`{{text1}}<div :innerHTML="{{foo}}"></div>{{text2}}<div :innerHTML="{{bar}}"></div>{{text3}}`);
+        }));
+        test("should resolve a unescaped data bindings in a mix of other data attribute bindings and nesting", () => __awaiter(void 0, void 0, void 0, function* () {
+            expect(transformInnerHTML(`<div data-foo="{{text1}}">{{{foo}}}</div><div data-bar="{{text2}}"></div>{{{bar}}}<div data-bat="{{text3}}"></div>`)).toEqual(`<div data-foo="{{text1}}"><div :innerHTML="{{foo}}"></div></div><div data-bar="{{text2}}"></div><div :innerHTML="{{bar}}"></div><div data-bat="{{text3}}"></div>`);
+        }));
+        test("should resolve a non-data and non-attribute bindings", () => __awaiter(void 0, void 0, void 0, function* () {
+            expect(transformInnerHTML(`<button @click="{handleNoArgsClick()}">No arguments</button>`)).toEqual(`<button @click="{handleNoArgsClick()}">No arguments</button>`);
+        }));
+    }));
 }));

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

@@ -13,7 +13,14 @@ __decorate([
 ], TestElement.prototype, "type", void 0);
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -14,4 +14,10 @@ test.describe("f-template", () => __awaiter(void 0, void 0, void 0, function* ()
         yield expect(yield customElement.getAttribute("text")).toEqual("Hello pluto");
         yield expect(customElement).toHaveText("Hello pluto");
     }));
+    test("create an unescaped binding", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
+        yield page.goto("/binding");
+        const customElement = yield page.locator("test-element-unescaped");
+        yield expect(yield customElement.locator("p").count()).toEqual(1);
+        yield expect(customElement).toHaveText("Hello world");
+    }));
 }));

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

@@ -14,6 +14,27 @@ __decorate([
 TestElement.define({
     name: "test-element",
 });
-TemplateElement.define({
+class TestElementUnescaped extends FASTElement {
+    constructor() {
+        super(...arguments);
+        this.html = `<p>Hello world</p>`;
+    }
+}
+TestElementUnescaped.define({
+    name: "test-element-unescaped",
+    shadowOptions: null,
+});
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-unescaped": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -18,7 +18,14 @@ __decorate([
 ], TestElement.prototype, "list", void 0);
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -10,7 +10,14 @@ class TestElement extends FASTElement {
 }
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -22,7 +22,14 @@ __decorate([
 ], TestElement.prototype, "foo", void 0);
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -25,7 +25,14 @@ class TestElement extends FASTElement {
 }
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -8,7 +8,14 @@ class TestElement extends FASTElement {
 }
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -14,7 +14,14 @@ __decorate([
 ], TestElement.prototype, "list", void 0);
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -16,7 +16,14 @@ __decorate([
 ], TestElement.prototype, "slottedNodes", void 0);
 TestElement.define({
     name: "test-element",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });

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

@@ -140,7 +140,59 @@ __decorate([
 ], TestElementAnd.prototype, "thatVar", void 0);
 TestElementAnd.define({
     name: "test-element-and",
+    shadowOptions: null,
 });
-TemplateElement.define({
+TemplateElement.options({
+    "test-element": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-not": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-equals": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-not-equals": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-ge": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-gt": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-le": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-lt": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-or": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+    "test-element-and": {
+        shadowOptions: {
+            mode: "closed",
+        },
+    },
+}).define({
     name: "f-template",
 });