@microsoft/fast-html 1.0.0-alpha.8 → 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.
 
@@ -175,6 +189,34 @@ Example:
 
 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/esm/components/template.js

@@ -15,12 +15,17 @@ 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) {
@@ -31,6 +36,9 @@ class TemplateElement extends FASTElement {
                         // 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 {
@@ -294,6 +302,10 @@ class TemplateElement extends FASTElement {
         });
     }
 }
+/**
+ * A dictionary of custom element options
+ */
+TemplateElement.elementOptions = {};
 __decorate([
     attr,
     __metadata("design:type", String)

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/main.js

@@ -22,7 +22,19 @@ class TestElementUnescaped extends FASTElement {
 }
 TestElementUnescaped.define({
     name: "test-element-unescaped",
+    shadowOptions: null,
 });
-TemplateElement.define({
+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",
 });