@microsoft/fast-html 1.0.0-alpha.16 → 1.0.0-alpha.18

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

@@ -1,10 +1,10 @@
-import { FASTElement } from "@microsoft/fast-element";
-export declare abstract class RenderableFASTElement extends FASTElement {
-    deferHydration: boolean;
-    constructor();
-    /**
-     * A user defined function for determining if the element is ready to be hydrated.
-     * This function will get called if it has been defined after the template is connected.
-     */
-    private prepare;
-}
+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,2 +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,143 @@
+import type { CachedPathMap, ContextCache, PathType } from "./utilities.js";
+interface PathConfig {
+    path: string;
+    self: boolean;
+    parentContext: string | null;
+    contextPath: string | null;
+    type: PathType;
+    level: number;
+    rootPath: string | null;
+    context: ContextCache | null;
+}
+/**
+ * ObserverMap provides functionality for caching binding paths, extracting root properties,
+ * and defining observable properties on class prototypes
+ */
+export declare class ObserverMap {
+    private cachePaths;
+    private contextCache;
+    private classPrototype;
+    constructor(classPrototype: any);
+    private getRootProperty;
+    /**
+     * Caches a binding path with context information for later use in generating observable properties
+     * @param context - The path context information containing path, self, parentContext, contextPath, type, and level
+     */
+    cachePathWithContext(config: PathConfig): void;
+    /**
+     * Handles caching of paths with relative navigation ("../")
+     * Determines the correct context level and caches the path accordingly
+     */
+    private handleRelativePathCaching;
+    /**
+     * Counts the number of "../" sequences in a path without using regex
+     */
+    private countRelativeNavigationLevels;
+    /**
+     * Extracts the property name from a relative path, removing all "../" sequences
+     */
+    private extractPropertyNameFromRelativePath;
+    /**
+     * Determines the target context after navigating up the specified number of levels
+     */
+    private getTargetContextForRelativePath;
+    /**
+     * Caches a path at the root level
+     */
+    private cacheAtRootLevel;
+    /**
+     * Caches a path at a specific context level
+     */
+    private cacheAtContextLevel;
+    /**
+     * Handles caching of access-type paths (property bindings)
+     */
+    private handleAccessPath;
+    /**
+     * Handles caching of repeat-type paths (array/loop contexts)
+     */
+    private handleRepeatPath;
+    /**
+     * Caches a simple access path without context complexity
+     */
+    private cacheSimpleAccessPath;
+    /**
+     * Finds a context item in the temporary context cache
+     */
+    private findContextInCache;
+    /**
+     * Attempts to place an access path under an existing repeat structure
+     * @returns true if successfully placed, false otherwise
+     */
+    private tryPlaceInExistingRepeat;
+    /**
+     * Recursively searches for and places access paths in matching repeat structures
+     */
+    private searchAndPlaceInRepeat;
+    /**
+     * Checks if a cached path is a repeat structure with matching context
+     */
+    private isMatchingRepeatStructure;
+    /**
+     * Determines if a cached path can be searched for nested structures
+     */
+    private canSearchNested;
+    /**
+     * Places an access path within an existing repeat structure
+     */
+    private placeAccessInRepeat;
+    /**
+     * Builds absolute paths for nested repeat access patterns
+     * @example "root.items.__index__.subitems.__index__.title"
+     */
+    private buildNestedRepeatAbsolutePath;
+    /**
+     * Caches access paths that have context information
+     */
+    private cacheAccessPathWithContext;
+    /**
+     * Extracts the relative path from a context's absolute path
+     * For nested contexts, this should match the cache structure path
+     */
+    private getRelativeContextPath;
+    /**
+     * Ensures a repeat structure exists in the cache
+     */
+    private ensureRepeatStructureExists;
+    /**
+     * Creates the cache structure for nested repeat patterns
+     */
+    private createNestedRepeatStructure;
+    /**
+     * Finds the cache path where a parent context's repeat structure is located
+     */
+    private findParentRepeatPath;
+    getCachedPathsWithContext(): CachedPathMap;
+    private resolveContextPath;
+    private resolveRootAndContextPath;
+    getAbsolutePath(config: PathConfig): string;
+    /**
+     * Builds the full context path by looking up parent contexts in contextCache
+     * @param parentContext - The immediate parent context to start from
+     * @param contextPath - The current context path (like "items")
+     * @returns The full absolute path including all parent contexts
+     */
+    private getPathFromCachedContext;
+    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;
+}
+export {};

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

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

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

@@ -1,7 +1,9 @@
 import { FASTElement, ShadowRootOptions } from "@microsoft/fast-element";
 import "@microsoft/fast-element/install-hydratable-view-templates.js";
+export type ObserverMapOption = "all";
 export interface ElementOptions {
     shadowOptions?: ShadowRootOptions | undefined;
+    observerMap?: ObserverMapOption | undefined;
 }
 /**
  * A dictionary of element options the TemplateElement will use to update the registered element
@@ -22,6 +24,10 @@ declare class TemplateElement extends FASTElement {
      */
     static elementOptions: ElementOptionsDictionary;
     private partials;
