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

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

@@ -1,39 +1,34 @@
-import type { Behavior } from "../observation/behavior.js";
-import type { ExecutionContext } from "../observation/observable.js";
+import type { Disposable } from "../interfaces.js";
+import { ExecutionContext, SourceLifetime } from "../observation/observable.js";
+import type { ViewBehaviorFactory, ViewBehaviorTargets, ViewController } 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>;
     /**
      * 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 +39,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 +58,86 @@ 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>, ExecutionContext<TParent> {
     private fragment;
+    private factories;
+    readonly targets: ViewBehaviorTargets;
     private behaviors;
+    private unbindables;
     /**
      * The data that the view is bound to.
      */
-    source: any | null;
+    source: TSource | null;
+    /**
+     * Indicates whether the controller is bound.
+     */
+    isBound: boolean;
+    /**
+     * Indicates how the source's lifetime relates to the controller's lifetime.
+     */
+    readonly sourceLifetime: SourceLifetime;
     /**
      * The execution context the view is running within.
      */
-    context: ExecutionContext | null;
+    context: ExecutionContext<TParent>;
+    /**
+     * The index of the current item within a repeat context.
+     */
+    index: number;
+    /**
+     * The length of the current collection within a repeat context.
+     */
+    length: number;
+    /**
+     * The parent data source within a nested context.
+     */
+    readonly parent: TParent;
+    /**
+     * The parent execution context when in nested context scenarios.
+     */
+    readonly parentContext: ExecutionContext<TParent>;
+    /**
+     * The current event within an event handler.
+     */
+    get event(): Event;
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an even index.
+     */
+    get isEven(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an odd index.
+     */
+    get isOdd(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the first item in the collection.
+     */
+    get isFirst(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is somewhere in the middle of the collection.
+     */
+    get isInMiddle(): boolean;
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the last item in the collection.
+     */
+    get isLast(): boolean;
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail<TDetail>(): TDetail;
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget<TTarget extends EventTarget>(): TTarget;
     /**
      * The first DOM node in the range of nodes that make up the view.
      */
@@ -97,7 +151,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.
@@ -118,16 +172,20 @@ export declare class HTMLView implements ElementView, SyntheticView {
      * Once a view has been disposed, it cannot be inserted or bound again.
      */
     dispose(): void;
+    onUnbind(behavior: {
+        unbind(controller: ViewController<TSource, TParent>): any;
+    }): void;
     /**
      * 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 behaviors within.
      */
-    bind(source: unknown, context: ExecutionContext): void;
+    bind(source: TSource, context?: ExecutionContext<TParent>): void;
     /**
      * Unbinds a view's behaviors from its binding source.
      */
     unbind(): void;
+    private evaluateUnbindables;
     /**
      * Efficiently disposes of a contiguous range of synthetic view instances.
      * @param views - A contiguous range of views to be disposed.

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

@@ -1,10 +1,10 @@
-import type { Binding } from "../observation/observable.js";
+import type { Expression } from "../observation/observable.js";
 import type { CaptureType, SyntheticViewTemplate } from "./template.js";
 /**
  * A directive that enables basic conditional rendering in a template.
- * @param binding - The condition to test for rendering.
+ * @param condition - The condition to test for rendering.
  * @param templateOrTemplateBinding - The template or a binding that gets
  * the template to render when the condition is true.
  * @public
  */
-export declare function when<TSource = any, TReturn = any>(binding: Binding<TSource, TReturn>, templateOrTemplateBinding: SyntheticViewTemplate | Binding<TSource, SyntheticViewTemplate>): CaptureType<TSource>;
+export declare function when<TSource = any, TReturn = any, TParent = any>(condition: Expression<TSource, TReturn, TParent> | boolean, templateOrTemplateBinding: SyntheticViewTemplate<TSource, TParent> | Expression<TSource, SyntheticViewTemplate<TSource, TParent>, TParent>): CaptureType<TSource, TParent>;

package/dist/dts/testing/exports.d.ts

@@ -0,0 +1,3 @@
+export { timeout } from "./timeout.js";
+export * from "./fixture.js";
+export * from "./fakes.js";

package/dist/dts/testing/fakes.d.ts

@@ -0,0 +1,4 @@
+import { ExecutionContext } from "../index.js";
+export declare const Fake: Readonly<{
+    executionContext<TParent = any>(parent?: TParent | undefined, parentContext?: ExecutionContext<TParent> | undefined): ExecutionContext<TParent>;
+}>;

package/dist/dts/testing/fixture.d.ts

@@ -0,0 +1,84 @@
+import type { Constructable } from "../interfaces.js";
+import { ViewTemplate } from "../templating/template.js";
+import type { HTMLView } from "../templating/view.js";
+/**
+ * Options used to customize the creation of the test fixture.
+ * @public
+ */
+export interface FixtureOptions {
+    /**
+     * The document to run the fixture in.
+     * @defaultValue `globalThis.document`
+     */
+    document?: Document;
+    /**
+     * The parent element to append the fixture to.
+     * @defaultValue An instance of `HTMLDivElement`.
+     */
+    parent?: HTMLElement;
+    /**
+     * The data source to bind the HTML to.
+     * @defaultValue An empty object.
+     */
+    source?: any;
+}
+/**
+ * A test fixture.
+ * @public
+ */
+export interface Fixture<TElement = HTMLElement> {
+    /**
+     * The document the fixture is running in.
+     */
+    document: Document;
+    /**
+     * The template the fixture was created from.
+     */
+    template: ViewTemplate;
+    /**
+     * The view that was created from the fixture's template.
+     */
+    view: HTMLView;
+    /**
+     * The parent element that the view was appended to.
+     * @remarks
+     * This element will be appended to the DOM only
+     * after {@link Fixture.connect} has been called.
+     */
+    parent: HTMLElement;
+    /**
+     * The first element in the {@link Fixture.view}.
+     */
+    element: TElement;
+    /**
+     * Adds the {@link Fixture.parent} to the DOM, causing the
+     * connect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    connect: () => Promise<void>;
+    /**
+     * Removes the {@link Fixture.parent} from the DOM, causing the
+     * disconnect lifecycle to begin.
+     * @remarks
+     * Yields control to the caller one Microtask later, in order to
+     * ensure that the DOM has settled.
+     */
+    disconnect: () => Promise<void>;
+}
+/**
+ * Creates a random, unique name suitable for use as a Custom Element name.
+ * @public
+ */
+export declare function uniqueElementName(prefix?: string): string;
+/**
+ * Creates a test fixture suitable for testing custom elements, templates, and bindings.
+ * @param templateNameOrType An HTML template or single element name to create the fixture for.
+ * @param options Enables customizing fixture creation behavior.
+ * @remarks
+ * Yields control to the caller one Microtask later, in order to
+ * ensure that the DOM has settled.
+ * @public
+ */
+export declare function fixture<TElement = HTMLElement>(templateNameOrType: ViewTemplate | string | Constructable<TElement>, options?: FixtureOptions): Promise<Fixture<TElement>>;

package/dist/dts/testing/timeout.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A timeout helper for use in tests.
+ * @param timeout The length of the timeout.
+ * @returns A promise that resolves once the configured time has elapsed.
+ * @public
+ */
+export declare function timeout(timeout?: number): Promise<void>;

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,22 @@
+/**
+ * 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,20 @@
 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";
+import { createMetadataLocator } from "../platform.js";
+const booleanMode = "boolean";
+const reflectMode = "reflect";
+/**
+ * Metadata used to configure a custom attribute's behavior.
+ * @public
+ */
+export const AttributeConfiguration = Object.freeze({
+    /**
+     * Locates all attribute configurations associated with a type.
+     */
+    locate: createMetadataLocator(),
+});
 /**
  * A {@link ValueConverter} that converts to and from `boolean` values.
  * @remarks
@@ -11,16 +26,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 +51,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 +72,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 +82,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 +129,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;
             }
@@ -140,7 +152,7 @@ export class AttributeDefinition {
      */
     static collect(Owner, ...attributeLists) {
         const attributes = [];
-        attributeLists.push(Owner.attributes);
+        attributeLists.push(AttributeConfiguration.locate(Owner));
         for (let i = 0, ii = attributeLists.length; i < ii; ++i) {
             const list = attributeLists[i];
             if (list === void 0) {
@@ -148,7 +160,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 {
@@ -170,9 +182,7 @@ export function attr(configOrTarget, prop) {
             // - @attr({...opts})
             config.property = $prop;
         }
-        const attributes = $target.constructor.attributes ||
-            ($target.constructor.attributes = []);
-        attributes.push(config);
+        AttributeConfiguration.locate($target.constructor).push(config);
     }
     if (arguments.length > 1) {
         // Non invocation: