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

package/dist/dts/utilities.d.ts

@@ -1,3 +1,5 @@
+import type { HostBehavior } from "./styles/host.js";
+import type { ViewBehavior, ViewBehaviorFactory, ViewController } from "./templating/html-directive.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
@@ -12,7 +14,7 @@ export declare function composedParent<T extends HTMLElement>(element: T): HTMLE
  * 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.
@@ -20,3 +22,55 @@ export declare function composedParent<T extends HTMLElement>(element: T): HTMLE
  * @public
  */
 export declare function composedContains(reference: HTMLElement, test: HTMLElement): boolean;
+/**
+ * An extension of MutationObserver that supports unobserving nodes.
+ * @internal
+ */
+export declare class UnobservableMutationObserver extends MutationObserver {
+    private readonly callback;
+    private observedNodes;
+    /**
+     * Creates an instance of UnobservableMutationObserver.
+     * @param callback - The callback to invoke when observed nodes are changed.
+     */
+    constructor(callback: MutationCallback);
+    observe(target: Node, options?: MutationObserverInit | undefined): void;
+    unobserve(target: Node): void;
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export interface ViewBehaviorOrchestrator<TSource = any, TParent = any> extends ViewController<TSource, TParent>, HostBehavior<TSource> {
+    /**
+     *
+     * @param nodeId - The structural id of the DOM node to which a behavior will apply.
+     * @param target - The DOM node associated with the id.
+     */
+    addTarget(nodeId: string, target: Node): void;
+    /**
+     * Adds a behavior.
+     * @param behavior - The behavior to add.
+     */
+    addBehavior(behavior: ViewBehavior): void;
+    /**
+     * Adds a behavior factory.
+     * @param factory - The behavior factory to add.
+     * @param target - The target the factory will create behaviors for.
+     */
+    addBehaviorFactory(factory: ViewBehaviorFactory, target: Node): void;
+}
+/**
+ * Bridges between ViewBehaviors and HostBehaviors, enabling a host to
+ * control ViewBehaviors.
+ * @public
+ */
+export declare const ViewBehaviorOrchestrator: Readonly<{
+    /**
+     * Creates a ViewBehaviorOrchestrator.
+     * @param source - The source to to associate behaviors with.
+     * @returns A ViewBehaviorOrchestrator.
+     */
+    create<TSource = any, TParent = any>(source: TSource): ViewBehaviorOrchestrator<TSource, TParent>;
+}>;

package/dist/esm/binding/binding.js

@@ -0,0 +1,18 @@
+/**
+ * Captures a binding expression along with related information and capabilities.
+ *
+ * @public
+ */
+export class Binding {
+    /**
+     * Creates a binding.
+     * @param evaluate - Evaluates the binding.
+     * @param policy - The security policy to associate with this binding.
+     * @param isVolatile - Indicates whether the binding is volatile.
+     */
+    constructor(evaluate, policy, isVolatile = false) {
+        this.evaluate = evaluate;
+        this.policy = policy;
+        this.isVolatile = isVolatile;
+    }
+}

package/dist/esm/binding/normalize.js

@@ -0,0 +1,17 @@
+import { isFunction } from "../interfaces.js";
+import { Binding } from "./binding.js";
+import { oneWay } from "./one-way.js";
+import { oneTime } from "./one-time.js";
+/**
+ * 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)
+        ? oneWay(value)
+        : value instanceof Binding
+            ? value
+            : oneTime(() => value);
+}

package/dist/esm/binding/one-time.js

@@ -0,0 +1,21 @@
+import { makeSerializationNoop } from "../platform.js";
+import { Binding } from "./binding.js";
+class OneTimeBinding extends Binding {
+    createObserver() {
+        return this;
+    }
+    bind(controller) {
+        return this.evaluate(controller.source, controller.context);
+    }
+}
+makeSerializationNoop(OneTimeBinding);
+/**
+ * Creates a one time binding
+ * @param expression - The binding to refresh when signaled.
+ * @param policy - The security policy to associate with th binding.
+ * @returns A binding configuration.
+ * @public
+ */
+export function oneTime(expression, policy) {
+    return new OneTimeBinding(expression, policy);
+}

package/dist/esm/binding/one-way.js

@@ -0,0 +1,30 @@
+import { Observable } from "../observation/observable.js";
+import { Binding } from "./binding.js";
+class OneWayBinding extends Binding {
+    createObserver(subscriber) {
+        return Observable.binding(this.evaluate, subscriber, this.isVolatile);
+    }
+}
+/**
+ * Creates an standard binding.
+ * @param expression - The binding to refresh when changed.
+ * @param policy - The security policy to associate with th binding.
+ * @param isVolatile - Indicates whether the binding is volatile or not.
+ * @returns A binding configuration.
+ * @public
+ */
+export function oneWay(expression, policy, isVolatile = Observable.isVolatileBinding(expression)) {
+    return new OneWayBinding(expression, policy, isVolatile);
+}
+/**
+ * Creates an event listener binding.
+ * @param expression - The binding to invoke when the event is raised.
+ * @param options - Event listener options.
+ * @returns A binding configuration.
+ * @public
+ */
+export function listener(expression, options) {
+    const config = new OneWayBinding(expression);
+    config.options = options;
+    return config;
+}

package/dist/esm/{templating/binding-signal.js → binding/signal.js}

@@ -1,7 +1,17 @@
 import { isString } from "../interfaces.js";
-import { Binding } from "./html-directive.js";
+import { makeSerializationNoop } from "../platform.js";
+import { Binding } from "./binding.js";
 const subscribers = Object.create(null);
+/**
+ * The gateway to signal APIs.
+ * @public
+ */
 export const Signal = Object.freeze({
+    /**
+     * Subscribes to a signal.
+     * @param signal The signal to subscribe to.
+     * @param subscriber The subscriber.
+     */
     subscribe(signal, subscriber) {
         const found = subscribers[signal];
         if (found) {
@@ -13,6 +23,11 @@ export const Signal = Object.freeze({
             subscribers[signal] = subscriber;
         }
     },
+    /**
+     * Unsubscribes from the signal.
+     * @param signal The signal to unsubscribe from.
+     * @param subscriber The subscriber.
+     */
     unsubscribe(signal, subscriber) {
         const found = subscribers[signal];
         if (found && found instanceof Set) {
@@ -23,9 +38,8 @@ export const Signal = Object.freeze({
         }
     },
     /**
-     * Sends the specified signal to signaled bindings.
+     * Sends the specified signal to subscribers.
      * @param signal - The signal to send.
-     * @public
      */
     send(signal) {
         const found = subscribers[signal];
@@ -64,8 +78,9 @@ class SignalObserver {
             : options(controller.source, controller.context);
     }
 }
+makeSerializationNoop(SignalObserver);
 class SignalBinding extends Binding {
-    createObserver(directive, subscriber) {
+    createObserver(subscriber) {
         return new SignalObserver(this, subscriber);
     }
 }
@@ -73,11 +88,12 @@ class SignalBinding extends Binding {
  * Creates a signal binding configuration with the supplied options.
  * @param expression - The binding to refresh when signaled.
  * @param options - The signal name or a binding to use to retrieve the signal name.
+ * @param policy - The security policy to associate with th binding.
  * @returns A binding configuration.
  * @public
  */
-export function signal(expression, options) {
-    const binding = new SignalBinding(expression);
+export function signal(expression, options, policy) {
+    const binding = new SignalBinding(expression, policy);
     binding.options = options;
     return binding;
 }

package/dist/esm/{templating/binding-two-way.js → binding/two-way.js}

@@ -1,7 +1,7 @@
 import { isString } from "../interfaces.js";
 import { Observable, } from "../observation/observable.js";
-import { FAST } from "../platform.js";
-import { Binding } from "./html-directive.js";
+import { FAST, makeSerializationNoop } from "../platform.js";
+import { Binding } from "./binding.js";
 const defaultOptions = {
     fromView: v => v,
 };
@@ -10,6 +10,9 @@ let twoWaySettings = {
         return "change";
     },
 };
+/**
+ * Enables configuring two-way binding settings.
+ */
 export const TwoWaySettings = Object.freeze({
     /**
      * Configures two-way binding.
@@ -48,7 +51,7 @@ class TwoWayObserver {
         this.subscriber.handleChange(this.dataBinding.evaluate, this);
     }
     handleEvent(event) {
-        const directive = this.directive;
+        const bindingSource = this.directive;
         const target = event.currentTarget;
         const notifier = this.notifier;
         const last = notifier.last; // using internal API!!!
@@ -57,37 +60,40 @@ class TwoWayObserver {
             return;
         }
         let value;
-        switch (directive.aspectType) {
+        switch (bindingSource.aspectType) {
             case 1:
-                value = target.getAttribute(directive.targetAspect);
+                value = target.getAttribute(bindingSource.targetAspect);
                 break;
             case 2:
-                value = target.hasAttribute(directive.targetAspect);
+                value = target.hasAttribute(bindingSource.targetAspect);
                 break;
             case 4:
                 value = target.innerText;
                 break;
             default:
-                value = target[directive.targetAspect];
+                value = target[bindingSource.targetAspect];
                 break;
         }
-        last.propertySource[last.propertyName] = this.dataBinding.options.fromView(value);
+        last.propertySource[last.propertyName] =
+            this.dataBinding.options.fromView(value);
     }
 }
+makeSerializationNoop(TwoWayObserver);
 class TwoWayBinding extends Binding {
-    createObserver(directive, subscriber) {
-        return new TwoWayObserver(directive, subscriber, this);
+    createObserver(subscriber, bindingSource) {
+        return new TwoWayObserver(bindingSource, subscriber, this);
     }
 }
 /**
  * Creates a default binding.
  * @param expression - The binding to refresh when changed.
  * @param optionsOrChangeEvent - The binding options or the name of the change event to use.
+ * @param policy - The security policy to associate with the binding.
  * @param isBindingVolatile - Indicates whether the binding is volatile or not.
  * @returns A binding.
  * @public
  */
-export function twoWay(expression, optionsOrChangeEvent, isBindingVolatile = Observable.isVolatileBinding(expression)) {
+export function twoWay(expression, optionsOrChangeEvent, policy, isBindingVolatile = Observable.isVolatileBinding(expression)) {
     if (isString(optionsOrChangeEvent)) {
         optionsOrChangeEvent = { changeEvent: optionsOrChangeEvent };
     }
@@ -97,7 +103,7 @@ export function twoWay(expression, optionsOrChangeEvent, isBindingVolatile = Obs
     else if (!optionsOrChangeEvent.fromView) {
         optionsOrChangeEvent.fromView = defaultOptions.fromView;
     }
-    const binding = new TwoWayBinding(expression, isBindingVolatile);
+    const binding = new TwoWayBinding(expression, policy, isBindingVolatile);
     binding.options = optionsOrChangeEvent;
     return binding;
 }

package/dist/esm/components/attributes.js

@@ -1,7 +1,7 @@
 import { Observable } from "../observation/observable.js";
 import { isString } from "../interfaces.js";
 import { Updates } from "../observation/update-queue.js";
-import { DOM } from "../templating/dom.js";
+import { DOM } from "../dom.js";
 import { createMetadataLocator } from "../platform.js";
 const booleanMode = "boolean";
 const reflectMode = "reflect";
@@ -35,6 +35,21 @@ export const booleanConverter = {
             : true;
     },
 };
+/**
+ * A {@link ValueConverter} that converts to and from `boolean` values. `null`, `undefined`, `""`,
+ * and `void` values are converted to `null`.
+ * @public
+ */
+export const nullableBooleanConverter = {
+    toView(value) {
+        return typeof value === "boolean" ? value.toString() : "";
+    },
+    fromView(value) {
+        return [null, undefined, void 0].includes(value)
+            ? null
+            : booleanConverter.fromView(value);
+    },
+};
 function toNumber(value) {
     if (value === null || value === undefined) {
         return null;