@microsoft/fast-html 1.0.0-alpha.3 → 1.0.0-alpha.31

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

@@ -1,4 +1,241 @@
+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
+     * @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 +245,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 +304,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 +322,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 +331,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/fast-html",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.31",
   "type": "module",
   "author": {
     "name": "Microsoft",
@@ -17,7 +17,8 @@
     "url": "https://github.com/Microsoft/fast/issues/new/choose"
   },
   "files": [
-    "./dist"
+    "./dist",
+    "./rules/*.yml"
   ],
   "scripts": {
     "clean": "tsc -b --clean src",
@@ -28,12 +29,13 @@
     "build:binding": "webpack --config ./src/fixtures/binding/webpack.config.js",
     "build:children": "webpack --config ./src/fixtures/children/webpack.config.js",
     "build:dot-syntax": "webpack --config ./src/fixtures/dot-syntax/webpack.config.js",
-    "build:partial": "webpack --config ./src/fixtures/partial/webpack.config.js",
     "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:lifecycle-callbacks": "webpack --config ./src/fixtures/lifecycle-callbacks/webpack.config.js",
+    "build-app": "npm run build:attribute && npm run build:dot-syntax && 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 && npm run build:lifecycle-callbacks",
     "build-server": "tsc -b server",
     "doc": "api-extractor run --local",
     "doc:ci": "api-extractor run",
@@ -43,8 +45,9 @@
     "pretest": "npm run build && npm run build-server",
     "prettier:diff": "prettier --config ../../../.prettierrc \"**/*.{ts,html}\" --list-different",
     "prettier": "prettier --config ../../../.prettierrc --write \"**/*.{ts,html}\"",
-    "test": "npm run build-app && playwright test --config=playwright.config.cjs",
+    "test": "npm run build-app && playwright test && npm run test:rules",
     "test-server": "node server/dist/server.js",
+    "test:rules": "sg test --skip-snapshot-tests",
     "install-playwright-browsers": "npm run playwright install",
     "dev": "npm run build && npm run build-app && npm run build-server && npm run test-server"
   },
@@ -54,17 +57,19 @@
       "types": "./dist/dts/index.d.ts",
       "default": "./dist/esm/index.js"
     },
