@microsoft/fast-html 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/fast-html.api.json

@@ -172,6 +172,185 @@
       "name": "",
       "preserveMemberOrder": false,
       "members": [
+        {
+          "kind": "Class",
+          "canonicalReference": "@microsoft/fast-html!ObserverMap:class",
+          "docComment": "/**\n * ObserverMap provides functionality for caching binding paths, extracting root properties, and defining observable properties on class prototypes\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class ObserverMap "
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/observer-map.d.ts",
+          "releaseTag": "Public",
+          "isAbstract": false,
+          "name": "ObserverMap",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@microsoft/fast-html!ObserverMap:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `ObserverMap` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(classPrototype: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "any"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", schema: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Schema",
+                  "canonicalReference": "@microsoft/fast-html!~Schema:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "classPrototype",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "schema",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ]
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@microsoft/fast-html!ObserverMap#defineProperties:member(1)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "defineProperties(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "void"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "defineProperties"
+            }
+          ],
+          "implementsTokenRanges": []
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@microsoft/fast-html!RenderableFASTElement:function(1)",
+          "docComment": "/**\n * A mixin function that extends a base class with additional functionality for rendering and hydration.\n *\n * @param BaseCtor - The base class to extend.\n *\n * @returns A new class that extends the provided base class with additional functionality for rendering and hydration.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare function RenderableFASTElement<T extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Constructable",
+              "canonicalReference": "@microsoft/fast-element!Constructable:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "FASTElement",
+              "canonicalReference": "@microsoft/fast-element!FASTElement:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            },
+            {
+              "kind": "Content",
+              "text": ">(BaseCtor: "
+            },
+            {
+              "kind": "Content",
+              "text": "T"
+            },
+            {
+              "kind": "Content",
+              "text": "): "
+            },
+            {
+              "kind": "Content",
+              "text": "T"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "dist/dts/components/element.d.ts",
+          "returnTypeTokenRange": {
+            "startIndex": 8,
+            "endIndex": 9
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "BaseCtor",
+              "parameterTypeTokenRange": {
+                "startIndex": 6,
+                "endIndex": 7
+              },
+              "isOptional": false
+            }
+          ],
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "RenderableFASTElement"
+        },
         {
           "kind": "Class",
           "canonicalReference": "@microsoft/fast-html!TemplateElement:class",
@@ -197,6 +376,21 @@
           "name": "TemplateElement",
           "preserveMemberOrder": false,
           "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@microsoft/fast-html!TemplateElement:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `TemplateElement` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor();"
+                }
+              ],
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": []
+            },
             {
               "kind": "Method",
               "canonicalReference": "@microsoft/fast-html!TemplateElement#connectedCallback:member(1)",
@@ -228,6 +422,37 @@
               "isAbstract": false,
               "name": "connectedCallback"
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@microsoft/fast-html!TemplateElement.elementOptions:member",
+              "docComment": "/**\n * A dictionary of custom element options\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static elementOptions: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ElementOptionsDictionary",
+                  "canonicalReference": "@microsoft/fast-html!~ElementOptionsDictionary:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "elementOptions",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": true,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@microsoft/fast-html!TemplateElement#name:member",
@@ -257,6 +482,60 @@
               "isStatic": false,
               "isProtected": false,
               "isAbstract": false
+            },
+            {
+              "kind": "Method",
+              "canonicalReference": "@microsoft/fast-html!TemplateElement.options:member(1)",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "static options(elementOptions?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ElementOptionsDictionary",
+                  "canonicalReference": "@microsoft/fast-html!~ElementOptionsDictionary:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "typeof "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TemplateElement",
+                  "canonicalReference": "@microsoft/fast-html!TemplateElement:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": true,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 5
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "elementOptions",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": true
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "options"
             }
           ],
           "extendsTokenRange": {

package/dist/fast-html.d.ts

@@ -1,4 +1,197 @@
+import { Constructable } from '@microsoft/fast-element';
 import { FASTElement } from '@microsoft/fast-element';
+import { ShadowRootOptions } from '@microsoft/fast-element';
+
+declare interface AccessCachedPath extends CachedPathCommon {
+    type: AccessCachedPathType;
+}
+
+declare type AccessCachedPathType = "access";
+
+declare type CachedPath = DefaultCachedPath | RepeatCachedPath | AccessCachedPath | EventCachedPath;
+
+declare interface CachedPathCommon {
+    parentContext: string | null;
+    currentContext: string | null;
+    path: string;
+}
+
+declare interface DefaultCachedPath extends CachedPathCommon {
+    type: DefaultCachedPathType;
+}
+
+declare type DefaultCachedPathType = "default";
+
+declare interface ElementOptions {
+    shadowOptions?: ShadowRootOptions | undefined;
+    observerMap?: ObserverMapOption | undefined;
+}
+
+/**
+ * A dictionary of element options the TemplateElement will use to update the registered element
+ */
+declare interface ElementOptionsDictionary<ElementOptionsType = ElementOptions> {
+    [key: string]: ElementOptionsType;
+}
+
+declare interface EventCachedPath extends CachedPathCommon {
+    type: EventCachedPathType;
+}
+
+declare type EventCachedPathType = "event";
+
+declare interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+    $ref?: string;
+}
+
+declare interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+    items?: any;
+}
+
+declare interface JSONSchemaDefinition extends JSONSchemaCommon {
+    $fast_context: string;
+    $fast_parent_contexts: Array<string>;
+}
+
+/**
+ * ObserverMap provides functionality for caching binding paths, extracting root properties,
+ * and defining observable properties on class prototypes
+ */
+export declare class ObserverMap {
+    private schema;
+    private classPrototype;
+    constructor(classPrototype: any, schema: Schema);
+    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 RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+}
+
+/**
+ * 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 extends CachedPathCommon {
+    type: RepeatCachedPathType;
+}
+
+declare type RepeatCachedPathType = "repeat";
+
+/**
+ * A constructed JSON schema from a template
+ */
+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;
+    /**
+     * Gets root properties
+     * @returns IterableIterator<string>
+     */
+    getRootProperties(): IterableIterator<string>;
+    /**
+     * 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;
+}
 
 /**
  * The <f-template> custom element that will provide view logic to the element
@@ -8,12 +201,30 @@ export declare class TemplateElement extends FASTElement {
      * The name of the custom element this template will be applied to
      */
     name?: string;
+    /**
+     * A dictionary of custom element options
+     */
+    static elementOptions: ElementOptionsDictionary;
     private partials;
+    /**
+     * ObserverMap instance for caching binding paths
+     */
+    private observerMap?;
+    private schema?;
+    private static defaultElementOptions;
+    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;
     /**
@@ -27,6 +238,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;
     /**
@@ -43,6 +256,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;
     /**
@@ -51,13 +265,9 @@ 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;
-    /**
-     * Resolve all partial templates
-     * @param unresolvedInnerHTML - The innerHTML.
-     */
-    private resolveAllPartials;
 }
 
 export { }