@microsoft/fast-element 2.0.0-beta.9 → 2.0.1

package/scripts/run-benchmarks.js

@@ -0,0 +1,46 @@
+import fs from 'fs/promises';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.join(__dirname, '..');
+const tensileConfig = 'tensile.config.js';
+
+try {
+  const esmOutput = path.join(rootDir, 'dist', 'esm');
+  const items = await fs.readdir(esmOutput);
+
+  // Collect all component folders
+  const folders = [];
+  for (const item of items) {
+    const itemPath = path.join(esmOutput, item);
+    const stats = await fs.lstat(itemPath);
+    if (stats.isDirectory()) {
+      folders.push(item);
+    }
+  }
+
+  // Collect all .bench.js files
+  const benchFiles = [];
+  for (const folder of folders) {
+    const folderPath = path.join(esmOutput, folder);
+    const files = await fs.readdir(folderPath);
+    const filteredFiles = files.filter(file => file.endsWith('.bench.js'));
+    benchFiles.push(...filteredFiles.map(file => path.relative(rootDir, path.join(folderPath, file))));
+  }
+
+  // Execute tensile for each .bench.js file
+  for (const file of benchFiles) {
+    try {
+      // eslint-disable-next-line no-undef
+      execSync(`tensile --file ./${file} --config ${tensileConfig} ${process.argv[2]}`, { stdio: 'inherit' });
+    } catch (error) {
+      console.error(`Error executing command for file ${file}: ${error.message}`);
+    }
+  }
+
+} catch (error) {
+  console.error(`Error reading directory: ${error.message}`);
+}

package/tensile.config.js

@@ -0,0 +1,12 @@
+const config = {
+    // Browsers to test against
+    browsers: ['chrome'],
+
+    // Importmaps for your test.
+    // See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap
+    imports: {
+        '@tensile-perf/web-components': '/node_modules/@tensile-perf/web-components/lib/index.js',
+    }
+  };
+
+  export default config;

package/dist/dts/templating/dom.d.ts

@@ -1,41 +0,0 @@
-import type { Callable } from "../interfaces.js";
-/**
- * Common DOM APIs.
- * @public
- */
-export declare const DOM: Readonly<{
-    /**
-     * @deprecated
-     * Use Updates.enqueue().
-     */
-    queueUpdate: (callable: Callable) => void;
-    /**
-     * @deprecated
-     * Use Updates.next()
-     */
-    nextUpdate: () => Promise<void>;
-    /**
-     * @deprecated
-     * Use Updates.process()
-     */
-    processUpdates: () => 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;
-}>;

package/dist/esm/templating/binding.js

