@microsoft/fast-html 1.0.0-alpha.3 → 1.0.0-alpha.31

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,10 +36,9 @@ export interface TemplateDirectiveBehaviorConfig extends BehaviorConfig {
     closingTagStartIndex: number;
     closingTagEndIndex: number;
 }
-interface PartialTemplateConfig {
-    innerHTML: string;
-    startIndex: number;
-    endIndex: number;
+export interface ChildrenMap {
+    customElementName: string;
+    attributeName: string;
 }
 /**
  * Get the index of the next matching tag
@@ -52,18 +55,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 +62,105 @@ 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(previousString: string | null, 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;
+/**
+ * Find a definition
+ * This may exist as a $ref at the root or as a $ref in any anyOf or not at all
+ * if the Observer Map has not been enabled on a child component
+ * @param schema - The JSON schema to find the ref in
+ * @returns The definition or null
+ */
+export declare function findDef(schema: JSONSchema | JSONSchemaDefinition): string | null;
+/**
+ * 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;
+/**
+ * Get details of bindings to the attributes of child custom elements
+ * @param previousString - The previous string before the binding
+ * @returns null, or a custom element name and attribute name
+ */
+export declare function getChildrenMap(previousString: string | null): ChildrenMap | null;
 export {};

package/dist/dts/fixtures/lifecycle-callbacks/lifecycle-callbacks.spec.d.ts

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

package/dist/dts/fixtures/lifecycle-callbacks/main.d.ts

@@ -0,0 +1,5 @@
+export declare const lifecycleEvents: Array<{
+    callback: string;
+    name?: string;
+}>;
+export declare let hydrationCompleteEmitted: boolean;

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,28 @@
+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) {
+            var _a, _b;
+            super(...args);
+            this.deferHydration = true;
+            this.needsHydration = true;
+            if (this.$fastController.hasExistingShadowRoot) {
+                this.toggleAttribute("defer-hydration", true);
+            }
+            ((_b = (_a = this.prepare) === null || _a === void 0 ? void 0 : _a.call(this)) !== null && _b !== void 0 ? _b : Promise.resolve()).then(() => {
+                this.deferHydration = false;
+            });
+        }
+    };
+    attr({ mode: "boolean", attribute: "defer-hydration" })(C.prototype, "deferHydration");
+    attr({ mode: "boolean", attribute: "defer-hydration" })(C.prototype, "needsHydration");
+    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";
+export { ObserverMapOption, TemplateElement, } from "./template.js";

package/dist/esm/components/observer-map.js

@@ -0,0 +1,53 @@
+import { Observable } from "@microsoft/fast-element/observable.js";
+import { assignObservables } from "./utilities.js";
+/**
+ * ObserverMap provides functionality for caching binding paths, extracting root properties,
+ * and defining observable properties on class prototypes
+ */
+export class ObserverMap {
+    constructor(classPrototype, schema) {
+        /**
+         * 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
+         */
+        this.defineChanged = (propertyName) => {
+            const getAndAssignObservablesAlias = this.getAndAssignObservables;
+            const schema = this.schema;
+            function instanceResolverChanged(prev, next) {
+                if (prev === undefined ||
+                    ((prev === null || prev === void 0 ? void 0 : prev.$isProxy) && !(next === null || next === void 0 ? void 0 : next.$isProxy)) ||
+                    (Array.isArray(prev) &&
+                        Array.isArray(next) &&
+                        !(next === null || next === void 0 ? void 0 : next.$fastController))) {
+                    const proxy = getAndAssignObservablesAlias(this, propertyName, next, schema);
+                    this[propertyName] = proxy;
+                }
+            }
+            return instanceResolverChanged;
+        };
+        this.classPrototype = classPrototype;
+        this.schema = schema;
+    }
+    defineProperties() {
+        const propertyNames = this.schema.getRootProperties();
+        for (const propertyName of propertyNames) {
+            Observable.defineProperty(this.classPrototype, propertyName);
+            this.classPrototype[`${propertyName}Changed`] =
+                this.defineChanged(propertyName);
+        }
+    }
+    /**
+     * 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
+     */
+    getAndAssignObservables(target, rootProperty, object, schema) {
+        let proxiedObject = object;
+        proxiedObject = assignObservables(schema.getSchema(rootProperty), schema.getSchema(rootProperty), proxiedObject, target, rootProperty);
+        return proxiedObject;
+    }
+}

package/dist/esm/components/observer-map.spec.js

