@fluentui/web-components 3.0.0-rc.18 → 3.0.0-rc.19

package/dist/web-components.js

@@ -65,6 +65,44 @@ switch (kernelMode) {
         });
         break;
 }
+/**
+ * Warning and error messages.
+ * @internal
+ */
+var Message;
+(function (Message) {
+    // 1000 - 1100 Kernel
+    // 1101 - 1200 Observation
+    Message[Message["needsArrayObservation"] = 1101] = "needsArrayObservation";
+    // 1201 - 1300 Templating
+    Message[Message["onlySetDOMPolicyOnce"] = 1201] = "onlySetDOMPolicyOnce";
+    Message[Message["bindingInnerHTMLRequiresTrustedTypes"] = 1202] = "bindingInnerHTMLRequiresTrustedTypes";
+    Message[Message["twoWayBindingRequiresObservables"] = 1203] = "twoWayBindingRequiresObservables";
+    Message[Message["hostBindingWithoutHost"] = 1204] = "hostBindingWithoutHost";
+    Message[Message["unsupportedBindingBehavior"] = 1205] = "unsupportedBindingBehavior";
+    Message[Message["directCallToHTMLTagNotAllowed"] = 1206] = "directCallToHTMLTagNotAllowed";
+    Message[Message["onlySetTemplatePolicyOnce"] = 1207] = "onlySetTemplatePolicyOnce";
+    Message[Message["cannotSetTemplatePolicyAfterCompilation"] = 1208] = "cannotSetTemplatePolicyAfterCompilation";
+    Message[Message["blockedByDOMPolicy"] = 1209] = "blockedByDOMPolicy";
+    // 1301 - 1400 Styles
+    // 1401 - 1500 Components
+    Message[Message["missingElementDefinition"] = 1401] = "missingElementDefinition";
+    // 1501 - 1600 Context and Dependency Injection
+    Message[Message["noRegistrationForContext"] = 1501] = "noRegistrationForContext";
+    Message[Message["noFactoryForResolver"] = 1502] = "noFactoryForResolver";
+    Message[Message["invalidResolverStrategy"] = 1503] = "invalidResolverStrategy";
+    Message[Message["cannotAutoregisterDependency"] = 1504] = "cannotAutoregisterDependency";
+    Message[Message["cannotResolveKey"] = 1505] = "cannotResolveKey";
+    Message[Message["cannotConstructNativeFunction"] = 1506] = "cannotConstructNativeFunction";
+    Message[Message["cannotJITRegisterNonConstructor"] = 1507] = "cannotJITRegisterNonConstructor";
+    Message[Message["cannotJITRegisterIntrinsic"] = 1508] = "cannotJITRegisterIntrinsic";
+    Message[Message["cannotJITRegisterInterface"] = 1509] = "cannotJITRegisterInterface";
+    Message[Message["invalidResolver"] = 1510] = "invalidResolver";
+    Message[Message["invalidKey"] = 1511] = "invalidKey";
+    Message[Message["noDefaultResolver"] = 1512] = "noDefaultResolver";
+    Message[Message["cyclicDependency"] = 1513] = "cyclicDependency";
+    Message[Message["connectUpdateRequiresController"] = 1514] = "connectUpdateRequiresController";
+})(Message || (Message = {}));
 /**
  * Determines whether or not an object is a function.
  * @public
@@ -110,6 +148,39 @@ var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof win
         result.globalThis = result;
     }
 })();
+(function requestIdleCallbackPolyfill() {
+    if ("requestIdleCallback" in globalThis) {
+        return;
+    }
+    /**
+     * A polyfill for requestIdleCallback that falls back to setTimeout.
+     *
+     * @param callback - The function to call when the browser is idle.
+     * @param options - Options object that may contain a timeout property.
+     * @returns An ID that can be used to cancel the callback.
+     * @public
+     */
+    globalThis.requestIdleCallback = function requestIdleCallback(callback, options) {
+        const start = Date.now();
+        return setTimeout(() => {
+            callback({
+                didTimeout: (options === null || options === void 0 ? void 0 : options.timeout)
+                    ? Date.now() - start >= options.timeout
+                    : false,
+                timeRemaining: () => 0,
+            });
+        }, 1);
+    };
+    /**
+     * A polyfill for cancelIdleCallback that falls back to clearTimeout.
+     *
+     * @param id - The ID of the callback to cancel.
+     * @public
+     */
+    globalThis.cancelIdleCallback = function cancelIdleCallback(id) {
+        clearTimeout(id);
+    };
+})();
 
 // ensure FAST global - duplicated debug.ts
 const propConfig = {
@@ -274,7 +345,7 @@ const DOM = Object.freeze({
      */
     setPolicy(value) {
         if (defaultPolicy !== fastPolicy) {
-            throw FAST.error(1201 /* Message.onlySetDOMPolicyOnce */);
+            throw FAST.error(Message.onlySetDOMPolicyOnce);
         }
         defaultPolicy = value;
     },
@@ -307,72 +378,6 @@ const DOM = Object.freeze({
     },
 });
 
-/**
- * The default UpdateQueue.
- * @public
- */
-const Updates = FAST.getById(KernelServiceId.updateQueue, () => {
-    const tasks = [];
-    const pendingErrors = [];
-    const rAF = globalThis.requestAnimationFrame;
-    let updateAsync = true;
-    function throwFirstError() {
-        if (pendingErrors.length) {
-            throw pendingErrors.shift();
-        }
-    }
-    function tryRunTask(task) {
-        try {
-            task.call();
-        }
-        catch (error) {
-            if (updateAsync) {
-                pendingErrors.push(error);
-                setTimeout(throwFirstError, 0);
-            }
-            else {
-                tasks.length = 0;
-                throw error;
-            }
-        }
-    }
-    function process() {
-        const capacity = 1024;
-        let index = 0;
-        while (index < tasks.length) {
-            tryRunTask(tasks[index]);
-            index++;
-            // Prevent leaking memory for long chains of recursive calls to `enqueue`.
-            // If we call `enqueue` within a task scheduled by `enqueue`, the queue will
-            // grow, but to avoid an O(n) walk for every task we execute, we don't
-            // shift tasks off the queue after they have been executed.
-            // Instead, we periodically shift 1024 tasks off the queue.
-            if (index > capacity) {
-                // Manually shift all values starting at the index back to the
-                // beginning of the queue.
-                for (let scan = 0, newLength = tasks.length - index; scan < newLength; scan++) {
-                    tasks[scan] = tasks[scan + index];
-                }
-                tasks.length -= index;
-                index = 0;
-            }
-        }
-        tasks.length = 0;
-    }
-    function enqueue(callable) {
-        tasks.push(callable);
-        if (tasks.length < 2) {
-            updateAsync ? rAF(process) : process();
-        }
-    }
-    return Object.freeze({
-        enqueue,
-        next: () => new Promise(enqueue),
-        process,
-        setMode: (isAsync) => (updateAsync = isAsync),
-    });
-});
-
 /**
  * An implementation of {@link Notifier} that efficiently keeps track of
  * subscribers interested in a specific change notification on an
@@ -538,6 +543,72 @@ class PropertyChangeNotifier {
     }
 }
 
+/**
+ * The default UpdateQueue.
+ * @public
+ */
+const Updates = FAST.getById(KernelServiceId.updateQueue, () => {
+    const tasks = [];
+    const pendingErrors = [];
+    const rAF = globalThis.requestAnimationFrame;
+    let updateAsync = true;
+    function throwFirstError() {
+        if (pendingErrors.length) {
+            throw pendingErrors.shift();
+        }
+    }
+    function tryRunTask(task) {
+        try {
+            task.call();
+        }
+        catch (error) {
+            if (updateAsync) {
+                pendingErrors.push(error);
+                setTimeout(throwFirstError, 0);
+            }
+            else {
+                tasks.length = 0;
+                throw error;
+            }
+        }
+    }
+    function process() {
+        const capacity = 1024;
+        let index = 0;
+        while (index < tasks.length) {
+            tryRunTask(tasks[index]);
+            index++;
+            // Prevent leaking memory for long chains of recursive calls to `enqueue`.
+            // If we call `enqueue` within a task scheduled by `enqueue`, the queue will
+            // grow, but to avoid an O(n) walk for every task we execute, we don't
+            // shift tasks off the queue after they have been executed.
+            // Instead, we periodically shift 1024 tasks off the queue.
+            if (index > capacity) {
+                // Manually shift all values starting at the index back to the
+                // beginning of the queue.
+                for (let scan = 0, newLength = tasks.length - index; scan < newLength; scan++) {
+                    tasks[scan] = tasks[scan + index];
+                }
+                tasks.length -= index;
+                index = 0;
+            }
+        }
+        tasks.length = 0;
+    }
+    function enqueue(callable) {
+        tasks.push(callable);
+        if (tasks.length < 2) {
+            updateAsync ? rAF(process) : process();
+        }
+    }
+    return Object.freeze({
+        enqueue,
+        next: () => new Promise(enqueue),
+        process,
+        setMode: (isAsync) => (updateAsync = isAsync),
+    });
+});
+
 /**
  * Describes how the source's lifetime relates to its controller's lifetime.
  * @public
@@ -563,7 +634,7 @@ const Observable = FAST.getById(KernelServiceId.observable, () => {
     const notifierLookup = new WeakMap();
     let watcher = void 0;
     let createArrayObserver = (array) => {
-        throw FAST.error(1101 /* Message.needsArrayObservation */);
+        throw FAST.error(Message.needsArrayObservation);
     };
     function getNotifier(source) {
         var _a;
@@ -929,97 +1000,6 @@ function oneTime(expression, policy) {
     return new OneTimeBinding(expression, policy);
 }
 
-let DefaultStyleStrategy;
-function reduceStyles(styles) {
-    return styles
-        .map((x) => x instanceof ElementStyles ? reduceStyles(x.styles) : [x])
-        .reduce((prev, curr) => prev.concat(curr), []);
-}
-/**
- * Represents styles that can be applied to a custom element.
- * @public
- */
-class ElementStyles {
-    /**
-     * Creates an instance of ElementStyles.
-     * @param styles - The styles that will be associated with elements.
-     */
-    constructor(styles) {
-        this.styles = styles;
-        this.targets = new WeakSet();
-        this._strategy = null;
-        this.behaviors = styles
-            .map((x) => x instanceof ElementStyles ? x.behaviors : null)
-            .reduce((prev, curr) => (curr === null ? prev : prev === null ? curr : prev.concat(curr)), null);
-    }
-    /**
-     * Gets the StyleStrategy associated with these element styles.
-     */
-    get strategy() {
-        if (this._strategy === null) {
-            this.withStrategy(DefaultStyleStrategy);
-        }
-        return this._strategy;
-    }
-    /** @internal */
-    addStylesTo(target) {
-        this.strategy.addStylesTo(target);
-        this.targets.add(target);
-    }
-    /** @internal */
-    removeStylesFrom(target) {
-        this.strategy.removeStylesFrom(target);
-        this.targets.delete(target);
-    }
-    /** @internal */
-    isAttachedTo(target) {
-        return this.targets.has(target);
-    }
-    /**
-     * Associates behaviors with this set of styles.
-     * @param behaviors - The behaviors to associate.
-     */
-    withBehaviors(...behaviors) {
-        this.behaviors =
-            this.behaviors === null ? behaviors : this.behaviors.concat(behaviors);
-        return this;
-    }
-    /**
-     * Sets the strategy that handles adding/removing these styles for an element.
-     * @param strategy - The strategy to use.
-     */
-    withStrategy(Strategy) {
-        this._strategy = new Strategy(reduceStyles(this.styles));
-        return this;
-    }
-    /**
-     * Sets the default strategy type to use when creating style strategies.
-     * @param Strategy - The strategy type to construct.
-     */
-    static setDefaultStrategy(Strategy) {
-        DefaultStyleStrategy = Strategy;
-    }
-    /**
-     * Normalizes a set of composable style options.
-     * @param styles - The style options to normalize.
-     * @returns A singular ElementStyles instance or undefined.
-     */
-    static normalize(styles) {
-        return styles === void 0
-            ? void 0
-            : Array.isArray(styles)
-                ? new ElementStyles(styles)
-                : styles instanceof ElementStyles
-                    ? styles
-                    : new ElementStyles([styles]);
-    }
-}
-/**
- * Indicates whether the DOM supports the adoptedStyleSheets feature.
- */
-ElementStyles.supportsAdoptedStyleSheets = Array.isArray(document.adoptedStyleSheets) &&
-    "replace" in CSSStyleSheet.prototype;
-
 const registry$1 = createTypeRegistry();
 /**
  * Instructs the css engine to provide dynamic styles or
@@ -1123,22 +1103,113 @@ class CSSBindingDirective {
 }
 CSSDirective.define(CSSBindingDirective);
 
-const marker$1 = `${Math.random().toString(36).substring(2, 8)}`;
-let varId = 0;
-const nextCSSVariable = () => `--v${marker$1}${++varId}`;
-function collectStyles(strings, values) {
-    const styles = [];
-    let cssString = "";
-    const behaviors = [];
-    const add = (behavior) => {
-        behaviors.push(behavior);
-    };
-    for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
-        cssString += strings[i];
-        let value = values[i];
-        if (isFunction(value)) {
-            value = new CSSBindingDirective(oneWay(value), nextCSSVariable()).createCSS(add);
-        }
+let DefaultStyleStrategy;
+function reduceStyles(styles) {
+    return styles
+        .map((x) => x instanceof ElementStyles ? reduceStyles(x.styles) : [x])
+        .reduce((prev, curr) => prev.concat(curr), []);
+}
+/**
+ * Represents styles that can be applied to a custom element.
+ * @public
+ */
+class ElementStyles {
+    /**
+     * Gets the StyleStrategy associated with these element styles.
+     */
+    get strategy() {
+        if (this._strategy === null) {
+            this.withStrategy(DefaultStyleStrategy);
+        }
+        return this._strategy;
+    }
+    /**
+     * Creates an instance of ElementStyles.
+     * @param styles - The styles that will be associated with elements.
+     */
+    constructor(styles) {
+        this.styles = styles;
+        this.targets = new WeakSet();
+        this._strategy = null;
+        this.behaviors = styles
+            .map((x) => x instanceof ElementStyles ? x.behaviors : null)
+            .reduce((prev, curr) => (curr === null ? prev : prev === null ? curr : prev.concat(curr)), null);
+    }
+    /** @internal */
+    addStylesTo(target) {
+        this.strategy.addStylesTo(target);
+        this.targets.add(target);
+    }
+    /** @internal */
+    removeStylesFrom(target) {
+        this.strategy.removeStylesFrom(target);
+        this.targets.delete(target);
+    }
+    /** @internal */
+    isAttachedTo(target) {
+        return this.targets.has(target);
+    }
+    /**
+     * Associates behaviors with this set of styles.
+     * @param behaviors - The behaviors to associate.
+     */
+    withBehaviors(...behaviors) {
+        this.behaviors =
+            this.behaviors === null ? behaviors : this.behaviors.concat(behaviors);
+        return this;
+    }
+    /**
+     * Sets the strategy that handles adding/removing these styles for an element.
+     * @param strategy - The strategy to use.
+     */
+    withStrategy(Strategy) {
+        this._strategy = new Strategy(reduceStyles(this.styles));
+        return this;
+    }
+    /**
+     * Sets the default strategy type to use when creating style strategies.
+     * @param Strategy - The strategy type to construct.
+     */
+    static setDefaultStrategy(Strategy) {
+        DefaultStyleStrategy = Strategy;
+    }
+    /**
+     * Normalizes a set of composable style options.
+     * @param styles - The style options to normalize.
+     * @returns A singular ElementStyles instance or undefined.
+     */
+    static normalize(styles) {
+        return styles === void 0
+            ? void 0
+            : Array.isArray(styles)
+                ? new ElementStyles(styles)
+                : styles instanceof ElementStyles
+                    ? styles
+                    : new ElementStyles([styles]);
+    }
+}
+/**
+ * Indicates whether the DOM supports the adoptedStyleSheets feature.
+ */
+ElementStyles.supportsAdoptedStyleSheets = Array.isArray(document.adoptedStyleSheets) &&
+    "replace" in CSSStyleSheet.prototype;
+
+const marker$1 = `${Math.random().toString(36).substring(2, 8)}`;
+let varId = 0;
+const nextCSSVariable = () => `--v${marker$1}${++varId}`;
+function collectStyles(strings, values) {
+    const styles = [];
+    let cssString = "";
+    const behaviors = [];
+    const add = (behavior) => {
+        behaviors.push(behavior);
+    };
+    for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
+        cssString += strings[i];
+        let value = values[i];
+        if (isFunction(value)) {
+            value = new CSSBindingDirective(oneWay(value), nextCSSVariable()).createCSS(add);
+        }
         else if (value instanceof Binding) {
             value = new CSSBindingDirective(value, nextCSSVariable()).createCSS(add);
         }
@@ -1215,111 +1286,12 @@ css.partial = (strings, ...values) => {
     return new CSSPartial(styles, behaviors);
 };
 
-const bindingStartMarker = /fe-b\$\$start\$\$(\d+)\$\$(.+)\$\$fe-b/;
-const bindingEndMarker = /fe-b\$\$end\$\$(\d+)\$\$(.+)\$\$fe-b/;
-const repeatViewStartMarker = /fe-repeat\$\$start\$\$(\d+)\$\$fe-repeat/;
-const repeatViewEndMarker = /fe-repeat\$\$end\$\$(\d+)\$\$fe-repeat/;
-const elementBoundaryStartMarker = /^(?:.{0,1000})fe-eb\$\$start\$\$(.+?)\$\$fe-eb/;
-const elementBoundaryEndMarker = /fe-eb\$\$end\$\$(.{0,1000})\$\$fe-eb(?:.{0,1000})$/;
-function isComment$1(node) {
-    return node && node.nodeType === Node.COMMENT_NODE;
-}
-/**
- * Markup utilities to aid in template hydration.
- * @internal
- */
-const HydrationMarkup = Object.freeze({
-    attributeMarkerName: "data-fe-b",
-    attributeBindingSeparator: " ",
-    contentBindingStartMarker(index, uniqueId) {
-        return `fe-b$$start$$${index}$$${uniqueId}$$fe-b`;
-    },
-    contentBindingEndMarker(index, uniqueId) {
-        return `fe-b$$end$$${index}$$${uniqueId}$$fe-b`;
-    },
-    repeatStartMarker(index) {
-        return `fe-repeat$$start$$${index}$$fe-repeat`;
-    },
-    repeatEndMarker(index) {
-        return `fe-repeat$$end$$${index}$$fe-repeat`;
-    },
-    isContentBindingStartMarker(content) {
-        return bindingStartMarker.test(content);
-    },
-    isContentBindingEndMarker(content) {
-        return bindingEndMarker.test(content);
-    },
-    isRepeatViewStartMarker(content) {
-        return repeatViewStartMarker.test(content);
-    },
-    isRepeatViewEndMarker(content) {
-        return repeatViewEndMarker.test(content);
-    },
-    isElementBoundaryStartMarker(node) {
-        return isComment$1(node) && elementBoundaryStartMarker.test(node.data.trim());
-    },
-    isElementBoundaryEndMarker(node) {
-        return isComment$1(node) && elementBoundaryEndMarker.test(node.data);
-    },
-    /**
-     * Returns the indexes of the ViewBehaviorFactories affecting
-     * attributes for the element, or null if no factories were found.
-     */
-    parseAttributeBinding(node) {
-        const attr = node.getAttribute(this.attributeMarkerName);
-        return attr === null
-            ? attr
-            : attr.split(this.attributeBindingSeparator).map(i => parseInt(i));
-    },
-    /**
-     * Parses the ViewBehaviorFactory index from string data. Returns
-     * the binding index or null if the index cannot be retrieved.
-     */
-    parseContentBindingStartMarker(content) {
-        return parseIndexAndIdMarker(bindingStartMarker, content);
-    },
-    parseContentBindingEndMarker(content) {
-        return parseIndexAndIdMarker(bindingEndMarker, content);
-    },
-    /**
-     * Parses the index of a repeat directive from a content string.
-     */
-    parseRepeatStartMarker(content) {
-        return parseIntMarker(repeatViewStartMarker, content);
-    },
-    parseRepeatEndMarker(content) {
-        return parseIntMarker(repeatViewEndMarker, content);
-    },
-    /**
-     * Parses element Id from element boundary markers
-     */
-    parseElementBoundaryStartMarker(content) {
-        return parseStringMarker(elementBoundaryStartMarker, content.trim());
-    },
-    parseElementBoundaryEndMarker(content) {
-        return parseStringMarker(elementBoundaryEndMarker, content);
-    },
-});
-function parseIntMarker(regex, content) {
-    const match = regex.exec(content);
-    return match === null ? match : parseInt(match[1]);
-}
-function parseStringMarker(regex, content) {
-    const match = regex.exec(content);
-    return match === null ? match : match[1];
-}
-function parseIndexAndIdMarker(regex, content) {
-    const match = regex.exec(content);
-    return match === null ? match : [parseInt(match[1]), match[2]];
-}
 /**
- * @internal
+ * A unique per-session random marker string used to create placeholder tokens in HTML.
+ * Bindings embedded in template literals are replaced with interpolation markers
+ * of the form `fast-xxxxxx{id}fast-xxxxxx` so the compiler can later locate them in the
+ * parsed DOM and associate each marker with its ViewBehaviorFactory.
  */
-const Hydratable = Symbol.for("fe-hydration");
-function isHydratable(value) {
-    return value[Hydratable] === Hydratable;
-}
-
 const marker = `fast-${Math.random().toString(36).substring(2, 8)}`;
 const interpolationStart = `${marker}{`;
 const interpolationEnd = `}${marker}`;
@@ -1371,6 +1343,8 @@ const Parser = Object.freeze({
      * directives or null if no directives are found in the string.
      */
     parse(value, factories) {
+        // Split on the interpolation start marker. If there's only one part,
+        // no placeholders exist and we return null to signal "no directives here."
         const parts = value.split(interpolationStart);
         if (parts.length === 1) {
             return null;
@@ -1424,7 +1398,13 @@ const HTMLDirective = Object.freeze({
         return type;
     },
     /**
-     *
+     * Determines the DOM aspect type for a directive based on attribute name prefix.
+     * The prefix convention maps to aspect types as follows:
+     *   - No prefix (e.g. "class")  → DOMAspect.attribute
+     *   - ":" prefix (e.g. ":value") → DOMAspect.property (":classList" → DOMAspect.tokenList)
+     *   - "?" prefix (e.g. "?disabled") → DOMAspect.booleanAttribute
+     *   - `@` prefix (e.g. `@click`) → DOMAspect.event
+     *   - Falsy or absent value → DOMAspect.content (see remarks)
      * @param directive - The directive to assign the aspect to.
      * @param value - The value to base the aspect determination on.
      * @remarks
@@ -1490,21 +1470,294 @@ class StatelessAttachedAttributeDirective {
 }
 makeSerializationNoop(StatelessAttachedAttributeDirective);
 
-class HydrationTargetElementError extends Error {
-    constructor(
+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
+ */
+const elements = (selector) => selector
+    ? value => value.nodeType === 1 && value.matches(selector)
+    : selectElements;
+/**
+ * A base class for node observation.
+ * @public
+ * @remarks
+ * Internally used by the SlottedDirective and the ChildrenDirective.
+ */
+class NodeObservationDirective extends StatelessAttachedAttributeDirective {
     /**
-     * The error message
+     * The unique id of the factory.
      */
-    message, 
+    get id() {
+        return this._id;
+    }
+    set id(value) {
+        this._id = value;
+        this._controllerProperty = `${value}-c`;
+    }
     /**
-     * The Compiled View Behavior Factories that belong to the view.
+     * 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.
      */
-    factories, 
+    bind(controller) {
+        const target = controller.targets[this.targetNodeId];
+        target[this._controllerProperty] = controller;
+        this.updateTarget(controller.source, this.computeNodes(target));
+        this.observe(target);
+        controller.onUnbind(this);
+    }
     /**
-     * The node to target factory.
-     */
-    node) {
-        super(message);
+     * 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(controller) {
+        const target = controller.targets[this.targetNodeId];
+        this.updateTarget(controller.source, emptyArray);
+        this.disconnect(target);
+        target[this._controllerProperty] = null;
+    }
+    /**
+     * Gets the data source for the target.
+     * @param target - The target to get the source for.
+     * @returns The source.
+     */
+    getSource(target) {
+        return target[this._controllerProperty].source;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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;
+    }
+}
+
+/**
+ * Regex patterns for parsing hydration markers embedded as HTML comments by the SSR renderer.
+ * Each marker type encodes factory indices so the client can map markers back to ViewBehaviorFactories.
+ *
+ * Content binding markers bracket text/template content:
+ *   <!-- fe-b$$start$$<factoryIndex>$$<uniqueId>$$fe-b -->
+ *   ...content...
+ *   <!-- fe-b$$end$$<factoryIndex>$$<uniqueId>$$fe-b -->
+ *
+ * Repeat markers bracket each repeated item:
+ *   <!-- fe-repeat$$start$$<itemIndex>$$fe-repeat -->
+ *   <!-- fe-repeat$$end$$<itemIndex>$$fe-repeat -->
+ *
+ * Element boundary markers demarcate nested custom elements so parent walkers can skip them:
+ *   <!-- fe-eb$$start$$<elementId>$$fe-eb -->
+ *   <!-- fe-eb$$end$$<elementId>$$fe-eb -->
+ */
+const bindingStartMarker = /fe-b\$\$start\$\$(\d+)\$\$(.+)\$\$fe-b/;
+const bindingEndMarker = /fe-b\$\$end\$\$(\d+)\$\$(.+)\$\$fe-b/;
+const repeatViewStartMarker = /fe-repeat\$\$start\$\$(\d+)\$\$fe-repeat/;
+const repeatViewEndMarker = /fe-repeat\$\$end\$\$(\d+)\$\$fe-repeat/;
+const elementBoundaryStartMarker = /^(?:.{0,1000})fe-eb\$\$start\$\$(.+?)\$\$fe-eb/;
+const elementBoundaryEndMarker = /fe-eb\$\$end\$\$(.{0,1000})\$\$fe-eb(?:.{0,1000})$/;
+function isComment$1(node) {
+    return node && node.nodeType === Node.COMMENT_NODE;
+}
+/**
+ * Markup utilities to aid in template hydration.
+ * @internal
+ */
+const HydrationMarkup = Object.freeze({
+    attributeMarkerName: "data-fe-b",
+    compactAttributeMarkerName: "data-fe-c",
+    attributeBindingSeparator: " ",
+    contentBindingStartMarker(index, uniqueId) {
+        return `fe-b$$start$$${index}$$${uniqueId}$$fe-b`;
+    },
+    contentBindingEndMarker(index, uniqueId) {
+        return `fe-b$$end$$${index}$$${uniqueId}$$fe-b`;
+    },
+    repeatStartMarker(index) {
+        return `fe-repeat$$start$$${index}$$fe-repeat`;
+    },
+    repeatEndMarker(index) {
+        return `fe-repeat$$end$$${index}$$fe-repeat`;
+    },
+    isContentBindingStartMarker(content) {
+        return bindingStartMarker.test(content);
+    },
+    isContentBindingEndMarker(content) {
+        return bindingEndMarker.test(content);
+    },
+    isRepeatViewStartMarker(content) {
+        return repeatViewStartMarker.test(content);
+    },
+    isRepeatViewEndMarker(content) {
+        return repeatViewEndMarker.test(content);
+    },
+    isElementBoundaryStartMarker(node) {
+        return isComment$1(node) && elementBoundaryStartMarker.test(node.data.trim());
+    },
+    isElementBoundaryEndMarker(node) {
+        return isComment$1(node) && elementBoundaryEndMarker.test(node.data);
+    },
+    /**
+     * Returns the indexes of the ViewBehaviorFactories affecting
+     * attributes for the element, or null if no factories were found.
+     *
+     * This method parses the space-separated format: `data-fe-b="0 1 2"`.
+     */
+    parseAttributeBinding(node) {
+        const attr = node.getAttribute(this.attributeMarkerName);
+        return attr === null
+            ? attr
+            : attr.split(this.attributeBindingSeparator).map(i => parseInt(i));
+    },
+    /**
+     * Returns the indexes of the ViewBehaviorFactories affecting
+     * attributes for the element, or null if no factories were found.
+     *
+     * This method parses the enumerated format: `data-fe-b-0`, `data-fe-b-1`, `data-fe-b-2`.
+     * This is an alternative format that uses separate attributes for each binding index.
+     */
+    parseEnumeratedAttributeBinding(node) {
+        const attrs = [];
+        const prefixLength = this.attributeMarkerName.length + 1;
+        const prefix = `${this.attributeMarkerName}-`;
+        for (const attr of node.getAttributeNames()) {
+            if (attr.startsWith(prefix)) {
+                const count = Number(attr.slice(prefixLength));
+                if (!Number.isNaN(count)) {
+                    attrs.push(count);
+                }
+                else {
+                    throw FAST.error(1601 /* invalidAttributeMarkerName */, {
+                        name: attr,
+                        expectedFormat: `${prefix}<number>`,
+                    });
+                }
+            }
+        }
+        return attrs.length === 0 ? null : attrs;
+    },
+    /**
+     * Returns the indexes of the ViewBehaviorFactories affecting
+     * attributes for the element, or null if no factories were found.
+     *
+     * This method parses the compact format: `data-fe-c-{index}-{count}`.
+     */
+    parseCompactAttributeBinding(node) {
+        const prefix = `${this.compactAttributeMarkerName}-`;
+        const attrName = node.getAttributeNames().find(name => name.startsWith(prefix));
+        if (!attrName) {
+            return null;
+        }
+        const suffix = attrName.slice(prefix.length);
+        const parts = suffix.split("-");
+        const startIndex = parseInt(parts[0], 10);
+        const count = parseInt(parts[1], 10);
+        if (parts.length !== 2 ||
+            Number.isNaN(startIndex) ||
+            Number.isNaN(count) ||
+            startIndex < 0 ||
+            count < 1) {
+            throw FAST.error(1604 /* invalidCompactAttributeMarkerName */, {
+                name: attrName,
+                expectedFormat: `${this.compactAttributeMarkerName}-{index}-{count}`,
+            });
+        }
+        const indexes = [];
+        for (let i = 0; i < count; i++) {
+            indexes.push(startIndex + i);
+        }
+        return indexes;
+    },
+    /**
+     * Parses the ViewBehaviorFactory index from string data. Returns
+     * the binding index or null if the index cannot be retrieved.
+     */
+    parseContentBindingStartMarker(content) {
+        return parseIndexAndIdMarker(bindingStartMarker, content);
+    },
+    parseContentBindingEndMarker(content) {
+        return parseIndexAndIdMarker(bindingEndMarker, content);
+    },
+    /**
+     * Parses the index of a repeat directive from a content string.
+     */
+    parseRepeatStartMarker(content) {
+        return parseIntMarker(repeatViewStartMarker, content);
+    },
+    parseRepeatEndMarker(content) {
+        return parseIntMarker(repeatViewEndMarker, content);
+    },
+    /**
+     * Parses element Id from element boundary markers
+     */
+    parseElementBoundaryStartMarker(content) {
+        return parseStringMarker(elementBoundaryStartMarker, content.trim());
+    },
+    parseElementBoundaryEndMarker(content) {
+        return parseStringMarker(elementBoundaryEndMarker, content);
+    },
+});
+function parseIntMarker(regex, content) {
+    const match = regex.exec(content);
+    return match === null ? match : parseInt(match[1]);
+}
+function parseStringMarker(regex, content) {
+    const match = regex.exec(content);
+    return match === null ? match : match[1];
+}
+function parseIndexAndIdMarker(regex, content) {
+    const match = regex.exec(content);
+    return match === null ? match : [parseInt(match[1]), match[2]];
+}
+/**
+ * @internal
+ */
+const Hydratable = Symbol.for("fe-hydration");
+/** @beta */
+function isHydratable(value) {
+    return value[Hydratable] === Hydratable;
+}
+/**
+ * The attribute used to defer hydration of an element.
+ * @beta
+ */
+const deferHydrationAttribute = "defer-hydration";
+
+class HydrationTargetElementError extends Error {
+    constructor(
+    /**
+     * The error message
+     */
+    message, 
+    /**
+     * The Compiled View Behavior Factories that belong to the view.
+     */
+    factories, 
+    /**
+     * The node to target factory.
+     */
+    node) {
+        super(message);
         this.factories = factories;
         this.node = node;
     }
@@ -1534,7 +1787,23 @@ function isShadowRoot(node) {
     return node instanceof DocumentFragment && "mode" in node;
 }
 /**
- * Maps {@link CompiledViewBehaviorFactory} ids to the corresponding node targets for the view.
+ * Maps compiled ViewBehaviorFactory IDs to their corresponding DOM nodes in the
+ * server-rendered shadow root. Uses a TreeWalker to scan the existing DOM between
+ * firstNode and lastNode, parsing hydration markers to build the targets map.
+ *
+ * For element nodes: parses `data-fe-b` (or variant) attributes to identify which
+ * factories target each element, then removes the marker attribute.
+ *
+ * For comment nodes: parses content binding markers (`fe-b$$start/end$$`) to find
+ * the DOM range controlled by each content binding. Single text nodes become the
+ * direct target; multi-node ranges are stored in boundaries for structural directives.
+ * Element boundary markers (`fe-eb$$start/end$$`) cause the walker to skip over
+ * nested custom elements that handle their own hydration.
+ *
+ * Host bindings (targetNodeId='h') appear at the start of the factories array but
+ * have no SSR markers — getHydrationIndexOffset() computes how many to skip so that
+ * marker indices align with the correct non-host factories.
+ *
  * @param firstNode - The first node of the view.
  * @param lastNode -  The last node of the view.
  * @param factories - The Compiled View Behavior Factories that belong to the view.
@@ -1543,6 +1812,7 @@ function isShadowRoot(node) {
 function buildViewBindingTargets(firstNode, lastNode, factories) {
     const range = createRangeForNodes(firstNode, lastNode);
     const treeRoot = range.commonAncestorContainer;
+    const hydrationIndexOffset = getHydrationIndexOffset(factories);
     const walker = document.createTreeWalker(treeRoot, NodeFilter.SHOW_ELEMENT + NodeFilter.SHOW_COMMENT + NodeFilter.SHOW_TEXT, {
         acceptNode(node) {
             return range.comparePoint(node, 0) === 0
@@ -1556,11 +1826,11 @@ function buildViewBindingTargets(firstNode, lastNode, factories) {
     while (node !== null) {
         switch (node.nodeType) {
             case Node.ELEMENT_NODE: {
-                targetElement(node, factories, targets);
+                targetElement(node, factories, targets, hydrationIndexOffset);
                 break;
             }
             case Node.COMMENT_NODE: {
-                targetComment(node, walker, factories, targets, boundaries);
+                targetComment(node, walker, factories, targets, boundaries, hydrationIndexOffset);
                 break;
             }
         }
@@ -1569,20 +1839,22 @@ function buildViewBindingTargets(firstNode, lastNode, factories) {
     range.detach();
     return { targets, boundaries };
 }
-function targetElement(node, factories, targets) {
+function targetElement(node, factories, targets, hydrationIndexOffset) {
+    var _a, _b;
     // Check for attributes and map any factories.
-    const attrFactoryIds = HydrationMarkup.parseAttributeBinding(node);
+    const attrFactoryIds = (_b = (_a = HydrationMarkup.parseAttributeBinding(node)) !== null && _a !== void 0 ? _a : HydrationMarkup.parseEnumeratedAttributeBinding(node)) !== null && _b !== void 0 ? _b : HydrationMarkup.parseCompactAttributeBinding(node);
     if (attrFactoryIds !== null) {
         for (const id of attrFactoryIds) {
-            if (!factories[id]) {
+            const factory = factories[id + hydrationIndexOffset];
+            if (!factory) {
                 throw new HydrationTargetElementError(`HydrationView was unable to successfully target factory on ${node.nodeName} inside ${node.getRootNode().host.nodeName}. This likely indicates a template mismatch between SSR rendering and hydration.`, factories, node);
             }
-            targetFactory(factories[id], node, targets);
+            targetFactory(factory, node, targets);
         }
         node.removeAttribute(HydrationMarkup.attributeMarkerName);
     }
 }
-function targetComment(node, walker, factories, targets, boundaries) {
+function targetComment(node, walker, factories, targets, boundaries, hydrationIndexOffset) {
     if (HydrationMarkup.isElementBoundaryStartMarker(node)) {
         skipToElementBoundaryEndMarker(node, walker);
         return;
@@ -1593,7 +1865,7 @@ function targetComment(node, walker, factories, targets, boundaries) {
             return;
         }
         const [index, id] = parsed;
-        const factory = factories[index];
+        const factory = factories[index + hydrationIndexOffset];
         const nodes = [];
         let current = walker.nextSibling();
         node.data = "";
@@ -1657,6 +1929,23 @@ function skipToElementBoundaryEndMarker(node, walker) {
         current = walker.nextSibling();
     }
 }
+/**
+ * Counts how many factories at the start of the array are host bindings (targetNodeId='h').
+ * Host bindings target the custom element itself and are not represented by SSR markers,
+ * so the marker indices must be offset by this count to align with the correct factory.
+ */
+function getHydrationIndexOffset(factories) {
+    let offset = 0;
+    for (let i = 0, ii = factories.length; i < ii; ++i) {
+        if (factories[i].targetNodeId === "h") {
+            offset++;
+        }
+        else {
+            break;
+        }
+    }
+    return offset;
+}
 function targetFactory(factory, node, targets) {
     if (factory.targetNodeId === undefined) {
         // Dev error, this shouldn't ever be thrown
@@ -1665,7 +1954,7 @@ function targetFactory(factory, node, targets) {
     targets[factory.targetNodeId] = node;
 }
 
-var _a;
+var _a$1;
 function removeNodeSequence(firstNode, lastNode) {
     const parent = firstNode.parentNode;
     let current = firstNode;
@@ -1840,6 +2129,17 @@ class HTMLView extends DefaultExecutionContext {
     }
     /**
      * Binds a view's behaviors to its binding source.
+     *
+     * On the first call, this iterates through all compiled factories, calling
+     * createBehavior() on each to produce a ViewBehavior instance (e.g., an
+     * HTMLBindingDirective), and then immediately binds it. This is where event
+     * listeners are registered, expression observers are created, and initial
+     * DOM values are set.
+     *
+     * On subsequent calls with a new source, existing behaviors are re-bound
+     * to the new data source, which re-evaluates all binding expressions and
+     * updates the DOM accordingly.
+     *
      * @param source - The binding source for the view's binding behaviors.
      * @param context - The execution context to run the behaviors within.
      */
@@ -1849,6 +2149,8 @@ class HTMLView extends DefaultExecutionContext {
         }
         let behaviors = this.behaviors;
         if (behaviors === null) {
+            // First bind: create behaviors from factories and bind each one.
+            // The view (this) acts as the ViewController, providing targets and source.
             this.source = source;
             this.context = context;
             this.behaviors = behaviors = new Array(this.factories.length);
@@ -1941,13 +2243,22 @@ class HydrationBindingError extends Error {
     }
 }
 class HydrationView extends DefaultExecutionContext {
+    get hydrationStage() {
+        return this._hydrationStage;
+    }
+    get targets() {
+        return this._targets;
+    }
+    get bindingViewBoundaries() {
+        return this._bindingViewBoundaries;
+    }
     constructor(firstChild, lastChild, sourceTemplate, hostBindingTarget) {
         super();
         this.firstChild = firstChild;
         this.lastChild = lastChild;
         this.sourceTemplate = sourceTemplate;
         this.hostBindingTarget = hostBindingTarget;
-        this[_a] = Hydratable;
+        this[_a$1] = Hydratable;
         this.context = this;
         this.source = null;
         this.isBound = false;
@@ -1960,15 +2271,6 @@ class HydrationView extends DefaultExecutionContext {
         this._targets = {};
         this.factories = sourceTemplate.compile().factories;
     }
-    get hydrationStage() {
-        return this._hydrationStage;
-    }
-    get targets() {
-        return this._targets;
-    }
-    get bindingViewBoundaries() {
-        return this._bindingViewBoundaries;
-    }
     /**
      * no-op. Hydrated views are don't need to be moved from a documentFragment
      * to the target node.
@@ -2023,7 +2325,7 @@ class HydrationView extends DefaultExecutionContext {
         fragment.appendChild(end);
     }
     bind(source, context = this) {
-        var _b, _c;
+        var _b;
         if (this.hydrationStage !== HydrationStage.hydrated) {
             this._hydrationStage = HydrationStage.hydrating;
         }
@@ -2067,7 +2369,28 @@ class HydrationView extends DefaultExecutionContext {
                     if (typeof templateString !== "string") {
                         templateString = templateString.innerHTML;
                     }
-                    throw new HydrationBindingError(`HydrationView was unable to successfully target bindings inside "${(_c = ((_b = this.firstChild) === null || _b === void 0 ? void 0 : _b.getRootNode()).host) === null || _c === void 0 ? void 0 : _c.nodeName}".`, factory, createRangeForNodes(this.firstChild, this.lastChild).cloneContents(), templateString);
+                    const hostElement = ((_b = this.firstChild) === null || _b === void 0 ? void 0 : _b.getRootNode())
+                        .host;
+                    const hostName = (hostElement === null || hostElement === void 0 ? void 0 : hostElement.nodeName) || "unknown";
+                    const factoryInfo = factory;
+                    // Build detailed error message
+                    const details = [
+                        `HydrationView was unable to successfully target bindings inside "<${hostName.toLowerCase()}>".`,
+                        `\nMismatch Details:`,
+                        `  - Expected target node ID: "${factory.targetNodeId}"`,
+                        `  - Available target IDs: [${Object.keys(this.targets).join(", ") || "none"}]`,
+                    ];
+                    if (factory.targetTagName) {
+                        details.push(`  - Expected tag name: "${factory.targetTagName}"`);
+                    }
+                    if (factoryInfo.sourceAspect) {
+                        details.push(`  - Source aspect: "${factoryInfo.sourceAspect}"`);
+                    }
+                    if (factoryInfo.aspectType !== undefined) {
+                        details.push(`  - Aspect type: ${factoryInfo.aspectType}`);
+                    }
+                    details.push(`\nThis usually means:`, `  1. The server-rendered HTML doesn't match the client template`, `  2. The hydration markers are missing or corrupted`, `  3. The DOM structure was modified before hydration`, `\nTemplate: ${templateString.slice(0, 200)}${templateString.length > 200 ? "..." : ""}`);
+                    throw new HydrationBindingError(details.join("\n"), factory, createRangeForNodes(this.firstChild, this.lastChild).cloneContents(), templateString);
                 }
             }
         }
@@ -2113,12 +2436,20 @@ class HydrationView extends DefaultExecutionContext {
         unbindables.length = 0;
     }
 }
-_a = Hydratable;
+_a$1 = Hydratable;
 makeSerializationNoop(HydrationView);
 
 function isContentTemplate(value) {
     return value.create !== undefined;
 }
+/**
+ * Sink function for DOMAspect.content bindings (text content interpolation).
+ * Handles two cases:
+ * - If the value is a ContentTemplate (has a create() method), it composes a child
+ *   view into the DOM, managing view lifecycle (create/reuse/remove/bind).
+ * - If the value is a primitive, it sets target.textContent directly, first removing
+ *   any previously composed view.
+ */
 function updateContent(target, aspect, value, controller) {
     // If there's no actual value, then this equates to the
     // empty string for the purposes of content bindings.
@@ -2187,6 +2518,12 @@ function updateContent(target, aspect, value, controller) {
         target.textContent = value;
     }
 }
+/**
+ * Sink function for DOMAspect.tokenList bindings (e.g., :classList).
+ * Uses a versioning scheme to efficiently track which CSS classes were added
+ * in the current update vs. the previous one. Classes from the previous version
+ * that aren't present in the new value are automatically removed.
+ */
 function updateTokenList(target, aspect, value) {
     var _a;
     const lookup = `${this.id}-t`;
@@ -2219,6 +2556,12 @@ function updateTokenList(target, aspect, value) {
         }
     }
 }
+/**
+ * Maps each DOMAspect type to its corresponding DOM update ("sink") function.
+ * When a binding value changes, the sink function for the binding's aspect type
+ * is called to push the new value into the DOM. Events are handled separately
+ * via addEventListener in bind(), so the event sink is a no-op.
+ */
 const sinkLookup = {
     [DOMAspect.attribute]: DOM.setAttribute,
     [DOMAspect.booleanAttribute]: DOM.setBooleanAttribute,
@@ -2228,7 +2571,18 @@ const sinkLookup = {
     [DOMAspect.event]: () => void 0,
 };
 /**
- * A directive that applies bindings.
+ * The central binding directive that bridges data expressions and DOM updates.
+ *
+ * HTMLBindingDirective fulfills three roles simultaneously:
+ * - **HTMLDirective**: Produces placeholder HTML via createHTML() during template authoring.
+ * - **ViewBehaviorFactory**: Creates behaviors (returns itself) during view creation.
+ * - **ViewBehavior / EventListener**: Attaches to a DOM node during bind, manages
+ *   expression observers for reactive updates, and handles DOM events directly.
+ *
+ * The aspectType (set by HTMLDirective.assignAspect during template processing)
+ * determines which DOM "sink" function is used to apply values — e.g.,
+ * setAttribute for attributes, addEventListener for events, textContent for content.
+ *
  * @public
  */
 class HTMLBindingDirective {
@@ -2260,14 +2614,25 @@ class HTMLBindingDirective {
             const sink = sinkLookup[this.aspectType];
             const policy = (_a = this.dataBinding.policy) !== null && _a !== void 0 ? _a : this.policy;
             if (!sink) {
-                throw FAST.error(1205 /* Message.unsupportedBindingBehavior */);
+                throw FAST.error(Message.unsupportedBindingBehavior);
             }
             this.data = `${this.id}-d`;
             this.updateTarget = policy.protect(this.targetTagName, this.aspectType, this.targetAspect, sink);
         }
         return this;
     }
-    /** @internal */
+    /**
+     * Attaches this binding to its target DOM node.
+     * - For events: stores the controller reference on the target element and registers
+     *   this directive as the EventListener via addEventListener. The directive's
+     *   handleEvent() method will be called when the event fires.
+     * - For content bindings: registers an unbind handler, then falls through to the
+     *   default path.
+     * - For all non-event bindings: creates (or reuses) an ExpressionObserver, evaluates
+     *   the binding expression, and applies the result to the DOM via the updateTarget
+     *   sink function. The observer will call handleChange() on future data changes.
+     * @internal
+     */
     bind(controller) {
         var _a;
         const target = controller.targets[this.targetNodeId];
@@ -2282,7 +2647,7 @@ class HTMLBindingDirective {
             case DOMAspect.content:
                 controller.onUnbind(this);
             // intentional fall through
-            default:
+            default: {
                 const observer = (_a = target[this.data]) !== null && _a !== void 0 ? _a : (target[this.data] = this.dataBinding.createObserver(this, this));
                 observer.target = target;
                 observer.controller = controller;
@@ -2295,6 +2660,7 @@ class HTMLBindingDirective {
                 }
                 this.updateTarget(target, this.targetAspect, observer.bind(controller), controller);
                 break;
+            }
         }
     }
     /** @internal */
@@ -2306,7 +2672,14 @@ class HTMLBindingDirective {
             view.needsBindOnly = true;
         }
     }
-    /** @internal */
+    /**
+     * Implements the EventListener interface. When a DOM event fires on the target
+     * element, this method retrieves the ViewController stored on the element,
+     * sets the event on the ExecutionContext so `c.event` is available to the
+     * binding expression, and evaluates the expression. If the expression returns
+     * anything other than `true`, the event's default action is prevented.
+     * @internal
+     */
     handleEvent(event) {
         const controller = event.currentTarget[this.data];
         if (controller.isBound) {
@@ -2318,15 +2691,38 @@ class HTMLBindingDirective {
             }
         }
     }
-    /** @internal */
-    handleChange(binding, observer) {
-        const target = observer.target;
-        const controller = observer.controller;
+    /**
+     * Called by the ExpressionObserver when a tracked dependency changes.
+     * Re-evaluates the binding expression via observer.bind() and pushes
+     * the new value to the DOM through the updateTarget sink function.
+     * This is the reactive update path that keeps the DOM in sync with data.
+     *
+     * Guards against stale notifications: when a view is unbound (e.g., after
+     * a parent `when` directive tears down a child element), coupled-lifetime
+     * observers may still hold active subscriptions. If a property change fires
+     * on the source element while the view is inactive, this guard prevents
+     * the binding expression from evaluating with a null source.
+     * @internal
+     */
+    handleChange(binding, observer) {
+        const controller = observer.controller;
+        // https://github.com/microsoft/fast/issues/7444
+        // This guard will be reconsidered in the next major version.
+        if (!controller.isBound) {
+            return;
+        }
+        const target = observer.target;
         this.updateTarget(target, this.targetAspect, observer.bind(controller), controller);
     }
 }
 HTMLDirective.define(HTMLBindingDirective, { aspected: true });
 
+/**
+ * Builds a hierarchical node ID by appending the child index to the parent's ID.
+ * For example, the third child of root is "r.2", and its first child is "r.2.0".
+ * These IDs are used as property names on the targets prototype so that each
+ * binding's target DOM node can be lazily resolved via a chain of childNodes lookups.
+ */
 const targetIdFrom = (parentId, nodeIndex) => `${parentId}.${nodeIndex}`;
 const descriptorCache = {};
 // used to prevent creating lots of objects just to track node and index while compiling
@@ -2336,7 +2732,7 @@ const next = {
 };
 function tryWarn(name) {
     if (!name.startsWith("fast-")) {
-        FAST.warn(1204 /* Message.hostBindingWithoutHost */, { name });
+        FAST.warn(Message.hostBindingWithoutHost, { name });
     }
 }
 const warningHost = new Proxy(document.createElement("div"), {
@@ -2376,6 +2772,13 @@ class CompilationContext {
         this.proto = Object.create(null, this.descriptors);
         return this;
     }
+    /**
+     * Registers a lazy getter on the targets prototype that resolves a DOM node
+     * by navigating from its parent's childNodes at the given index. Getters are
+     * chained: accessing targets["r.0.2"] first resolves targets["r.0"] (which
+     * resolves targets["r"]), then returns childNodes[2]. Results are cached so
+     * each node is resolved at most once per view instance.
+     */
     addTargetDescriptor(parentId, targetId, targetIndex) {
         const descriptors = this.descriptors;
         if (targetId === "r" || // root
@@ -2386,7 +2789,7 @@ class CompilationContext {
         if (!descriptors[parentId]) {
             const index = parentId.lastIndexOf(".");
             const grandparentId = parentId.substring(0, index);
-            const childIndex = parseInt(parentId.substring(index + 1));
+            const childIndex = parseInt(parentId.substring(index + 1), 10);
             this.addTargetDescriptor(grandparentId, parentId, childIndex);
         }
         let descriptor = descriptorCache[targetId];
@@ -2401,13 +2804,20 @@ class CompilationContext {
         }
         descriptors[targetId] = descriptor;
     }
+    /**
+     * Creates a new HTMLView by cloning the compiled DocumentFragment and building
+     * a targets object. The targets prototype contains lazy getters that resolve
+     * each binding's target DOM node via childNodes traversal. Accessing every
+     * registered nodeId eagerly triggers the getter chain so all nodes are resolved
+     * before behaviors are bound.
+     */
     createView(hostBindingTarget) {
         const fragment = this.fragment.cloneNode(true);
         const targets = Object.create(this.proto);
-        targets.r = fragment;
-        targets.h = hostBindingTarget !== null && hostBindingTarget !== void 0 ? hostBindingTarget : warningHost;
+        targets.r = fragment; // root — the cloned DocumentFragment
+        targets.h = hostBindingTarget !== null && hostBindingTarget !== void 0 ? hostBindingTarget : warningHost; // host — the custom element
         for (const id of this.nodeIds) {
-            targets[id]; // trigger locator
+            Reflect.get(targets, id); // trigger lazy getter to resolve and cache the DOM node
         }
         return new HTMLView(fragment, this.factories, targets);
     }
@@ -2427,7 +2837,6 @@ function compileAttributes(context, parentId, node, nodeId, nodeIndex, includeBa
             }
         }
         else {
-            /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
             result = Compiler.aggregate(parseResult, context.policy);
         }
         if (result !== null) {
@@ -2472,7 +2881,6 @@ function compileChildren(context, parent, parentId) {
     let nodeIndex = 0;
     let childNode = parent.firstChild;
     while (childNode) {
-        /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
         const result = compileNode(context, parentId, childNode, nodeIndex);
         childNode = result.node;
         nodeIndex = result.index;
@@ -2487,14 +2895,14 @@ function compileNode(context, parentId, node, nodeIndex) {
             break;
         case 3: // text node
             return compileContent(context, node, parentId, nodeId, nodeIndex);
-        case 8: // comment
+        case 8: {
+            // comment
             const parts = Parser.parse(node.data, context.directives);
             if (parts !== null) {
-                context.addFactory(
-                /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
-                Compiler.aggregate(parts), parentId, nodeId, nodeIndex, null);
+                context.addFactory(Compiler.aggregate(parts), parentId, nodeId, nodeIndex, null);
             }
             break;
+        }
     }
     next.index = nodeIndex + 1;
     next.node = node.nextSibling;
@@ -2502,7 +2910,7 @@ function compileNode(context, parentId, node, nodeIndex) {
 }
 function isMarker(node, directives) {
     return (node &&
-        node.nodeType == 8 &&
+        node.nodeType === 8 &&
         Parser.parse(node.data, directives) !== null);
 }
 const templateTag = "TEMPLATE";
@@ -2604,631 +3012,634 @@ const Compiler = {
     },
 };
 
-// Much thanks to LitHTML for working this out!
-const lastAttributeNameRegex = 
-/* eslint-disable-next-line no-control-regex, max-len */
-/([ \x09\x0a\x0c\x0d])([^\0-\x1F\x7F-\x9F "'>=/]+)([ \x09\x0a\x0c\x0d]*=[ \x09\x0a\x0c\x0d]*(?:[^ \x09\x0a\x0c\x0d"'`<>=]*|"[^"]*|'[^']*))$/;
-const noFactories = Object.create(null);
 /**
- * Inlines a template into another template.
+ * The runtime behavior for template references.
  * @public
  */
-class InlineTemplateDirective {
-    /**
-     * Creates an instance of InlineTemplateDirective.
-     * @param template - The template to inline.
-     */
-    constructor(html, factories = noFactories) {
-        this.html = html;
-        this.factories = factories;
-    }
+class RefDirective extends StatelessAttachedAttributeDirective {
     /**
-     * Creates HTML to be used within a template.
-     * @param add - Can be used to add  behavior factories to a template.
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
      */
-    createHTML(add) {
-        const factories = this.factories;
-        for (const key in factories) {
-            add(factories[key]);
-        }
-        return this.html;
+    bind(controller) {
+        controller.source[this.options] = controller.targets[this.targetNodeId];
     }
 }
+HTMLDirective.define(RefDirective);
 /**
- * An empty template partial.
+ * 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
  */
-InlineTemplateDirective.empty = new InlineTemplateDirective("");
-HTMLDirective.define(InlineTemplateDirective);
-function createHTML(value, prevString, add, definition = HTMLDirective.getForInstance(value)) {
-    if (definition.aspected) {
-        const match = lastAttributeNameRegex.exec(prevString);
-        if (match !== null) {
-            HTMLDirective.assignAspect(value, match[2]);
-        }
-    }
-    return value.createHTML(add);
-}
+const ref = (propertyName) => new RefDirective(propertyName);
+
+const booleanMode = "boolean";
+const reflectMode = "reflect";
 /**
- * A template capable of creating HTMLView instances or rendering directly to DOM.
+ * Metadata used to configure a custom attribute's behavior.
  * @public
  */
-class ViewTemplate {
+const AttributeConfiguration = Object.freeze({
     /**
-     * Creates an instance of ViewTemplate.
-     * @param html - The html representing what this template will instantiate, including placeholders for directives.
-     * @param factories - The directives that will be connected to placeholders in the html.
-     * @param policy - The security policy to use when compiling this template.
+     * Locates all attribute configurations associated with a type.
      */
-    constructor(html, factories = {}, policy) {
-        this.policy = policy;
-        this.result = null;
-        this.html = html;
-        this.factories = factories;
+    locate: createMetadataLocator(),
+});
+/**
+ * A {@link ValueConverter} that converts to and from `boolean` values.
+ * @remarks
+ * Used automatically when the `boolean` {@link AttributeMode} is selected.
+ * @public
+ */
+const booleanConverter = {
+    toView(value) {
+        return value ? "true" : "false";
+    },
+    fromView(value) {
+        return !(value === null ||
+            value === void 0 ||
+            value === "false" ||
+            value === false ||
+            value === 0);
+    },
+};
+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
+ * This converter allows for nullable numbers, returning `null` if the
+ * input was `null`, `undefined`, or `NaN`.
+ * @public
+ */
+const nullableNumberConverter = {
+    toView(value) {
+        const output = toNumber(value);
+        return output ? output.toString() : output;
+    },
+    fromView: toNumber,
+};
+/**
+ * An implementation of {@link Accessor} that supports reactivity,
+ * change callbacks, attribute reflection, and type conversion for
+ * custom elements.
+ * @public
+ */
+class AttributeDefinition {
     /**
-     * @internal
+     * Creates an instance of AttributeDefinition.
+     * @param Owner - The class constructor that owns this attribute.
+     * @param name - The name of the property associated with the attribute.
+     * @param attribute - The name of the attribute in HTML.
+     * @param mode - The {@link AttributeMode} that describes the behavior of this attribute.
+     * @param converter - A {@link ValueConverter} that integrates with the property getter/setter
+     * to convert values to and from a DOM string.
      */
-    compile() {
-        if (this.result === null) {
-            this.result = Compiler.compile(this.html, this.factories, this.policy);
+    constructor(Owner, name, attribute = name.toLowerCase(), mode = reflectMode, converter) {
+        this.guards = new Set();
+        this.Owner = Owner;
+        this.name = name;
+        this.attribute = attribute;
+        this.mode = mode;
+        this.converter = converter;
+        this.fieldName = `_${name}`;
+        this.callbackName = `${name}Changed`;
+        this.hasCallback = this.callbackName in Owner.prototype;
+        if (mode === booleanMode && converter === void 0) {
+            this.converter = booleanConverter;
         }
-        return this.result;
     }
     /**
-     * Creates an HTMLView instance based on this template definition.
-     * @param hostBindingTarget - The element that host behaviors will be bound to.
+     * Sets the value of the attribute/property on the source element.
+     * @param source - The source element to access.
+     * @param newValue - The value to set the attribute/property to.
      */
-    create(hostBindingTarget) {
-        return this.compile().createView(hostBindingTarget);
+    setValue(source, newValue) {
+        const oldValue = source[this.fieldName];
+        const converter = this.converter;
+        if (converter !== void 0) {
+            newValue = converter.fromView(newValue);
+        }
+        if (oldValue !== newValue) {
+            source[this.fieldName] = newValue;
+            this.tryReflectToAttribute(source);
+            if (this.hasCallback) {
+                source[this.callbackName](oldValue, newValue);
+            }
+            source.$fastController.notify(this.name);
+        }
     }
     /**
-     * Returns a directive that can inline the template.
+     * Gets the value of the attribute/property on the source element.
+     * @param source - The source element to access.
      */
-    inline() {
-        return new InlineTemplateDirective(isString(this.html) ? this.html : this.html.innerHTML, this.factories);
+    getValue(source) {
+        Observable.track(source, this.name);
+        return source[this.fieldName];
     }
-    /**
-     * Sets the DOMPolicy for this template.
-     * @param policy - The policy to associated with this template.
-     * @returns The modified template instance.
-     * @remarks
-     * The DOMPolicy can only be set once for a template and cannot be
-     * set after the template is compiled.
-     */
-    withPolicy(policy) {
-        if (this.result) {
-            throw FAST.error(1208 /* Message.cannotSetTemplatePolicyAfterCompilation */);
+    /** @internal */
+    onAttributeChangedCallback(element, value) {
+        if (this.guards.has(element)) {
+            return;
         }
-        if (this.policy) {
-            throw FAST.error(1207 /* Message.onlySetTemplatePolicyOnce */);
+        this.guards.add(element);
+        this.setValue(element, value);
+        this.guards.delete(element);
+    }
+    tryReflectToAttribute(element) {
+        const mode = this.mode;
+        const guards = this.guards;
+        if (guards.has(element) || mode === "fromView") {
+            return;
         }
-        this.policy = policy;
-        return this;
+        Updates.enqueue(() => {
+            guards.add(element);
+            const latestValue = element[this.fieldName];
+            switch (mode) {
+                case reflectMode:
+                    const converter = this.converter;
+                    DOM.setAttribute(element, this.attribute, converter !== void 0 ? converter.toView(latestValue) : latestValue);
+                    break;
+                case booleanMode:
+                    DOM.setBooleanAttribute(element, this.attribute, latestValue);
+                    break;
+            }
+            guards.delete(element);
+        });
     }
     /**
-     * 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.
-     * @param host - The Element where the template will be rendered.
-     * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
-     * host that the template is being attached to.
+     * Collects all attribute definitions associated with the owner.
+     * @param Owner - The class constructor to collect attribute for.
+     * @param attributeLists - Any existing attributes to collect and merge with those associated with the owner.
+     * @internal
      */
-    render(source, host, hostBindingTarget) {
-        const view = this.create(hostBindingTarget);
-        view.bind(source);
-        view.appendTo(host);
-        return view;
-    }
-    /**
-     * Creates a template based on a set of static strings and dynamic values.
-     * @param strings - The static strings to create the template with.
-     * @param values - The dynamic values to create the template with.
-     * @param policy - The DOMPolicy to associated with the template.
-     * @returns A ViewTemplate.
-     * @remarks
-     * This API should not be used directly under normal circumstances because constructing
-     * a template in this way, if not done properly, can open up the application to XSS
-     * attacks. When using this API, provide a strong DOMPolicy that can properly sanitize
-     * and also be sure to manually sanitize all static strings particularly if they can
-     * come from user input.
-     */
-    static create(strings, values, policy) {
-        let html = "";
-        const factories = Object.create(null);
-        const add = (factory) => {
-            var _a;
-            const id = (_a = factory.id) !== null && _a !== void 0 ? _a : (factory.id = nextId());
-            factories[id] = factory;
-            return id;
-        };
-        for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
-            const currentString = strings[i];
-            let currentValue = values[i];
-            let definition;
-            html += currentString;
-            if (isFunction(currentValue)) {
-                currentValue = new HTMLBindingDirective(oneWay(currentValue));
-            }
-            else if (currentValue instanceof Binding) {
-                currentValue = new HTMLBindingDirective(currentValue);
-            }
-            else if (!(definition = HTMLDirective.getForInstance(currentValue))) {
-                const staticValue = currentValue;
-                currentValue = new HTMLBindingDirective(oneTime(() => staticValue));
-            }
-            html += createHTML(currentValue, currentString, add, definition);
-        }
-        return new ViewTemplate(html + strings[strings.length - 1], factories, policy);
+    static collect(Owner, ...attributeLists) {
+        const attributes = [];
+        attributeLists.push(AttributeConfiguration.locate(Owner));
+        for (let i = 0, ii = attributeLists.length; i < ii; ++i) {
+            const list = attributeLists[i];
+            if (list === void 0) {
+                continue;
+            }
+            for (let j = 0, jj = list.length; j < jj; ++j) {
+                const config = list[j];
+                if (isString(config)) {
+                    attributes.push(new AttributeDefinition(Owner, config));
+                }
+                else {
+                    attributes.push(new AttributeDefinition(Owner, config.property, config.attribute, config.mode, config.converter));
+                }
+            }
+        }
+        return attributes;
     }
 }
-makeSerializationNoop(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
- * The html helper supports interpolation of strings, numbers, binding expressions,
- * other template instances, and Directive instances.
- * @public
- */
-const html = ((strings, ...values) => {
-    if (Array.isArray(strings) && Array.isArray(strings.raw)) {
-        return ViewTemplate.create(strings, values);
+function attr(configOrTarget, prop) {
+    let config;
+    function decorator($target, $prop) {
+        if (arguments.length > 1) {
+            // Non invocation:
+            // - @attr
+            // Invocation with or w/o opts:
+            // - @attr()
+            // - @attr({...opts})
+            config.property = $prop;
+        }
+        AttributeConfiguration.locate($target.constructor).push(config);
     }
-    throw FAST.error(1206 /* Message.directCallToHTMLTagNotAllowed */);
-});
-html.partial = (html) => {
-    return new InlineTemplateDirective(html);
-};
-
-/**
- * The runtime behavior for template references.
- * @public
- */
-class RefDirective extends StatelessAttachedAttributeDirective {
-    /**
-     * Bind this behavior.
-     * @param controller - The view controller that manages the lifecycle of this behavior.
-     */
-    bind(controller) {
-        controller.source[this.options] = controller.targets[this.targetNodeId];
+    if (arguments.length > 1) {
+        // Non invocation:
+        // - @attr
+        config = {};
+        decorator(configOrTarget, prop);
+        return;
     }
+    // Invocation with or w/o opts:
+    // - @attr()
+    // - @attr({...opts})
+    config = configOrTarget === void 0 ? {} : configOrTarget;
+    return decorator;
 }
-HTMLDirective.define(RefDirective);
+
+var __awaiter = (undefined && undefined.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a;
+const defaultShadowOptions = { mode: "open" };
+const defaultElementOptions = {};
+const fastElementBaseTypes = new Set();
 /**
- * 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
+ * The FAST custom element registry
+ * @internal
  */
-const ref = (propertyName) => new RefDirective(propertyName);
-
-const selectElements = (value) => value.nodeType === 1;
+const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () => createTypeRegistry());
 /**
- * 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
+ * Values for the `templateOptions` property.
+ * @alpha
  */
-const elements = (selector) => selector
-    ? value => value.nodeType === 1 && value.matches(selector)
-    : selectElements;
+const TemplateOptions = {
+    deferAndHydrate: "defer-and-hydrate",
+};
 /**
- * A base class for node observation.
+ * Defines metadata for a FASTElement.
  * @public
- * @remarks
- * Internally used by the SlottedDirective and the ChildrenDirective.
  */
-class NodeObservationDirective extends StatelessAttachedAttributeDirective {
+class FASTElementDefinition {
     /**
-     * The unique id of the factory.
+     * Indicates if this element has been defined in at least one registry.
      */
-    get id() {
-        return this._id;
-    }
-    set id(value) {
-        this._id = value;
-        this._controllerProperty = `${value}-c`;
+    get isDefined() {
+        return this.platformDefined;
     }
-    /**
-     * 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(controller) {
-        const target = controller.targets[this.targetNodeId];
-        target[this._controllerProperty] = controller;
-        this.updateTarget(controller.source, this.computeNodes(target));
-        this.observe(target);
-        controller.onUnbind(this);
+    constructor(type, nameOrConfig = type.definition) {
+        var _b;
+        this.platformDefined = false;
+        if (isString(nameOrConfig)) {
+            nameOrConfig = { name: nameOrConfig };
+        }
+        this.type = type;
+        this.name = nameOrConfig.name;
+        this.template = nameOrConfig.template;
+        this.templateOptions = nameOrConfig.templateOptions;
+        this.registry = (_b = nameOrConfig.registry) !== null && _b !== void 0 ? _b : customElements;
+        const proto = type.prototype;
+        const attributes = AttributeDefinition.collect(type, nameOrConfig.attributes);
+        const observedAttributes = new Array(attributes.length);
+        const propertyLookup = {};
+        const attributeLookup = {};
+        for (let i = 0, ii = attributes.length; i < ii; ++i) {
+            const current = attributes[i];
+            observedAttributes[i] = current.attribute;
+            propertyLookup[current.name] = current;
+            attributeLookup[current.attribute] = current;
+            Observable.defineProperty(proto, current);
+        }
+        Reflect.defineProperty(type, "observedAttributes", {
+            value: observedAttributes,
+            enumerable: true,
+        });
+        this.attributes = attributes;
+        this.propertyLookup = propertyLookup;
+        this.attributeLookup = attributeLookup;
+        this.shadowOptions =
+            nameOrConfig.shadowOptions === void 0
+                ? defaultShadowOptions
+                : nameOrConfig.shadowOptions === null
+                    ? void 0
+                    : Object.assign(Object.assign({}, defaultShadowOptions), nameOrConfig.shadowOptions);
+        this.elementOptions =
+            nameOrConfig.elementOptions === void 0
+                ? defaultElementOptions
+                : Object.assign(Object.assign({}, defaultElementOptions), nameOrConfig.elementOptions);
+        this.styles = ElementStyles.normalize(nameOrConfig.styles);
+        fastElementRegistry.register(this);
+        Observable.defineProperty(_a.isRegistered, this.name);
+        _a.isRegistered[this.name] = this.type;
     }
     /**
-     * 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.
+     * Defines a custom element based on this definition.
+     * @param registry - The element registry to define the element in.
+     * @remarks
+     * This operation is idempotent per registry.
      */
-    unbind(controller) {
-        const target = controller.targets[this.targetNodeId];
-        this.updateTarget(controller.source, emptyArray);
-        this.disconnect(target);
-        target[this._controllerProperty] = null;
+    define(registry = this.registry) {
+        var _b, _c;
+        const type = this.type;
+        if (!registry.get(this.name)) {
+            this.platformDefined = true;
+            registry.define(this.name, type, this.elementOptions);
+            (_c = (_b = this.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.elementDidDefine) === null || _c === void 0 ? void 0 : _c.call(_b, this.name);
+        }
+        return this;
     }
     /**
-     * Gets the data source for the target.
-     * @param target - The target to get the source for.
-     * @returns The source.
+     * Creates an instance of FASTElementDefinition.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
      */
-    getSource(target) {
-        return target[this._controllerProperty].source;
+    static compose(type, nameOrDef) {
+        if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
+            return new _a(class extends type {
+            }, nameOrDef);
+        }
+        return new _a(type, nameOrDef);
     }
     /**
-     * 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.
+     * Registers a FASTElement base type.
+     * @param type - The type to register as a base type.
+     * @internal
      */
-    updateTarget(source, value) {
-        source[this.options.property] = value;
+    static registerBaseType(type) {
+        fastElementBaseTypes.add(type);
     }
     /**
-     * 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.
+     * Creates an instance of FASTElementDefinition asynchronously. This option assumes
+     * that a template and shadowOptions will be provided and completes when those requirements
+     * are met.
+     * @param type - The type this definition is being created for.
+     * @param nameOrDef - The name of the element to define or a config object
+     * that describes the element to define.
+     * @alpha
      */
-    computeNodes(target) {
-        let nodes = this.getNodes(target);
-        if ("filter" in this.options) {
-            nodes = nodes.filter(this.options.filter);
-        }
-        return nodes;
+    static composeAsync(type, nameOrDef) {
+        return new Promise(resolve => {
+            if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
+                resolve(new _a(class extends type {
+                }, nameOrDef));
+            }
+            const definition = new _a(type, nameOrDef);
+            Observable.getNotifier(definition).subscribe({
+                handleChange: () => {
+                    var _b, _c;
+                    (_c = (_b = definition.lifecycleCallbacks) === null || _b === void 0 ? void 0 : _b.templateDidUpdate) === null || _c === void 0 ? void 0 : _c.call(_b, definition.name);
+                    resolve(definition);
+                },
+            }, "template");
+        });
     }
 }
-
-const slotEvent = "slotchange";
+_a = FASTElementDefinition;
 /**
- * The runtime behavior for slotted node observation.
- * @public
+ * The definition has been registered to the FAST element registry.
  */
-class SlottedDirective extends NodeObservationDirective {
-    /**
-     * Begins observation of the nodes.
-     * @param target - The target to observe.
-     */
-    observe(target) {
-        target.addEventListener(slotEvent, this);
-    }
-    /**
-     * Disconnects observation of the nodes.
-     * @param target - The target to unobserve.
-     */
-    disconnect(target) {
-        target.removeEventListener(slotEvent, this);
-    }
-    /**
-     * Retrieves the raw nodes that should be assigned to the source property.
-     * @param target - The target to get the node to.
-     */
-    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);
+FASTElementDefinition.isRegistered = {};
 /**
- * A directive that observes the `assignedNodes()` of a slot and updates a property
- * whenever they change.
- * @param propertyOrOptions - The options used to configure slotted node observation.
- * @public
+ * Gets the element definition associated with the specified type.
+ * @param type - The custom element type to retrieve the definition for.
  */
-function slotted(propertyOrOptions) {
-    if (isString(propertyOrOptions)) {
-        propertyOrOptions = { property: propertyOrOptions };
-    }
-    return new SlottedDirective(propertyOrOptions);
-}
-
-const booleanMode = "boolean";
-const reflectMode = "reflect";
+FASTElementDefinition.getByType = fastElementRegistry.getByType;
 /**
- * Metadata used to configure a custom attribute's behavior.
- * @public
+ * Gets the element definition associated with the instance.
+ * @param instance - The custom element instance to retrieve the definition for.
  */
-const AttributeConfiguration = Object.freeze({
-    /**
-     * Locates all attribute configurations associated with a type.
-     */
-    locate: createMetadataLocator(),
+FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
+/**
+ * Indicates when a custom elements definition has been registered with the fastElementRegistry.
+ * @param name - The name of the defined custom element.
+ * @alpha
+ */
+FASTElementDefinition.registerAsync = (name) => __awaiter(void 0, void 0, void 0, function* () {
+    return new Promise(resolve => {
+        if (_a.isRegistered[name]) {
+            resolve(_a.isRegistered[name]);
+        }
+        Observable.getNotifier(_a.isRegistered).subscribe({ handleChange: () => resolve(_a.isRegistered[name]) }, name);
+    });
 });
+Observable.defineProperty(FASTElementDefinition.prototype, "template");
+
+// Much thanks to LitHTML for working this out!
+const lastAttributeNameRegex = 
+/* eslint-disable-next-line no-control-regex, max-len */
+/([ \x09\x0a\x0c\x0d])([^\0-\x1F\x7F-\x9F "'>=/]+)([ \x09\x0a\x0c\x0d]*=[ \x09\x0a\x0c\x0d]*(?:[^ \x09\x0a\x0c\x0d"'`<>=]*|"[^"]*|'[^']*))$/;
+const noFactories = Object.create(null);
 /**
- * A {@link ValueConverter} that converts to and from `boolean` values.
- * @remarks
- * Used automatically when the `boolean` {@link AttributeMode} is selected.
+ * Inlines a template into another template.
  * @public
  */
-const booleanConverter = {
-    toView(value) {
-        return value ? "true" : "false";
-    },
-    fromView(value) {
-        return value === null ||
-            value === void 0 ||
-            value === "false" ||
-            value === false ||
-            value === 0
-            ? false
-            : true;
-    },
-};
-function toNumber(value) {
-    if (value === null || value === undefined) {
-        return null;
+class InlineTemplateDirective {
+    /**
+     * Creates an instance of InlineTemplateDirective.
+     * @param template - The template to inline.
+     */
+    constructor(html, factories = noFactories) {
+        this.html = html;
+        this.factories = factories;
+    }
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add) {
+        const factories = this.factories;
+        for (const key in factories) {
+            add(factories[key]);
+        }
+        return this.html;
     }
-    const number = value * 1;
-    return isNaN(number) ? null : number;
 }
 /**
- * A {@link ValueConverter} that converts to and from `number` values.
- * @remarks
- * This converter allows for nullable numbers, returning `null` if the
- * input was `null`, `undefined`, or `NaN`.
- * @public
+ * An empty template partial.
  */
-const nullableNumberConverter = {
-    toView(value) {
-        const output = toNumber(value);
-        return output ? output.toString() : output;
-    },
-    fromView: toNumber,
-};
+InlineTemplateDirective.empty = new InlineTemplateDirective("");
+HTMLDirective.define(InlineTemplateDirective);
+function createHTML(value, prevString, add, definition = HTMLDirective.getForInstance(value)) {
+    if (definition.aspected) {
+        const match = lastAttributeNameRegex.exec(prevString);
+        if (match !== null) {
+            HTMLDirective.assignAspect(value, match[2]);
+        }
+    }
+    return value.createHTML(add);
+}
 /**
- * An implementation of {@link Accessor} that supports reactivity,
- * change callbacks, attribute reflection, and type conversion for
- * custom elements.
+ * A template capable of creating HTMLView instances or rendering directly to DOM.
  * @public
  */
-class AttributeDefinition {
+class ViewTemplate {
     /**
-     * Creates an instance of AttributeDefinition.
-     * @param Owner - The class constructor that owns this attribute.
-     * @param name - The name of the property associated with the attribute.
-     * @param attribute - The name of the attribute in HTML.
-     * @param mode - The {@link AttributeMode} that describes the behavior of this attribute.
-     * @param converter - A {@link ValueConverter} that integrates with the property getter/setter
-     * to convert values to and from a DOM string.
+     * Creates an instance of ViewTemplate.
+     * @param html - The html representing what this template will instantiate, including placeholders for directives.
+     * @param factories - The directives that will be connected to placeholders in the html.
+     * @param policy - The security policy to use when compiling this template.
      */
-    constructor(Owner, name, attribute = name.toLowerCase(), mode = reflectMode, converter) {
-        this.guards = new Set();
-        this.Owner = Owner;
-        this.name = name;
-        this.attribute = attribute;
-        this.mode = mode;
-        this.converter = converter;
-        this.fieldName = `_${name}`;
-        this.callbackName = `${name}Changed`;
-        this.hasCallback = this.callbackName in Owner.prototype;
-        if (mode === booleanMode && converter === void 0) {
-            this.converter = booleanConverter;
-        }
+    constructor(html, factories = {}, policy) {
+        this.policy = policy;
+        this.result = null;
+        this.html = html;
+        this.factories = factories;
     }
     /**
-     * Sets the value of the attribute/property on the source element.
-     * @param source - The source element to access.
-     * @param value - The value to set the attribute/property to.
+     * @internal
      */
-    setValue(source, newValue) {
-        const oldValue = source[this.fieldName];
-        const converter = this.converter;
-        if (converter !== void 0) {
-            newValue = converter.fromView(newValue);
-        }
-        if (oldValue !== newValue) {
-            source[this.fieldName] = newValue;
-            this.tryReflectToAttribute(source);
-            if (this.hasCallback) {
-                source[this.callbackName](oldValue, newValue);
-            }
-            source.$fastController.notify(this.name);
+    compile() {
+        if (this.result === null) {
+            this.result = Compiler.compile(this.html, this.factories, this.policy);
         }
+        return this.result;
     }
     /**
-     * Gets the value of the attribute/property on the source element.
-     * @param source - The source element to access.
+     * Creates an HTMLView instance based on this template definition.
+     * @param hostBindingTarget - The element that host behaviors will be bound to.
      */
-    getValue(source) {
-        Observable.track(source, this.name);
-        return source[this.fieldName];
+    create(hostBindingTarget) {
+        return this.compile().createView(hostBindingTarget);
     }
-    /** @internal */
-    onAttributeChangedCallback(element, value) {
-        if (this.guards.has(element)) {
-            return;
-        }
-        this.guards.add(element);
-        this.setValue(element, value);
-        this.guards.delete(element);
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline() {
+        return new InlineTemplateDirective(isString(this.html) ? this.html : this.html.innerHTML, this.factories);
     }
-    tryReflectToAttribute(element) {
-        const mode = this.mode;
-        const guards = this.guards;
-        if (guards.has(element) || mode === "fromView") {
-            return;
+    /**
+     * Sets the DOMPolicy for this template.
+     * @param policy - The policy to associated with this template.
+     * @returns The modified template instance.
+     * @remarks
+     * The DOMPolicy can only be set once for a template and cannot be
+     * set after the template is compiled.
+     */
+    withPolicy(policy) {
+        if (this.result) {
+            throw FAST.error(Message.cannotSetTemplatePolicyAfterCompilation);
         }
-        Updates.enqueue(() => {
-            guards.add(element);
-            const latestValue = element[this.fieldName];
-            switch (mode) {
-                case reflectMode:
-                    const converter = this.converter;
-                    DOM.setAttribute(element, this.attribute, converter !== void 0 ? converter.toView(latestValue) : latestValue);
-                    break;
-                case booleanMode:
-                    DOM.setBooleanAttribute(element, this.attribute, latestValue);
-                    break;
-            }
-            guards.delete(element);
-        });
+        if (this.policy) {
+            throw FAST.error(Message.onlySetTemplatePolicyOnce);
+        }
+        this.policy = policy;
+        return this;
     }
     /**
-     * Collects all attribute definitions associated with the owner.
-     * @param Owner - The class constructor to collect attribute for.
-     * @param attributeLists - Any existing attributes to collect and merge with those associated with the owner.
-     * @internal
+     * 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.
+     * @param host - The Element where the template will be rendered.
+     * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
+     * host that the template is being attached to.
      */
-    static collect(Owner, ...attributeLists) {
-        const attributes = [];
-        attributeLists.push(AttributeConfiguration.locate(Owner));
-        for (let i = 0, ii = attributeLists.length; i < ii; ++i) {
-            const list = attributeLists[i];
-            if (list === void 0) {
-                continue;
+    render(source, host, hostBindingTarget) {
+        const view = this.create(hostBindingTarget);
+        view.bind(source);
+        view.appendTo(host);
+        return view;
+    }
+    /**
+     * Processes the tagged template literal's static strings and interpolated values and
+     * creates a ViewTemplate.
+     *
+     * For each interpolated value:
+     * 1. Functions (binding expressions, e.g., `x => x.name`) → wrapped in a one-way HTMLBindingDirective
+     * 2. Binding instances → wrapped in an HTMLBindingDirective
+     * 3. HTMLDirective instances → used as-is
+     * 4. Static values (strings, numbers) → wrapped in a one-time HTMLBindingDirective
+     *
+     * Each directive's createHTML() is called with an `add` callback that registers
+     * the factory in the factories record under a unique ID and returns that ID.
+     * The directive inserts a placeholder marker (e.g., `fast-abc123{0}fast-abc123`) into
+     * the HTML string so the compiler can later find and associate it with the factory.
+     *
+     * Aspect detection happens here too: the `lastAttributeNameRegex` checks whether
+     * the placeholder appears inside an attribute value, and if so, assignAspect()
+     * sets the correct DOMAspect (attribute, property, event, etc.) based on the
+     * attribute name prefix.
+     *
+     * @param strings - The static strings to create the template with.
+     * @param values - The dynamic values to create the template with.
+     * @param policy - The DOMPolicy to associated with the template.
+     * @returns A ViewTemplate.
+     * @remarks
+     * This API should not be used directly under normal circumstances because constructing
+     * a template in this way, if not done properly, can open up the application to XSS
+     * attacks. When using this API, provide a strong DOMPolicy that can properly sanitize
+     * and also be sure to manually sanitize all static strings particularly if they can
+     * come from user input.
+     */
+    static create(strings, values, policy) {
+        let html = "";
+        const factories = Object.create(null);
+        const add = (factory) => {
+            var _a;
+            const id = (_a = factory.id) !== null && _a !== void 0 ? _a : (factory.id = nextId());
+            factories[id] = factory;
+            return id;
+        };
+        for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
+            const currentString = strings[i];
+            let currentValue = values[i];
+            let definition;
+            html += currentString;
+            if (isFunction(currentValue)) {
+                currentValue = new HTMLBindingDirective(oneWay(currentValue));
             }
-            for (let j = 0, jj = list.length; j < jj; ++j) {
-                const config = list[j];
-                if (isString(config)) {
-                    attributes.push(new AttributeDefinition(Owner, config));
-                }
-                else {
-                    attributes.push(new AttributeDefinition(Owner, config.property, config.attribute, config.mode, config.converter));
-                }
+            else if (currentValue instanceof Binding) {
+                currentValue = new HTMLBindingDirective(currentValue);
             }
-        }
-        return attributes;
-    }
-}
-function attr(configOrTarget, prop) {
-    let config;
-    function decorator($target, $prop) {
-        if (arguments.length > 1) {
-            // Non invocation:
-            // - @attr
-            // Invocation with or w/o opts:
-            // - @attr()
-            // - @attr({...opts})
-            config.property = $prop;
-        }
-        AttributeConfiguration.locate($target.constructor).push(config);
-    }
-    if (arguments.length > 1) {
-        // Non invocation:
-        // - @attr
-        config = {};
-        decorator(configOrTarget, prop);
-        return;
+            else if (!(definition = HTMLDirective.getForInstance(currentValue))) {
+                const staticValue = currentValue;
+                currentValue = new HTMLBindingDirective(oneTime(() => staticValue));
+            }
+            html += createHTML(currentValue, currentString, add, definition);
+        }
+        return new ViewTemplate(html + strings[strings.length - 1], factories, policy);
     }
-    // Invocation with or w/o opts:
-    // - @attr()
-    // - @attr({...opts})
-    config = configOrTarget === void 0 ? {} : configOrTarget;
-    return decorator;
 }
-
-const defaultShadowOptions = { mode: "open" };
-const defaultElementOptions = {};
-const fastElementBaseTypes = new Set();
-const fastElementRegistry = FAST.getById(KernelServiceId.elementRegistry, () => createTypeRegistry());
+makeSerializationNoop(ViewTemplate);
 /**
- * Defines metadata for a FASTElement.
+ * 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
  */
-class FASTElementDefinition {
-    constructor(type, nameOrConfig = type.definition) {
-        var _a;
-        this.platformDefined = false;
-        if (isString(nameOrConfig)) {
-            nameOrConfig = { name: nameOrConfig };
-        }
-        this.type = type;
-        this.name = nameOrConfig.name;
-        this.template = nameOrConfig.template;
-        this.registry = (_a = nameOrConfig.registry) !== null && _a !== void 0 ? _a : customElements;
-        const proto = type.prototype;
-        const attributes = AttributeDefinition.collect(type, nameOrConfig.attributes);
-        const observedAttributes = new Array(attributes.length);
-        const propertyLookup = {};
-        const attributeLookup = {};
-        for (let i = 0, ii = attributes.length; i < ii; ++i) {
-            const current = attributes[i];
-            observedAttributes[i] = current.attribute;
-            propertyLookup[current.name] = current;
-            attributeLookup[current.attribute] = current;
-            Observable.defineProperty(proto, current);
-        }
-        Reflect.defineProperty(type, "observedAttributes", {
-            value: observedAttributes,
-            enumerable: true,
-        });
-        this.attributes = attributes;
-        this.propertyLookup = propertyLookup;
-        this.attributeLookup = attributeLookup;
-        this.shadowOptions =
-            nameOrConfig.shadowOptions === void 0
-                ? defaultShadowOptions
-                : nameOrConfig.shadowOptions === null
-                    ? void 0
-                    : Object.assign(Object.assign({}, defaultShadowOptions), nameOrConfig.shadowOptions);
-        this.elementOptions =
-            nameOrConfig.elementOptions === void 0
-                ? defaultElementOptions
-                : Object.assign(Object.assign({}, defaultElementOptions), nameOrConfig.elementOptions);
-        this.styles = ElementStyles.normalize(nameOrConfig.styles);
-        fastElementRegistry.register(this);
+const html = ((strings, ...values) => {
+    if (Array.isArray(strings) && Array.isArray(strings.raw)) {
+        return ViewTemplate.create(strings, values);
     }
+    throw FAST.error(Message.directCallToHTMLTagNotAllowed);
+});
+html.partial = (html) => {
+    return new InlineTemplateDirective(html);
+};
+
+const slotEvent = "slotchange";
+/**
+ * The runtime behavior for slotted node observation.
+ * @public
+ */
+class SlottedDirective extends NodeObservationDirective {
     /**
-     * Indicates if this element has been defined in at least one registry.
+     * Begins observation of the nodes.
+     * @param target - The target to observe.
      */
-    get isDefined() {
-        return this.platformDefined;
+    observe(target) {
+        target.addEventListener(slotEvent, this);
     }
     /**
-     * Defines a custom element based on this definition.
-     * @param registry - The element registry to define the element in.
-     * @remarks
-     * This operation is idempotent per registry.
+     * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
      */
-    define(registry = this.registry) {
-        const type = this.type;
-        if (!registry.get(this.name)) {
-            this.platformDefined = true;
-            registry.define(this.name, type, this.elementOptions);
-        }
-        return this;
+    disconnect(target) {
+        target.removeEventListener(slotEvent, this);
     }
     /**
-     * Creates an instance of FASTElementDefinition.
-     * @param type - The type this definition is being created for.
-     * @param nameOrDef - The name of the element to define or a config object
-     * that describes the element to define.
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
      */
-    static compose(type, nameOrDef) {
-        if (fastElementBaseTypes.has(type) || fastElementRegistry.getByType(type)) {
-            return new FASTElementDefinition(class extends type {
-            }, nameOrDef);
-        }
-        return new FASTElementDefinition(type, nameOrDef);
+    getNodes(target) {
+        return target.assignedNodes(this.options);
     }
-    /**
-     * Registers a FASTElement base type.
-     * @param type - The type to register as a base type.
-     * @internal
-     */
-    static registerBaseType(type) {
-        fastElementBaseTypes.add(type);
+    /** @internal */
+    handleEvent(event) {
+        const target = event.currentTarget;
+        this.updateTarget(this.getSource(target), this.computeNodes(target));
     }
 }
+HTMLDirective.define(SlottedDirective);
 /**
- * Gets the element definition associated with the specified type.
- * @param type - The custom element type to retrieve the definition for.
- */
-FASTElementDefinition.getByType = fastElementRegistry.getByType;
-/**
- * Gets the element definition associated with the instance.
- * @param instance - The custom element instance to retrieve the definition for.
+ * A directive that observes the `assignedNodes()` of a slot and updates a property
+ * whenever they change.
+ * @param propertyOrOptions - The options used to configure slotted node observation.
+ * @public
  */
-FASTElementDefinition.getForInstance = fastElementRegistry.getForInstance;
+function slotted(propertyOrOptions) {
+    if (isString(propertyOrOptions)) {
+        propertyOrOptions = { property: propertyOrOptions };
+    }
+    return new SlottedDirective(propertyOrOptions);
+}
 
 /**
  * An extension of MutationObserver that supports unobserving nodes.
@@ -3336,92 +3747,33 @@ function getShadowRoot(element) {
     return (_b = (_a = element.shadowRoot) !== null && _a !== void 0 ? _a : shadowRoots.get(element)) !== null && _b !== void 0 ? _b : null;
 }
 let elementControllerStrategy;
+/**
+ * The various lifecycle stages of an ElementController.
+ * @public
+ */
+var Stages;
+(function (Stages) {
+    /** The element is in the process of connecting. */
+    Stages[Stages["connecting"] = 0] = "connecting";
+    /** The element is connected. */
+    Stages[Stages["connected"] = 1] = "connected";
+    /** The element is in the process of disconnecting. */
+    Stages[Stages["disconnecting"] = 2] = "disconnecting";
+    /** The element is disconnected. */
+    Stages[Stages["disconnected"] = 3] = "disconnected";
+})(Stages || (Stages = {}));
 /**
  * Controls the lifecycle and rendering of a `FASTElement`.
  * @public
  */
 class ElementController extends PropertyChangeNotifier {
-    /**
-     * Creates a Controller to control the specified element.
-     * @param element - The element to be controlled by this controller.
-     * @param definition - The element definition metadata that instructs this
-     * controller in how to handle rendering and other platform integrations.
-     * @internal
-     */
-    constructor(element, definition) {
-        super(element);
-        this.boundObservables = null;
-        this.needsInitialization = true;
-        this.hasExistingShadowRoot = false;
-        this._template = null;
-        this.stage = 3 /* Stages.disconnected */;
-        /**
-         * A guard against connecting behaviors multiple times
-         * during connect in scenarios where a behavior adds
-         * another behavior during it's connectedCallback
-         */
-        this.guardBehaviorConnection = false;
-        this.behaviors = null;
-        /**
-         * Tracks whether behaviors are connected so that
-         * behaviors cant be connected multiple times
-         */
-        this.behaviorsConnected = false;
-        this._mainStyles = null;
-        /**
-         * This allows Observable.getNotifier(...) to return the Controller
-         * when the notifier for the Controller itself is being requested. The
-         * result is that the Observable system does not need to create a separate
-         * instance of Notifier for observables on the Controller. The component and
-         * the controller will now share the same notifier, removing one-object construct
-         * per web component instance.
-         */
-        this.$fastController = this;
-        /**
-         * The view associated with the custom element.
-         * @remarks
-         * If `null` then the element is managing its own rendering.
-         */
-        this.view = null;
-        this.source = element;
-        this.definition = definition;
-        const shadowOptions = definition.shadowOptions;
-        if (shadowOptions !== void 0) {
-            let shadowRoot = element.shadowRoot;
-            if (shadowRoot) {
-                this.hasExistingShadowRoot = true;
-            }
-            else {
-                shadowRoot = element.attachShadow(shadowOptions);
-                if (shadowOptions.mode === "closed") {
-                    shadowRoots.set(element, shadowRoot);
-                }
-            }
-        }
-        // Capture any observable values that were set by the binding engine before
-        // the browser upgraded the element. Then delete the property since it will
-        // shadow the getter/setter that is required to make the observable operate.
-        // Later, in the connect callback, we'll re-apply the values.
-        const accessors = Observable.getAccessors(element);
-        if (accessors.length > 0) {
-            const boundObservables = (this.boundObservables = Object.create(null));
-            for (let i = 0, ii = accessors.length; i < ii; ++i) {
-                const propertyName = accessors[i].name;
-                const value = element[propertyName];
-                if (value !== void 0) {
-                    delete element[propertyName];
-                    boundObservables[propertyName] = value;
-                }
-            }
-        }
-    }
     /**
      * Indicates whether or not the custom element has been
      * connected to the document.
      */
     get isConnected() {
         Observable.track(this, isConnectedPropertyName);
-        return this.stage === 1 /* Stages.connected */;
+        return this.stage === Stages.connected;
     }
     /**
      * The context the expression is evaluated against.
@@ -3474,6 +3826,28 @@ class ElementController extends PropertyChangeNotifier {
             this.renderTemplate(value);
         }
     }
+    /**
+     * The shadow root options for the component.
+     */
+    get shadowOptions() {
+        return this._shadowRootOptions;
+    }
+    set shadowOptions(value) {
+        // options on the shadowRoot can only be set once
+        if (this._shadowRootOptions === void 0 && value !== void 0) {
+            this._shadowRootOptions = value;
+            let shadowRoot = this.source.shadowRoot;
+            if (shadowRoot) {
+                this.hasExistingShadowRoot = true;
+            }
+            else {
+                shadowRoot = this.source.attachShadow(value);
+                if (value.mode === "closed") {
+                    shadowRoots.set(this.source, shadowRoot);
+                }
+            }
+        }
+    }
     /**
      * The main set of styles used for the component, independent
      * of any dynamically added styles.
@@ -3492,19 +3866,103 @@ class ElementController extends PropertyChangeNotifier {
                 this._mainStyles = (_a = definition.styles) !== null && _a !== void 0 ? _a : null;
             }
         }
-        return this._mainStyles;
-    }
-    set mainStyles(value) {
-        if (this._mainStyles === value) {
-            return;
-        }
-        if (this._mainStyles !== null) {
-            this.removeStyles(this._mainStyles);
-        }
-        this._mainStyles = value;
-        if (!this.needsInitialization) {
-            this.addStyles(value);
-        }
+        return this._mainStyles;
+    }
+    set mainStyles(value) {
+        if (this._mainStyles === value) {
+            return;
+        }
+        if (this._mainStyles !== null) {
+            this.removeStyles(this._mainStyles);
+        }
+        this._mainStyles = value;
+        if (!this.needsInitialization) {
+            this.addStyles(value);
+        }
+    }
+    /**
+     * Creates a Controller to control the specified element.
+     * @param element - The element to be controlled by this controller.
+     * @param definition - The element definition metadata that instructs this
+     * controller in how to handle rendering and other platform integrations.
+     * @internal
+     */
+    constructor(element, definition) {
+        super(element);
+        /**
+         * A map of observable properties that were set on the element before upgrade.
+         */
+        this.boundObservables = null;
+        /**
+         * Indicates whether the controller needs to perform initial rendering.
+         */
+        this.needsInitialization = true;
+        /**
+         * Indicates whether the element has an existing shadow root (e.g. from declarative shadow DOM).
+         */
+        this.hasExistingShadowRoot = false;
+        /**
+         * The template used to render the component.
+         */
+        this._template = null;
+        /**
+         * The current lifecycle stage of the controller.
+         */
+        this.stage = Stages.disconnected;
+        /**
+         * A guard against connecting behaviors multiple times
+         * during connect in scenarios where a behavior adds
+         * another behavior during it's connectedCallback
+         */
+        this.guardBehaviorConnection = false;
+        /**
+         * The behaviors associated with the component.
+         */
+        this.behaviors = null;
+        /**
+         * Tracks whether behaviors are connected so that
+         * behaviors cant be connected multiple times
+         */
+        this.behaviorsConnected = false;
+        /**
+         * The main set of styles used for the component, independent of any
+         * dynamically added styles.
+         */
+        this._mainStyles = null;
+        /**
+         * This allows Observable.getNotifier(...) to return the Controller
+         * when the notifier for the Controller itself is being requested. The
+         * result is that the Observable system does not need to create a separate
+         * instance of Notifier for observables on the Controller. The component and
+         * the controller will now share the same notifier, removing one-object construct
+         * per web component instance.
+         */
+        this.$fastController = this;
+        /**
+         * The view associated with the custom element.
+         * @remarks
+         * If `null` then the element is managing its own rendering.
+         */
+        this.view = null;
+        this.source = element;
+        this.definition = definition;
+        this.shadowOptions = definition.shadowOptions;
+        // Capture any observable values that were set by the binding engine before
+        // the browser upgraded the element. Then delete the property since it will
+        // shadow the getter/setter that is required to make the observable operate.
+        // Later, in the connect callback, we'll re-apply the values.
+        const accessors = Observable.getAccessors(element);
+        if (accessors.length > 0) {
+            const boundObservables = (this.boundObservables = Object.create(null));
+            for (let i = 0, ii = accessors.length; i < ii; ++i) {
+                const propertyName = accessors[i].name;
+                const value = element[propertyName];
+                if (value !== void 0) {
+                    delete element[propertyName];
+                    boundObservables[propertyName] = value;
+                }
+            }
+        }
     }
     /**
      * Registers an unbind handler with the controller.
@@ -3527,7 +3985,7 @@ class ElementController extends PropertyChangeNotifier {
             behavior.addedCallback && behavior.addedCallback(this);
             if (behavior.connectedCallback &&
                 !this.guardBehaviorConnection &&
-                (this.stage === 1 /* Stages.connected */ || this.stage === 0 /* Stages.connecting */)) {
+                (this.stage === Stages.connected || this.stage === Stages.connecting)) {
                 behavior.connectedCallback(this);
             }
         }
@@ -3551,7 +4009,7 @@ class ElementController extends PropertyChangeNotifier {
         }
         if (count === 1 || force) {
             targetBehaviors.delete(behavior);
-            if (behavior.disconnectedCallback && this.stage !== 3 /* Stages.disconnected */) {
+            if (behavior.disconnectedCallback && this.stage !== Stages.disconnected) {
                 behavior.disconnectedCallback(this);
             }
             behavior.removedCallback && behavior.removedCallback(this);
@@ -3612,10 +4070,10 @@ class ElementController extends PropertyChangeNotifier {
      * Runs connected lifecycle behavior on the associated element.
      */
     connect() {
-        if (this.stage !== 3 /* Stages.disconnected */) {
+        if (this.stage !== Stages.disconnected) {
             return;
         }
-        this.stage = 0 /* Stages.connecting */;
+        this.stage = Stages.connecting;
         this.bindObservables();
         this.connectBehaviors();
         if (this.needsInitialization) {
@@ -3626,9 +4084,12 @@ class ElementController extends PropertyChangeNotifier {
         else if (this.view !== null) {
             this.view.bind(this.source);
         }
-        this.stage = 1 /* Stages.connected */;
+        this.stage = Stages.connected;
         Observable.notify(this, isConnectedPropertyName);
     }
+    /**
+     * Binds any observables that were set before upgrade.
+     */
     bindObservables() {
         if (this.boundObservables !== null) {
             const element = this.source;
@@ -3641,6 +4102,9 @@ class ElementController extends PropertyChangeNotifier {
             this.boundObservables = null;
         }
     }
+    /**
+     * Connects any existing behaviors on the associated element.
+     */
     connectBehaviors() {
         if (this.behaviorsConnected === false) {
             const behaviors = this.behaviors;
@@ -3654,6 +4118,9 @@ class ElementController extends PropertyChangeNotifier {
             this.behaviorsConnected = true;
         }
     }
+    /**
+     * Disconnects any behaviors on the associated element.
+     */
     disconnectBehaviors() {
         if (this.behaviorsConnected === true) {
             const behaviors = this.behaviors;
@@ -3669,16 +4136,16 @@ class ElementController extends PropertyChangeNotifier {
      * Runs disconnected lifecycle behavior on the associated element.
      */
     disconnect() {
-        if (this.stage !== 1 /* Stages.connected */) {
+        if (this.stage !== Stages.connected) {
             return;
         }
-        this.stage = 2 /* Stages.disconnecting */;
+        this.stage = Stages.disconnecting;
         Observable.notify(this, isConnectedPropertyName);
         if (this.view !== null) {
             this.view.unbind();
         }
         this.disconnectBehaviors();
-        this.stage = 3 /* Stages.disconnected */;
+        this.stage = Stages.disconnected;
     }
     /**
      * Runs the attribute changed callback for the associated element.
@@ -3701,11 +4168,18 @@ class ElementController extends PropertyChangeNotifier {
      * Only emits events if connected.
      */
     emit(type, detail, options) {
-        if (this.stage === 1 /* Stages.connected */) {
+        if (this.stage === Stages.connected) {
             return this.source.dispatchEvent(new CustomEvent(type, Object.assign(Object.assign({ detail }, defaultEventOptions), options)));
         }
         return false;
     }
+    /**
+     * Renders the provided template to the element.
+     *
+     * @param template - The template to render.
+     * @remarks
+     * If `null` is provided, any existing view will be removed.
+     */
     renderTemplate(template) {
         var _a;
         // When getting the host to render to, we start by looking
@@ -3735,20 +4209,33 @@ class ElementController extends PropertyChangeNotifier {
     /**
      * Locates or creates a controller for the specified element.
      * @param element - The element to return the controller for.
+     * @param override - Reset the controller even if one has been defined.
      * @remarks
      * The specified element must have a {@link FASTElementDefinition}
      * registered either through the use of the {@link customElement}
      * decorator or a call to `FASTElement.define`.
      */
-    static forCustomElement(element) {
+    static forCustomElement(element, override = false) {
         const controller = element.$fastController;
-        if (controller !== void 0) {
+        if (controller !== void 0 && !override) {
             return controller;
         }
         const definition = FASTElementDefinition.getForInstance(element);
         if (definition === void 0) {
-            throw FAST.error(1401 /* Message.missingElementDefinition */);
+            throw FAST.error(Message.missingElementDefinition);
         }
+        Observable.getNotifier(definition).subscribe({
+            handleChange: () => {
+                ElementController.forCustomElement(element, true);
+                element.$fastController.connect();
+            },
+        }, "template");
+        Observable.getNotifier(definition).subscribe({
+            handleChange: () => {
+                ElementController.forCustomElement(element, true);
+                element.$fastController.connect();
+            },
+        }, "shadowOptions");
         return (element.$fastController = new elementControllerStrategy(element, definition));
     }
     /**
@@ -3880,7 +4367,10 @@ if (ElementStyles.supportsAdoptedStyleSheets) {
 else {
     ElementStyles.setDefaultStrategy(StyleElementStrategy);
 }
-const deferHydrationAttribute = "defer-hydration";
+/**
+ * The attribute used to indicate that an element needs hydration.
+ * @public
+ */
 const needsHydrationAttribute = "needs-hydration";
 /**
  * An ElementController capable of hydrating FAST elements from
@@ -3889,22 +4379,90 @@ const needsHydrationAttribute = "needs-hydration";
  * @beta
  */
 class HydratableElementController extends ElementController {
+    /**
+     * {@inheritdoc ElementController.shadowOptions}
+     */
+    get shadowOptions() {
+        return super.shadowOptions;
+    }
+    set shadowOptions(value) {
+        super.shadowOptions = value;
+        if ((this.hasExistingShadowRoot || (value !== void 0 && !this.template)) &&
+            this.definition.templateOptions === TemplateOptions.deferAndHydrate) {
+            this.source.toggleAttribute(deferHydrationAttribute, true);
+            this.source.toggleAttribute(needsHydrationAttribute, true);
+        }
+    }
+    /**
+     * Adds the current element instance to the hydrating instances map
+     */
+    addHydratingInstance() {
+        if (!HydratableElementController.hydratingInstances) {
+            return;
+        }
+        const name = this.definition.name;
+        let instances = HydratableElementController.hydratingInstances.get(name);
+        if (!instances) {
+            instances = new Set();
+            HydratableElementController.hydratingInstances.set(name, instances);
+        }
+        instances.add(this.source);
+    }
+    /**
+     * Configure lifecycle callbacks for hydration events
+     */
+    static config(callbacks) {
+        HydratableElementController.lifecycleCallbacks = callbacks;
+        return this;
+    }
     static hydrationObserverHandler(records) {
         for (const record of records) {
-            HydratableElementController.hydrationObserver.unobserve(record.target);
-            record.target.$fastController.connect();
+            if (!record.target.hasAttribute(deferHydrationAttribute)) {
+                HydratableElementController.hydrationObserver.unobserve(record.target);
+                record.target.$fastController.connect();
+            }
+        }
+    }
+    /**
+     * Checks to see if hydration is complete and if so, invokes the hydrationComplete callback.
+     * Then resets the ElementController strategy to the default so that future elements
+     * don't use the HydratableElementController.
+     *
+     * @param deadline - the idle deadline object
+     */
+    static checkHydrationComplete(deadline) {
+        var _a, _b, _c;
+        if (deadline.didTimeout) {
+            HydratableElementController.idleCallbackId = requestIdleCallback(HydratableElementController.checkHydrationComplete, { timeout: 50 });
+            return;
+        }
+        // If there are no more hydrating instances, invoke the hydrationComplete callback
+        if (((_a = HydratableElementController.hydratingInstances) === null || _a === void 0 ? void 0 : _a.size) === 0) {
+            try {
+                (_c = (_b = HydratableElementController.lifecycleCallbacks).hydrationComplete) === null || _c === void 0 ? void 0 : _c.call(_b);
+            }
+            catch (_d) {
+                // A lifecycle callback must never prevent post-hydration cleanup.
+            }
+            // Reset to the default strategy after hydration is complete
+            ElementController.setStrategy(ElementController);
         }
     }
+    /**
+     * Runs connected lifecycle behavior on the associated element.
+     */
     connect() {
-        var _a, _b;
+        var _a, _b, _c, _d, _e, _f, _g;
         // Initialize needsHydration on first connect
-        if (this.needsHydration === undefined) {
-            this.needsHydration =
-                this.source.getAttribute(needsHydrationAttribute) !== null;
+        this.needsHydration =
+            (_a = this.needsHydration) !== null && _a !== void 0 ? _a : this.source.hasAttribute(needsHydrationAttribute);
+        if (this.needsHydration) {
+            this.addHydratingInstance();
         }
         // If the `defer-hydration` attribute exists on the source,
         // wait for it to be removed before continuing connection behavior.
         if (this.source.hasAttribute(deferHydrationAttribute)) {
+            this.addHydratingInstance();
             HydratableElementController.hydrationObserver.observe(this.source, {
                 attributeFilter: [deferHydrationAttribute],
             });
@@ -3916,18 +4474,34 @@ class HydratableElementController extends ElementController {
         // class
         if (!this.needsHydration) {
             super.connect();
+            this.removeHydratingInstance();
             return;
         }
-        if (this.stage !== 3 /* Stages.disconnected */) {
+        if (this.stage !== Stages.disconnected) {
             return;
         }
-        this.stage = 0 /* Stages.connecting */;
+        if (!HydratableElementController.hydrationStarted) {
+            HydratableElementController.hydrationStarted = true;
+            try {
+                (_c = (_b = HydratableElementController.lifecycleCallbacks).hydrationStarted) === null || _c === void 0 ? void 0 : _c.call(_b);
+            }
+            catch (_h) {
+                // A lifecycle callback must never prevent hydration.
+            }
+        }
+        try {
+            (_e = (_d = HydratableElementController.lifecycleCallbacks).elementWillHydrate) === null || _e === void 0 ? void 0 : _e.call(_d, this.source);
+        }
+        catch (_j) {
+            // A lifecycle callback must never prevent hydration.
+        }
+        this.stage = Stages.connecting;
         this.bindObservables();
         this.connectBehaviors();
-        const element = this.source;
-        const host = (_a = getShadowRoot(element)) !== null && _a !== void 0 ? _a : element;
         if (this.template) {
             if (isHydratable(this.template)) {
+                const element = this.source;
+                const host = (_f = getShadowRoot(element)) !== null && _f !== void 0 ? _f : element;
                 let firstChild = host.firstChild;
                 let lastChild = host.lastChild;
                 if (element.shadowRoot === null) {
@@ -3942,27 +4516,86 @@ class HydratableElementController extends ElementController {
                     }
                 }
                 this.view = this.template.hydrate(firstChild, lastChild, element);
-                (_b = this.view) === null || _b === void 0 ? void 0 : _b.bind(this.source);
+                (_g = this.view) === null || _g === void 0 ? void 0 : _g.bind(this.source);
             }
             else {
                 this.renderTemplate(this.template);
             }
         }
         this.addStyles(this.mainStyles);
-        this.stage = 1 /* Stages.connected */;
+        this.stage = Stages.connected;
         this.source.removeAttribute(needsHydrationAttribute);
         this.needsInitialization = this.needsHydration = false;
+        this.removeHydratingInstance();
         Observable.notify(this, isConnectedPropertyName);
     }
+    /**
+     * Removes the current element instance from the hydrating instances map
+     */
+    removeHydratingInstance() {
+        var _a, _b;
+        if (!HydratableElementController.hydratingInstances) {
+            return;
+        }
+        try {
+            (_b = (_a = HydratableElementController.lifecycleCallbacks).elementDidHydrate) === null || _b === void 0 ? void 0 : _b.call(_a, this.source);
+        }
+        catch (_c) {
+            // A lifecycle callback must never prevent hydration.
+        }
+        const name = this.definition.name;
+        const instances = HydratableElementController.hydratingInstances.get(name);
+        if (instances) {
+            instances.delete(this.source);
+            if (!instances.size) {
+                HydratableElementController.hydratingInstances.delete(name);
+            }
+            if (HydratableElementController.idleCallbackId) {
+                cancelIdleCallback(HydratableElementController.idleCallbackId);
+            }
+            HydratableElementController.idleCallbackId = requestIdleCallback(HydratableElementController.checkHydrationComplete, { timeout: 50 });
+        }
+    }
+    /**
+     * Unregisters the hydration observer when the element is disconnected.
+     */
     disconnect() {
         super.disconnect();
         HydratableElementController.hydrationObserver.unobserve(this.source);
     }
+    /**
+     * Sets the ElementController strategy to HydratableElementController.
+     * @remarks
+     * This method is typically called during application startup to enable
+     * hydration support for FAST elements.
+     */
     static install() {
         ElementController.setStrategy(HydratableElementController);
     }
 }
 HydratableElementController.hydrationObserver = new UnobservableMutationObserver(HydratableElementController.hydrationObserverHandler);
+/**
+ * Lifecycle callbacks for hydration events
+ */
+HydratableElementController.lifecycleCallbacks = {};
+/**
+ * Whether the hydrationStarted callback has already been invoked.
+ */
+HydratableElementController.hydrationStarted = false;
+/**
+ * An idle callback ID used to track hydration completion
+ */
+HydratableElementController.idleCallbackId = null;
+/**
+ * A map of element instances by the name of the custom element they are
+ * associated with. The key is the custom element name, and the value is the
+ * instances of hydratable elements which currently need to be hydrated.
+ *
+ * When all of the instances in the set have been hydrated, the set is
+ * cleared and removed from the map. If the map is empty, the
+ * hydrationComplete callback is invoked.
+ */
+HydratableElementController.hydratingInstances = new Map();
 
 /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
 function createFASTElement(BaseType) {
@@ -3994,6 +4627,24 @@ function compose(type, nameOrDef) {
     }
     return FASTElementDefinition.compose(this, type);
 }
+function defineAsync(type, nameOrDef) {
+    if (isFunction(type)) {
+        return new Promise(resolve => {
+            FASTElementDefinition.composeAsync(type, nameOrDef).then(value => {
+                resolve(value);
+            });
+        }).then(value => {
+            return value.define().type;
+        });
+    }
+    return new Promise(resolve => {
+        FASTElementDefinition.composeAsync(this, type).then(value => {
+            resolve(value);
+        });
+    }).then(value => {
+        return value.define().type;
+    });
+}
 function define(type, nameOrDef) {
     if (isFunction(type)) {
         return FASTElementDefinition.compose(type, nameOrDef).define().type;
@@ -4027,6 +4678,11 @@ const FASTElement = Object.assign(createFASTElement(HTMLElement), {
      * @public
      */
     compose,
+    /**
+     * Defines metadata for a FASTElement which can be used after it has been resolved to define the element.
+     * @alpha
+     */
+    defineAsync,
 });
 
 function staticallyCompose(item) {
@@ -4414,7 +5070,7 @@ const AccordionExpandMode = {
 };
 const tagName$E = `${FluentDesignSystem.prefix}-accordion`;
 
-function requestIdleCallback(callback, options) {
+function requestIdleCallback$1(callback, options) {
   if ("requestIdleCallback" in globalThis) {
     return globalThis.requestIdleCallback(callback, options);
   }
@@ -4434,13 +5090,13 @@ function waitForConnectedDescendants(target, callback, options) {
   const scheduleCheck = (deadline) => {
     if (target.querySelector(selector) === null || deadline && deadline.timeRemaining() <= 0) {
       if (useIdleCallback) {
-        requestIdleCallback(callback, { timeout });
+        requestIdleCallback$1(callback, { timeout });
       } else {
         callback();
       }
       return;
     }
-    requestIdleCallback(scheduleCheck, { timeout });
+    requestIdleCallback$1(scheduleCheck, { timeout });
   };
   scheduleCheck();
 }
@@ -6146,7 +6802,7 @@ class CompoundButton extends Button {
 const styles$x = css`${styles$C} :host,:host(:is([size])){gap:12px;height:auto;padding-top:14px;padding-inline:12px;padding-bottom:16px;font-size:${fontSizeBase300};line-height:${lineHeightBase300}}.content{display:flex;flex-direction:column;text-align:start}::slotted([slot='description']){color:${colorNeutralForeground2};line-height:100%;font-size:${fontSizeBase200};font-weight:${fontWeightRegular}}::slotted(svg),:host([size='large']) ::slotted(svg){font-size:40px;height:40px;width:40px}:host(:hover) ::slotted([slot='description']){color:${colorNeutralForeground2Hover}}:host(:active) ::slotted([slot='description']){color:${colorNeutralForeground2Pressed}}:host(:is([appearance='primary'],[appearance='primary']:is(:hover,:active))) ::slotted([slot='description']){color:${colorNeutralForegroundOnBrand}}:host(:is([appearance='transparent'],[appearance='subtle'],[appearance='subtle']:is(:hover,:active))) ::slotted([slot='description']){color:${colorNeutralForeground2}}:host([appearance='transparent']:hover) ::slotted([slot='description']){color:${colorNeutralForeground2BrandHover}}:host([appearance='transparent']:active) ::slotted([slot='description']){color:${colorNeutralForeground2BrandPressed}}:host(:is(:disabled,:disabled[appearance],[disabled-focusable],[disabled-focusable][appearance])) ::slotted([slot='description']){color:${colorNeutralForegroundDisabled}}:host([size='small']){padding:8px;padding-bottom:10px}:host([icon-only]){min-width:52px;max-width:52px;padding:${spacingHorizontalSNudge}}:host([icon-only][size='small']){min-width:48px;max-width:48px;padding:${spacingHorizontalXS}}:host([icon-only][size='large']){min-width:56px;max-width:56px;padding:${spacingHorizontalS}}:host([size='large']){padding-top:18px;padding-inline:16px;padding-bottom:20px;font-size:${fontSizeBase400};line-height:${lineHeightBase400}}:host([size='large']) ::slotted([slot='description']){font-size:${fontSizeBase300}}@media (forced-colors:active){:host([appearance='primary']:not(:hover,:focus-visible,:disabled,[disabled-focusable])) ::slotted([slot='description']){color:HighlightText}}`;
 
 function buttonTemplate(options = {}) {
-  return html`<template ?disabled=${(x) => x.disabled} tabindex=${(x) => x.disabled ? null : x.tabIndex ?? 0}>${startSlotTemplate(options)} <span class=content part=content><slot ${slotted("defaultSlottedContent")}></slot><slot name=description></slot></span>${endSlotTemplate(options)}</template>`;
+  return html`<template @click=${(x, c) => x.clickHandler(c.event)} @keypress=${(x, c) => x.keypressHandler(c.event)}>${startSlotTemplate(options)} <span class=content part=content><slot ${slotted("defaultSlottedContent")}></slot><slot name=description></slot></span>${endSlotTemplate(options)}</template>`;
 }
 const template$y = buttonTemplate();
 
@@ -6274,19 +6930,6 @@ var __decorateClass$B = (decorators, target, key, kind) => {
 class Dialog extends FASTElement {
   constructor() {
     super(...arguments);
-    this.type = DialogType.modal;
-    /**
-     * Method to emit an event before the dialog's open state changes
-     * HTML spec proposal: https://github.com/whatwg/html/issues/9733
-     *
-     * @public
-     */
-    this.emitBeforeToggle = () => {
-      this.$emit("beforetoggle", {
-        oldState: this.dialog.open ? "open" : "closed",
-        newState: this.dialog.open ? "closed" : "open"
-      });
-    };
     /**
      * Method to emit an event after the dialog's open state changes
      * HTML spec proposal: https://github.com/whatwg/html/issues/9733
@@ -6300,11 +6943,48 @@ class Dialog extends FASTElement {
       });
     };
   }
-  dialogChanged() {
-    this.updateDialogAttributes();
+  get dialogDescribedby() {
+    if (this.dialog) {
+      return this.ariaDescribedby;
+    }
   }
-  typeChanged(prev, next) {
-    this.updateDialogAttributes();
+  get dialogLabel() {
+    if (this.dialog) {
+      return this.ariaLabel;
+    }
+  }
+  get dialogLabelledby() {
+    if (this.dialog) {
+      return this.ariaLabelledby;
+    }
+  }
+  get dialogModal() {
+    if (this.dialog && this.type !== DialogType.nonModal) {
+      return true;
+    }
+  }
+  get dialogRole() {
+    if (this.dialog && this.type === DialogType.alert) {
+      return "alertdialog";
+    }
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    Updates.enqueue(() => {
+      this.type = this.type ?? DialogType.modal;
+    });
+  }
+  /**
+   * Method to emit an event before the dialog's open state changes
+   * HTML spec proposal: https://github.com/whatwg/html/issues/9733
+   *
+   * @public
+   */
+  emitBeforeToggle() {
+    this.$emit("beforetoggle", {
+      oldState: this.dialog.open ? "open" : "closed",
+      newState: this.dialog.open ? "closed" : "open"
+    });
   }
   /**
    * Method to show the dialog
@@ -6345,26 +7025,6 @@ class Dialog extends FASTElement {
     }
     return true;
   }
-  /**
-   * Updates the internal dialog element's attributes based on its type.
-   *
-   * @internal
-   */
-  updateDialogAttributes() {
-    if (!this.dialog) {
-      return;
-    }
-    if (this.type === DialogType.alert) {
-      this.dialog.setAttribute("role", "alertdialog");
-    } else {
-      this.dialog.removeAttribute("role");
-    }
-    if (this.type !== DialogType.nonModal) {
-      this.dialog.setAttribute("aria-modal", "true");
-    } else {
-      this.dialog.removeAttribute("aria-modal");
-    }
-  }
 }
 __decorateClass$B([
   observable
@@ -6381,8 +7041,23 @@ __decorateClass$B([
 __decorateClass$B([
   attr
 ], Dialog.prototype, "type", 2);
+__decorateClass$B([
+  volatile
+], Dialog.prototype, "dialogDescribedby", 1);
+__decorateClass$B([
+  volatile
+], Dialog.prototype, "dialogLabel", 1);
+__decorateClass$B([
+  volatile
+], Dialog.prototype, "dialogLabelledby", 1);
+__decorateClass$B([
+  volatile
+], Dialog.prototype, "dialogModal", 1);
+__decorateClass$B([
+  volatile
+], Dialog.prototype, "dialogRole", 1);
 
-const template$w = html`<dialog class=dialog part=dialog aria-describedby=${(x) => x.ariaDescribedby} aria-labelledby=${(x) => x.ariaLabelledby} aria-label=${(x) => x.ariaLabel} @click=${(x, c) => x.clickHandler(c.event)} @cancel=${(x) => x.hide()} ${ref("dialog")}><slot></slot></dialog>`;
+const template$w = html`<dialog class=dialog part=dialog aria-modal=${(x) => x.dialogModal} aria-describedby=${(x) => x.dialogDescribedby} aria-labelledby=${(x) => x.dialogLabelledby} aria-label=${(x) => x.dialogLabel} role=${(x) => x.dialogRole} @click=${(x, c) => x.clickHandler(c.event)} @cancel=${(x) => x.hide()} ${ref("dialog")}><slot></slot></dialog>`;
 
 const styles$v = css`@layer base{:host{--dialog-backdrop:${colorBackgroundOverlay};--dialog-starting-scale:0.85}::backdrop{background:var(--dialog-backdrop,rgba(0,0,0,0.4))}dialog{background:${colorNeutralBackground1};border-radius:${borderRadiusXLarge};border:none;box-shadow:${shadow64};color:${colorNeutralForeground1};max-height:100vh;padding:0;width:100%;max-width:600px}:host([type='non-modal']) dialog{inset:0;position:fixed;z-index:2;overflow:auto}@supports (max-height:1dvh){dialog{max-height:100dvh}}}@layer animations{@media (prefers-reduced-motion:no-preference){dialog,::backdrop{transition:display allow-discrete,opacity,overlay allow-discrete,scale;transition-duration:${durationGentle};transition-timing-function:${curveDecelerateMid};opacity:0}::backdrop{transition-timing-function:${curveLinear}}[open],[open]::backdrop{opacity:1}dialog:not([open]){scale:var(--dialog-starting-scale);transition-timing-function:${curveAccelerateMid}}}@starting-style{[open],[open]::backdrop{opacity:0}dialog{scale:var(--dialog-starting-scale)}}}@media (forced-colors:active){@layer base{dialog{border:${strokeWidthThin} solid ${colorTransparentStroke}}}}`;
 
@@ -6572,7 +7247,6 @@ var __decorateClass$y = (decorators, target, key, kind) => {
 class Drawer extends FASTElement {
   constructor() {
     super(...arguments);
-    this.type = DrawerType.modal;
     this.position = DrawerPosition.start;
     this.size = DrawerSize.medium;
     /**
@@ -6600,27 +7274,37 @@ class Drawer extends FASTElement {
       });
     };
   }
-  typeChanged() {
-    if (!this.dialog) {
-      return;
+  get dialogDescribedby() {
+    if (this.dialog) {
+      return this.ariaDescribedby;
     }
-    this.updateDialogRole();
-    if (this.type === DrawerType.modal) {
-      this.dialog.setAttribute("aria-modal", "true");
-    } else {
-      this.dialog.removeAttribute("aria-modal");
+  }
+  get dialogLabel() {
+    if (this.dialog) {
+      return this.ariaLabel;
     }
   }
-  /** @internal */
+  get dialogLabelledby() {
+    if (this.dialog) {
+      return this.ariaLabelledby;
+    }
+  }
+  get dialogModal() {
+    if (this.dialog && this.type === DrawerType.modal) {
+      return true;
+    }
+  }
+  get dialogRole() {
+    if (this.dialog && this.type === DrawerType.modal) {
+      return "dialog";
+    }
+    return this.role;
+  }
   connectedCallback() {
     super.connectedCallback();
-    this.typeChanged();
-    this.observeRoleAttr();
-  }
-  /** @internal */
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    this.roleAttrObserver.disconnect();
+    Updates.enqueue(() => {
+      this.type = this.type ?? DrawerType.modal;
+    });
   }
   /**
    * Method to show the drawer
@@ -6668,24 +7352,6 @@ class Drawer extends FASTElement {
   cancelHandler() {
     this.hide();
   }
-  observeRoleAttr() {
-    if (this.roleAttrObserver) {
-      return;
-    }
-    this.roleAttrObserver = new MutationObserver(() => {
-      this.updateDialogRole();
-    });
-    this.roleAttrObserver.observe(this, {
-      attributes: true,
-      attributeFilter: ["role"]
-    });
-  }
-  updateDialogRole() {
-    if (!this.dialog) {
-      return;
-    }
-    this.dialog.role = this.type === DrawerType.modal ? "dialog" : this.role;
-  }
 }
 __decorateClass$y([
   attr
@@ -6699,17 +7365,35 @@ __decorateClass$y([
 __decorateClass$y([
   attr
 ], Drawer.prototype, "position", 2);
+__decorateClass$y([
+  observable
+], Drawer.prototype, "role", 2);
 __decorateClass$y([
   attr({ attribute: "size" })
 ], Drawer.prototype, "size", 2);
 __decorateClass$y([
   observable
 ], Drawer.prototype, "dialog", 2);
+__decorateClass$y([
+  volatile
+], Drawer.prototype, "dialogDescribedby", 1);
+__decorateClass$y([
+  volatile
+], Drawer.prototype, "dialogLabel", 1);
+__decorateClass$y([
+  volatile
+], Drawer.prototype, "dialogLabelledby", 1);
+__decorateClass$y([
+  volatile
+], Drawer.prototype, "dialogModal", 1);
+__decorateClass$y([
+  volatile
+], Drawer.prototype, "dialogRole", 1);
 
 const styles$s = css`${display("block")} :host{--dialog-backdrop:${colorBackgroundOverlay}}:host([type='non-modal']) dialog[open]::backdrop{display:none}:host([type='non-modal']) dialog{position:fixed;top:0;bottom:0}:host([type='inline']){height:100%;width:fit-content}:host([type='inline']) dialog[open]{box-shadow:none;position:relative}:host([size='small']) dialog{width:320px;max-width:320px}:host([size='large']) dialog{width:940px;max-width:940px}:host([size='full']) dialog{width:100%;max-width:100%}:host([position='end']) dialog{margin-inline-start:auto;margin-inline-end:0}dialog{box-sizing:border-box;z-index:var(--drawer-elevation,1000);font-size:${fontSizeBase300};line-height:${lineHeightBase300};font-family:${fontFamilyBase};font-weight:${fontWeightRegular};color:${colorNeutralForeground1};max-width:var(--drawer-width,592px);max-height:100vh;height:100%;margin-inline-start:0;margin-inline-end:auto;border-inline-end-color:${colorTransparentStroke};border-inline-start-color:var(--drawer-separator,${colorTransparentStroke});outline:none;top:0;bottom:0;width:var(--drawer-width,592px);border-radius:0;padding:0;max-width:var(--drawer-width,592px);box-shadow:${shadow64};border:${strokeWidthThin} solid ${colorTransparentStroke};background:${colorNeutralBackground1}}dialog::backdrop{background:var(--dialog-backdrop)}@layer animations{@media (prefers-reduced-motion:no-preference){dialog{transition:display allow-discrete,opacity,overlay allow-discrete,transform;transition-duration:${durationGentle};transition-timing-function:${curveDecelerateMid}}:host dialog:not([open]){transform:translateX(-100%);transition-timing-function:${curveAccelerateMid}}:host([position='end']) dialog:not([open]){transform:translateX(100%);transition-timing-function:${curveAccelerateMid}}dialog[open]{transform:translateX(0)}dialog::backdrop{transition:display allow-discrete,opacity,overlay allow-discrete,scale;transition-duration:${durationGentle};transition-timing-function:${curveDecelerateMid};background:var(--dialog-backdrop,${colorBackgroundOverlay});opacity:0}dialog[open]::backdrop{opacity:1}dialog::backdrop{transition-timing-function:${curveLinear}}}@starting-style{dialog[open]{transform:translateX(-100%)}:host([position='end']) dialog[open]{transform:translateX(100%)}dialog[open]::backdrop{opacity:0}}}`;
 
 function drawerTemplate() {
-  return html`<dialog class=dialog part=dialog aria-describedby=${(x) => x.ariaDescribedby} aria-labelledby=${(x) => x.ariaLabelledby} aria-label=${(x) => x.ariaLabel} size=${(x) => x.size} position=${(x) => x.position} @click=${(x, c) => x.clickHandler(c.event)} @cancel=${(x) => x.cancelHandler()} ${ref("dialog")}><slot></slot></dialog>`;
+  return html`<dialog class=dialog part=dialog aria-describedby=${(x) => x.dialogDescribedby} aria-labelledby=${(x) => x.dialogLabelledby} aria-label=${(x) => x.dialogLabel} aria-modal=${(x) => x.dialogModal} role=${(x) => x.dialogRole} size=${(x) => x.size} position=${(x) => x.position} @click=${(x, c) => x.clickHandler(c.event)} @cancel=${(x) => x.cancelHandler()} ${ref("dialog")}><slot></slot></dialog>`;
 }
 const template$t = drawerTemplate();
 
@@ -9091,6 +9775,9 @@ const _BaseMenuList = class _BaseMenuList extends FASTElement {
    */
   disconnectedCallback() {
     super.disconnectedCallback();
+    Array.from(this.children).forEach((child) => {
+      Observable.getNotifier(child).unsubscribe(this, "hidden");
+    });
     this.menuChildren = void 0;
     this.removeEventListener("change", this.changedMenuItemHandler);
   }
@@ -9112,6 +9799,9 @@ const _BaseMenuList = class _BaseMenuList extends FASTElement {
   }
   setItems() {
     const children = Array.from(this.children);
+    children.forEach((child) => {
+      Observable.getNotifier(child).subscribe(this, "hidden");
+    });
     this.menuChildren = children.filter((child) => !child.hasAttribute("hidden"));
     this.menuItems = this.menuChildren?.filter(this.isMenuItemElement);
     const indent = this.menuItems?.reduce((accum, current) => {
@@ -13235,6 +13925,8 @@ class BaseTree extends FASTElement {
         if (item?.childTreeItems?.length) {
           if (!item.expanded) {
             item.expanded = true;
+          } else {
+            return true;
           }
         }
         return;
@@ -13359,7 +14051,7 @@ class Tree extends BaseTree {
       this.fg = new FocusGroup(this, this.fgItems, {
         definition: {
           behavior: "menu",
-          axis: "block",
+          axis: void 0,
           memory: false
         }
       });
@@ -13398,7 +14090,7 @@ __decorateClass$2([
 
 const styles$1 = css`${display("block")} :host{outline:none}`;
 
-const template$1 = html`<template focusgroup="menu nowrap nomemory" @click=${(x, c) => x.clickHandler(c.event)} @keydown=${(x, c) => x.keydownHandler(c.event)} @change=${(x, c) => x.changeHandler(c.event)} @toggle=${(x, c) => x.itemToggleHandler()}><slot ${ref("defaultSlot")} @slotchange=${(x) => x.handleDefaultSlotChange()}></slot></template>`;
+const template$1 = html`<template focusgroup="menu inline block nowrap nomemory" @click=${(x, c) => x.clickHandler(c.event)} @keydown=${(x, c) => x.keydownHandler(c.event)} @change=${(x, c) => x.changeHandler(c.event)} @toggle=${(x, c) => x.itemToggleHandler()}><slot ${ref("defaultSlot")} @slotchange=${(x) => x.handleDefaultSlotChange()}></slot></template>`;
 
 const definition$1 = Tree.compose({
   name: tagName$1,