@@ -1,282 +0,0 @@
-import { isFunction } from "../interfaces.js";
-import { ExecutionContext, Observable, } from "../observation/observable.js";
-import { FAST } from "../platform.js";
-import { DOM } from "./dom.js";
-import { Aspect, Binding, HTMLDirective, } from "./html-directive.js";
-import { Markup, nextId } from "./markup.js";
-const createInnerHTMLBinding = globalThis.TrustedHTML
-    ? (binding) => (s, c) => {
-        const value = binding(s, c);
-        if (value instanceof TrustedHTML) {
-            return value;
-        }
-        throw FAST.error(1202 /* Message.bindingInnerHTMLRequiresTrustedTypes */);
-    }
-    : (binding) => binding;
-class OnChangeBinding extends Binding {
-    createObserver(_, subscriber) {
-        return Observable.binding(this.evaluate, subscriber, this.isVolatile);
-    }
-}
-class OneTimeBinding extends Binding {
-    createObserver() {
-        return this;
-    }
-    bind(controller) {
-        return this.evaluate(controller.source, controller.context);
-    }
-}
-function updateContent(target, aspect, value, controller) {
-    // If there's no actual value, then this equates to the
-    // empty string for the purposes of content bindings.
-    if (value === null || value === undefined) {
-        value = "";
-    }
-    // If the value has a "create" method, then it's a ContentTemplate.
-    if (value.create) {
-        target.textContent = "";
-        let view = target.$fastView;
-        // If there's no previous view that we might be able to
-        // reuse then create a new view from the template.
-        if (view === void 0) {
-            view = value.create();
-        }
-        else {
-            // If there is a previous view, but it wasn't created
-            // from the same template as the new value, then we
-            // need to remove the old view if it's still in the DOM
-            // and create a new view from the template.
-            if (target.$fastTemplate !== value) {
-                if (view.isComposed) {
-                    view.remove();
-                    view.unbind();
-                }
-                view = value.create();
-            }
-        }
-        // It's possible that the value is the same as the previous template
-        // and that there's actually no need to compose it.
-        if (!view.isComposed) {
-            view.isComposed = true;
-            view.bind(controller.source, controller.context);
-            view.insertBefore(target);
-            target.$fastView = view;
-            target.$fastTemplate = value;
-        }
-        else if (view.needsBindOnly) {
-            view.needsBindOnly = false;
-            view.bind(controller.source, controller.context);
-        }
-    }
-    else {
-        const view = target.$fastView;
-        // If there is a view and it's currently composed into
-        // the DOM, then we need to remove it.
-        if (view !== void 0 && view.isComposed) {
-            view.isComposed = false;
-            view.remove();
-            if (view.needsBindOnly) {
-                view.needsBindOnly = false;
-            }
-            else {
-                view.unbind();
-            }
-        }
-        target.textContent = value;
-    }
-}
-function updateTokenList(target, aspect, value) {
-    var _a;
-    const lookup = `${this.id}-t`;
-    const state = (_a = target[lookup]) !== null && _a !== void 0 ? _a : (target[lookup] = { c: 0, v: Object.create(null) });
-    const versions = state.v;
-    let currentVersion = state.c;
-    const tokenList = target[aspect];
-    // Add the classes, tracking the version at which they were added.
-    if (value !== null && value !== undefined && value.length) {
-        const names = value.split(/\s+/);
-        for (let i = 0, ii = names.length; i < ii; ++i) {
-            const currentName = names[i];
-            if (currentName === "") {
-                continue;
-            }
-            versions[currentName] = currentVersion;
-            tokenList.add(currentName);
-        }
-    }
-    state.v = currentVersion + 1;
-    // If this is the first call to add classes, there's no need to remove old ones.
-    if (currentVersion === 0) {
-        return;
-    }
-    // Remove classes from the previous version.
-    currentVersion -= 1;
-    for (const name in versions) {
-        if (versions[name] === currentVersion) {
-            tokenList.remove(name);
-        }
-    }
-}
-const setProperty = (t, a, v) => (t[a] = v);
-const eventTarget = () => void 0;
-/**
- * A directive that applies bindings.
- * @public
- */
-export class HTMLBindingDirective {
-    /**
-     * Creates an instance of HTMLBindingDirective.
-     * @param dataBinding - The binding configuration to apply.
-     */
-    constructor(dataBinding) {
-        this.dataBinding = dataBinding;
-        this.updateTarget = null;
-        /**
-         * The unique id of the factory.
-         */
-        this.id = nextId();
-        /**
-         * The type of aspect to target.
-         */
-        this.aspectType = Aspect.content;
-        /** @internal */
-        this.bind = this.bindDefault;
-        this.data = `${this.id}-d`;
-    }
-    /**
-     * Creates HTML to be used within a template.
-     * @param add - Can be used to add  behavior factories to a template.
-     */
-    createHTML(add) {
-        return Markup.interpolation(add(this));
-    }
-    /**
-     * Creates a behavior.
-     */
-    createBehavior() {
-        if (this.updateTarget === null) {
-            if (this.targetAspect === "innerHTML") {
-                this.dataBinding.evaluate = createInnerHTMLBinding(this.dataBinding.evaluate);
-            }
-            switch (this.aspectType) {
-                case 1:
-                    this.updateTarget = DOM.setAttribute;
-                    break;
-                case 2:
-                    this.updateTarget = DOM.setBooleanAttribute;
-                    break;
-                case 3:
-                    this.updateTarget = setProperty;
-                    break;
-                case 4:
-                    this.bind = this.bindContent;
-                    this.updateTarget = updateContent;
-                    break;
-                case 5:
-                    this.updateTarget = updateTokenList;
-                    break;
-                case 6:
-                    this.bind = this.bindEvent;
-                    this.updateTarget = eventTarget;
-                    break;
-                default:
-                    throw FAST.error(1205 /* Message.unsupportedBindingBehavior */);
-            }
-        }
-        return this;
-    }
-    /** @internal */
-    bindDefault(controller) {
-        var _a;
-        const target = controller.targets[this.nodeId];
-        const observer = (_a = target[this.data]) !== null && _a !== void 0 ? _a : (target[this.data] = this.dataBinding.createObserver(this, this));
-        observer.target = target;
-        observer.controller = controller;
-        this.updateTarget(target, this.targetAspect, observer.bind(controller), controller);
-        if (this.updateTarget === updateContent) {
-            controller.onUnbind(this);
-        }
-    }
-    /** @internal */
-    bindContent(controller) {
-        this.bindDefault(controller);
-        controller.onUnbind(this);
-    }
-    /** @internal */
-    bindEvent(controller) {
-        const target = controller.targets[this.nodeId];
-        target[this.data] = controller;
-        target.addEventListener(this.targetAspect, this, this.dataBinding.options);
-    }
-    /** @internal */
-    unbind(controller) {
-        const target = controller.targets[this.nodeId];
-        const view = target.$fastView;
-        if (view !== void 0 && view.isComposed) {
-            view.unbind();
-            view.needsBindOnly = true;
-        }
-    }
-    /** @internal */
-    handleEvent(event) {
-        const target = event.currentTarget;
-        ExecutionContext.setEvent(event);
-        const controller = target[this.data];
-        const result = this.dataBinding.evaluate(controller.source, controller.context);
-        ExecutionContext.setEvent(null);
-        if (result !== true) {
-            event.preventDefault();
-        }
-    }
-    /** @internal */
-    handleChange(binding, observer) {
-        const target = observer.target;
-        const controller = observer.controller;
-        this.updateTarget(target, this.targetAspect, observer.bind(controller), controller);
-    }
-}
-HTMLDirective.define(HTMLBindingDirective, { aspected: true });
-/**
- * Creates an standard binding.
- * @param binding - The binding to refresh when changed.
- * @param isVolatile - Indicates whether the binding is volatile or not.
- * @returns A binding configuration.
- * @public
- */
-export function bind(binding, isVolatile = Observable.isVolatileBinding(binding)) {
-    return new OnChangeBinding(binding, isVolatile);
-}
-/**
- * Creates a one time binding
- * @param binding - The binding to refresh when signaled.
- * @returns A binding configuration.
- * @public
- */
-export function oneTime(binding) {
-    return new OneTimeBinding(binding);
-}
-/**
- * Creates an event listener binding.
- * @param binding - The binding to invoke when the event is raised.
- * @param options - Event listener options.
- * @returns A binding configuration.
- * @public
- */
-export function listener(binding, options) {
-    const config = new OnChangeBinding(binding, false);
-    config.options = options;
-    return config;
-}
-/**
- * Normalizes the input value into a binding.
- * @param value - The value to create the default binding for.
- * @returns A binding configuration for the provided value.
- * @public
- */
-export function normalizeBinding(value) {
-    return isFunction(value)
-        ? bind(value)
-        : value instanceof Binding
-            ? value
-            : oneTime(() => value);
-}

