@microsoft/fast-element 1.10.5 → 2.0.0-beta.10

package/docs/fast-element-2-changes.md

@@ -0,0 +1,15 @@
+# Changes in FASTElement 2.0
+
+## Breaking Changes
+
+* `HTMLDirective` - The `targetIndex: number` property has been replaced by a `targetId: string` property. The `createBehavior` method no longer takes a target `Node` but instead takes a `BehaviorTargets` instance. The actual target can be looked up on the `BehaviorTargets` instance by indexing with the `targetId` property.
+* `compileTemplate()` - Internals have been significantly changed. The implementation no longer uses a TreeWalker. The return type has change to an `HTMLTemplateCompilationResult` with different properties.
+* `View` and `HTMLView` - Type parameters added to enable strongly typed views based on their data source. The constructor of `HTMLView` has a new signature based on changes to the compiler's output. Internals have been cleaned up and no longer rely on the Range type.
+* `ElementViewTemplate`, `SyntheticViewTemplate`, and `ViewTemplate` - Added type parameters throughout. Logic to instantiate and apply behaviors moved out of the template and into the view where it can be lazily executed. Removed the ability of the `render` method to take a string id of the node to render to. You must provide a node.
+* `DOM` - Tree Walker methods are no longer used and are thus removed. The API for removing child nodes has been removed as well since it was only used in one place and could be inlined. The helper `createCustomAttributePlaceholder()` no longer requires an attribute name. It will be uniquely generated internally.
+* `class` - Bindings to `class` are now more nuanced. Binding directly to `class` will simply set the `className` property. If you need to bind to `class` knowing that manual JS will also manipulate the `classList` in addition to the binding, then you should now bind to `:classList` instead. This allows for performance optimizations in the simple, most common case.
+* `Behavior` and `ViewBehavior` - `Behavior` now requires an `ExecutionContext` for `unbind`. Behaviors can be used for elements or views. `ViewBehavior` has been introduced for use exclusively with views, and provides some optimization opportunities.
+* `RefBehavior` has been replaced with `RefDirective`. The directive also implements `ViewBehavior` allowing a single directive instance to be shared across all template instances that use the ref.
+* Removed `SlottedBehavior` and `ChildrenBehavior` have been replaced with `SlottedDirective` and `ChildrenDirective`. These directives allow a single directive instance to be shared across all template instances that use the ref.
+* Removed `AttachedBehaviorHTMLDirective` and `AttachedBehaviorType` since they are no longer used in the new directive/behavior architecture for ref, slotted, and children.
+* Renamed `Notifier#source` to `Notifier#subject` to align with other observable terminology and prevent name clashes with `BindingObserver` properties.

package/karma.conf.cjs

@@ -1,5 +1,4 @@
 const path = require("path");
