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

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

@@ -1,16 +1,17 @@
-import { Binding } from "../observation/observable.js";
-import { ElementView, HTMLView, SyntheticView } from "./view.js";
-import { HTMLDirective } from "./html-directive.js";
+import { Binding, ChildContext, ExecutionContext, ItemContext } from "../observation/observable.js";
+import { HTMLDirective, ViewBehaviorFactory } from "./html-directive.js";
+import type { ElementView, HTMLView, SyntheticView } from "./view.js";
 /**
  * A template capable of creating views specifically for rendering custom elements.
  * @public
  */
-export interface ElementViewTemplate {
+export interface ElementViewTemplate<TSource = any, TParent = any> {
+    type: "element";
     /**
      * Creates an ElementView instance based on this template definition.
      * @param hostBindingTarget - The element that host behaviors will be bound to.
      */
-    create(hostBindingTarget: Element): ElementView;
+    create(hostBindingTarget: Element): ElementView<TSource, TParent>;
     /**
      * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
      * @param source - The data source to bind the template to.
@@ -18,29 +19,63 @@ export interface ElementViewTemplate {
      * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
      * host that the template is being attached to.
      */
-    render(source: any, host: Node, hostBindingTarget?: Element): HTMLView;
+    render(source: TSource, host: Node, hostBindingTarget?: Element): ElementView<TSource, TParent>;
 }
 /**
  * A template capable of rendering views not specifically connected to custom elements.
  * @public
  */
-export interface SyntheticViewTemplate<TSource = any, TParent = any> {
+export interface SyntheticViewTemplate<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>> {
+    type: "synthetic";
     /**
      * Creates a SyntheticView instance based on this template definition.
      */
-    create(): SyntheticView;
+    create(): SyntheticView<TSource, TParent, TContext>;
+}
+/**
+ * A template capable of rendering child views not specifically connected to custom elements.
+ * @public
+ */
+export interface ChildViewTemplate<TSource = any, TParent = any> {
+    type: "child";
+    /**
+     * Creates a SyntheticView instance based on this template definition.
+     */
+    create(): SyntheticView<TSource, TParent, ChildContext<TParent>>;
+}
+/**
+ * A template capable of rendering item views not specifically connected to custom elements.
+ * @public
+ */
+export interface ItemViewTemplate<TSource = any, TParent = any> {
+    type: "item";
+    /**
+     * Creates a SyntheticView instance based on this template definition.
+     */
+    create(): SyntheticView<TSource, TParent, ItemContext<TParent>>;
+}
+/**
+ * The result of a template compilation operation.
+ * @public
+ */
+export interface HTMLTemplateCompilationResult<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>> {
+    /**
+     * Creates a view instance.
+     * @param hostBindingTarget - The host binding target for the view.
+     */
+    createView(hostBindingTarget?: Element): HTMLView<TSource, TParent, TContext>;
 }
 /**
  * A template capable of creating HTMLView instances or rendering directly to DOM.
  * @public
  */
-export declare class ViewTemplate<TSource = any, TParent = any> implements ElementViewTemplate, SyntheticViewTemplate {
-    private behaviorCount;
-    private hasHostBehaviors;
-    private fragment;
-    private targetOffset;
-    private viewBehaviorFactories;
-    private hostBehaviorFactories;
+export declare class ViewTemplate<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext> implements ElementViewTemplate<TSource, TParent>, SyntheticViewTemplate<TSource, TParent, TContext> {
+    private result;
+    /**
+     * Used for TypeScript purposes only.
+     * Do not use.
+     */
+    type: any;
     /**
      * The html representing what this template will
      * instantiate, including placeholders for directives.
@@ -49,18 +84,18 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
     /**
      * The directives that will be connected to placeholders in the html.
      */
-    readonly directives: ReadonlyArray<HTMLDirective>;
+    readonly factories: Record<string, ViewBehaviorFactory>;
     /**
      * Creates an instance of ViewTemplate.
      * @param html - The html representing what this template will instantiate, including placeholders for directives.
-     * @param directives - The directives that will be connected to placeholders in the html.
+     * @param factories - The directives that will be connected to placeholders in the html.
      */
-    constructor(html: string | HTMLTemplateElement, directives: ReadonlyArray<HTMLDirective>);
+    constructor(html: string | HTMLTemplateElement, factories: Record<string, ViewBehaviorFactory>);
     /**
      * Creates an HTMLView instance based on this template definition.
      * @param hostBindingTarget - The element that host behaviors will be bound to.
      */
-    create(hostBindingTarget?: Element): HTMLView;
+    create(hostBindingTarget?: Element): HTMLView<TSource, TParent, TContext>;
     /**
      * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
      * @param source - The data source to bind the template to.
@@ -68,7 +103,7 @@ export declare class ViewTemplate<TSource = any, TParent = any> implements Eleme
      * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
      * host that the template is being attached to.
      */
-    render(source: TSource, host: Node | string, hostBindingTarget?: Element): HTMLView;
+    render(source: TSource, host: Node, hostBindingTarget?: Element, context?: TContext): HTMLView<TSource, TParent, TContext>;
 }
 /**
  * A marker interface used to capture types when interpolating Directive helpers
@@ -81,9 +116,29 @@ export interface CaptureType<TSource> {
  * Represents the types of values that can be interpolated into a template.
  * @public
  */
-export declare type TemplateValue<TScope, TParent = any> = Binding<TScope, any, TParent> | string | number | HTMLDirective | CaptureType<TScope>;
+export declare type TemplateValue<TSource, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>> = Binding<TSource, any, TContext> | HTMLDirective | CaptureType<TSource>;
+/**
+ * Transforms a template literal string into a ViewTemplate.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The html helper supports interpolation of strings, numbers, binding expressions,
+ * other template instances, and Directive instances.
+ * @public
+ */
+export declare function html<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>>(strings: TemplateStringsArray, ...values: TemplateValue<TSource, TParent, TContext>[]): ViewTemplate<TSource, TParent>;
+/**
+ * Transforms a template literal string into a ChildViewTemplate.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The html helper supports interpolation of strings, numbers, binding expressions,
+ * other template instances, and Directive instances.
+ * @public
+ */
+export declare const child: <TChild = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TChild, TParent, ChildContext<TParent>>[]) => ChildViewTemplate<TChild, TParent>;
 /**
- * Transforms a template literal string into a renderable ViewTemplate.
+ * Transforms a template literal string into an ItemViewTemplate.
  * @param strings - The string fragments that are interpolated with the values.
  * @param values - The values that are interpolated with the string fragments.
  * @remarks
@@ -91,4 +146,4 @@ export declare type TemplateValue<TScope, TParent = any> = Binding<TScope, any,
  * other template instances, and Directive instances.
  * @public
  */
-export declare function html<TSource = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TSource, TParent>[]): ViewTemplate<TSource, TParent>;
+export declare const item: <TItem = any, TParent = any>(strings: TemplateStringsArray, ...values: TemplateValue<TItem, TParent, ItemContext<TParent>>[]) => ItemViewTemplate<TItem, TParent>;

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

@@ -1,39 +1,35 @@
-import type { Behavior } from "../observation/behavior.js";
-import type { ExecutionContext } from "../observation/observable.js";
+import type { Disposable } from "../interfaces.js";
+import type { ExecutionContext, RootContext } from "../observation/observable.js";
+import type { ViewBehaviorFactory, ViewBehaviorTargets } from "./html-directive.js";
 /**
  * Represents a collection of DOM nodes which can be bound to a data source.
  * @public
  */
-export interface View {
+export interface View<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>> extends Disposable {
     /**
      * The execution context the view is running within.
      */
-    readonly context: ExecutionContext | null;
+    readonly context: TContext | null;
     /**
      * The data that the view is bound to.
      */
-    readonly source: any | null;
+    readonly source: TSource | null;
     /**
      * 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 view within.
      */
-    bind(source: unknown, context: ExecutionContext): void;
+    bind(source: TSource, context: TContext): void;
     /**
      * Unbinds a view's behaviors from its binding source and context.
      */
     unbind(): void;
-    /**
-     * Removes the view and unbinds its behaviors, disposing of DOM nodes afterward.
-     * Once a view has been disposed, it cannot be inserted or bound again.
-     */
-    dispose(): void;
 }
 /**
  * A View representing DOM nodes specifically for rendering the view of a custom element.
  * @public
  */
-export interface ElementView extends View {
+export interface ElementView<TSource = any, TParent = any> extends View<TSource, TParent, RootContext> {
     /**
      * Appends the view's DOM nodes to the referenced node.
      * @param node - The parent node to append the view's DOM nodes to.
@@ -44,7 +40,7 @@ export interface ElementView extends View {
  * A view representing a range of DOM nodes which can be added/removed ad hoc.
  * @public
  */
-export interface SyntheticView extends View {
+export interface SyntheticView<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>> extends View<TSource, TParent, TContext> {
     /**
      * The first DOM node in the range of nodes that make up the view.
      */
@@ -63,27 +59,24 @@ export interface SyntheticView extends View {
      * The nodes are not disposed and the view can later be re-inserted.
      */
     remove(): void;
-    /**
-     * Removes the view and unbinds its behaviors, disposing of DOM nodes afterward.
-     * Once a view has been disposed, it cannot be inserted or bound again.
-     */
-    dispose(): void;
 }
 /**
  * The standard View implementation, which also implements ElementView and SyntheticView.
  * @public
  */
-export declare class HTMLView implements ElementView, SyntheticView {
+export declare class HTMLView<TSource = any, TParent = any, TContext extends ExecutionContext<TParent> = ExecutionContext<TParent>> implements ElementView<TSource, TParent>, SyntheticView<TSource, TParent, TContext> {
     private fragment;
+    private factories;
+    private targets;
     private behaviors;
     /**
      * The data that the view is bound to.
      */
-    source: any | null;
+    source: TSource | null;
     /**
      * The execution context the view is running within.
      */
-    context: ExecutionContext | null;
+    context: TContext | null;
     /**
      * The first DOM node in the range of nodes that make up the view.
      */
@@ -97,7 +90,7 @@ export declare class HTMLView implements ElementView, SyntheticView {
      * @param fragment - The html fragment that contains the nodes for this view.
      * @param behaviors - The behaviors to be applied to this view.
      */
-    constructor(fragment: DocumentFragment, behaviors: Behavior[]);
+    constructor(fragment: DocumentFragment, factories: ReadonlyArray<ViewBehaviorFactory>, targets: ViewBehaviorTargets);
     /**
      * Appends the view's DOM nodes to the referenced node.
      * @param node - The parent node to append the view's DOM nodes to.
@@ -123,7 +116,7 @@ export declare class HTMLView implements ElementView, SyntheticView {
      * @param source - The binding source for the view's binding behaviors.
      * @param context - The execution context to run the behaviors within.
      */
-    bind(source: unknown, context: ExecutionContext): void;
+    bind(source: TSource, context: TContext): void;
     /**
      * Unbinds a view's behaviors from its binding source.
      */

package/dist/dts/utilities.d.ts

@@ -0,0 +1,40 @@
+import { Disposable } from "./interfaces.js";
+import type { Subscriber } from "./observation/notifier.js";
+/**
+ * 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 declare function makeObservable<T>(object: T, deep?: boolean): T;
+/**
+ * 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 declare function watch(object: any, subscriber: Subscriber | ((subject: any, args: any) => void)): Disposable;
+/**
+ * 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
+ * element of the shadow root. Otherwise it will return the parent node or null if
+ * no parent node exists.
+ * @param element - The element for which to retrieve the composed parent
+ *
+ * @public
+ */
+export declare function composedParent<T extends HTMLElement>(element: T): HTMLElement | null;
+/**
+ * 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
+ * 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.
+ *
+ * @public
+ */
+export declare function composedContains(reference: HTMLElement, test: HTMLElement): boolean;

package/dist/esm/components/attributes.js

@@ -1,5 +1,9 @@
 import { Observable } from "../observation/observable.js";
-import { DOM } from "../dom.js";
+import { isString } from "../interfaces.js";
+import { Updates } from "../observation/update-queue.js";
+import { DOM } from "../templating/dom.js";
+const booleanMode = "boolean";
+const reflectMode = "reflect";
 /**
  * A {@link ValueConverter} that converts to and from `boolean` values.
  * @remarks
@@ -11,16 +15,22 @@ export const booleanConverter = {
         return value ? "true" : "false";
     },
     fromView(value) {
-        if (value === null ||
+        return value === null ||
             value === void 0 ||
             value === "false" ||
             value === false ||
-            value === 0) {
-            return false;
-        }
-        return true;
+            value === 0
+            ? false
+            : true;
     },
 };
+function toNumber(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const number = value * 1;
+    return isNaN(number) ? null : number;
+}
 /**
  * A {@link ValueConverter} that converts to and from `number` values.
  * @remarks
@@ -30,19 +40,10 @@ export const booleanConverter = {
  */
 export const nullableNumberConverter = {
     toView(value) {
-        if (value === null || value === undefined) {
-            return null;
-        }
-        const number = value * 1;
-        return isNaN(number) ? null : number.toString();
-    },
-    fromView(value) {
-        if (value === null || value === undefined) {
-            return null;
-        }
-        const number = value * 1;
-        return isNaN(number) ? null : number;
+        const output = toNumber(value);
+        return output ? output.toString() : output;
     },
+    fromView: toNumber,
 };
 /**
  * An implementation of {@link Accessor} that supports reactivity,
@@ -60,7 +61,7 @@ export class AttributeDefinition {
      * @param converter - A {@link ValueConverter} that integrates with the property getter/setter
      * to convert values to and from a DOM string.
      */
-    constructor(Owner, name, attribute = name.toLowerCase(), mode = "reflect", converter) {
+    constructor(Owner, name, attribute = name.toLowerCase(), mode = reflectMode, converter) {
         this.guards = new Set();
         this.Owner = Owner;
         this.name = name;
@@ -70,7 +71,7 @@ export class AttributeDefinition {
         this.fieldName = `_${name}`;
         this.callbackName = `${name}Changed`;
         this.hasCallback = this.callbackName in Owner.prototype;
-        if (mode === "boolean" && converter === void 0) {
+        if (mode === booleanMode && converter === void 0) {
             this.converter = booleanConverter;
         }
     }
@@ -117,15 +118,15 @@ export class AttributeDefinition {
         if (guards.has(element) || mode === "fromView") {
             return;
         }
-        DOM.queueUpdate(() => {
+        Updates.enqueue(() => {
             guards.add(element);
             const latestValue = element[this.fieldName];
             switch (mode) {
-                case "reflect":
+                case reflectMode:
                     const converter = this.converter;
                     DOM.setAttribute(element, this.attribute, converter !== void 0 ? converter.toView(latestValue) : latestValue);
                     break;
-                case "boolean":
+                case booleanMode:
                     DOM.setBooleanAttribute(element, this.attribute, latestValue);
                     break;
             }
@@ -148,7 +149,7 @@ export class AttributeDefinition {
             }
             for (let j = 0, jj = list.length; j < jj; ++j) {
                 const config = list[j];
-                if (typeof config === "string") {
+                if (isString(config)) {
                     attributes.push(new AttributeDefinition(Owner, config));
                 }
                 else {