@microsoft/fast-element 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/esm/templating/view.js

@@ -1,3 +1,5 @@
+import { noop } from "../interfaces.js";
+import { ExecutionContext, Observable, SourceLifetime, } from "../observation/observable.js";
 function removeNodeSequence(firstNode, lastNode) {
     const parent = firstNode.parentNode;
     let current = firstNode;
@@ -24,17 +26,92 @@ export class HTMLView {
         this.factories = factories;
         this.targets = targets;
         this.behaviors = null;
+        this.unbindables = [];
         /**
          * The data that the view is bound to.
          */
         this.source = null;
+        /**
+         * Indicates whether the controller is bound.
+         */
+        this.isBound = false;
+        /**
+         * Indicates how the source's lifetime relates to the controller's lifetime.
+         */
+        this.sourceLifetime = SourceLifetime.unknown;
         /**
          * The execution context the view is running within.
          */
-        this.context = null;
+        this.context = this;
+        /**
+         * The index of the current item within a repeat context.
+         */
+        this.index = 0;
+        /**
+         * The length of the current collection within a repeat context.
+         */
+        this.length = 0;
+        /**
+         * Opts out of JSON stringification.
+         * @internal
+         */
+        this.toJSON = noop;
         this.firstChild = fragment.firstChild;
         this.lastChild = fragment.lastChild;
     }
+    /**
+     * The current event within an event handler.
+     */
+    get event() {
+        return ExecutionContext.getEvent();
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an even index.
+     */
+    get isEven() {
+        return this.index % 2 === 0;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an odd index.
+     */
+    get isOdd() {
+        return this.index % 2 !== 0;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the first item in the collection.
+     */
+    get isFirst() {
+        return this.index === 0;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * is somewhere in the middle of the collection.
+     */
+    get isInMiddle() {
+        return !this.isFirst && !this.isLast;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the last item in the collection.
+     */
+    get isLast() {
+        return this.index === this.length - 1;
+    }
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail() {
+        return this.event.detail;
+    }
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget() {
+        return this.event.target;
+    }
     /**
      * Appends the view's DOM nodes to the referenced node.
      * @param node - The parent node to append the view's DOM nodes to.
@@ -51,8 +128,10 @@ export class HTMLView {
             node.parentNode.insertBefore(this.fragment, node);
         }
         else {
-            const parentNode = node.parentNode;
             const end = this.lastChild;
+            if (node.previousSibling === end)
+                return;
+            const parentNode = node.parentNode;
             let current = this.firstChild;
             let next;
             while (current !== end) {
@@ -87,58 +166,61 @@ export class HTMLView {
         removeNodeSequence(this.firstChild, this.lastChild);
         this.unbind();
     }
+    onUnbind(behavior) {
+        this.unbindables.push(behavior);
+    }
     /**
      * Binds a view's behaviors to its binding source.
      * @param source - The binding source for the view's binding behaviors.
      * @param context - The execution context to run the behaviors within.
      */
-    bind(source, context) {
-        let behaviors = this.behaviors;
-        const oldSource = this.source;
-        if (oldSource === source) {
+    bind(source, context = this) {
+        if (this.source === source) {
             return;
         }
-        this.source = source;
-        this.context = context;
-        const targets = this.targets;
-        if (oldSource !== null) {
-            for (let i = 0, ii = behaviors.length; i < ii; ++i) {
-                const current = behaviors[i];
-                current.unbind(oldSource, context, targets);
-                current.bind(source, context, targets);
-            }
-        }
-        else if (behaviors === null) {
+        let behaviors = this.behaviors;
+        if (behaviors === null) {
+            this.source = source;
+            this.context = context;
             this.behaviors = behaviors = new Array(this.factories.length);
             const factories = this.factories;
             for (let i = 0, ii = factories.length; i < ii; ++i) {
-                const behavior = factories[i].createBehavior(targets);
-                behavior.bind(source, context, targets);
+                const behavior = factories[i].createBehavior();
+                behavior.bind(this);
                 behaviors[i] = behavior;
             }
         }
         else {
+            if (this.source !== null) {
+                this.evaluateUnbindables();
+            }
+            this.isBound = false;
+            this.source = source;
+            this.context = context;
             for (let i = 0, ii = behaviors.length; i < ii; ++i) {
-                behaviors[i].bind(source, context, targets);
+                behaviors[i].bind(this);
             }
         }
+        this.isBound = true;
     }
     /**
      * Unbinds a view's behaviors from its binding source.
      */
     unbind() {
-        const oldSource = this.source;
-        if (oldSource === null) {
+        if (!this.isBound || this.source === null) {
             return;
         }
-        const targets = this.targets;
-        const context = this.context;
-        const behaviors = this.behaviors;
-        for (let i = 0, ii = behaviors.length; i < ii; ++i) {
-            behaviors[i].unbind(oldSource, context, targets);
-        }
+        this.evaluateUnbindables();
         this.source = null;
-        this.context = null;
+        this.context = this;
+        this.isBound = false;
+    }
+    evaluateUnbindables() {
+        const unbindables = this.unbindables;
+        for (let i = 0, ii = unbindables.length; i < ii; ++i) {
+            unbindables[i].unbind(this);
+        }
+        unbindables.length = 0;
     }
     /**
      * Efficiently disposes of a contiguous range of synthetic view instances.
@@ -154,3 +236,5 @@ export class HTMLView {
         }
     }
 }
+Observable.defineProperty(HTMLView.prototype, "index");
+Observable.defineProperty(HTMLView.prototype, "length");

package/dist/esm/templating/when.js

@@ -1,14 +1,15 @@
 import { isFunction } from "../interfaces.js";
 /**
  * A directive that enables basic conditional rendering in a template.
- * @param binding - The condition to test for rendering.
+ * @param condition - The condition to test for rendering.
  * @param templateOrTemplateBinding - The template or a binding that gets
  * the template to render when the condition is true.
  * @public
  */
-export function when(binding, templateOrTemplateBinding) {
-    const getTemplate = isFunction(templateOrTemplateBinding)
+export function when(condition, templateOrTemplateBinding) {
+    const dataBinding = isFunction(condition) ? condition : () => condition;
+    const templateBinding = isFunction(templateOrTemplateBinding)
         ? templateOrTemplateBinding
         : () => templateOrTemplateBinding;
-    return (source, context) => binding(source, context) ? getTemplate(source, context) : null;
+    return (source, context) => dataBinding(source, context) ? templateBinding(source, context) : null;
 }

package/dist/esm/testing/exports.js

@@ -0,0 +1,3 @@
+export { timeout } from "./timeout.js";
+export * from "./fixture.js";
+export * from "./fakes.js";

package/dist/esm/testing/fakes.js

@@ -0,0 +1,107 @@
+import { ExecutionContext, } from "../index.js";
+import { noop } from "../interfaces.js";
+export const Fake = Object.freeze({
+    executionContext(parent, parentContext) {
+        return {
+            /**
+             * The index of the current item within a repeat context.
+             */
+            index: 0,
+            /**
+             * The length of the current collection within a repeat context.
+             */
+            length: 0,
+            /**
+             * The parent data source within a nested context.
+             */
+            parent: parent,
+            /**
+             * The parent execution context when in nested context scenarios.
+             */
+            parentContext: parentContext,
+            /**
+             * The current event within an event handler.
+             */
+            get event() {
+                return ExecutionContext.getEvent();
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * has an even index.
+             */
+            get isEven() {
+                return this.index % 2 === 0;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * has an odd index.
+             */
+            get isOdd() {
+                return this.index % 2 !== 0;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * is the first item in the collection.
+             */
+            get isFirst() {
+                return this.index === 0;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * is somewhere in the middle of the collection.
+             */
+            get isInMiddle() {
+                return !this.isFirst && !this.isLast;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * is the last item in the collection.
+             */
+            get isLast() {
+                return this.index === this.length - 1;
+            },
+            /**
+             * Returns the typed event detail of a custom event.
+             */
+            eventDetail() {
+                return this.event.detail;
+            },
+            /**
+             * Returns the typed event target of the event.
+             */
+            eventTarget() {
+                return this.event.target;
+            },
+        };
+    },
+    viewController(targets = {}, ...behaviors) {
+        const unbindables = new Set();
+        return {
+            isBound: false,
+            context: null,
+            onUnbind(object) {
+                unbindables.add(object);
+            },
+            source: null,
+            targets,
+            toJSON: noop,
+            bind(source, context = Fake.executionContext()) {
+                if (this.isBound) {
+                    return;
+                }
+                this.source = source;
+                this.context = context;
+                behaviors.forEach(x => x.bind(this));
+                this.isBound = true;
+            },
+            unbind() {
+                if (this.isBound) {
+                    unbindables.forEach(x => x.unbind(this));
+                    this.source = null;
+                    this.context = null;
+                    this.isBound = false;
+                }
+            },
+        };
+    },
+});

package/dist/esm/testing/fixture.js

@@ -0,0 +1,86 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { FASTElementDefinition } from "../components/fast-definitions.js";
+import { ViewTemplate } from "../templating/template.js";
+function findElement(view) {
+    let current = view.firstChild;
+    while (current !== null && current.nodeType !== 1) {
+        current = current.nextSibling;
+    }
+    return current;
+}
+/**
+ * Creates a random, unique name suitable for use as a Custom Element name.
+ * @public
+ */
+export function uniqueElementName(prefix = "fast-unique") {
+    return `${prefix}-${Math.random().toString(36).substring(7)}`;
+}
+/**
+ * Creates a test fixture suitable for testing custom elements, templates, and bindings.
+ * @param templateNameOrType An HTML template or single element name to create the fixture for.
+ * @param options Enables customizing fixture creation behavior.
+ * @remarks
+ * Yields control to the caller one Microtask later, in order to
+ * ensure that the DOM has settled.
+ * @public
+ */
+export function fixture(templateNameOrType, options = {}) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const document = options.document || globalThis.document;
+        const parent = options.parent || document.createElement("div");
+        const source = options.source || {};
+        if (typeof templateNameOrType === "function") {
+            const def = FASTElementDefinition.getByType(templateNameOrType);
+            if (!def) {
+                throw new Error("Missing FASTElement definition.");
+            }
+            templateNameOrType = def.name;
+        }
+        if (typeof templateNameOrType === "string") {
+            const html = `<${templateNameOrType}></${templateNameOrType}>`;
+            templateNameOrType = new ViewTemplate(html);
+        }
+        const view = templateNameOrType.create();
+        const element = findElement(view);
+        let isConnected = false;
+        view.bind(source);
+        view.appendTo(parent);
+        customElements.upgrade(parent);
+        // Hook into the Microtask Queue to ensure the DOM is settled
+        // before yielding control to the caller.
+        yield Promise.resolve();
+        const connect = () => __awaiter(this, void 0, void 0, function* () {
+            if (isConnected) {
+                return;
+            }
+            isConnected = true;
+            document.body.appendChild(parent);
+            yield Promise.resolve();
+        });
+        const disconnect = () => __awaiter(this, void 0, void 0, function* () {
+            if (!isConnected) {
+                return;
+            }
+            isConnected = false;
+            document.body.removeChild(parent);
+            yield Promise.resolve();
+        });
+        return {
+            document,
+            template: templateNameOrType,
+            view,
+            parent,
+            element,
+            connect,
+            disconnect,
+        };
+    });
+}

package/dist/esm/testing/timeout.js

@@ -0,0 +1,24 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * A timeout helper for use in tests.
+ * @param timeout The length of the timeout.
+ * @returns A promise that resolves once the configured time has elapsed.
+ * @public
+ */
+export function timeout(timeout = 0) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return new Promise((resolve, reject) => {
+            window.setTimeout(() => {
+                resolve(void 0);
+            }, timeout);
+        });
+    });
+}

package/dist/esm/utilities.js

@@ -1,98 +1,6 @@
-import { ArrayObserver } from "./index.debug.js";
-import { isFunction } from "./interfaces.js";
-import { Observable } from "./observation/observable.js";
-function shouldTraverse(value, traversed) {
-    return (value !== null &&
-        value !== void 0 &&
-        typeof value === "object" &&
-        !traversed.has(value));
-}
-function traverseObject(object, deep, visitor, data, traversed) {
-    if (!shouldTraverse(object, traversed)) {
-        return;
-    }
-    traversed.add(object);
-    if (Array.isArray(object)) {
-        visitor.visitArray(object, data);
-        for (const item of object) {
-            traverseObject(item, deep, visitor, data, traversed);
-        }
-    }
-    else {
-        visitor.visitObject(object, data);
-        for (const key in object) {
-            const value = object[key];
-            visitor.visitProperty(object, key, value, data);
-            if (deep) {
-                traverseObject(value, deep, visitor, data, traversed);
-            }
-        }
-    }
-}
-const noop = () => void 0;
-const observed = new WeakSet();
-const makeObserverVisitor = {
-    visitObject: noop,
-    visitArray: noop,
-    visitProperty(object, propertyName, value) {
-        Reflect.defineProperty(object, propertyName, {
-            enumerable: true,
-            get() {
-                Observable.track(object, propertyName);
-                return value;
-            },
-            set(newValue) {
-                if (value !== newValue) {
-                    value = newValue;
-                    Observable.notify(object, propertyName);
-                }
-            },
-        });
-    },
-};
-function watchObject(object, data) {
-    const notifier = Observable.getNotifier(object);
-    notifier.subscribe(data.subscriber);
-    data.notifiers.push(notifier);
-}
-const watchVisitor = {
-    visitProperty: noop,
-    visitObject: watchObject,
-    visitArray: watchObject,
-};
-/**
- * Converts a plain object to an observable object.
- * @param object - The object to make observable.
- * @param deep - Indicates whether or not to deeply convert the oject.
- * @returns The converted object.
- * @beta
- */
-export function makeObservable(object, deep = false) {
-    traverseObject(object, deep, makeObserverVisitor, void 0, observed);
-    return object;
-}
-/**
- * Deeply subscribes to changes in existing observable objects.
- * @param object - The observable object to watch.
- * @param subscriber - The handler to call when changes are made to the object.
- * @returns A disposable that can be used to unsubscribe from change updates.
- * @beta
- */
-export function watch(object, subscriber) {
-    const data = {
-        notifiers: [],
-        subscriber: isFunction(subscriber) ? { handleChange: subscriber } : subscriber,
-    };
-    ArrayObserver.enable();
-    traverseObject(object, true, watchVisitor, data, new Set());
-    return {
-        dispose() {
-            for (const n of data.notifiers) {
-                n.unsubscribe(data.subscriber);
-            }
-        },
-    };
-}
+import { DOM } from "./dom.js";
+import { ExecutionContext } from "./observation/observable.js";
+import { nextId } from "./templating/markup.js";
 /**
  * Retrieves the "composed parent" element of a node, ignoring DOM tree boundaries.
  * When the parent of a node is a shadow-root, it will return the host
@@ -120,7 +28,7 @@ export function composedParent(element) {
  * Determines if the reference element contains the test element in a "composed" DOM tree that
  * ignores shadow DOM boundaries.
  *
- * Returns true of the test element is a descendent of the reference, or exist in
+ * Returns true of the test element is a descendent of the reference, or exists in
  * a shadow DOM that is a logical descendent of the reference. Otherwise returns false.
  * @param reference - The element to test for containment against.
  * @param test - The element being tested for containment.
@@ -137,3 +45,96 @@ export function composedContains(reference, test) {
     }
     return false;
 }
+/**
+ * An extension of MutationObserver that supports unobserving nodes.
+ * @internal
+ */
+export class UnobservableMutationObserver extends MutationObserver {
+    /**
+     * Creates an instance of UnobservableMutationObserver.
+     * @param callback - The callback to invoke when observed nodes are changed.
+     */
+    constructor(callback) {
+        function handler(mutations) {
+            this.callback.call(null, mutations.filter(record => this.observedNodes.has(record.target)));
+        }
+        super(handler);
+        this.callback = callback;
+        this.observedNodes = new Set();
+    }
+    observe(target, options) {
+        this.observedNodes.add(target);
+        super.observe(target, options);
+    }
+    unobserve(target) {
+        this.observedNodes.delete(target);
+        if (this.observedNodes.size < 1) {
+            this.disconnect();
+        }
+    }
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export const ViewBehaviorOrchestrator = Object.freeze({
+    /**
+     * Creates a ViewBehaviorOrchestrator.
+     * @param source - The source to to associate behaviors with.
+     * @returns A ViewBehaviorOrchestrator.
+     */
+    create(source) {
+        const behaviors = [];
+        const targets = {};
+        let unbindables = null;
+        let isConnected = false;
+        return {
+            source,
+            context: ExecutionContext.default,
+            targets,
+            get isBound() {
+                return isConnected;
+            },
+            addBehaviorFactory(factory, target) {
+                var _a, _b, _c, _d;
+                const compiled = factory;
+                compiled.id = (_a = compiled.id) !== null && _a !== void 0 ? _a : nextId();
+                compiled.targetNodeId = (_b = compiled.targetNodeId) !== null && _b !== void 0 ? _b : nextId();
+                compiled.targetTagName = (_c = target.tagName) !== null && _c !== void 0 ? _c : null;
+                compiled.policy = (_d = compiled.policy) !== null && _d !== void 0 ? _d : DOM.policy;
+                this.addTarget(compiled.targetNodeId, target);
+                this.addBehavior(compiled.createBehavior());
+            },
+            addTarget(nodeId, target) {
+                targets[nodeId] = target;
+            },
+            addBehavior(behavior) {
+                behaviors.push(behavior);
+                if (isConnected) {
+                    behavior.bind(this);
+                }
+            },
+            onUnbind(unbindable) {
+                if (unbindables === null) {
+                    unbindables = [];
+                }
+                unbindables.push(unbindable);
+            },
+            connectedCallback(controller) {
+                if (!isConnected) {
+                    isConnected = true;
+                    behaviors.forEach(x => x.bind(this));
+                }
+            },
+            disconnectedCallback(controller) {
+                if (isConnected) {
+                    isConnected = false;
+                    if (unbindables !== null) {
+                        unbindables.forEach(x => x.unbind(this));
+                    }
+                }
+            },
+        };
+    },
+});