@microsoft/fast-html 1.0.0-alpha.4 → 1.0.0-alpha.41

package/dist/fast-html.d.ts

@@ -1,4 +1,242 @@
+import { Constructable } from '@microsoft/fast-element';
 import { FASTElement } from '@microsoft/fast-element';
+import { HydrationControllerCallbacks } from '@microsoft/fast-element';
+import { TemplateLifecycleCallbacks } 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 type CachedPathMap = Map<string, Map<string, JSONSchema>>;
+
+declare interface ChildrenMap {
+    customElementName: string;
+    attributeName: string;
+}
+
+declare interface DefaultCachedPath extends CachedPathCommon {
+    type: DefaultCachedPathType;
+}
+
+declare type DefaultCachedPathType = "default";
+
+/**
+ * Element options the TemplateElement will use to update the registered element
+ */
+declare interface ElementOptions {
+    observerMap?: ObserverMapOption;
+}
+
+/**
+ * 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";
+
+/**
+ * Lifecycle callbacks for template and hydration events.
+ * Combines template lifecycle callbacks with hydration callbacks and adds template-processing events.
+ */
+declare 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;
+}
+
+declare interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+}
+
+declare interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+    items?: any;
+    anyOf?: Array<any>;
+    $ref?: string;
+}
+
+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
+     * @param existingChangedMethod - Optional existing changed method to call after the instance resolver logic
+     * @returns A function that handles property changes and sets up proxies for object values
+     */
+    private defineChanged;
+}
+
+/**
+ * Values for the observerMap element option.
+ */
+declare const ObserverMapOption: {
+    readonly all: "all";
+};
+
+/**
+ * Type for the observerMap element option.
+ */
+declare type ObserverMapOption = (typeof ObserverMapOption)[keyof typeof ObserverMapOption];
+
+declare interface RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+    childrenMap: ChildrenMap | null;
+}
+
+/**
+ * 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
+     */
+    static jsonSchemaMap: CachedPathMap;
+    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;
+    /**
+     * Get the schema $id
+     * @param customElementName - The custom element name
+     * @param propertyName - The property name
+     * @returns The ID that can be used in the JSON schema as $id
+     */
+    private getSchemaId;
+    /**
+     * 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 +246,52 @@ export 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;
     /**
@@ -27,6 +305,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 +323,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 +332,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 { }

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

@@ -1,4 +1,242 @@
+import { Constructable } from '@microsoft/fast-element';
 import { FASTElement } from '@microsoft/fast-element';
+import { HydrationControllerCallbacks } from '@microsoft/fast-element';
+import { TemplateLifecycleCallbacks } 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 type CachedPathMap = Map<string, Map<string, JSONSchema>>;
+
+declare interface ChildrenMap {
+    customElementName: string;
+    attributeName: string;
+}
+
+declare interface DefaultCachedPath extends CachedPathCommon {
+    type: DefaultCachedPathType;
+}
+
+declare type DefaultCachedPathType = "default";
+
+/**
+ * Element options the TemplateElement will use to update the registered element
+ */
+declare interface ElementOptions {
+    observerMap?: ObserverMapOption;
+}
+
+/**
+ * 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";
+
+/**
+ * Lifecycle callbacks for template and hydration events.
+ * Combines template lifecycle callbacks with hydration callbacks and adds template-processing events.
+ */
+declare 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;
+}
+
+declare interface JSONSchema extends JSONSchemaCommon {
+    $schema: string;
+    $id: string;
+    $defs?: Record<string, JSONSchemaDefinition>;
+}
+
+declare interface JSONSchemaCommon {
+    type?: string;
+    properties?: any;
+    items?: any;
+    anyOf?: Array<any>;
+    $ref?: string;
+}
+
+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
+     * @param existingChangedMethod - Optional existing changed method to call after the instance resolver logic
+     * @returns A function that handles property changes and sets up proxies for object values
+     */
+    private defineChanged;
+}
+
+/**
+ * Values for the observerMap element option.
+ */
+declare const ObserverMapOption: {
+    readonly all: "all";
+};
+
+/**
+ * Type for the observerMap element option.
+ */
+declare type ObserverMapOption = (typeof ObserverMapOption)[keyof typeof ObserverMapOption];
+
+declare interface RegisterPathConfig {
+    rootPropertyName: string;
+    pathConfig: CachedPath;
+    childrenMap: ChildrenMap | null;
+}
+
+/**
+ * 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
+     */
+    static jsonSchemaMap: CachedPathMap;
+    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;
+    /**
+     * Get the schema $id
+     * @param customElementName - The custom element name
+     * @param propertyName - The property name
+     * @returns The ID that can be used in the JSON schema as $id
+     */
+    private getSchemaId;
+    /**
+     * 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 +246,52 @@ export 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;
     /**
@@ -27,6 +305,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 +323,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 +332,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 { }