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

package/dist/fast-html.untrimmed.d.ts

@@ -1,8 +1,44 @@
+import { Constructable } from '@microsoft/fast-element';
 import { FASTElement } from '@microsoft/fast-element';
 import { ShadowRootOptions } from '@microsoft/fast-element';
 
+declare interface AccessCachedPath {
+    type: AccessCachedPathType;
+    relativePath: string;
+    absolutePath: string;
+}
+
+declare type AccessCachedPathType = "access";
+
+declare type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+
+declare type CachedPathMap = Record<string, CachedPath>;
+
+declare 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;
+}
+
+declare interface DefaultCachedPath {
+    type: DefaultCachedPathType;
+    paths: Record<string, CachedPath>;
+}
+
+declare type DefaultCachedPathType = "default";
+
 declare interface ElementOptions {
     shadowOptions?: ShadowRootOptions | undefined;
+    observerMap?: ObserverMapOption | undefined;
 }
 
 /**
@@ -12,16 +48,179 @@ declare interface ElementOptionsDictionary<ElementOptionsType = ElementOptions>
     [key: string]: ElementOptionsType;
 }
 
-export declare abstract class RenderableFASTElement extends FASTElement {
-    deferHydration: boolean;
-    constructor();
+declare interface EventCachedPath {
+    type: EventCachedPathType;
+    relativePath: string;
+    absolutePath: string;
+}
+
+declare type EventCachedPathType = "event";
+
+/**
+ * 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;
     /**
-     * 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.
+     * Finds a context item in the temporary context cache
      */
-    private prepare;
+    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;
+}
+
+declare type ObserverMapOption = "all";
+
+declare interface PathConfig {
+    path: string;
+    self: boolean;
+    parentContext: string | null;
+    contextPath: string | null;
+    type: PathType;
+    level: number;
+    rootPath: string | null;
+    context: ContextCache | null;
 }
 
+declare type PathType = "access" | "default" | "event" | "repeat";
+
+/**
+ * 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;
+
+declare interface RepeatCachedPath {
+    type: RepeatCachedPathType;
+    context: string;
+    paths: Record<string, CachedPath>;
+}
+
+declare type RepeatCachedPathType = "repeat";
+
 /**
  * The <f-template> custom element that will provide view logic to the element
  */
@@ -35,6 +234,10 @@ export 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();
@@ -48,6 +251,7 @@ export 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;
     /**
@@ -61,6 +265,8 @@ export 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;
     /**
@@ -77,6 +283,7 @@ export 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;
     /**
@@ -85,6 +292,7 @@ export 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/fast-html",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.18",
   "type": "module",
   "author": {
     "name": "Microsoft",
@@ -33,8 +33,9 @@
     "build:when": "webpack --config ./src/fixtures/when/webpack.config.js",
     "build:ref": "webpack --config ./src/fixtures/ref/webpack.config.js",
     "build:repeat": "webpack --config ./src/fixtures/repeat/webpack.config.js",
+    "build:observer-map": "webpack --config ./src/fixtures/observer-map/webpack.config.js",
     "build:slotted": "webpack --config ./src/fixtures/slotted/webpack.config.js",
-    "build-app": "npm run build:attribute && npm run build:dot-syntax && npm run build:partial && npm run build:event && npm run build:children && npm run build:binding && npm run build:when && npm run build:ref && npm run build:repeat && npm run build:slotted",
+    "build-app": "npm run build:attribute && npm run build:dot-syntax && npm run build:partial && npm run build:event && npm run build:children && npm run build:binding && npm run build:when && npm run build:ref && npm run build:repeat && npm run build:observer-map && npm run build:slotted",
     "build-server": "tsc -b server",
     "doc": "api-extractor run --local",
     "doc:ci": "api-extractor run",
@@ -63,12 +64,12 @@
     "./dist/esm/index.js"
   ],
   "peerDependencies": {
-    "@microsoft/fast-element": "^2.5.0"
+    "@microsoft/fast-element": "^2.6.0"
   },
   "devDependencies": {
     "@ast-grep/cli": "^0.37.0",
     "@microsoft/api-extractor": "^7.47.0",
-    "@microsoft/fast-element": "^2.5.0",
+    "@microsoft/fast-element": "^2.6.0",
     "@playwright/test": "^1.49.0",
     "@types/express": "^4.17.21",
     "@types/node": "^17.0.17",