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

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

@@ -1,64 +1,149 @@
-import { DOM } from "../dom.js";
+import { createTypeRegistry } from "../platform.js";
+import { Markup } from "./markup.js";
+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;
+    },
+});
 /**
- * A {@link HTMLDirective} that targets a named attribute or property on a node.
+ * Decorator: Defines an HTMLDirective.
+ * @param options - Provides options that specify the directive's application.
  * @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 function htmlDirective(options) {
+    /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+    return function (type) {
+        HTMLDirective.define(type, options);
+    };
 }
 /**
- * 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.
+     * @param directive - The directive to assign the aspect to.
+     * @param value - The value to base the aspect determination on.
      */
-    constructor(name, behavior, options) {
-        super();
-        this.name = name;
-        this.behavior = behavior;
+    assign(directive, value) {
+        directive.sourceAspect = value;
+        if (!value) {
+            return;
+        }
+        switch (value[0]) {
+            case ":":
+                directive.targetAspect = value.substring(1);
+                switch (directive.targetAspect) {
+                    case "innerHTML":
+                        directive.aspectType = Aspect.property;
+                        break;
+                    case "classList":
+                        directive.aspectType = Aspect.tokenList;
+                        break;
+                    default:
+                        directive.aspectType = Aspect.property;
+                        break;
+                }
+                break;
+            case "?":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType = Aspect.booleanAttribute;
+                break;
+            case "@":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType = Aspect.event;
+                break;
+            default:
+                if (value === "class") {
+                    directive.targetAspect = "className";
+                    directive.aspectType = Aspect.property;
+                }
+                else {
+                    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;
     }
     /**
-     * Creates a placeholder string based on the directive's index within the template.
-     * @param index - The index of the directive within the template.
-     * @remarks
-     * Creates a custom attribute placeholder.
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
      */
-    createPlaceholder(index) {
-        return DOM.createCustomAttributePlaceholder(this.name, index);
+    createBehavior(targets) {
+        return this;
     }
     /**
-     * Creates a behavior for the provided target node.
-     * @param target - The node instance to create the behavior for.
+     * Creates a placeholder string based on the directive's index within the template.
+     * @param index - The index of the directive within the template.
      * @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 custom attribute placeholder.
      */
-    createBehavior(target) {
-        return new this.behavior(target, this.options);
+    createHTML(add) {
+        return Markup.attribute(add(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,77 @@
-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(source, context, targets) {
+        const target = targets[this.nodeId];
+        target[this.sourceProperty] = source;
+        this.updateTarget(source, this.computeNodes(target));
+        this.observe(target);
     }
     /**
      * 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(source, context, targets) {
+        const target = targets[this.nodeId];
+        this.updateTarget(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,25 +1,17 @@
-import { AttachedBehaviorHTMLDirective } from "./html-directive.js";
+import { HTMLDirective, StatelessAttachedAttributeDirective, } from "./html-directive.js";
 /**
  * The runtime behavior for template references.
  * @public
  */
-export class RefBehavior {
-    /**
-     * Creates an instance of RefBehavior.
-     * @param target - The element to reference.
-     * @param propertyName - The name of the property to assign the reference to.
-     */
-    constructor(target, propertyName) {
-        this.target = target;
-        this.propertyName = propertyName;
-    }
+export class RefDirective extends StatelessAttachedAttributeDirective {
     /**
      * 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) {
-        source[this.propertyName] = this.target;
+    bind(source, context, targets) {
+        source[this.options] = targets[this.nodeId];
     }
     /**
      * Unbinds this behavior from the source.
@@ -28,11 +20,10 @@ export class RefBehavior {
     /* 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);

package/dist/esm/templating/repeat.js

@@ -1,8 +1,9 @@
-import { DOM } from "../dom.js";
+import { isFunction } from "../interfaces.js";
 import { Observable, } from "../observation/observable.js";
-import { enableArrayObservation } from "../observation/array-observer.js";
 import { emptyArray } from "../platform.js";
-import { HTMLDirective } from "./html-directive.js";
+import { ArrayObserver } from "../observation/arrays.js";
+import { Markup } from "./markup.js";
+import { HTMLDirective, } from "./html-directive.js";
 import { HTMLView } from "./view.js";
 const defaultRepeatOptions = Object.freeze({
     positioning: false,
@@ -12,10 +13,7 @@ function bindWithoutPositioning(view, items, index, context) {
     view.bind(items[index], context);
 }
 function bindWithPositioning(view, items, index, context) {
-    const childContext = Object.create(context);
-    childContext.index = index;
-    childContext.length = items.length;
-    view.bind(items[index], childContext);
+    view.bind(items[index], context.createItemContext(index, items.length));
 }
 /**
  * A behavior that renders a template for each item in an array.
@@ -40,7 +38,7 @@ export class RepeatBehavior {
         this.views = [];
         this.items = null;
         this.itemsObserver = null;
-        this.originalContext = void 0;
+        this.context = void 0;
         this.childContext = void 0;
         this.bindView = bindWithoutPositioning;
         this.itemsBindingObserver = Observable.binding(itemsBinding, this, isItemsBindingVolatile);
@@ -56,12 +54,10 @@ export class RepeatBehavior {
      */
     bind(source, context) {
         this.source = source;
-        this.originalContext = context;
-        this.childContext = Object.create(context);
-        this.childContext.parent = source;
-        this.childContext.parentContext = this.originalContext;
-        this.items = this.itemsBindingObserver.observe(source, this.originalContext);
-        this.template = this.templateBindingObserver.observe(source, this.originalContext);
+        this.context = context;
+        this.childContext = context.createChildContext(source);
+        this.items = this.itemsBindingObserver.observe(source, this.context);
+        this.template = this.templateBindingObserver.observe(source, this.context);
         this.observeItems(true);
         this.refreshAllViews();
     }
@@ -76,20 +72,27 @@ export class RepeatBehavior {
             this.itemsObserver.unsubscribe(this);
         }
         this.unbindAllViews();
-        this.itemsBindingObserver.disconnect();
-        this.templateBindingObserver.disconnect();
+        this.itemsBindingObserver.dispose();
+        this.templateBindingObserver.dispose();
     }
-    /** @internal */
+    /**
+     * Handles changes in the array, its items, and the repeat template.
+     * @param source - The source of the change.
+     * @param args - The details about what was changed.
+     */
     handleChange(source, args) {
         if (source === this.itemsBinding) {
-            this.items = this.itemsBindingObserver.observe(this.source, this.originalContext);
+            this.items = this.itemsBindingObserver.observe(this.source, this.context);
             this.observeItems();
             this.refreshAllViews();
         }
         else if (source === this.templateBinding) {
-            this.template = this.templateBindingObserver.observe(this.source, this.originalContext);
+            this.template = this.templateBindingObserver.observe(this.source, this.context);
             this.refreshAllViews(true);
         }
+        else if (args[0].reset) {
+            this.refreshAllViews();
+        }
         else {
             this.updateViews(args);
         }
@@ -110,8 +113,8 @@ export class RepeatBehavior {
         }
     }
     updateViews(splices) {
-        const childContext = this.childContext;
         const views = this.views;
+        const childContext = this.childContext;
         const totalRemoved = [];
         const bindView = this.bindView;
         let removeDelta = 0;
@@ -143,18 +146,16 @@ export class RepeatBehavior {
         }
         if (this.options.positioning) {
             for (let i = 0, ii = views.length; i < ii; ++i) {
-                const currentContext = views[i].context;
-                currentContext.length = ii;
-                currentContext.index = i;
+                views[i].context.updatePosition(i, ii);
             }
         }
     }
     refreshAllViews(templateChanged = false) {
         const items = this.items;
-        const childContext = this.childContext;
         const template = this.template;
         const location = this.location;
         const bindView = this.bindView;
+        const childContext = this.childContext;
         let itemsLength = items.length;
         let views = this.views;
         let viewsLength = views.length;
@@ -205,7 +206,7 @@ export class RepeatBehavior {
  * A directive that configures list rendering.
  * @public
  */
-export class RepeatDirective extends HTMLDirective {
+export class RepeatDirective {
     /**
      * Creates an instance of RepeatDirective.
      * @param itemsBinding - The binding that provides the array to render.
@@ -213,37 +214,31 @@ export class RepeatDirective extends HTMLDirective {
      * @param options - Options used to turn on special repeat features.
      */
     constructor(itemsBinding, templateBinding, options) {
-        super();
         this.itemsBinding = itemsBinding;
         this.templateBinding = templateBinding;
         this.options = options;
-        /**
-         * 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.createBlockPlaceholder;
-        enableArrayObservation();
+        ArrayObserver.enable();
         this.isItemsBindingVolatile = Observable.isVolatileBinding(itemsBinding);
         this.isTemplateBindingVolatile = Observable.isVolatileBinding(templateBinding);
     }
+    /**
+     * Creates a placeholder string based on the directive's index within the template.
+     * @param index - The index of the directive within the template.
+     */
+    createHTML(add) {
+        return Markup.comment(add(this));
+    }
     /**
      * Creates a behavior for the provided target node.
      * @param target - The node instance to create the behavior for.
      */
-    createBehavior(target) {
-        return new RepeatBehavior(target, this.itemsBinding, this.isItemsBindingVolatile, this.templateBinding, this.isTemplateBindingVolatile, this.options);
+    createBehavior(targets) {
+        return new RepeatBehavior(targets[this.nodeId], this.itemsBinding, this.isItemsBindingVolatile, this.templateBinding, this.isTemplateBindingVolatile, this.options);
     }
 }
-/**
- * A directive that enables list rendering.
- * @param itemsBinding - The array to render.
- * @param templateOrTemplateBinding - The template or a template binding used obtain a template
- * to render for each item in the array.
- * @param options - Options used to turn on special repeat features.
- * @public
- */
+HTMLDirective.define(RepeatDirective);
 export function repeat(itemsBinding, templateOrTemplateBinding, options = defaultRepeatOptions) {
-    const templateBinding = typeof templateOrTemplateBinding === "function"
+    const templateBinding = isFunction(templateOrTemplateBinding)
         ? templateOrTemplateBinding
         : () => templateOrTemplateBinding;
     return new RepeatDirective(itemsBinding, templateBinding, options);

package/dist/esm/templating/slotted.js

@@ -1,37 +1,40 @@
-import { AttachedBehaviorHTMLDirective } from "./html-directive.js";
-import { NodeObservationBehavior } from "./node-observation.js";
+import { isString } from "../interfaces.js";
+import { HTMLDirective } from "./html-directive.js";
+import { NodeObservationDirective } from "./node-observation.js";
+const slotEvent = "slotchange";
 /**
  * The runtime behavior for slotted node observation.
  * @public
  */
-export class SlottedBehavior extends NodeObservationBehavior {
-    /**
-     * Creates an instance of SlottedBehavior.
-     * @param target - The slot element target to observe.
-     * @param options - The options to use when observing the slot.
-     */
-    constructor(target, options) {
-        super(target, options);
-    }
+export class SlottedDirective extends NodeObservationDirective {
     /**
      * Begins observation of the nodes.
+     * @param target - The target to observe.
      */
-    observe() {
-        this.target.addEventListener("slotchange", this);
+    observe(target) {
+        target.addEventListener(slotEvent, this);
     }
     /**
      * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
      */
-    disconnect() {
-        this.target.removeEventListener("slotchange", this);
+    disconnect(target) {
+        target.removeEventListener(slotEvent, this);
     }
     /**
-     * Retrieves the nodes that should be assigned to the target.
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
      */
-    getNodes() {
-        return this.target.assignedNodes(this.options);
+    getNodes(target) {
+        return target.assignedNodes(this.options);
+    }
+    /** @internal */
+    handleEvent(event) {
+        const target = event.currentTarget;
+        this.updateTarget(this.getSource(target), this.computeNodes(target));
     }
 }
+HTMLDirective.define(SlottedDirective);
 /**
  * A directive that observes the `assignedNodes()` of a slot and updates a property
  * whenever they change.
@@ -39,8 +42,8 @@ export class SlottedBehavior extends NodeObservationBehavior {
  * @public
  */
 export function slotted(propertyOrOptions) {
-    if (typeof propertyOrOptions === "string") {
+    if (isString(propertyOrOptions)) {
         propertyOrOptions = { property: propertyOrOptions };
     }
-    return new AttachedBehaviorHTMLDirective("fast-slotted", SlottedBehavior, propertyOrOptions);
+    return new SlottedDirective(propertyOrOptions);
 }