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

package/dist/esm/templating/html-directive.js

@@ -1,46 +1,206 @@
-import { DOM } from "../dom.js";
+import { ExecutionContext, } from "../observation/observable.js";
+import { createTypeRegistry } from "../platform.js";
+import { Markup, nextId } from "./markup.js";
+/**
+ * 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) {
+                const nodeId = factory.nodeId || (factory.nodeId = nextId());
+                factory.id || (factory.id = nextId());
+                this.addTarget(nodeId, target);
+                this.addBehavior(factory.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));
+                    }
+                }
+            },
+        };
+    },
+});
+const registry = createTypeRegistry();
 /**
  * Instructs the template engine to apply behavior to a node.
  * @public
  */
-export class HTMLDirective {
-    constructor() {
-        /**
-         * The index of the DOM node to which the created behavior will apply.
-         */
-        this.targetIndex = 0;
-    }
+export const HTMLDirective = Object.freeze({
+    /**
+     * Gets the directive definition associated with the instance.
+     * @param instance - The directive instance to retrieve the definition for.
+     */
+    getForInstance: registry.getForInstance,
+    /**
+     * Gets the directive definition associated with the specified type.
+     * @param type - The directive type to retrieve the definition for.
+     */
+    getByType: registry.getByType,
+    /**
+     * Defines an HTMLDirective based on the options.
+     * @param type - The type to define as a directive.
+     * @param options - Options that specify the directive's application.
+     */
+    define(type, options) {
+        options = options || {};
+        options.type = type;
+        registry.register(options);
+        return type;
+    },
+});
+/**
+ * Decorator: Defines an HTMLDirective.
+ * @param options - Provides options that specify the directive's application.
+ * @public
+ */
+export function htmlDirective(options) {
+    /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+    return function (type) {
+        HTMLDirective.define(type, options);
+    };
 }
 /**
- * A {@link HTMLDirective} that targets a named attribute or property on a node.
+ * Captures a binding expression along with related information and capabilities.
+ *
  * @public
  */
-export class TargetedHTMLDirective extends HTMLDirective {
-    constructor() {
-        super(...arguments);
-        /**
-         * Creates a placeholder string based on the directive's index within the template.
-         * @param index - The index of the directive within the template.
-         */
-        this.createPlaceholder = DOM.createInterpolationPlaceholder;
+export class Binding {
+    /**
+     * Creates a binding.
+     * @param evaluate - Evaluates the binding.
+     * @param isVolatile - Indicates whether the binding is volatile.
+     */
+    constructor(evaluate, isVolatile = false) {
+        this.evaluate = evaluate;
+        this.isVolatile = isVolatile;
     }
 }
 /**
- * A directive that attaches special behavior to an element via a custom attribute.
+ * The type of HTML aspect to target.
  * @public
  */
-export class AttachedBehaviorHTMLDirective extends HTMLDirective {
+export const Aspect = Object.freeze({
+    /**
+     * Not aspected.
+     */
+    none: 0,
+    /**
+     * An attribute.
+     */
+    attribute: 1,
+    /**
+     * A boolean attribute.
+     */
+    booleanAttribute: 2,
+    /**
+     * A property.
+     */
+    property: 3,
+    /**
+     * Content
+     */
+    content: 4,
+    /**
+     * A token list.
+     */
+    tokenList: 5,
+    /**
+     * An event.
+     */
+    event: 6,
     /**
      *
-     * @param name - The name of the behavior; used as a custom attribute on the element.
-     * @param behavior - The behavior to instantiate and attach to the element.
-     * @param options - Options to pass to the behavior during creation.
-     */
-    constructor(name, behavior, options) {
-        super();
-        this.name = name;
-        this.behavior = behavior;
+     * @param directive - The directive to assign the aspect to.
+     * @param value - The value to base the aspect determination on.
+     * @remarks
+     * If a falsy value is provided, then the content aspect will be assigned.
+     */
+    assign(directive, value) {
+        if (!value) {
+            directive.aspectType = Aspect.content;
+            return;
+        }
+        directive.sourceAspect = value;
+        switch (value[0]) {
+            case ":":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType =
+                    directive.targetAspect === "classList"
+                        ? Aspect.tokenList
+                        : Aspect.property;
+                break;
+            case "?":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType = Aspect.booleanAttribute;
+                break;
+            case "@":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType = Aspect.event;
+                break;
+            default:
+                directive.targetAspect = value;
+                directive.aspectType = Aspect.attribute;
+                break;
+        }
+    },
+});
+/**
+ * A base class used for attribute directives that don't need internal state.
+ * @public
+ */
+export class StatelessAttachedAttributeDirective {
+    /**
+     * Creates an instance of RefDirective.
+     * @param options - The options to use in configuring the directive.
+     */
+    constructor(options) {
         this.options = options;
+        /**
+         * The unique id of the factory.
+         */
+        this.id = nextId();
     }
     /**
      * Creates a placeholder string based on the directive's index within the template.
@@ -48,17 +208,14 @@ export class AttachedBehaviorHTMLDirective extends HTMLDirective {
      * @remarks
      * Creates a custom attribute placeholder.
      */
-    createPlaceholder(index) {
-        return DOM.createCustomAttributePlaceholder(this.name, index);
+    createHTML(add) {
+        return Markup.attribute(add(this));
     }
     /**
-     * Creates a behavior for the provided target node.
-     * @param target - The node instance to create the behavior for.
-     * @remarks
-     * Creates an instance of the `behavior` type this directive was constructed with
-     * and passes the target and options to that `behavior`'s constructor.
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
      */
-    createBehavior(target) {
-        return new this.behavior(target, this.options);
+    createBehavior() {
+        return this;
     }
 }

package/dist/esm/templating/markup.js

@@ -0,0 +1,75 @@
+const marker = `fast-${Math.random().toString(36).substring(2, 8)}`;
+const interpolationStart = `${marker}{`;
+const interpolationEnd = `}${marker}`;
+const interpolationEndLength = interpolationEnd.length;
+let id = 0;
+/** @internal */
+export const nextId = () => `${marker}-${++id}`;
+/**
+ * Common APIs related to markup generation.
+ * @public
+ */
+export const Markup = Object.freeze({
+    /**
+     * 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.
+     */
+    interpolation: (id) => `${interpolationStart}${id}${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`.
+     */
+    attribute: (id) => `${nextId()}="${interpolationStart}${id}${interpolationEnd}"`,
+    /**
+     * 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`.
+     */
+    comment: (id) => `<!--${interpolationStart}${id}${interpolationEnd}-->`,
+});
+/**
+ * Common APIs related to content parsing.
+ * @public
+ */
+export const Parser = Object.freeze({
+    /**
+     * Parses text content or HTML attribute content, separating out the static strings
+     * from the directives.
+     * @param value - The content or attribute string to parse.
+     * @param factories - A list of directives to search for in the string.
+     * @returns A heterogeneous array of static strings interspersed with
+     * directives or null if no directives are found in the string.
+     */
+    parse(value, factories) {
+        const parts = value.split(interpolationStart);
+        if (parts.length === 1) {
+            return null;
+        }
+        const result = [];
+        for (let i = 0, ii = parts.length; i < ii; ++i) {
+            const current = parts[i];
+            const index = current.indexOf(interpolationEnd);
+            let literal;
+            if (index === -1) {
+                literal = current;
+            }
+            else {
+                const factoryId = current.substring(0, index);
+                result.push(factories[factoryId]);
+                literal = current.substring(index + interpolationEndLength);
+            }
+            if (literal !== "") {
+                result.push(literal);
+            }
+        }
+        return result;
+    },
+});

package/dist/esm/templating/node-observation.js

@@ -1,72 +1,78 @@
-import { Observable } from "../observation/observable.js";
 import { emptyArray } from "../platform.js";
+import { StatelessAttachedAttributeDirective } from "./html-directive.js";
+const selectElements = (value) => value.nodeType === 1;
 /**
  * Creates a function that can be used to filter a Node array, selecting only elements.
  * @param selector - An optional selector to restrict the filter to.
  * @public
  */
-export function elements(selector) {
-    if (selector) {
-        return function (value, index, array) {
-            return value.nodeType === 1 && value.matches(selector);
-        };
-    }
-    return function (value, index, array) {
-        return value.nodeType === 1;
-    };
-}
+export const elements = (selector) => selector
+    ? value => value.nodeType === 1 && value.matches(selector)
+    : selectElements;
 /**
  * A base class for node observation.
- * @internal
+ * @public
+ * @remarks
+ * Internally used by the SlottedDirective and the ChildrenDirective.
  */
-export class NodeObservationBehavior {
-    /**
-     * Creates an instance of NodeObservationBehavior.
-     * @param target - The target to assign the nodes property on.
-     * @param options - The options to use in configuring node observation.
-     */
-    constructor(target, options) {
-        this.target = target;
-        this.options = options;
-        this.source = null;
+export class NodeObservationDirective extends StatelessAttachedAttributeDirective {
+    constructor() {
+        super(...arguments);
+        this.sourceProperty = `${this.id}-s`;
     }
     /**
      * Bind this behavior to the source.
      * @param source - The source to bind to.
      * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
      */
-    bind(source) {
-        const name = this.options.property;
-        this.shouldUpdate = Observable.getAccessors(source).some((x) => x.name === name);
-        this.source = source;
-        this.updateTarget(this.computeNodes());
-        if (this.shouldUpdate) {
-            this.observe();
-        }
+    bind(controller) {
+        const target = controller.targets[this.nodeId];
+        target[this.sourceProperty] = controller.source;
+        this.updateTarget(controller.source, this.computeNodes(target));
+        this.observe(target);
+        controller.onUnbind(this);
     }
     /**
      * Unbinds this behavior from the source.
      * @param source - The source to unbind from.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
      */
-    unbind() {
-        this.updateTarget(emptyArray);
-        this.source = null;
-        if (this.shouldUpdate) {
-            this.disconnect();
-        }
+    unbind(controller) {
+        const target = controller.targets[this.nodeId];
+        this.updateTarget(controller.source, emptyArray);
+        this.disconnect(target);
+        target[this.sourceProperty] = null;
     }
-    /** @internal */
-    handleEvent() {
-        this.updateTarget(this.computeNodes());
+    /**
+     * Gets the data source for the target.
+     * @param target - The target to get the source for.
+     * @returns The source.
+     */
+    getSource(target) {
+        return target[this.sourceProperty];
+    }
+    /**
+     * Updates the source property with the computed nodes.
+     * @param source - The source object to assign the nodes property to.
+     * @param value - The nodes to assign to the source object property.
+     */
+    updateTarget(source, value) {
+        source[this.options.property] = value;
     }
-    computeNodes() {
-        let nodes = this.getNodes();
-        if (this.options.filter !== void 0) {
+    /**
+     * Computes the set of nodes that should be assigned to the source property.
+     * @param target - The target to compute the nodes for.
+     * @returns The computed nodes.
+     * @remarks
+     * Applies filters if provided.
+     */
+    computeNodes(target) {
+        let nodes = this.getNodes(target);
+        if ("filter" in this.options) {
             nodes = nodes.filter(this.options.filter);
         }
         return nodes;
     }
-    updateTarget(value) {
-        this.source[this.options.property] = value;
-    }
 }

package/dist/esm/templating/ref.js

@@ -1,38 +1,21 @@
-import { AttachedBehaviorHTMLDirective } from "./html-directive.js";
+import { HTMLDirective, StatelessAttachedAttributeDirective, } from "./html-directive.js";
 /**
  * The runtime behavior for template references.
  * @public
  */
-export class RefBehavior {
+export class RefDirective extends StatelessAttachedAttributeDirective {
     /**
-     * Creates an instance of RefBehavior.
-     * @param target - The element to reference.
-     * @param propertyName - The name of the property to assign the reference to.
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
      */
-    constructor(target, propertyName) {
-        this.target = target;
-        this.propertyName = propertyName;
+    bind(controller) {
+        controller.source[this.options] = controller.targets[this.nodeId];
     }
-    /**
-     * 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) {
-        source[this.propertyName] = this.target;
-    }
-    /**
-     * Unbinds this behavior from the source.
-     * @param source - The source to unbind from.
-     */
-    /* eslint-disable-next-line @typescript-eslint/no-empty-function */
-    unbind() { }
 }
+HTMLDirective.define(RefDirective);
 /**
  * A directive that observes the updates a property with a reference to the element.
  * @param propertyName - The name of the property to assign the reference to.
  * @public
  */
-export function ref(propertyName) {
-    return new AttachedBehaviorHTMLDirective("fast-ref", RefBehavior, propertyName);
-}
+export const ref = (propertyName) => new RefDirective(propertyName);