@microsoft/fast-html 1.0.0-alpha.2 → 1.0.0-alpha.21

package/README.md

@@ -22,7 +22,13 @@ npm install --save @microsoft/fast-html
 In your JS bundle you will need to include the `@microsoft/fast-html` package:
 
 ```typescript
-import { TemplateElement } from "@microsoft/fast-html";
+import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
+import { MyCustomElement } from "./my-custom-element";
+
+RenderableFASTElement(MyCustomElement).defineAsync({
+    name: "my-custom-element",
+    templateOptions: "defer-and-hydrate",
+});
 
 TemplateElement.define({
     name: "f-template",
@@ -45,9 +51,39 @@ 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.
+
+#### Using the RenderableFASTElement
+
+The use of `RenderableFASTElement` as a mixin for your custom element will automatically remove the `defer-hydration` attribute signalling for hydration to begin, and if you need to add state before hydration should occur you can make use of the `prepare` method.
+
+Example:
+```typescript
+class MyCustomElement extends FASTElement {
+    private prepare(): Promise<void> {
+        // Get initial state
+    }
+}
+
+RenderableFASTElement(MyCustomElement).defineAsync({
+    name: "my-custom-element",
+    templateOptions: "defer-and-hydrate",
+});
+```
+
 ### 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 +96,49 @@ 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>
+    <slot f-slotted="{slottedNodes filter elements()}"></slot>
+    <slot f-slotted="{slottedNodes filter elements(div, p)}"></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 +147,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,26 +169,54 @@ Template directives include:
     <ul><f-repeat value="{{item in list}}"><li>{{item}}</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.
+    Should you need to refer to the parent element (not the individual item in the list), you can use the context of a previous repeat, or no context which will resolve to the custom element.
 
     Example:
     ```html
