@microsoft/fast-html 1.0.0-alpha.17 → 1.0.0-alpha.19

package/README.md

@@ -22,12 +22,12 @@ 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";
 
-MyCustomElement.define({
+RenderableFASTElement(MyCustomElement).defineAsync({
     name: "my-custom-element",
-    shadowOptions: null,
+    templateOptions: "defer-and-hydrate",
 });
 
 TemplateElement.define({
@@ -35,9 +35,7 @@ TemplateElement.define({
 });
 ```
 
-This will include the `<f-template>` custom element and all logic for interpreting the declarative HTML syntax for a FAST web component as well as the `shadowOptions` for any element an `<f-template>` has been used to define.
-
-It is necessary to set the initial `shadowOptions` of your custom elements to `null` otherwise a shadowRoot will be attached and cause a FOUC (Flash Of Unstyled Content). For more information about how this affects hydration, check out our [document](./RENDERING.md#setting-shadow-options) on rendering DOM from a non-browser environment.
+This will include the `<f-template>` custom element and all logic for interpreting the declarative HTML syntax for a FAST web component.
 
 The template must be wrapped in `<f-template name="[custom-element-name]"><template>[template logic]</template></f-template>` with a `name` attribute for the custom elements name, and the template logic inside.
 
@@ -77,23 +75,19 @@ TemplateElement.options({
 
 #### Using the RenderableFASTElement
 
-The exported abstract class `RenderableFASTElement` is available for automatic addition and removal of `defer-hydration` and `needs-hydration`. If you use `FASTElement` you will need to add `defer-hydration` and `needs-hydration` attributes to your rendered markup and remove them via your component.
+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
-import { RenderableFASTElement, TemplateElement } from "@microsoft/fast-html";
-
-class MyCustomElement extends RenderableFASTElement {
-    // component logic
+class MyCustomElement extends FASTElement {
+    private prepare(): Promise<void> {
+        // Get initial state
+    }
 }
 
-MyCustomElement.define({
+RenderableFASTElement(MyCustomElement).defineAsync({
     name: "my-custom-element",
-    shadowOptions: null,
-});
-
-TemplateElement.define({
-    name: "f-template",
+    templateOptions: "defer-and-hydrate",
 });
 ```
 

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/schema.d.ts

@@ -0,0 +1,126 @@
+interface JSONSchemaDefinition extends JSONSchemaCommon {
+    $fast_context: string;
+    $fast_parent_contexts: Array<string>;
+}
+interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+}
+interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+    $ref?: string;
+}
+type AccessCachedPathType = "access";
+export interface AccessCachedPath {
+    type: AccessCachedPathType;
+    currentContext: string | null;
+    path: string;
+}
+type DefaultCachedPathType = "default";
+export interface DefaultCachedPath {
+    type: DefaultCachedPathType;
+    currentContext: string | null;
+    path: string;
+}
+type EventCachedPathType = "event";
+export interface EventCachedPath {
+    type: EventCachedPathType;
+    currentContext: string | null;
+    path: string;
+}
+type RepeatCachedPathType = "repeat";
+export interface RepeatCachedPath {
+    type: RepeatCachedPathType;
+    parentContext: string | null;
+    currentContext: string;
+    path: string;
+}
+export type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+export type CachedPathMap = Map<string, JSONSchema>;
+interface RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+}
+/**
+ * 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;
+    /**
+     * 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/schema.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/index.js

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