@microsoft/fast-element 1.10.2 → 2.0.0-beta.3

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

@@ -1,9 +1,9 @@
-import { Binding, ExecutionContext } from "../observation/observable.js";
-import type { Subscriber } from "../observation/notifier.js";
-import type { Splice } from "../observation/array-change-records.js";
 import type { Behavior } from "../observation/behavior.js";
-import { HTMLDirective } from "./html-directive.js";
-import type { CaptureType, SyntheticViewTemplate } from "./template.js";
+import type { Subscriber } from "../observation/notifier.js";
+import { Binding, ExecutionContext } from "../observation/observable.js";
+import { Splice } from "../observation/arrays.js";
+import { AddViewBehaviorFactory, HTMLDirective, ViewBehaviorFactory, ViewBehaviorTargets } from "./html-directive.js";
+import type { CaptureType, SyntheticViewTemplate, ViewTemplate } from "./template.js";
 /**
  * Options for configuring repeat behavior.
  * @public
@@ -34,7 +34,7 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
     private items;
     private itemsObserver;
     private itemsBindingObserver;
-    private originalContext;
+    private context;
     private childContext;
     private bindView;
     /**
@@ -58,7 +58,11 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
      * @param source - The source to unbind from.
      */
     unbind(): void;
-    /** @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: any, args: Splice[]): void;
     private observeItems;
     private updateViews;
@@ -69,17 +73,25 @@ export declare class RepeatBehavior<TSource = any> implements Behavior, Subscrib
  * A directive that configures list rendering.
  * @public
  */