@@ -0,0 +1,19 @@
+import { __awaiter } from "tslib";
+import { expect, test } from "@playwright/test";
+import { ObserverMap } from "./observer-map.js";
+import { Schema } from "./schema.js";
+test.describe("ObserverMap", () => __awaiter(void 0, void 0, void 0, function* () {
+    let observerMap;
+    let schema = new Schema("test-class");
+    class TestClass {
+    }
+    test.beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+        // Use TestClass.prototype so instances will have the observable properties
+        observerMap = new ObserverMap(TestClass.prototype, schema);
+    }));
+    test("should create new instances", () => __awaiter(void 0, void 0, void 0, function* () {
+        const instance1 = new ObserverMap(TestClass.prototype, schema);
+        const instance2 = new ObserverMap(TestClass.prototype, schema);
+        expect(instance1).not.toBe(instance2);
+    }));
+}));

package/dist/esm/components/schema.js

@@ -0,0 +1,250 @@
+// The context, in most cases the array property e.g. users
+export const fastContextMetaData = "$fast_context";
+// The list of contexts preceeding this context, the first of which should be the root property
+export const fastContextsMetaData = "$fast_parent_contexts";
+export const defsPropertyName = "$defs";
+export const refPropertyName = "$ref";
+/**
+ * A constructed JSON schema from a template
+ */
+export class Schema {
+    constructor(name) {
+        this.customElementName = name;
+        Schema.jsonSchemaMap.set(this.customElementName, new Map());
+    }
+    /**
+     * Add a path to a schema
+     * @param config RegisterPathConfig
+     */
+    addPath(config) {
+        var _a, _b, _c;
+        const splitPath = this.getSplitPath(config.pathConfig.path);
+        let schema = Schema.jsonSchemaMap.get(this.customElementName).get(config.rootPropertyName);
+        let childRef = null;
+        // Create a root level property JSON
+        if (!schema) {
+            this.addNewSchema(config.rootPropertyName);
+            schema = Schema.jsonSchemaMap.get(this.customElementName).get(config.rootPropertyName);
+        }
+        if (config.childrenMap) {
+            childRef = this.getSchemaId(config.childrenMap.customElementName, config.childrenMap.attributeName);
+            if (splitPath.length === 1) {
+                schema.anyOf
+                    ? schema.anyOf.push({ [refPropertyName]: childRef })
+                    : (schema.anyOf = [{ [refPropertyName]: childRef }]);
+            }
+        }
+        switch (config.pathConfig.type) {
+            case "default":
+            case "access": {
+                if (splitPath.length > 1) {
+                    if (config.pathConfig.currentContext === null) {
+                        this.addPropertiesToAnObject(schema, splitPath.slice(1), config.pathConfig.currentContext, childRef);
+                    }
+                    else {
+                        if (!((_a = schema[defsPropertyName]) === null || _a === void 0 ? void 0 : _a[splitPath[0]])) {
+                            schema[defsPropertyName] = {
+                                [splitPath[0]]: {},
+                            };
+                        }
+                        this.addPropertiesToAContext(schema[defsPropertyName][splitPath[0]], splitPath.slice(1), config.pathConfig.currentContext, childRef);
+                    }
+                }
+                break;
+            }
+            case "repeat": {
+                this.addContext(schema, splitPath.at(-1), // example items
+                config.pathConfig.currentContext, // example item
+                config.pathConfig.parentContext);
+                if (splitPath.length > 2) {
+                    let updatedSchema = schema;
+                    const hasParentContext = !!config.pathConfig.parentContext;
+                    if (hasParentContext) {
+                        updatedSchema = this.addPropertiesToAnObject((_b = schema[defsPropertyName]) === null || _b === void 0 ? void 0 : _b[config.pathConfig.parentContext], splitPath.slice(1, -1), config.pathConfig.parentContext, childRef);
+                    }
+                    this.addPropertiesToAnObject(updatedSchema, hasParentContext ? splitPath.slice(2) : splitPath.slice(1), config.pathConfig.currentContext, childRef, "array");
+                }
+                else if (splitPath.length > 1) {
+                    let schemaDefinition;
+                    if (config.pathConfig.parentContext) {
+                        schemaDefinition = (_c = schema === null || schema === void 0 ? void 0 : schema[defsPropertyName]) === null || _c === void 0 ? void 0 : _c[config.pathConfig.parentContext];
+                    }
+                    this.addPropertiesToAnObject(schemaDefinition !== null && schemaDefinition !== void 0 ? schemaDefinition : schema, splitPath.slice(1), config.pathConfig.currentContext, childRef, "array");
+                }
+                else {
+                    schema.type = "array";
+                    schema[refPropertyName] = this.getDefsPath(config.pathConfig.currentContext);
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * 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) {
+        var _a;
+        return ((_a = Schema.jsonSchemaMap.get(this.customElementName).get(rootPropertyName)) !== null && _a !== void 0 ? _a : null);
+    }
+    /**
+     * Gets root properties
+     * @returns IterableIterator<string>
+     */
+    getRootProperties() {
+        return Schema.jsonSchemaMap.get(this.customElementName).keys();
+    }
+    /**
+     * 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
+     */
+    getSplitPath(path) {
+        return path.split(".");
+    }
+    /**
+     * 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
+     */
+    getDefsPath(context) {
+        return `#/${defsPropertyName}/${context}`;
+    }
+    /**
+     * Get the schema $id
+     * @param customElementName - The custom element name
+     * @param propertyName - The property name
+     * @returns The ID that can be used in the JSON schema as $id
+     */
+    getSchemaId(customElementName, propertyName) {
+        return `https://fast.design/schemas/${customElementName}/${propertyName}.json`;
+    }
+    /**
+     * Add a new JSON schema to the JSON schema map
+     * @param propertyName The name of the property to assign this JSON schema to
+     */
+    addNewSchema(propertyName) {
+        Schema.jsonSchemaMap.get(this.customElementName).set(propertyName, {
+            $schema: "https://json-schema.org/draft/2019-09/schema",
+            $id: this.getSchemaId(this.customElementName, propertyName),
+            [defsPropertyName]: {},
+        });
+    }
+    /**
+     * 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
+     */
+    addPropertiesToAContext(schema, splitPath, context, childRef) {
+        schema.type = "object";
+        if (schema.properties && !schema.properties[splitPath[0]]) {
+            schema.properties[splitPath[0]] = {};
+        }
+        else if (!schema.properties) {
+            schema.properties = {
+                [splitPath[0]]: {},
+            };
+        }
+        if (splitPath.length > 1) {
+            this.addPropertiesToAnObject(schema.properties[splitPath[0]], splitPath.slice(1), context, childRef);
+        }
+        else if (childRef) {
+            if (schema.properties[splitPath[0]].anyOf) {
+                schema.properties[splitPath[0]].anyOf.push({
+                    [refPropertyName]: childRef,
+                });
+            }
+            else {
+                schema.properties[splitPath[0]].anyOf = [{ [refPropertyName]: childRef }];
+            }
+        }
+    }
+    /**
+     * 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)
+     */
+    addPropertiesToAnObject(schema, splitPath, context, childRef, type = "object") {
+        schema.type = "object";
+        if (schema.properties && !schema.properties[splitPath[0]]) {
+            schema.properties[splitPath[0]] = {};
+        }
+        else if (!schema.properties) {
+            schema.properties = {
+                [splitPath[0]]: {},
+            };
+        }
+        if (type === "object" && splitPath.length > 1) {
+            return this.addPropertiesToAnObject(schema.properties[splitPath[0]], splitPath.slice(1), context, childRef, type);
+        }
+        else if (type === "array") {
+            if (splitPath.length > 1) {
+                return this.addPropertiesToAnObject(schema.properties[splitPath[0]], splitPath.slice(1), context, childRef, type);
+            }
+            else {
+                return this.addArrayToAnObject(schema.properties[splitPath[0]], context);
+            }
+        }
+        if (schema.properties[splitPath[0]].anyOf && childRef) {
+            schema.properties[splitPath[0]].anyOf.push({ [refPropertyName]: childRef });
+        }
+        else if (childRef) {
+            schema.properties[splitPath[0]].anyOf = [{ [refPropertyName]: childRef }];
+        }
+        return schema.properties[splitPath[0]];
+    }
+    /**
+     * Add an array to an object property
+     * @param schema The schema to add the properties to
+     * @param context The name of the context
+     */
+    addArrayToAnObject(schema, context) {
+        schema.type = "array";
+        schema.items = {
+            [refPropertyName]: this.getDefsPath(context),
+        };
+        return schema.items;
+    }
+    /**
+     * 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
+     */
+    addContext(schema, propertyName, // e.g items
+    currentContext, // e.g. item
+    parentContext) {
+        if (schema[defsPropertyName][currentContext]) {
+            return;
+        }
+        schema[defsPropertyName][currentContext] = {
+            [fastContextMetaData]: propertyName,
+            [fastContextsMetaData]: this.getParentContexts(schema, parentContext),
+        };
+    }
+    /**
+     * Get parent contexts
+     * @param schema The schema to use
+     * @param parentContext The parent context
+     * @param contexts A list of parent contexts
+     * @returns
+     */
+    getParentContexts(schema, parentContext, contexts = []) {
+        var _a;
+        if (parentContext === null) {
+            return [null, ...contexts];
+        }
+        const parentParentContext = (_a = schema === null || schema === void 0 ? void 0 : schema[defsPropertyName]) === null || _a === void 0 ? void 0 : _a[parentContext][fastContextsMetaData];
+        return this.getParentContexts(schema, parentParentContext.at(-1), [parentContext, ...contexts]);
+    }
+}
+/**
+ * A JSON schema describing each root schema
+ */
+Schema.jsonSchemaMap = new Map();