@microsoft/fast-html 1.0.0-alpha.1 → 1.0.0-alpha.10

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.
 
@@ -47,7 +61,15 @@ Example:
 
 ### Syntax
 
-All bindings use a handlebars syntax.
+All bindings use a handlebars-like syntax.
+
+Some bindings are only relevant to the browser, such as for click handlers or other pieces of dynamic interaction. As such, their bindings use single curly braces `{}`, this is to prevent an intial SSR (Server Side Rendering) or other build time rendering technologies from needing to interpret them.
+
+If a binding is relevant to both client and the back end rendering engine, it will use `{{}}` or `{{{}}}` depending on what type of data injection is being done.
+
+Browser-only bindings:
+- Event bindings
+- Attribute directives
 
 #### Content binding
 
@@ -60,33 +82,47 @@ All bindings use a handlebars syntax.
 Event bindings must include the `()` as well as being preceeded by `@` in keeping with `@microsoft/fast-element` tagged template `html` syntax.
 
 ```html
-<button @click="{{handleClick()}}"></button>
+<button @click="{handleClick()}"></button>
+```
+
+In addition you may include an event or attribute or observable, events are denoted with `e` as a reserved letter.
+
+Event:
+```html
+<button @click="{handleClick(e)}"></button>
+```
+
+Attribute/Observable:
+```html
+<button @click="{handleClick(foo)}"></button>
 ```
 
 #### Directives
 
 Directives are assumed to be either an attribute directive or a directive that also serves a template. Both are prepended by `f-`. The logic of these directives and what their use cases are is explained in the [FAST html documentation](https://fast.design/docs/getting-started/html-directives).
 
+Attribute directives are part of [client side binding](#syntax) and therefore use the `{}` syntax.
+
 Attribute directives include:
 - **slotted**
 
     Example:
     ```html
-    <slot f-slotted="{{slottedNodes}}"></slot>
+    <slot f-slotted="{slottedNodes}"></slot>
     ```
 
 - **children**
 
     Example:
     ```html
-    <ul f-children="{{listItems}}"><f-repeat value="{{item in list}}"><li>{{item}}</li></f-repeat></ul>
+    <ul f-children="{listItems}"><f-repeat value="{{item in list}}"><li>{{item}}</li></f-repeat></ul>
     ```
 
 - **ref**
 
     Example:
     ```html
-    <video f-ref="{{video}}"></video>
+    <video f-ref="{video}"></video>
     ```
 
 Template directives include:
@@ -95,8 +131,21 @@ Template directives include:
     Example:
     ```html
     <f-when value="{{show}}">Hello world</f-when>
+    <f-when value="{{!show}}">Goodbye world</f-when>
     ```
 
+The following operators can also be used:
+- `==`
+- `!=`
+- `>=`
+- `>`
+- `<=`
+- `<`
+- `||`
+- `&&`
+
+Where the right operand can be either a reference to a value (string e.g. `{{foo == 'bar'}}`, boolean e.g. `{{foo == true}}`, number e.g. `{{foo == 3}}`) or another binding value.
+
 - **repeat**
 
     Example:
@@ -104,6 +153,13 @@ Template directives include:
     <ul><f-repeat value="{{item in list}}"><li>{{item}}</li></f-repeat></ul>
     ```
 
+    Should you need to refer to the parent element (not the individual item in the list), you can use `../`. This will map to what `html` tag template literal uses, `c.parent`.
+
+    Example:
+    ```html
+    <ul><f-repeat value="{{item in list}}"><li>{{item}} - {{../title}}</li></f-repeat></ul>
+    ```
+
 - **partial & apply**
 
     These directives are new to the declarative HTML model and allow for the ability to declare a `partial` directive containing a template partial which can then be referenced by an `apply` directive.
@@ -120,10 +176,47 @@ Template directives include:
     <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/index.d.ts

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

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

@@ -0,0 +1,74 @@
+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
+ */
+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
+     * @param innerHTML - The innerHTML.
+     * @param self - Indicates that this should refer to itself instead of a property when creating bindings.
+     */
+    private resolveStringsAndValues;
+    /**
+     * Resolve a template or behavior
+     * @param strings - The strings array.
+     * @param values - The interpreted values.
+     */
+    private resolveTemplateOrBehavior;
+    /**
+     * Resolve a template directive
+     * @param behaviorConfig - The directive behavior configuration object.
+     * @param externalValues - The interpreted values from the parent.
+     * @param innerHTML - The innerHTML.
+     */
+    private resolveTemplateDirective;
+    /**
+     * Resolve a template directive
+     * @param name - The name of the directive.
+     * @param propName - The property name to pass to the directive.
+     * @param externalValues - The interpreted values from the parent.
+     */
+    private resolveAttributeDirective;
+    /**
+     * Resolver of a data binding
+     * @param innerHTML - The innerHTML.
+     * @param strings - The strings array.
+     * @param values - The interpreted values.
+     * @param self - Indicates that this should refer to itself instead of a property when creating bindings.
+     * @param behaviorConfig - The binding behavior configuration object.
+     */
+    private resolveDataBinding;
+    /**
+     * Resolver of the innerHTML string
+     * @param innerHTML - The innerHTML.
+     * @param strings - The strings array.
+     * @param values - The interpreted values.
+     * @param self - Indicates that this should refer to itself instead of a property when creating bindings.
+     */
+    private resolveInnerHTML;
+    /**
+     * Resolve all partial templates
+     * @param unresolvedInnerHTML - The innerHTML.
+     */
+    private resolveAllPartials;
+}
+export { TemplateElement };

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

@@ -0,0 +1,111 @@
+type BehaviorType = "dataBinding" | "templateDirective";
+type TemplateDirective = "when" | "repeat" | "apply";
+export type AttributeDirective = "children" | "slotted" | "ref";
+type DataBindingBindingType = "client" | "default" | "unescaped";
+interface BehaviorConfig {
+    type: BehaviorType;
+}
+export interface ContentDataBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
+    subtype: "content";
+}
+export interface AttributeDataBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
+    subtype: "attribute";
+    aspect: "@" | ":" | "?" | null;
+}
+export interface AttributeDirectiveBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
+    subtype: "attributeDirective";
+    name: AttributeDirective;
+}
+export type DataBindingBehaviorConfig = ContentDataBindingBehaviorConfig | AttributeDataBindingBehaviorConfig | AttributeDirectiveBindingBehaviorConfig;
+export interface BaseDataBindingBehaviorConfig extends BehaviorConfig {
+    type: "dataBinding";
+    bindingType: DataBindingBindingType;
+    openingStartIndex: number;
+    openingEndIndex: number;
+    closingStartIndex: number;
+    closingEndIndex: number;
+}
+export interface TemplateDirectiveBehaviorConfig extends BehaviorConfig {
+    type: "templateDirective";
+    name: TemplateDirective;
+    value: string;
+    openingTagStartIndex: number;
+    openingTagEndIndex: number;
+    closingTagStartIndex: number;
+    closingTagEndIndex: number;
+}
+interface PartialTemplateConfig {
+    innerHTML: string;
+    startIndex: number;
+    endIndex: number;
+}
+/**
+ * Get the index of the next matching tag
+ * @param openingTagStartSlice - The slice starting from the opening tag
+ * @param openingTag - The opening tag string
+ * @param closingTag - The closing tag
+ * @param openingTagStartIndex - The opening tag start index derived from the innerHTML
+ * @returns index
+ */
+export declare function getIndexOfNextMatchingTag(openingTagStartSlice: string, openingTag: string, closingTag: string, openingTagStartIndex: number): number;
+/**
+ * Get the next behavior
+ * @param innerHTML - The innerHTML string to evaluate
+ * @returns DataBindingBehaviorConfig | DirectiveBehaviorConfig | null - A configuration object or null
+ */
+export declare function getNextBehavior(innerHTML: string): DataBindingBehaviorConfig | TemplateDirectiveBehaviorConfig | null;
+/**
+ * Gets all the partials with their IDs
+ * @param innerHTML - The innerHTML string to evaluate
+ * @param offset - The index offset from the innerHTML
+ * @param partials - The partials found
+ * @returns {[key: string]: PartialTemplateConfig}
+ */
+export declare function getAllPartials(innerHTML: string, offset?: number, partials?: {
+    [key: string]: PartialTemplateConfig;
+}): {
+    [key: string]: PartialTemplateConfig;
+};
+/**
+ * Create a function to resolve a value from an object using a path with dot syntax.
+ * e.g. "foo.bar"
+ * @param path - The dot syntax path to an objects property.
+ * @param self - Where the first item in the path path refers to the item itself (used by repeat).
+ * @returns A function to access the value from a given path.
+ */
+export declare function pathResolver(path: string, self?: boolean): (accessibleObject: any, context: any) => any;
+/**
+ * Available operators include:
+ *
+ * - access (no operator)
+ * - not (!)
+ * - equals (==)
+ * - not equal (!=)
+ * - greater than or equal (>=)
+ * - greater than (>)
+ * - less than or equal (<=)
+ * - less than (<)
+ * - or (||)
+ * - and (&&) and the HTML character entity (&amp;&amp;)
+ */
+type Operator = "access" | "!" | "==" | "!=" | ">=" | ">" | "<=" | "<" | "||" | "&&" | "&amp;&amp;";
+interface OperatorConfig {
+    operator: Operator;
+    left: string;
+    right: string | boolean | number | null;
+    rightIsValue: boolean | null;
+}
+/**
+ * Get the operator used.
+ * @param value the binded value
+ * @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/dts/components/utilities.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/debug.d.ts

@@ -0,0 +1,3 @@
+export declare const debugMessages: {
+    2000: string;
+};

package/dist/dts/fixtures/attribute/attribute.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/attribute/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/binding/binding.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/binding/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/children/children.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/children/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/dot-syntax/dot-syntax.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/dot-syntax/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/event/event.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/event/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/partial/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/partial/partial.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/ref/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/ref/ref.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/repeat/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/repeat/repeat.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/slotted/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/slotted/slotted.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/when/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/fixtures/when/when.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dts/index.d.ts

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

package/dist/dts/interfaces.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Warning and error messages.
+ * @internal
+ */
+export declare const enum Message {
+    noTemplateProvided = 2000
+}

package/dist/dts/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.47.0"
+    }
+  ]
+}

package/dist/esm/components/index.js

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