-
 const basePath = path.resolve(__dirname);
 
 const commonChromeFlags = [
@@ -44,9 +43,9 @@ module.exports = function (config) {
             require("karma-chrome-launcher"),
             require("karma-firefox-launcher"),
         ],
-        files: [`dist/esm/__test__/${setup}.js`],
+        files: [`dist/esm/__test__/${setup}.cjs`],
         preprocessors: {
-            [`dist/esm/__test__/${setup}.js`]: ["webpack", "sourcemap"],
+            [`dist/esm/__test__/${setup}.cjs`]: ["webpack", "sourcemap"],
         },
         webpackMiddleware: {
             // webpack-dev-middleware configuration
@@ -54,7 +53,7 @@ module.exports = function (config) {
             stats: "errors-only",
         },
         webpack: {
-            mode: "none",
+            mode: "development",
             resolve: {
                 extensions: [".js"],
                 modules: ["dist", "node_modules"],
@@ -65,12 +64,8 @@ module.exports = function (config) {
                 hints: false,
             },
             optimization: {
-                namedModules: false,
-                namedChunks: false,
-                nodeEnv: false,
                 usedExports: true,
                 flagIncludedChunks: false,
-                occurrenceOrder: false,
                 sideEffects: true,
                 concatenateModules: true,
                 splitChunks: {
@@ -89,14 +84,8 @@ module.exports = function (config) {
                     },
                     {
                         test: /\.js$/,
-                        use: [
-                            {
-                                loader: "source-map-loader",
-                                options: {
-                                    enforce: "pre",
-                                },
-                            },
-                        ],
+                        use: ["source-map-loader"],
+                        enforce: "pre",
                     },
                 ],
             },
@@ -125,7 +114,7 @@ module.exports = function (config) {
                 timeout: 5000,
             },
         },
-        logLevel: config.LOG_ERROR, // to disable the WARN 404 for image requests
+        logLevel: config.LOG_ERROR, // to disable the WARN 404 for image requests,
     };
 
     if (config.coverage) {

package/package.json

@@ -1,24 +1,86 @@
 {
   "name": "@microsoft/fast-element",
   "description": "A library for constructing Web Components",
-  "sideEffects": false,
-  "version": "1.10.5",
+  "version": "2.0.0-beta.10",
   "author": {
     "name": "Microsoft",
     "url": "https://discord.gg/FcSNfg4"
   },
+  "homepage": "https://www.fast.design/",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Microsoft/fast.git"
+    "url": "git+https://github.com/Microsoft/fast.git",
+    "directory": "packages/web-components/fast-element"
   },
   "bugs": {
     "url": "https://github.com/Microsoft/fast/issues/new/choose"
   },
-  "main": "dist/esm/index.js",
-  "types": "dist/fast-element.d.ts",
   "type": "module",
+  "main": "dist/esm/index.js",
+  "types": "dist/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/dts/index.d.ts",
+      "production": "./dist/esm/index.js",
+      "development": "./dist/esm/index.debug.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./polyfills": {
+      "types": "./dist/dts/polyfills.d.ts",
+      "default": "./dist/esm/polyfills.js"
+    },
+    "./debug": {
+      "types": "./dist/dts/debug.d.ts",
+      "default": "./dist/esm/debug.js"
+    },
+    "./binding/two-way": {
+      "types": "./dist/dts/templating/binding-two-way.d.ts",
+      "default": "./dist/esm/templating/binding-two-way.js"
+    },
+    "./binding/signal": {
+      "types": "./dist/dts/templating/binding-signal.d.ts",
+      "default": "./dist/esm/templating/binding-signal.js"
+    },
+    "./render": {
+      "types": "./dist/dts/templating/render.d.ts",
+      "default": "./dist/esm/templating/render.js"
+    },
+    "./utilities": {
+      "types": "./dist/dts/utilities.d.ts",
+      "default": "./dist/esm/utilities.js"
+    },
+    "./state": {
+      "types": "./dist/dts/state/exports.d.ts",
+      "default": "./dist/esm/state/exports.js"
+    },
+    "./context": {
+      "types": "./dist/dts/context.d.ts",
+      "default": "./dist/esm/context.js"
+    },
+    "./metadata": {
+      "types": "./dist/dts/metadata.d.ts",
+      "default": "./dist/esm/metadata.js"
+    },
+    "./testing": {
+      "types": "./dist/dts/testing/exports.d.ts",
+      "default": "./dist/esm/testing/exports.js"
+    },
+    "./di": {
+      "types": "./dist/dts/di/di.d.ts",
+      "default": "./dist/esm/di/di.js"
+    },
+    "./pending-task": {
+      "types": "./dist/dts/pending-task.d.ts",
+      "default": "./dist/esm/pending-task.js"
+    },
+    "./package.json": "./package.json"
+  },
   "unpkg": "dist/fast-element.min.js",
+  "sideEffects": [
+    "./dist/esm/debug.js",
+    "./dist/esm/polyfills.js"
+  ],
   "scripts": {
     "clean:dist": "node ../../../build/clean.js dist",
     "doc": "api-extractor run --local",
@@ -46,13 +108,12 @@
     "test-firefox:verbose": "karma start karma.conf.cjs --browsers=FirefoxHeadless --single-run --coverage --reporter=mocha"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "7.23.1",
+    "@microsoft/api-extractor": "7.24.2",
     "@types/chai": "^4.2.11",
     "@types/chai-spies": "^1.0.3",
     "@types/karma": "^5.0.0",
     "@types/mocha": "^7.0.2",
     "@types/webpack-env": "^1.15.2",
-    "@types/web-ie11": "^0.0.0",
     "chai": "^4.2.0",
     "chai-spies": "^1.0.0",
     "esm": "^3.2.25",
@@ -70,21 +131,21 @@
     "karma-mocha-reporter": "^2.2.5",
     "karma-source-map-support": "^1.4.0",
     "karma-sourcemap-loader": "^0.3.7",
-    "karma-webpack": "^4.0.2",
+    "karma-webpack": "^5.0.0",
     "mocha": "^7.1.2",
     "prettier": "2.0.2",
-    "rollup": "^2.7.6",
+    "rollup": "^2.71.1",
     "rollup-plugin-filesize": "^9.1.2",
-    "rollup-plugin-terser": "^5.3.0",
-    "rollup-plugin-transform-tagged-template": "^0.0.3",
-    "rollup-plugin-typescript2": "^0.27.0",
+    "rollup-plugin-terser": "^7.0.2",
+    "@rollup/plugin-typescript": "^8.3.2",
     "source-map": "^0.7.3",
     "source-map-loader": "^0.2.4",
     "ts-loader": "^7.0.2",
     "ts-node": "^8.9.1",
     "tsconfig-paths": "^3.9.0",
-    "tslib": "^1.11.1",
-    "typescript": "^4.6.2",
-    "webpack": "^4.44.0"
+    "tslib": "^2.4.0",
+    "typescript": "^4.7.0",
+    "webpack": "^5.72.0",
+    "webpack-cli": "^4.9.2"
   }
 }

package/dist/dts/dom.d.ts

@@ -1,112 +0,0 @@
-import type { Callable } from "./interfaces.js";
-import { TrustedTypesPolicy } from "./platform.js";
-/** @internal */
-export declare const _interpolationStart: string;
-/** @internal */
-export declare const _interpolationEnd: string;
-/**
- * Common DOM APIs.
- * @public
- */
-export declare const DOM: Readonly<{
-    /**
-     * Indicates whether the DOM supports the adoptedStyleSheets feature.
-     */
-    supportsAdoptedStyleSheets: boolean;
-    /**
-     * Sets the HTML trusted types policy used by the templating engine.
-     * @param policy - The policy to set for HTML.
-     * @remarks
-     * This API can only be called once, for security reasons. It should be
-     * called by the application developer at the start of their program.
-     */
-    setHTMLPolicy(policy: TrustedTypesPolicy): void;
-    /**
-     * Turns a string into trusted HTML using the configured trusted types policy.
-     * @param html - The string to turn into trusted HTML.
-     * @remarks
-     * Used internally by the template engine when creating templates
-     * and setting innerHTML.
-     */
-    createHTML(html: string): string;
-    /**
-     * Determines if the provided node is a template marker used by the runtime.
-     * @param node - The node to test.
-     */
-    isMarker(node: Node): node is Comment;
-    /**
-     * Given a marker node, extract the {@link HTMLDirective} index from the placeholder.
-     * @param node - The marker node to extract the index from.
-     */
-    extractDirectiveIndexFromMarker(node: Comment): number;
-    /**
-     * Creates a placeholder string suitable for marking out a location *within*
-     * an attribute value or HTML content.
-     * @param index - The directive index to create the placeholder for.
-     * @remarks
-     * Used internally by binding directives.
-     */
-    createInterpolationPlaceholder(index: number): string;
-    /**
-     * Creates a placeholder that manifests itself as an attribute on an
-     * element.
-     * @param attributeName - The name of the custom attribute.
-     * @param index - The directive index to create the placeholder for.
-     * @remarks
-     * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
-     */
-    createCustomAttributePlaceholder(attributeName: string, index: number): string;
-    /**
-     * Creates a placeholder that manifests itself as a marker within the DOM structure.
-     * @param index - The directive index to create the placeholder for.
-     * @remarks
-     * Used internally by structural directives such as `repeat`.
-     */
-    createBlockPlaceholder(index: number): string;
-    /**
-     * Schedules DOM update work in the next async batch.
-     * @param callable - The callable function or object to queue.
-     */
-    queueUpdate: (callable: Callable) => void;
-    /**
-     * Immediately processes all work previously scheduled
-     * through queueUpdate.
-     * @remarks
-     * This also forces nextUpdate promises
-     * to resolve.
-     */
-    processUpdates: () => void;
-    /**
-     * Resolves with the next DOM update.
-     */
-    nextUpdate(): Promise<void>;
-    /**
-     * Sets an attribute value on an element.
-     * @param element - The element to set the attribute value on.
-     * @param attributeName - The attribute name to set.
-     * @param value - The value of the attribute to set.
-     * @remarks
-     * If the value is `null` or `undefined`, the attribute is removed, otherwise
-     * it is set to the provided value using the standard `setAttribute` API.
-     */
-    setAttribute(element: HTMLElement, attributeName: string, value: any): void;
-    /**
-     * Sets a boolean attribute value.
-     * @param element - The element to set the boolean attribute value on.
-     * @param attributeName - The attribute name to set.
-     * @param value - The value of the attribute to set.
-     * @remarks
-     * If the value is true, the attribute is added; otherwise it is removed.
-     */
-    setBooleanAttribute(element: HTMLElement, attributeName: string, value: boolean): void;
-    /**
-     * Removes all the child nodes of the provided parent node.
-     * @param parent - The node to remove the children from.
-     */
-    removeChildNodes(parent: Node): void;
-    /**
-     * Creates a TreeWalker configured to walk a template fragment.
-     * @param fragment - The fragment to walk.
-     */
-    createTemplateWalker(fragment: DocumentFragment): TreeWalker;
-}>;

package/dist/dts/observation/array-change-records.d.ts

@@ -1,48 +0,0 @@
-/**
- * Represents a set of splice-based changes against an Array.
- * @public
- */
-export interface Splice {
-    /**
-     * The index that the splice occurs at.
-     */
-    index: number;
-    /**
-     * The items that were removed.
-     */
-    removed: any[];
-    /**
-     * The  number of items that were added.
-     */
-    addedCount: number;
-}
-/** @internal */
-export declare function newSplice(index: number, removed: any[], addedCount: number): Splice;
-/**
- * Splice Projection functions:
- *
- * A splice map is a representation of how a previous array of items
- * was transformed into a new array of items. Conceptually it is a list of
- * tuples of
- *
- *   <index, removed, addedCount>
- *
- * which are kept in ascending index order of. The tuple represents that at
- * the |index|, |removed| sequence of items were removed, and counting forward
- * from |index|, |addedCount| items were added.
- */
-/**
- * @internal
- * @remarks
- * Lacking individual splice mutation information, the minimal set of
- * splices can be synthesized given the previous state and final state of an
- * array. The basic approach is to calculate the edit distance matrix and
- * choose the shortest path through it.
- *
- * Complexity: O(l * p)
- *   l: The length of the current array
- *   p: The length of the old array
- */
-export declare function calcSplices(current: any[], currentStart: number, currentEnd: number, old: any[], oldStart: number, oldEnd: number): ReadonlyArray<never> | Splice[];
-/** @internal */
-export declare function projectArraySplices(array: any[], changeRecords: any[]): Splice[];

package/dist/dts/observation/array-observer.d.ts

@@ -1,9 +0,0 @@
-/**
- * Enables the array observation mechanism.
- * @remarks
- * Array observation is enabled automatically when using the
- * {@link RepeatDirective}, so calling this API manually is
- * not typically necessary.
- * @public
- */
-export declare function enableArrayObservation(): void;

package/dist/dts/observation/behavior.d.ts

@@ -1,19 +0,0 @@
-import type { ExecutionContext } from "./observable.js";
-/**
- * Represents and object that can contribute behavior to a view or
- * element's bind/unbind operations.
- * @public
- */
-export interface Behavior {
-    /**
-     * Bind this behavior to the source.
-     * @param source - The source to bind to.
-     * @param context - The execution context that the binding is operating within.
-     */
-    bind(source: unknown, context: ExecutionContext): void;
-    /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
-     */
-    unbind(source: unknown): void;
-}

package/dist/esm/dom.js

@@ -1,207 +0,0 @@
-import { $global } from "./platform.js";
-const updateQueue = $global.FAST.getById(1 /* updateQueue */, () => {
-    const tasks = [];
-    const pendingErrors = [];
-    function throwFirstError() {
-        if (pendingErrors.length) {
-            throw pendingErrors.shift();
-        }
-    }
-    function tryRunTask(task) {
-        try {
-            task.call();
-        }
-        catch (error) {
-            pendingErrors.push(error);
-            setTimeout(throwFirstError, 0);
-        }
-    }
-    function process() {
-        const capacity = 1024;
-        let index = 0;
-        while (index < tasks.length) {
-            tryRunTask(tasks[index]);
-            index++;
-            // Prevent leaking memory for long chains of recursive calls to `DOM.queueUpdate`.
-            // If we call `DOM.queueUpdate` within a task scheduled by `DOM.queueUpdate`, the queue will
-            // grow, but to avoid an O(n) walk for every task we execute, we don't
-            // shift tasks off the queue after they have been executed.
-            // Instead, we periodically shift 1024 tasks off the queue.
-            if (index > capacity) {
-                // Manually shift all values starting at the index back to the
-                // beginning of the queue.
-                for (let scan = 0, newLength = tasks.length - index; scan < newLength; scan++) {
-                    tasks[scan] = tasks[scan + index];
-                }
-                tasks.length -= index;
-                index = 0;
-            }
-        }
-        tasks.length = 0;
-    }
-    function enqueue(callable) {
-        if (tasks.length < 1) {
-            $global.requestAnimationFrame(process);
-        }
-        tasks.push(callable);
-    }
-    return Object.freeze({
-        enqueue,
-        process,
-    });
-});
-/* eslint-disable */
-const fastHTMLPolicy = $global.trustedTypes.createPolicy("fast-html", {
-    createHTML: html => html,
-});
-/* eslint-enable */
-let htmlPolicy = fastHTMLPolicy;
-const marker = `fast-${Math.random().toString(36).substring(2, 8)}`;
-/** @internal */
-export const _interpolationStart = `${marker}{`;
-/** @internal */
-export const _interpolationEnd = `}${marker}`;
-/**
- * Common DOM APIs.
- * @public
- */
-export const DOM = Object.freeze({
-    /**
-     * Indicates whether the DOM supports the adoptedStyleSheets feature.
-     */
-    supportsAdoptedStyleSheets: Array.isArray(document.adoptedStyleSheets) &&
-        "replace" in CSSStyleSheet.prototype,
-    /**
-     * Sets the HTML trusted types policy used by the templating engine.
-     * @param policy - The policy to set for HTML.
-     * @remarks
-     * This API can only be called once, for security reasons. It should be
-     * called by the application developer at the start of their program.
-     */
-    setHTMLPolicy(policy) {
-        if (htmlPolicy !== fastHTMLPolicy) {
-            throw new Error("The HTML policy can only be set once.");
-        }
-        htmlPolicy = policy;
-    },
-    /**
-     * Turns a string into trusted HTML using the configured trusted types policy.
-     * @param html - The string to turn into trusted HTML.
-     * @remarks
-     * Used internally by the template engine when creating templates
-     * and setting innerHTML.
-     */
-    createHTML(html) {
-        return htmlPolicy.createHTML(html);
-    },
-    /**
-     * Determines if the provided node is a template marker used by the runtime.
-     * @param node - The node to test.
-     */
-    isMarker(node) {
-        return node && node.nodeType === 8 && node.data.startsWith(marker);
-    },
-    /**
-     * Given a marker node, extract the {@link HTMLDirective} index from the placeholder.
-     * @param node - The marker node to extract the index from.
-     */
-    extractDirectiveIndexFromMarker(node) {
-        return parseInt(node.data.replace(`${marker}:`, ""));
-    },
-    /**
-     * Creates a placeholder string suitable for marking out a location *within*
-     * an attribute value or HTML content.
-     * @param index - The directive index to create the placeholder for.
-     * @remarks
-     * Used internally by binding directives.
-     */
-    createInterpolationPlaceholder(index) {
-        return `${_interpolationStart}${index}${_interpolationEnd}`;
-    },
-    /**
-     * Creates a placeholder that manifests itself as an attribute on an
-     * element.
-     * @param attributeName - The name of the custom attribute.
-     * @param index - The directive index to create the placeholder for.
-     * @remarks
-     * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
-     */
-    createCustomAttributePlaceholder(attributeName, index) {
-        return `${attributeName}="${this.createInterpolationPlaceholder(index)}"`;
-    },
-    /**
-     * Creates a placeholder that manifests itself as a marker within the DOM structure.
-     * @param index - The directive index to create the placeholder for.
-     * @remarks
-     * Used internally by structural directives such as `repeat`.
-     */
-    createBlockPlaceholder(index) {
-        return `<!--${marker}:${index}-->`;
-    },
-    /**
-     * Schedules DOM update work in the next async batch.
-     * @param callable - The callable function or object to queue.
-     */
-    queueUpdate: updateQueue.enqueue,
-    /**
-     * Immediately processes all work previously scheduled
-     * through queueUpdate.
-     * @remarks
-     * This also forces nextUpdate promises
-     * to resolve.
-     */
-    processUpdates: updateQueue.process,
-    /**
-     * Resolves with the next DOM update.
-     */
-    nextUpdate() {
-        return new Promise(updateQueue.enqueue);
-    },
-    /**
-     * Sets an attribute value on an element.
-     * @param element - The element to set the attribute value on.
-     * @param attributeName - The attribute name to set.
-     * @param value - The value of the attribute to set.
-     * @remarks
-     * If the value is `null` or `undefined`, the attribute is removed, otherwise
-     * it is set to the provided value using the standard `setAttribute` API.
-     */
-    setAttribute(element, attributeName, value) {
-        if (value === null || value === undefined) {
-            element.removeAttribute(attributeName);
-        }
-        else {
-            element.setAttribute(attributeName, value);
-        }
-    },
-    /**
-     * Sets a boolean attribute value.
-     * @param element - The element to set the boolean attribute value on.
-     * @param attributeName - The attribute name to set.
-     * @param value - The value of the attribute to set.
-     * @remarks
-     * If the value is true, the attribute is added; otherwise it is removed.
-     */
-    setBooleanAttribute(element, attributeName, value) {
-        value
-            ? element.setAttribute(attributeName, "")
-            : element.removeAttribute(attributeName);
-    },
-    /**
-     * Removes all the child nodes of the provided parent node.
-     * @param parent - The node to remove the children from.
-     */
-    removeChildNodes(parent) {
-        for (let child = parent.firstChild; child !== null; child = parent.firstChild) {
-            parent.removeChild(child);
-        }
-    },
-    /**
-     * Creates a TreeWalker configured to walk a template fragment.
-     * @param fragment - The fragment to walk.
-     */
-    createTemplateWalker(fragment) {
-        return document.createTreeWalker(fragment, 133, // element, text, comment
-        null, false);
-    },
-});