package/dist/esm/templating/dom.js

@@ -1,49 +0,0 @@
-import { Updates } from "../observation/update-queue.js";
-/**
- * Common DOM APIs.
- * @public
- */
-export const DOM = Object.freeze({
-    /**
-     * @deprecated
-     * Use Updates.enqueue().
-     */
-    queueUpdate: Updates.enqueue,
-    /**
-     * @deprecated
-     * Use Updates.next()
-     */
-    nextUpdate: Updates.next,
-    /**
-     * @deprecated
-     * Use Updates.process()
-     */
-    processUpdates: Updates.process,
-    /**
-     * 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) {
-        value === null || value === undefined
-            ? element.removeAttribute(attributeName)
-            : 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);
-    },
-});

package/docs/guide/declaring-templates.md

@@ -1,230 +0,0 @@
----
-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
-
-While you can create and update nodes in the Shadow DOM manually, `FASTElement` provides a streamlined templating system for the most common rendering scenarios. To create an HTML template for an element, import and use the `html` tagged template helper and pass the template to the `@customElement` decorator.
-
-Here's how we would add a template for our `name-tag` component that renders some basic structure as well as our `greeting`:
-
-**Example: Adding a Template to a `FASTElement`**
-
-```ts
-import { FASTElement, customElement, attr, html } from '@microsoft/fast-element';
-
-const template = html<NameTag>`
-  <div class="header">
-    <h3>${x => x.greeting.toUpperCase()}</h3>
-    <h4>my name is</h4>
-  </div>
-
-  <div class="body">TODO: Name Here</div>
-
-  <div class="footer"></div>
-`;
-
-@customElement({
-  name: 'name-tag',
-  template
-})
-export class NameTag extends FASTElement {
-  @attr greeting: string = 'Hello';
-}
-```
-
-There are several important details in the above example, so let's break them down one-by-one.
-
-First, we create a template by using a [tagged template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals). The tag, `html`, provides special processing for the HTML string that follows, returning an instance of `ViewTemplate`.
-
-Within a template, we provide *bindings* that declare the *dynamic parts* of our template. These bindings are declared with [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions). Because the template is typed, the input to your arrow function will be an instance of the data model you declared in your `html` tag. When the `html` tag processes your template, it identifies these dynamic expressions and builds up an optimized model, capable of high-performance rendering, and efficient, incremental batched updates.
-
-Finally, we associate the template with our custom element by using a new form of the `@customElement` decorator, which allows us to pass more options. In this configuration, we pass an options object specifying the `name` and the `template`.
-
-With this in place, we now have a `name-tag` element that will render its template into the Shadow DOM and automatically update the `h3` content whenever the name tag's `greeting` attribute changes. Give it a try!
-
-### Typed Templates
-
-Your templates can be *typed* to the data model that they are rendering over. In TypeScript, we provide the type as part of the tag: `html<NameTag>`. For TypeScript 3.8 or higher, you can import `ViewTemplate` as a type:
-
-```ts
-import type { ViewTemplate } from '@microsoft/fast-element';
-
-const template: ViewTemplate<NameTag> = html`
-  <div>${x => x.greeting}</div>
-`;
-```
-
-## Understanding bindings
-
-We've seen how arrow functions can be used to declare dynamic parts of templates. Let's look at a few more examples to see the breadth of what is available to you.
-
-### Content
-
-To bind the content of an element, simply provide the expression within the start and end tags of the element. It can be the sole content of the element or interwoven with other elements and text.
-
-**Example: Basic Text Content**
-
-```html
-<h3>${x => x.greeting.toUpperCase()}</h3>
-```
-
-**Example: Interpolated Text Content**
-
-```html
-<h3>${x => x.greeting}, my name is ${x => x.name}.</h3>
-```
-
-**Example: Heterogeneous Content**
-
-```html
-<h3>
-  ${x => x.greeting}, my name is
-  <span class="name">${x => x.name}</span>.
-</h3>
-```
-
-:::note
-Dynamic content is set via the `textContent` HTML property for security reasons. You *cannot* set HTML content this way. See below for the explicit, opt-in mechanism for setting HTML.
-:::
-
-### Attributes
-
-You can also use an expression to set an attribute value on an HTML Element. Simply place the expression where the value of the HTML attribute would go. The template engine will then use your expression to set the value using `setAttribute(...)`, whenever it needs to be updated. Additionally, some attributes are known as [boolean attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#Boolean_Attributes) (e.g. required, readonly, disabled). These attributes behave differently from normal attributes and need special value handling. The templating engine will handle this for you if you prepend the attribute name with a `?`.
-
-**Example: Basic Attribute Values**
-
-```html
-<a href="${x => x.aboutLink}">About</a>
-```
-
-**Example: Interpolated Attribute Values**
-
-```html
-<a href="products/${x => x.id}">
-  ${x => x.name}
-</a>
-```
-
-```html
-<li class="list-item ${x => x.type}">
-  ...
-</li>
-```
-
-:::tip
-When binding to `class`, the underlying engine will not over-write classes added to the element via other mechanisms. It only adds and removes classes that result directly from the binding. This "safe by default" behavior does come at a slight performance cost. To opt-out of this feature and squeeze out every ounce of performance by always overwriting all classes, use a property binding (see below) on the `className` property. e.g. `:className="list-item ${x => x.type}"`.
-:::
-
-```html
-<span style="text-decoration: ${x => x.done ? 'line-through' : ''}">
-  ${x => x.description}
-</span>
-```
-
-**Example: ARIA Attributes**
-
-```html
-<div role="progressbar"
-     aria-valuenow="${x => x.value}"
-     aria-valuemin="${x => x.min}"
-     aria-valuemax="${x => x.max}">
-</div>
-```
-
-**Example: Boolean Attributes**
-
-```html
-<button type="submit" ?disabled="${x => !x.enabled}">Submit</button>
-```
-
-**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.
-
-```html
-<div aria-hidden="${x => x.isViewable ? 'true' : null}"></div>
-```
-
-### Properties
-
-Properties can also be set directly on an HTML element. To do so, prepend the property name with `:` to indicate a property binding. The template engine will then use your expression to assign the element's property value.
-
-**Example: Basic Property Values**
-
-```html
-<my-element :myCustomProperty="${x => x.mySpecialData}">
-  ...
-</my-element>
-```
-
-**Example: Inner HTML**
-
-```html
-<div :innerHTML="${x => x.someDangerousHTMLContent}"></div>
-```
-
-:::warning
-Avoid scenarios that require you to directly set HTML, especially when the content is coming from an external source. If you must do this, you should always sanitize the HTML.
-
-The best way to accomplish HTML sanitization is to configure [a trusted types policy](https://w3c.github.io/webappsec-trusted-types/dist/spec/) with FASTElement's template engine. FASTElement ensures that all HTML strings pass through the configured policy. Also, by leveraging the platform's trusted types capabilities, you get native enforcement of the policy through CSP headers. Here's an example of how to configure a custom policy to sanitize HTML:
-
-```ts
-import { DOM } from '@microsoft/fast-element';
-
-const myPolicy = trustedTypes.createPolicy('my-policy', {
-  createHTML(html) {
-    // TODO: invoke a sanitization library on the html before returning it
-    return html;
-  }
-});
-
-DOM.setHTMLPolicy(myPolicy);
-```
-
-For security reasons, the HTML Policy can only be set once. For this reason, it should be set by application developers and not by component authors, and it should be done immediately during the startup sequence of the application.
-:::
-
-### Events
-
-Besides rendering content, attributes, and properties, you'll often want to add event listeners and execute code when events fire. To do that, prepend the event name with `@` and provide the expression to be called when that event fires. Within an event binding, you also have access to a special *context* argument from which you can access the `event` object.
-
-**Example: Basic Events**
-
-```html
-<button @click="${x => x.remove()}">Remove</button>
-```
-
-**Example: Accessing Event Details**
-
-```html
-<input type="text"
-       :value="${x => x.description}"
-       @input="${(x, c) => x.handleDescriptionChange(c.event)}">
-```
-
-:::important
-In both examples above, after your event handler is executed, `preventDefault()` will be called on the event object by default. You can return `true` from your handler to opt-out of this behavior.
-:::
-
-The second example demonstrates an important characteristic of the templating engine: it only supports *unidirectional data flow* (model => view). It does not support *two-way data binding* (model <=> view). As shown above, pushing data from the view back to the model should be handled with explicit events that call into your model's API.
-
-## Templating and the element lifecycle
-
-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 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 by setting the controller's `template` property to any valid template.
-
-:::tip
-Check out [our Cheat Sheet](../resources/cheat-sheet.md#bindings) for a quick guide on bindings.
-:::