@microsoft/fast-element 1.10.0 → 2.0.0-beta.1

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/docs/guide/declaring-templates.md

@@ -3,6 +3,7 @@ id: declaring-templates
 title: Declaring Templates
 sidebar_label: Declaring Templates
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/declaring-templates.md
+description: While you can create and update nodes in the Shadow DOM manually, FASTElement provides a streamlined templating system for the most common rendering scenarios.
 ---
 
 ## Basic templates
@@ -143,7 +144,7 @@ When binding to `class`, the underlying engine will not over-write classes added
 
 **Example: Nullish value**
 
-Some cases may occur where an attribute needs to have a value when used however not present if unused. These are different than boolean attributes by where their presence alone triggers their effect. In this situation a nullish value (`null` or `undefined`) may be provided so the attribute won't exist in that condition.
+Some cases may occur where an attribute needs to have a value when used however not present if unused. These are different than boolean attributes by where their presence alone triggers their effect. In this situation, a nullish value (`null` or `undefined`) may be provided so the attribute won't exist in that condition.
 
 ```html
 <div aria-hidden="${x => x.isViewable ? 'true' : null}"></div>
@@ -217,13 +218,13 @@ The second example demonstrates an important characteristic of the templating en
 It is during the `connectedCallback` phase of the Custom Element lifecycle that `FASTElement` creates templates and binds the resulting view. The creation of the template only occurs the first time the element is connected, while binding happens every time the element is connected (with unbinding happening during the `disconnectedCallback` for symmetry).
 
 :::note
-In the future we're planning new optimizations that will enable us to safely determine when we do not need to unbind/rebind certain views.
+In the future, we're planning new optimizations that will enable us to safely determine when we do not need to unbind/rebind certain views.
 :::
 
 In most cases, the template that `FASTElement` renders is determined by the `template` property of the Custom Element's configuration. However, you can also implement a method on your Custom Element class named `resolveTemplate()` that returns a template instance. If this method is present, it will be called during `connectedCallback` to obtain the template to use. This allows the element author to dynamically select completely different templates based on the state of the element at the time of connection.
 
-In addition to dynamic template selection during the `connectedCallback`, the `$fastController` property of `FASTElement` enables dynamically changing the template at any time through setting the controller's `template` property to any valid template.
+In addition to dynamic template selection during the `connectedCallback`, the `$fastController` property of `FASTElement` enables dynamically changing the template at any time by setting the controller's `template` property to any valid template.
 
 :::tip
-Check out [our Cheat Sheet](/docs/resources/cheat-sheet#bindings) for a quick guide on bindings.
+Check out [our Cheat Sheet](../resources/cheat-sheet.md#bindings) for a quick guide on bindings.
 :::

package/docs/guide/defining-elements.md

@@ -3,6 +3,7 @@ id: defining-elements
 title: Defining Elements
 sidebar_label: Defining Elements
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/defining-elements.md
+description: To define a custom element, begin by creating a class that extends FASTElement and decorate it with the @customElement decorator, providing the element name.
 ---
 
 ## Basic elements
@@ -57,7 +58,7 @@ export class NameTag extends FASTElement {
 To add attributes to your HTML element, create properties decorated by the `@attr` decorator. All attributes defined this way will be automatically registered with the platform so that they can be updated through the browser's native `setAttribute` API as well as the property. You can optionally add a method with the naming convention *propertyName*Changed to your class (e.g. `greeting` and `greetingChanged()`), and this method will be called whenever your property changes, whether it changes through the property or the attribute API.
 
 :::note
-All properties decorated with `@attr` are also *observable*. See [observables and state](./observables-and-state) for information about how observables enable efficient rendering.
+All properties decorated with `@attr` are also *observable*. See [observables and state](./observables-and-state.md) for information about how observables enable efficient rendering.
 :::
 
 By default, anything extending from `FASTElement` will automatically have a `ShadowRoot` attached in order to enable encapsulated rendering. 
@@ -141,7 +142,7 @@ export class MyCounter extends FASTElement {
 
 ## The element lifecycle
 
-All Web Components support a series of lifecycle events that you can tap into to execute custom code at specific points in time. `FASTElement` implements several of these callbacks automatically in order to enable features of its templating engine (described in [declaring templates](./declaring-templates)). However, you can override them to provide your own code. Here's an example of how you would execute custom code when your element is inserted into the DOM.
+All Web Components support a series of lifecycle events that you can tap into to execute custom code at specific points in time. `FASTElement` implements several of these callbacks automatically in order to enable features of its templating engine (described in [declaring templates](./declaring-templates.md)). However, you can override them to provide your own code. Here's an example of how you would execute custom code when your element is inserted into the DOM.
 
 **Example: Tapping into the Custom Element Lifecycle**
 

package/docs/guide/leveraging-css.md

@@ -3,6 +3,7 @@ id: leveraging-css
 title: Leveraging CSS
 sidebar_label: Leveraging CSS
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/leveraging-css.md
+description: Similar to HTML, FASTElement provides a css tagged template helper to allow creating and re-using CSS.
 ---
 
 ## Basic styles

package/docs/guide/next-steps.md

@@ -3,10 +3,11 @@ id: next-steps
 title: Next Steps
 sidebar_label: Next Steps
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/next-steps.md
+description: Now that you're familiar with the robust and powerful features of FASTElement, you're ready to build your own components and apps.
 ---
 
 We've seen how to use `FASTElement` to declaratively build Web Components. In addition to the basics of element and attribute definition, `FASTElement` also provides a way to declare templates capable of high-performance rendering, and efficient, incremental batched updates. Finally, CSS can easily be associated with an element in a way that leverages core platform optimizations for performance and low memory allocation.
 
-Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](/docs/design-systems/fast-frame#configuring-components). Finally, you'll want to take advantage of a modern toolset by installing [a powerful editor and plugins](../tools/vscode).
+Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started.md), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design-systems/fast-frame.md#configuring-components). Finally, you'll want to take advantage of a modern toolset by installing [a powerful editor and plugins](../tools/vscode.md).
 
-For a quick reference, check out [our Cheat Sheet](/docs/resources/cheat-sheet).
+For a quick reference, check out [our Cheat Sheet](../resources/cheat-sheet.md).

package/docs/guide/observables-and-state.md

@@ -3,6 +3,7 @@ id: observables-and-state
 title: Observables and State
 sidebar_label: Observables and State
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/observables-and-state.md
+description: To enable binding tracking and change notification, properties must be decorated with either @attr or @observable.
 ---
 
 ## Reactivity
@@ -122,7 +123,7 @@ export class Person {
 
 ### External observation
 
-Decorated properties can be subscribed to, to receive notification of changes in the property value. The templating engine uses this, but you can also directly subscribe as well. Here's how you would subscribe to changes in the `name` property of a `Person` class:
+Decorated properties can be subscribed to, to receive notification of changes in the property value. The templating engine uses this, but you can also directly subscribe. Here's how you would subscribe to changes in the `name` property of a `Person` class:
 
 **Example: Subscribing to an Observable**
 

package/docs/guide/using-directives.md

@@ -3,6 +3,7 @@ id: using-directives
 title: Using Directives
 sidebar_label: Using Directives
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/using-directives.md
+description: In addition to declaring dynamic parts of templates with expressions, you also have access to several powerful directives, which aid in common scenarios.
 ---
 
 In addition to declaring dynamic parts of templates with expressions, you also have access to several powerful *directives*, which aid in common scenarios.
@@ -508,7 +509,7 @@ If using the `subtree` option for `children` then a `selector` is *required* in
 
 ### The `slotted` directive
 
-Sometimes you may want references to all nodes that are assigned to a particular slot. To accomplish this, use the `slotted` directive. (For more on slots, see [Working with Shadow DOM](./working-with-shadow-dom).)
+Sometimes you may want references to all nodes that are assigned to a particular slot. To accomplish this, use the `slotted` directive. (For more on slots, see [Working with Shadow DOM](./working-with-shadow-dom.md).)
 
 ```ts
 import { FASTElement, customElement, html, slotted } from '@microsoft/fast-element';

