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

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

@@ -1,4 +1,41 @@
-import { FASTElement } from "@microsoft/fast-element";
+import { FASTElement, HydrationControllerCallbacks, TemplateLifecycleCallbacks } from "@microsoft/fast-element";
+import "@microsoft/fast-element/install-hydratable-view-templates.js";
+/**
+ * Values for the observerMap element option.
+ */
+export declare const ObserverMapOption: {
+    readonly all: "all";
+};
+/**
+ * Type for the observerMap element option.
+ */
+export type ObserverMapOption = (typeof ObserverMapOption)[keyof typeof ObserverMapOption];
+/**
+ * Element options the TemplateElement will use to update the registered element
+ */
+export interface ElementOptions {
+    observerMap?: ObserverMapOption;
+}
+/**
+ * A dictionary of element options the TemplateElement will use to update the registered element
+ */
+export interface ElementOptionsDictionary<ElementOptionsType = ElementOptions> {
+    [key: string]: ElementOptionsType;
+}
+/**
+ * Lifecycle callbacks for template and hydration events.
+ * Combines template lifecycle callbacks with hydration callbacks and adds template-processing events.
+ */
+export interface HydrationLifecycleCallbacks extends HydrationControllerCallbacks, TemplateLifecycleCallbacks {
+    /**
+     * Called after the JS class definition has been registered
+     */
+    elementDidRegister?(name: string): void;
+    /**
+     * Called before the template has been evaluated and assigned
+     */
+    templateWillUpdate?(name: string): void;
+}
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
@@ -7,12 +44,52 @@ declare class TemplateElement extends FASTElement {
      * The name of the custom element this template will be applied to
      */
     name?: string;
-    private partials;
+    /**
+     * A dictionary of custom element options
+     */
+    static elementOptions: ElementOptionsDictionary;
+    /**
+     * 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?;
+    /**
+     * Lifecycle callbacks for hydration events
+     */
+    private static lifecycleCallbacks;
+    /**
+     * Configure lifecycle callbacks for hydration events.
+     *
+     * @param callbacks - Lifecycle callbacks to configure.
+     * @returns The {@link TemplateElement} class.
+     */
+    static config(callbacks: HydrationLifecycleCallbacks): typeof TemplateElement;
+    /**
+     * Set options for custom elements.
+     *
+     * @param elementOptions - A dictionary of custom element options
+     * @returns The TemplateElement class.
+     */
+    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 +103,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 +121,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 +130,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,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,23 @@
+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;
+            ((_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");
+    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/request-idle-callback.js

@@ -0,0 +1,72 @@
+/**
+ * A ponyfill for requestIdleCallback that falls back to setTimeout.
+ * Uses the native requestIdleCallback when available.
+ *
+ * @param callback - The function to call when the browser is idle.
+ * @param options - Options object that may contain a timeout property.
+ * @returns An ID that can be used to cancel the callback.
+ * @public
+ */
+export function requestIdleCallback(callback, options) {
+    if ("requestIdleCallback" in globalThis) {
+        return globalThis.requestIdleCallback(callback, options);
+    }
+    const start = Date.now();
+    return setTimeout(() => {
+        callback({
+            didTimeout: (options === null || options === void 0 ? void 0 : options.timeout) ? Date.now() - start >= options.timeout : false,
+            timeRemaining: () => 0,
+        });
+    }, 1);
+}
+/**
+ * A ponyfill for cancelIdleCallback that falls back to clearTimeout.
+ * Uses the native cancelIdleCallback when available.
+ *
+ * @param id - The ID of the callback to cancel.
+ * @public
+ */
+export function cancelIdleCallback(id) {
+    if ("cancelIdleCallback" in globalThis) {
+        globalThis.cancelIdleCallback(id);
+    }
+    else {
+        clearTimeout(id);
+    }
+}
+/**
+ * Waits for all custom element descendants of a target element to be connected.
+ *
+ * @param target - The target element to observe.
+ * @param callback - The function to call when all custom element descendants are connected.
+ * @param options - Options object that may contain a timeout property for the idle callback.
+ *
+ * @remarks
+ * This function uses requestIdleCallback to periodically check if all custom element
+ * descendants (elements with a hyphen in their tag name) are connected to the DOM.
+ * Once all such elements are connected, the provided callback is invoked.
+ *
+ * The `timeout` option specifies the maximum time to wait for each idle callback before
+ * rechecking, defaulting to 50 milliseconds.
+ *
+ * @public
+ */
+export function waitForConnectedDescendants(target, callback, options) {
+    var _a, _b;
+    let idleCallbackId;
+    const shallow = (_a = options === null || options === void 0 ? void 0 : options.shallow) !== null && _a !== void 0 ? _a : false;
+    const query = `${shallow ? ":scope > " : ""}:not(:defined)`;
+    const timeout = (_b = options === null || options === void 0 ? void 0 : options.timeout) !== null && _b !== void 0 ? _b : 50;
+    const scheduleCheck = (deadline) => {
+        if (idleCallbackId) {
+            cancelIdleCallback(idleCallbackId);
+            idleCallbackId = undefined;
+        }
+        if (!target.querySelector(query) || (deadline && deadline.timeRemaining() <= 0)) {
+            callback();
+            return;
+        }
+        idleCallbackId = requestIdleCallback(scheduleCheck, { timeout });
+    };
+    scheduleCheck();
+}