+    /**
+     * ObserverMap instance for caching binding paths
+     */
+    private observerMap?;
     private static defaultElementOptions;
     static options(elementOptions?: ElementOptionsDictionary): typeof TemplateElement;
     constructor();
@@ -35,6 +41,7 @@ declare class TemplateElement extends FASTElement {
      * 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;
     /**
@@ -48,6 +55,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;
     /**
@@ -64,6 +73,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;
     /**
@@ -72,6 +82,7 @@ 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;
     /**

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

@@ -1,3 +1,4 @@
+import { type ObserverMap } from "./observer-map.js";
 type BehaviorType = "dataBinding" | "templateDirective";
 type TemplateDirective = "when" | "repeat" | "apply";
 export type AttributeDirective = "children" | "slotted" | "ref";
@@ -5,6 +6,7 @@ type DataBindingBindingType = "client" | "default" | "unescaped";
 interface BehaviorConfig {
     type: BehaviorType;
 }
+export type PathType = "access" | "default" | "event" | "repeat";
 export interface ContentDataBindingBehaviorConfig extends BaseDataBindingBehaviorConfig {
     subtype: "content";
 }
@@ -39,6 +41,45 @@ interface PartialTemplateConfig {
     startIndex: number;
     endIndex: number;
 }
+type AccessCachedPathType = "access";
+export interface AccessCachedPath {
+    type: AccessCachedPathType;
+    relativePath: string;
+    absolutePath: string;
+}
+type DefaultCachedPathType = "default";
+export interface DefaultCachedPath {
+    type: DefaultCachedPathType;
+    paths: Record<string, CachedPath>;
+}
+type EventCachedPathType = "event";
+export interface EventCachedPath {
+    type: EventCachedPathType;
+    relativePath: string;
+    absolutePath: string;
+}
+type RepeatCachedPathType = "repeat";
+export interface RepeatCachedPath {
+    type: RepeatCachedPathType;
+    context: string;
+    paths: Record<string, CachedPath>;
+}
+export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+export type CachedPathMap = Record<string, CachedPath>;
+export interface ContextCache {
+    /**
+     * The path to this context
+     */
+    absolutePath: string;
+    /**
+     * The self string of that context
+     */
+    context: string;
+    /**
+     * The parent of this context
+     */
+    parent: string | null;
+}
 /**
  * Get the index of the next matching tag
  * @param openingTagStartSlice - The slice starting from the opening tag
@@ -74,6 +115,14 @@ export declare function getAllPartials(innerHTML: string, offset?: number, parti
  * @returns A function to access the value from a given path.
  */
 export declare function pathResolver(path: string, self?: boolean): (accessibleObject: any, context: any) => any;
+export declare function bindingResolver(path: string, self: boolean | undefined, parentContext: string | null, type: PathType, observerMap: ObserverMap | null, contextPath: string | null, level: number): (accessibleObject: any, context: any) => any;
+export declare function expressionResolver(self: boolean, expression: ChainedExpression, parentContext: string | null, level: number, observerMap?: ObserverMap): (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:
  *
@@ -93,6 +142,7 @@ type ChainingOperator = "||" | "&&" | "&amp;&amp;";
 interface Expression {
     operator: Operator;
     left: string;
+    leftIsValue: boolean | null;
     right: string | boolean | number | null;
     rightIsValue: boolean | null;
 }
@@ -119,7 +169,16 @@ export declare function transformInnerHTML(innerHTML: string, index?: number): s
  * @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
+ * @param observerMap - Optional ObserverMap instance for caching paths during template processing
  * @returns - A binding that resolves the chained expression logic
  */
-export declare function resolveWhen(self: boolean, { expression, next }: ChainedExpression): (x: boolean, c: any) => any;
+export declare function resolveWhen(self: boolean, expression: ChainedExpression, parentContext: string | null, level: number, observerMap?: ObserverMap): (x: boolean, c: any) => any;
+/**
+ * Get the next property
+ * @param path The dot syntax data path
+ * @returns The next property
+ */
+export declare function getNextProperty(path: string): string;
+export declare function assignObservables(cachePath: CachedPath, data: any, target: any, rootProperty: string): typeof Proxy;
+export declare function assignProxy(cachePath: CachedPath, target: any, rootProperty: string, object: any): typeof Proxy;
 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 { RenderableFASTElement, TemplateElement } from "./components/index.js";
+export { RenderableFASTElement, TemplateElement, ObserverMap, } from "./components/index.js";

package/dist/esm/components/element.js

@@ -1,20 +1,27 @@
-import { __decorate, __metadata } from "tslib";
-import { attr, FASTElement } from "@microsoft/fast-element";
-export class RenderableFASTElement extends FASTElement {
-    constructor() {
-        super();
-        this.deferHydration = true;
-        if (this.prepare) {
-            this.prepare().then(() => {
+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;
-            });
+            }
         }
-        else {
-            this.deferHydration = false;
-        }
-    }
+    };
+    attr({ mode: "boolean", attribute: "defer-hydration" })(C.prototype, "deferHydration");
+    return C;
 }
-__decorate([
-    attr({ mode: "boolean", attribute: "defer-hydration" }),
-    __metadata("design:type", Boolean)
-], RenderableFASTElement.prototype, "deferHydration", void 0);

package/dist/esm/components/index.js

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