+    "./rules/*.yml": "./rules/*.yml",
     "./package.json": "./package.json"
   },
   "sideEffects": [
     "./dist/esm/index.js"
   ],
   "peerDependencies": {
-    "@microsoft/fast-element": "^2.2.0"
+    "@microsoft/fast-element": "^2.8.1"
   },
   "devDependencies": {
+    "@ast-grep/cli": "^0.37.0",
     "@microsoft/api-extractor": "^7.47.0",
-    "@microsoft/fast-element": "^2.2.0",
+    "@microsoft/fast-element": "^2.8.1",
     "@playwright/test": "^1.49.0",
     "@types/express": "^4.17.21",
     "@types/node": "^17.0.17",

package/rules/attribute-directives.yml

@@ -0,0 +1,38 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: ${ref("defaultSlot")}
+# to: f-ref="{defaultSlot}"
+id: binding - convert attribute directives
+language: typescript
+utils:
+  call-expression:
+    has:
+      nthChild: 1
+      kind: call_expression
+      all:
+        - matches: identifier
+        - matches: arguments
+  identifier:
+    has:
+      nthChild: 1
+      kind: identifier
+      pattern: $DIRECTIVE
+  arguments:
+    has:
+      kind: arguments
+      matches: string
+  string:
+    has:
+      kind: string
+      matches: string-fragment
+  string-fragment:
+    has:
+      kind: string_fragment
+      pattern: $STRING
+constraints:
+  DIRECTIVE:
+    regex: ref|slotted|children
+rule:
+  kind: template_substitution
+  matches: call-expression
+fix:
+  'f-$DIRECTIVE="{$STRING}"'

package/rules/call-expression-with-event-argument.yml

@@ -0,0 +1,41 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: ${(x, c) => x.foo(c.event)}
+# to: {foo(event)}
+id: binding - convert call expression with event argument
+language: typescript
+utils:
+  arrow-function:
+    has:
+      kind: arrow_function
+      matches: call-expression
+  call-expression:
+    has:
+      kind: call_expression
+      all:
+        - matches: handler-arguments
+        - matches: handler-expression
+  handler-expression:
+    has:
+      kind: member_expression
+      matches: handler-expression-property
+  handler-expression-property:
+    has:
+      kind: property_identifier
+      pattern: $A
+  handler-arguments:
+    has:
+      kind: arguments
+      matches: handler-arguments-member-expression
+  handler-arguments-member-expression:
+    has:
+      kind: member_expression
+      matches: handler-arguments-property-identifier
+  handler-arguments-property-identifier:
+    has:
+      kind: property_identifier
+      pattern: $B
+rule:
+  kind: template_substitution
+  matches: arrow-function
+fix:
+  '{$A($B)}'

package/rules/member-expression.yml

@@ -0,0 +1,33 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: ${x => x.foo}
+# to: {{foo}}
+id: binding - convert member expression
+language: typescript
+utils:
+  arrow-function:
+    has:
+      kind: arrow_function
+      all:
+        - matches: identifier
+        - matches: member-expression
+  member-expression:
+    has:
+      kind: member_expression
+      nthChild: 2
+      all:
+        - matches: identifier
+        - matches: property-identifier
+  identifier:
+    has:
+      kind: identifier
+      nthChild: 1
+  property-identifier:
+    has:
+      kind: property_identifier
+      nthChild: 2
+      pattern: $A
+rule:
+  kind: template_substitution
+  matches: arrow-function
+fix:
+  '{{$A}}'

package/rules/tag-function-to-template-literal.yml

@@ -0,0 +1,16 @@
+# https://ast-grep.github.io/guide/rule-config.html#rule
+# from: export const template = html`<slot></slot>`
+# to: `<slot></slot>`
+id: convert tag function to template literal
+language: typescript
+utils:
+  is-tag-template:
+    has:
+      kind: template_string
+      pattern: $B
+rule:
+  kind: call_expression
+  matches: is-tag-template
+  pattern: $A
+fix:
+  '$B'

package/dist/esm/fixtures/partial/main.js

@@ -1,31 +0,0 @@
-import { TemplateElement } from "@microsoft/fast-html";
-import { FASTElement } from "@microsoft/fast-element";
-class TestElement extends FASTElement {
-    constructor() {
-        super(...arguments);
-        this.items = [
-            {
-                text: "Hello",
-            },
-            {
-                text: "Earth",
-                items: [
-                    {
-                        text: "Pluto",
-                        items: [
-                            {
-                                text: "Mars",
-                            },
-                        ],
-                    },
-                ],
-            },
-        ];
-    }
-}
-TestElement.define({
-    name: "test-element",
-});
-TemplateElement.define({
-    name: "f-template",
-});

package/dist/esm/fixtures/partial/partial.spec.js

@@ -1,14 +0,0 @@
-import { __awaiter } from "tslib";
-import { expect, test } from "@playwright/test";
-test.describe("f-template", () => __awaiter(void 0, void 0, void 0, function* () {
-    test("create a partial", ({ page }) => __awaiter(void 0, void 0, void 0, function* () {
-        yield page.goto("/partial");
-        const customElement = yield page.locator("#test");
-        let customElementListItems = yield customElement.locator("li");
-        expect(yield customElementListItems.count()).toEqual(4);
-        expect(yield customElementListItems.nth(0).textContent()).toEqual("Hello");
-        expect(yield customElementListItems.nth(1).textContent()).toContain("Earth");
-        expect(yield customElementListItems.nth(2).textContent()).toContain("Pluto");
-        expect(yield customElementListItems.nth(3).textContent()).toContain("Mars");
-    }));
-}));