-export declare class RepeatDirective<TSource = any> extends HTMLDirective {
-    private itemsBinding;
-    private templateBinding;
-    private options;
+export declare class RepeatDirective<TSource = any> implements HTMLDirective, ViewBehaviorFactory {
+    readonly itemsBinding: Binding;
+    readonly templateBinding: Binding<TSource, SyntheticViewTemplate>;
+    readonly options: RepeatOptions;
     private isItemsBindingVolatile;
     private isTemplateBindingVolatile;
+    /**
+     * The unique id of the factory.
+     */
+    id: string;
+    /**
+     * The structural id of the DOM node to which the created behavior will apply.
+     */
+    nodeId: string;
     /**
      * Creates a placeholder string based on the directive's index within the template.
      * @param index - The index of the directive within the template.
      */
-    createPlaceholder: (index: number) => string;
+    createHTML(add: AddViewBehaviorFactory): string;
     /**
      * Creates an instance of RepeatDirective.
      * @param itemsBinding - The binding that provides the array to render.
@@ -91,7 +103,7 @@ export declare class RepeatDirective<TSource = any> extends HTMLDirective {
      * Creates a behavior for the provided target node.
      * @param target - The node instance to create the behavior for.
      */
-    createBehavior(target: Node): RepeatBehavior<TSource>;
+    createBehavior(targets: ViewBehaviorTargets): RepeatBehavior<TSource>;
 }
 /**
  * A directive that enables list rendering.
@@ -101,4 +113,4 @@ export declare class RepeatDirective<TSource = any> extends HTMLDirective {
  * @param options - Options used to turn on special repeat features.
  * @public
  */
-export declare function repeat<TSource = any, TItem = any>(itemsBinding: Binding<TSource, readonly TItem[]>, templateOrTemplateBinding: SyntheticViewTemplate | Binding<TSource, SyntheticViewTemplate>, options?: RepeatOptions): CaptureType<TSource>;
+export declare function repeat<TSource = any, TArray extends ReadonlyArray<any> = ReadonlyArray<any>>(itemsBinding: Binding<TSource, TArray, ExecutionContext<TSource>>, templateOrTemplateBinding: ViewTemplate | Binding<TSource, ViewTemplate>, options?: RepeatOptions): CaptureType<TSource>;

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

@@ -1,34 +1,33 @@
-import { NodeBehaviorOptions, NodeObservationBehavior } from "./node-observation.js";
+import { NodeBehaviorOptions, NodeObservationDirective } from "./node-observation.js";
 import type { CaptureType } from "./template.js";
 /**
  * The options used to configure slotted node observation.
  * @public
  */
-export interface SlottedBehaviorOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
+export interface SlottedDirectiveOptions<T = any> extends NodeBehaviorOptions<T>, AssignedNodesOptions {
 }
 /**
  * The runtime behavior for slotted node observation.
  * @public
  */
-export declare class SlottedBehavior extends NodeObservationBehavior<SlottedBehaviorOptions> {
-    /**
-     * 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: HTMLSlotElement, options: SlottedBehaviorOptions);
+export declare class SlottedDirective extends NodeObservationDirective<SlottedDirectiveOptions> {
     /**
      * Begins observation of the nodes.
+     * @param target - The target to observe.
      */
-    observe(): void;
+    observe(target: EventSource): void;
     /**
      * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
      */
-    disconnect(): void;
+    disconnect(target: EventSource): void;
     /**
-     * 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.
      */
-    protected getNodes(): Node[];
+    getNodes(target: HTMLSlotElement): Node[];
+    /** @internal */
+    handleEvent(event: Event): void;
 }
 /**
  * A directive that observes the `assignedNodes()` of a slot and updates a property
@@ -36,4 +35,4 @@ export declare class SlottedBehavior extends NodeObservationBehavior<SlottedBeha
  * @param propertyOrOptions - The options used to configure slotted node observation.
  * @public
  */
-export declare function slotted<T = any>(propertyOrOptions: (keyof T & string) | SlottedBehaviorOptions<keyof T & string>): CaptureType<T>;
+export declare function slotted<T = any>(propertyOrOptions: (keyof T & string) | SlottedDirectiveOptions<keyof T & string>): CaptureType<T>;

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

@@ -1,16 +1,16 @@
-import { Binding } from "../observation/observable.js";
-import { ElementView, HTMLView, SyntheticView } from "./view.js";
-import { HTMLDirective } from "./html-directive.js";
+import { Binding, ExecutionContext } 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> {
     /**
      * 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,7 +18,7 @@ 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.
@@ -28,19 +28,25 @@ export interface SyntheticViewTemplate<TSource = any, TParent = any> {
     /**
      * Creates a SyntheticView instance based on this template definition.
      */
-    create(): SyntheticView;
+    create(): SyntheticView<TSource, TParent>;
+}
+/**
+ * The result of a template compilation operation.
+ * @public
+ */
+export interface HTMLTemplateCompilationResult<TSource = any, TParent = any> {
+    /**
+     * Creates a view instance.
+     * @param hostBindingTarget - The host binding target for the view.
+     */
+    createView(hostBindingTarget?: Element): HTMLView<TSource, TParent>;
 }
 /**
  * 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> implements ElementViewTemplate<TSource, TParent>, SyntheticViewTemplate<TSource, TParent> {
+    private result;
     /**
      * The html representing what this template will
      * instantiate, including placeholders for directives.
@@ -49,18 +55,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>;
     /**
      * 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 +74,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?: ExecutionContext): HTMLView<TSource, TParent>;
 }
 /**
  * A marker interface used to capture types when interpolating Directive helpers
@@ -81,9 +87,9 @@ 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> = Binding<TSource, any, TParent> | HTMLDirective | CaptureType<TSource>;
 /**
- * Transforms a template literal string into a renderable ViewTemplate.
+ * 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

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

@@ -1,39 +1,35 @@
-import type { Behavior } from "../observation/behavior.js";
+import type { Disposable } from "../interfaces.js";
 import type { ExecutionContext } 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> extends Disposable {
     /**
      * The execution context the view is running within.
      */
-    readonly context: ExecutionContext | null;
+    readonly context: ExecutionContext<TParent> | 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: ExecutionContext<TParent>): 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> {
     /**
      * 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> extends View<TSource, TParent> {
     /**
      * 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> implements ElementView<TSource, TParent>, SyntheticView<TSource, TParent> {
     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: ExecutionContext<TParent> | 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: ExecutionContext<TParent>): void;
     /**
      * Unbinds a view's behaviors from its binding source.
      */

package/dist/{tsdoc-metadata.json → dts/tsdoc-metadata.json}

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.23.1"
+      "packageVersion": "7.24.2"
     }
   ]
 }

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 {