package/docs/guide/working-with-shadow-dom.md

@@ -3,6 +3,7 @@ id: working-with-shadow-dom
 title: Working with Shadow DOM
 sidebar_label: Working with Shadow DOM
 custom_edit_url: https://github.com/microsoft/fast/edit/master/packages/web-components/fast-element/docs/guide/working-with-shadow-dom.md
+description: See how our custom elements can be composed together with standard HTML or other custom elements.
 ---
 
 So far we've looked at how to define elements, how to define attributes on those elements, and how to control element rendering through declarative templates. However, we haven't yet seen how our custom elements can be composed together with standard HTML or other custom elements.

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,57 @@
 {
   "name": "@microsoft/fast-element",
   "description": "A library for constructing Web Components",
-  "sideEffects": false,
-  "version": "1.10.0",
+  "version": "2.0.0-beta.1",
   "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"
   },
+  "type": "module",
   "main": "dist/esm/index.js",
   "types": "dist/fast-element.d.ts",
-  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/fast-element.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"
+    },
+    "./splice-strategies": {
+      "types": "./dist/dts/observation/splice-strategies.d.ts",
+      "default": "./dist/esm/observation/splice-strategies.js"
+    },
+    "./utilities": {
+      "types": "./dist/dts/utilities.d.ts",
+      "default": "./dist/esm/utilities.js"
+    },
+    "./hooks": {
+      "types": "./dist/dts/hooks.d.ts",
+      "default": "./dist/esm/hooks.js"
+    }
+  },
   "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 +79,14 @@
     "test-firefox:verbose": "karma start karma.conf.cjs --browsers=FirefoxHeadless --single-run --coverage --reporter=mocha"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "7.8.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",
     "ignore-loader": "^0.1.2",
     "istanbul": "^0.4.5",
@@ -68,21 +102,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;