-    <f-partial id="test">
-        <ul>
-            <f-repeat value="{{item in items}}">
-                <li>{{item.text}}<f-apply partial="test" value="{{item.items}}"></f-apply></li>
-            </f-repeat>
-        </ul>
-    </f-partial>
-    <f-apply partial="test" value="{{items}}"></f-apply>
+    <ul><f-repeat value="{{item in list}}"><li>{{item}} - {{title}}</li></f-repeat></ul>
     ```
 
+#### 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.
+
+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/).
+This project has been heavily inspired by [Handlebars](https://handlebarsjs.com/) and [Vue.js](https://vuejs.org/).

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

@@ -0,0 +1,10 @@
+import { type Constructable, type FASTElement } from "@microsoft/fast-element";
+/**
+ * A mixin function that extends a base class with additional functionality for
+ * rendering and hydration.
+ *
+ * @param BaseCtor - The base class to extend.
+ * @returns A new class that extends the provided base class with additional functionality for rendering and hydration.
+ * @public
+ */
+export declare function RenderableFASTElement<T extends Constructable<FASTElement>>(BaseCtor: T): T;

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

@@ -1 +1,3 @@
 export { TemplateElement } from "./template.js";
+export { RenderableFASTElement } from "./element.js";
+export { ObserverMap } from "./observer-map.js";

package/dist/dts/components/observer-map.d.ts

@@ -0,0 +1,26 @@
+import { Schema } from "./schema.js";
+/**
+ * ObserverMap provides functionality for caching binding paths, extracting root properties,
+ * and defining observable properties on class prototypes
+ */
+export declare class ObserverMap {
+    private schema;
+    private classPrototype;
+    constructor(classPrototype: any, schema: Schema);
+    defineProperties(): void;
+    /**
+     * Creates a proxy for an object that intercepts property mutations and triggers Observable notifications
+     * @param target - The target instance that owns the root property
+     * @param rootProperty - The name of the root property for notification purposes
+     * @param object - The object to wrap with a proxy
+     * @returns A proxy that triggers notifications on property mutations
+     */
+    private getAndAssignObservables;
+    /**
+     * Creates a property change handler function for observable properties
+     * This handler is called when an observable property transitions from undefined to a defined value
+     * @param propertyName - The name of the property for which to create the change handler
+     * @returns A function that handles property changes and sets up proxies for object values
+     */
+    private defineChanged;
+}

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

@@ -0,0 +1,134 @@
+type FastContextMetaData = "$fast_context";
+type FastContextsMetaData = "$fast_parent_contexts";
+export interface JSONSchemaDefinition extends JSONSchemaCommon {
+    $fast_context: string;
+    $fast_parent_contexts: Array<string>;
+}
+interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+    items?: any;
+}
+export interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+    $ref?: string;
+}
+interface CachedPathCommon {
+    parentContext: string | null;
+    currentContext: string | null;
+    path: string;
+}
+type AccessCachedPathType = "access";
+export interface AccessCachedPath extends CachedPathCommon {
+    type: AccessCachedPathType;
+}
+type DefaultCachedPathType = "default";
+export interface DefaultCachedPath extends CachedPathCommon {
+    type: DefaultCachedPathType;
+}
+type EventCachedPathType = "event";
+export interface EventCachedPath extends CachedPathCommon {
+    type: EventCachedPathType;
+}
+type RepeatCachedPathType = "repeat";
+export interface RepeatCachedPath extends CachedPathCommon {
+    type: RepeatCachedPathType;
+}
+export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+export type CachedPathMap = Map<string, JSONSchema>;
+interface RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+}
+export declare const fastContextMetaData: FastContextMetaData;
+export declare const fastContextsMetaData: FastContextsMetaData;
+export declare const defsPropertyName = "$defs";
+export declare const refPropertyName = "$ref";
+/**
+ * A constructed JSON schema from a template
+ */
+export declare class Schema {
+    /**
+     * The name of the custom element
+     */
+    private customElementName;
+    /**
+     * A JSON schema describing each root schema
+     */
+    private jsonSchemaMap;
+    constructor(name: string);
+    /**
+     * Add a path to a schema
+     * @param config RegisterPathConfig
+     */
+    addPath(config: RegisterPathConfig): void;
+    /**
+     * Gets the JSON schema for a property name
+     * @param rootPropertyName - the root property the JSON schema is mapped to
+     * @returns The JSON schema for the root property
+     */
+    getSchema(rootPropertyName: string): JSONSchema | null;
+    /**
+     * Gets root properties
+     * @returns IterableIterator<string>
+     */
+    getRootProperties(): IterableIterator<string>;
+    /**
+     * Get a path split into property names
+     * @param path The dot syntax path e.g. a.b.c
+     * @returns An array of items in the path
+     */
+    private getSplitPath;
+    /**
+     * Gets the path to the $def
+     * @param context The context name e.g. {{item in items}} in a repeat creates the "item" context
+     * @returns A string to use as a $ref
+     */
+    private getDefsPath;
+    /**
+     * Add a new JSON schema to the JSON schema map
+     * @param propertyName The name of the property to assign this JSON schema to
+     */
+    private addNewSchema;
+    /**
+     * Add properties to a context
+     * @param schema The schema to add the properties to
+     * @param splitPath The path split into property/context names
+     * @param context The paths context
+     */
+    private addPropertiesToAContext;
+    /**
+     * Add properties to an object
+     * @param schema The schema to add the properties to
+     * @param splitPath The path split into property/context names
+     * @param context The paths context
+     * @param type The data type (see JSON schema for details)
+     */
+    private addPropertiesToAnObject;
+    /**
+     * Add an array to an object property
+     * @param schema The schema to add the properties to
+     * @param context The name of the context
+     */
+    private addArrayToAnObject;
+    /**
+     * Add a context to the $defs property
+     * @param schema The schema to use
+     * @param propertyName The name of the property the context belongs to
+     * @param currentContext The current context
+     * @param parentContext The parent context
+     * @returns
+     */
+    private addContext;
+    /**
+     * Get parent contexts
+     * @param schema The schema to use
+     * @param parentContext The parent context
+     * @param contexts A list of parent contexts
+     * @returns
+     */
+    private getParentContexts;
+}
+export {};

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

@@ -1,4 +1,15 @@
 import { FASTElement } from "@microsoft/fast-element";
+import "@microsoft/fast-element/install-hydratable-view-templates.js";
+export type ObserverMapOption = "all";
+export interface ElementOptions {
+    observerMap?: ObserverMapOption | undefined;
+}
+/**
+ * A dictionary of element options the TemplateElement will use to update the registered element
+ */
+export interface ElementOptionsDictionary<ElementOptionsType = ElementOptions> {
+    [key: string]: ElementOptionsType;
+}
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
@@ -7,12 +18,36 @@ 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: ElementOptionsDictionary;
     private partials;
+    /**
+     * ObserverMap instance for caching binding paths
+     */
+    private observerMap?;
+    /**
+     * Default element options
+     */
+    private static defaultElementOptions;
+    /**
+     * Metadata containing JSON schema for properties on a custom eleemnt
+     */
+    private schema?;
+    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
      * @param innerHTML - The innerHTML.
      * @param self - Indicates that this should refer to itself instead of a property when creating bindings.
+     * @param observerMap - ObserverMap instance for caching binding paths (optional).
      */
     private resolveStringsAndValues;
     /**
@@ -26,6 +61,8 @@ declare class TemplateElement extends FASTElement {
      * @param behaviorConfig - The directive behavior configuration object.
      * @param externalValues - The interpreted values from the parent.
      * @param innerHTML - The innerHTML.
+     * @param self - Indicates that this should refer to itself instead of a property when creating bindings.
+     * @param observerMap - ObserverMap instance for caching binding paths (optional).
      */
     private resolveTemplateDirective;
     /**
@@ -42,6 +79,7 @@ declare class TemplateElement extends FASTElement {
      * @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.
+     * @param observerMap - ObserverMap instance for caching binding paths (optional).
      */
     private resolveDataBinding;
     /**
@@ -50,12 +88,8 @@ declare class TemplateElement extends FASTElement {
      * @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 observerMap - ObserverMap instance for caching binding paths (optional).
      */
     private resolveInnerHTML;
-    /**
-     * Resolve all partial templates
-     * @param unresolvedInnerHTML - The innerHTML.
-     */
-    private resolveAllPartials;
 }
 export { TemplateElement };

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

@@ -1,9 +1,12 @@
+import { JSONSchema, JSONSchemaDefinition, Schema } from "./schema.js";
 type BehaviorType = "dataBinding" | "templateDirective";
-type TemplateDirective = "when" | "repeat" | "apply";
+type TemplateDirective = "when" | "repeat";
 export type AttributeDirective = "children" | "slotted" | "ref";
+type DataBindingBindingType = "client" | "default" | "unescaped";
 interface BehaviorConfig {
     type: BehaviorType;
 }
+export type PathType = "access" | "default" | "event" | "repeat";
 export interface ContentDataBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
     subtype: "content";
 }
@@ -18,6 +21,7 @@ export interface AttributeDirectiveBindingBehaviorConfig extends BaseDataBinding
 export type DataBindingBehaviorConfig = ContentDataBindingBehaviorConfig | AttributeDataBindingBehaviorConfig | AttributeDirectiveBindingBehaviorConfig;
 export interface BaseDataBindingBehaviorConfig extends BehaviorConfig {
     type: "dataBinding";
+    bindingType: DataBindingBindingType;
     openingStartIndex: number;
     openingEndIndex: number;
     closingStartIndex: number;
@@ -32,11 +36,6 @@ export interface TemplateDirectiveBehaviorConfig extends BehaviorConfig {
     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
@@ -52,18 +51,6 @@ export declare function getIndexOfNextMatchingTag(openingTagStartSlice: string,
  * @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"
@@ -71,5 +58,91 @@ export declare function getAllPartials(innerHTML: string, offset?: number, parti
  * @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) => any;
+export declare function pathResolver(path: string, contextPath: string | null, level: number, rootSchema: JSONSchema): (accessibleObject: any, context: any) => any;
+export declare function bindingResolver(rootPropertyName: string | null, path: string, parentContext: string | null, type: PathType, schema: Schema, currentContext: string | null, level: number): (accessibleObject: any, context: any) => any;
+export declare function expressionResolver(rootPropertyName: string | null, expression: ChainedExpression, parentContext: string | null, level: number, schema: Schema): (accessibleObject: any, context: any) => any;
+/**
+ * Extracts all paths from a ChainedExpression, including nested expressions
+ * @param chainedExpression - The chained expression to extract paths from
+ * @returns A Set containing all unique paths found in the expression chain
+ */
+export declare function extractPathsFromChainedExpression(chainedExpression: ChainedExpression): Set<string>;
+/**
+ * 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" | "!" | "==" | "!=" | ">=" | ">" | "<=" | "<";
+type ChainingOperator = "||" | "&&" | "&amp;&amp;";
+interface Expression {
+    operator: Operator;
+    left: string;
+    leftIsValue: boolean | null;
+    right: string | boolean | number | null;
+    rightIsValue: boolean | null;
+}
+export interface ChainedExpression {
+    operator?: ChainingOperator;
+    expression: Expression;
+    next?: ChainedExpression;
+}
+/**
+ * Gets the expression chain as a configuration object
+ * @param value - The binding string value
+ * @returns - A configuration object containing information about the expression
+ */
+export declare function getExpressionChain(value: string): ChainedExpression | void;
+/**
+ * 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;
+/**
+ * Resolves f-when
+ * @param self - Where the first item in the path path refers to the item itself (used by repeat).
+ * @param chainedExpression - The chained expression which includes the expression and the next expression
+ * if there is another in the chain
+ * @returns - A binding that resolves the chained expression logic
+ */
+export declare function resolveWhen(rootPropertyName: string | null, expression: ChainedExpression, parentContext: string | null, level: number, schema: Schema): (x: boolean, c: any) => any;
+/**
+ * Assign observables to data
+ * @param schema - The schema
+ * @param rootSchema - The root schema mapping to the root property
+ * @param data - The data
+ * @param target - The target custom element
+ * @param rootProperty - The root property
+ * @returns
+ */
+export declare function assignObservables(schema: JSONSchema | JSONSchemaDefinition, rootSchema: JSONSchema, data: any, target: any, rootProperty: string): typeof Proxy;
+/**
+ * Assign a proxy to an object
+ * @param schema - The current schema
+ * @param rootSchema - The root schema for the root property
+ * @param target - The target custom element
+ * @param rootProperty - The root property
+ * @param object - The object to assign the proxy to
+ * @returns Proxy object
+ */
+export declare function assignProxy(schema: JSONSchema | JSONSchemaDefinition, rootSchema: JSONSchema, target: any, rootProperty: string, object: any): typeof Proxy;
+/**
+ * Get the root property name
+ * @param rootPropertyName - The root property
+ * @param path - The dot syntax path
+ * @param context - The context created by a repeat
+ * @param type - The type of path binding
+ * @returns
+ */
+export declare function getRootPropertyName(rootPropertyName: string | null, path: string, context: null | string, type: PathType): string | null;
 export {};

package/dist/dts/fixtures/observer-map/main.d.ts

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

package/dist/dts/fixtures/observer-map/observer-map.spec.d.ts

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

package/dist/dts/index.d.ts

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

package/dist/esm/components/element.js

@@ -0,0 +1,27 @@
+import { attr } from "@microsoft/fast-element";
+/**
+ * A mixin function that extends a base class with additional functionality for
+ * rendering and hydration.
+ *
+ * @param BaseCtor - The base class to extend.
+ * @returns A new class that extends the provided base class with additional functionality for rendering and hydration.
+ * @public
+ */
+export function RenderableFASTElement(BaseCtor) {
+    const C = class extends BaseCtor {
+        constructor(...args) {
+            super(...args);
+            this.deferHydration = true;
+            if (this.prepare) {
+                this.prepare().then(() => {
+                    this.deferHydration = false;
+                });
+            }
+            else {
+                this.deferHydration = false;
+            }
+        }
+    };
+    attr({ mode: "boolean", attribute: "defer-hydration" })(C.prototype, "deferHydration");
+    return C;
+}

package/dist/esm/components/index.js

@@ -1 +1,3 @@
 export { TemplateElement } from "./template.js";
+export { RenderableFASTElement } from "./element.js";
+export { ObserverMap } from "./observer-map.js";