@lushly-dev/fast-element 3.0.1-preview.0 → 3.0.1-preview.2

package/dist/esm/templating/html-binding-directive.js

@@ -0,0 +1,288 @@
+import { isHydratable } from "../components/hydration.js";
+import { DOM, DOMAspect } from "../dom.js";
+import { Message } from "../interfaces.js";
+import { ExecutionContext, } from "../observation/observable.js";
+import { FAST } from "../platform.js";
+import { HTMLDirective, } from "./html-directive.js";
+import { HydrationStage } from "./hydration-view.js";
+import { Markup } from "./markup.js";
+import { createChildView } from "./view.js";
+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.
+    if (value === null || value === undefined) {
+        value = "";
+    }
+    // If the value has a "create" method, then it's a ContentTemplate.
+    if (isContentTemplate(value)) {
+        target.textContent = "";
+        let view = target.$fastView;
+        // If there's no previous view that we might be able to
+        // reuse then create a new view from the template.
+        if (view === void 0) {
+            if (isHydratable(controller) &&
+                isHydratable(value) &&
+                controller.bindingViewBoundaries[this.targetNodeId] !== undefined &&
+                controller.hydrationStage !== HydrationStage.hydrated) {
+                const viewNodes = controller.bindingViewBoundaries[this.targetNodeId];
+                view = value.hydrate(viewNodes.first, viewNodes.last);
+            }
+            else {
+                view = createChildView(value, controller);
+            }
+        }
+        else {
+            // If there is a previous view, but it wasn't created
+            // from the same template as the new value, then we
+            // need to remove the old view if it's still in the DOM
+            // and create a new view from the template.
+            if (target.$fastTemplate !== value) {
+                if (view.isComposed) {
+                    view.remove();
+                    view.unbind();
+                }
+                view = createChildView(value, controller);
+            }
+        }
+        // It's possible that the value is the same as the previous template
+        // and that there's actually no need to compose it.
+        if (!view.isComposed) {
+            view.isComposed = true;
+            view.bind(controller.source, controller.context);
+            view.insertBefore(target);
+            target.$fastView = view;
+            target.$fastTemplate = value;
+        }
+        else if (view.needsBindOnly) {
+            view.needsBindOnly = false;
+            view.bind(controller.source, controller.context);
+        }
+    }
+    else {
+        const view = target.$fastView;
+        // If there is a view and it's currently composed into
+        // the DOM, then we need to remove it.
+        if (view !== void 0 && view.isComposed) {
+            view.isComposed = false;
+            view.remove();
+            if (view.needsBindOnly) {
+                view.needsBindOnly = false;
+            }
+            else {
+                view.unbind();
+            }
+        }
+        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`;
+    const state = (_a = target[lookup]) !== null && _a !== void 0 ? _a : (target[lookup] = { v: 0, cv: Object.create(null) });
+    const classVersions = state.cv;
+    let version = state.v;
+    const tokenList = target[aspect];
+    // Add the classes, tracking the version at which they were added.
+    if (value !== null && value !== undefined && value.length) {
+        const names = value.split(/\s+/);
+        for (let i = 0, ii = names.length; i < ii; ++i) {
+            const currentName = names[i];
+            if (currentName === "") {
+                continue;
+            }
+            classVersions[currentName] = version;
+            tokenList.add(currentName);
+        }
+    }
+    state.v = version + 1;
+    // If this is the first call to add classes, there's no need to remove old ones.
+    if (version === 0) {
+        return;
+    }
+    // Remove classes from the previous version.
+    version -= 1;
+    for (const name in classVersions) {
+        if (classVersions[name] === version) {
+            tokenList.remove(name);
+        }
+    }
+}
+/**
+ * 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,
+    [DOMAspect.property]: (t, a, v) => (t[a] = v),
+    [DOMAspect.content]: updateContent,
+    [DOMAspect.tokenList]: updateTokenList,
+    [DOMAspect.event]: () => void 0,
+};
+/**
+ * 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
+ */
+export class HTMLBindingDirective {
+    /**
+     * Creates an instance of HTMLBindingDirective.
+     * @param dataBinding - The binding configuration to apply.
+     */
+    constructor(dataBinding) {
+        this.updateTarget = null;
+        /**
+         * The type of aspect to target.
+         */
+        this.aspectType = DOMAspect.content;
+        this.dataBinding = dataBinding;
+    }
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add) {
+        return Markup.interpolation(add(this));
+    }
+    /**
+     * Creates a behavior.
+     */
+    createBehavior() {
+        var _a;
+        if (this.updateTarget === null) {
+            const sink = sinkLookup[this.aspectType];
+            const policy = (_a = this.dataBinding.policy) !== null && _a !== void 0 ? _a : this.policy;
+            if (!sink) {
+                throw FAST.error(Message.unsupportedBindingBehavior);
+            }
+            this.data = `${this.id}-d`;
+            this.updateTarget = policy.protect(this.targetTagName, this.aspectType, this.targetAspect, sink);
+        }
+        return this;
+    }
+    /**
+     * 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];
+        switch (this.aspectType) {
+            case DOMAspect.event:
+                target[this.data] = controller;
+                target.addEventListener(this.targetAspect, this, this.dataBinding.options);
+                break;
+            case DOMAspect.content:
+                controller.onUnbind(this);
+            // intentional fall through
+            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;
+                // Evaluate to establish dependency tracking
+                const value = observer.bind(controller);
+                // Skip DOM update for attribute bindings when prerendered —
+                // the server has already rendered the correct attribute values.
+                // Content, property, and tokenList bindings must still run
+                // so structural directives, host properties, and class lists
+                // are properly initialized.
+                if (controller._skipAttrUpdates &&
+                    (this.aspectType === DOMAspect.attribute ||
+                        this.aspectType === DOMAspect.booleanAttribute)) {
+                    break;
+                }
+                this.updateTarget(target, this.targetAspect, value, controller);
+                break;
+            }
+        }
+    }
+    /** @internal */
+    unbind(controller) {
+        const target = controller.targets[this.targetNodeId];
+        const view = target.$fastView;
+        if (view !== void 0 && view.isComposed) {
+            view.unbind();
+            view.needsBindOnly = true;
+        }
+    }
+    /**
+     * 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) {
+            ExecutionContext.setEvent(event);
+            const result = this.dataBinding.evaluate(controller.source, controller.context);
+            ExecutionContext.setEvent(null);
+            if (result !== true) {
+                event.preventDefault();
+            }
+        }
+    }
+    /**
+     * 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 });

package/dist/esm/templating/html-directive.js

@@ -0,0 +1,113 @@
+import { DOMAspect } from "../dom.js";
+import { createTypeRegistry, makeSerializationNoop } from "../platform.js";
+import { Markup } from "./markup.js";
+const registry = createTypeRegistry();
+/**
+ * Instructs the template engine to apply behavior to a node.
+ * @public
+ */
+export const HTMLDirective = Object.freeze({
+    /**
+     * Gets the directive definition associated with the instance.
+     * @param instance - The directive instance to retrieve the definition for.
+     */
+    getForInstance: registry.getForInstance,
+    /**
+     * Gets the directive definition associated with the specified type.
+     * @param type - The directive type to retrieve the definition for.
+     */
+    getByType: registry.getByType,
+    /**
+     * Defines an HTMLDirective based on the options.
+     * @param type - The type to define as a directive.
+     * @param options - Options that specify the directive's application.
+     */
+    define(type, options) {
+        options = options || {};
+        options.type = type;
+        registry.register(options);
+        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
+     * If a falsy value is provided, then the content aspect will be assigned.
+     */
+    assignAspect(directive, value) {
+        if (!value) {
+            directive.aspectType = DOMAspect.content;
+            return;
+        }
+        directive.sourceAspect = value;
+        switch (value[0]) {
+            case ":":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType =
+                    directive.targetAspect === "classList"
+                        ? DOMAspect.tokenList
+                        : DOMAspect.property;
+                break;
+            case "?":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType = DOMAspect.booleanAttribute;
+                break;
+            case "@":
+                directive.targetAspect = value.substring(1);
+                directive.aspectType = DOMAspect.event;
+                break;
+            default:
+                directive.targetAspect = value;
+                directive.aspectType = DOMAspect.attribute;
+                break;
+        }
+    },
+});
+/**
+ * Decorator: Defines an HTMLDirective.
+ * @param options - Provides options that specify the directive's application.
+ * @public
+ */
+export function htmlDirective(options) {
+    /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+    return function (type) {
+        HTMLDirective.define(type, options);
+    };
+}
+/**
+ * A base class used for attribute directives that don't need internal state.
+ * @public
+ */
+export class StatelessAttachedAttributeDirective {
+    /**
+     * Creates an instance of RefDirective.
+     * @param options - The options to use in configuring the directive.
+     */
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * Creates a placeholder string based on the directive's index within the template.
+     * @param index - The index of the directive within the template.
+     * @remarks
+     * Creates a custom attribute placeholder.
+     */
+    createHTML(add) {
+        return Markup.attribute(add(this));
+    }
+    /**
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior() {
+        return this;
+    }
+}
+makeSerializationNoop(StatelessAttachedAttributeDirective);

package/dist/esm/templating/html.js

@@ -0,0 +1 @@
+export { html } from "./template.js";

package/dist/esm/templating/hydration-view.js

@@ -0,0 +1,228 @@
+var _a;
+import { Hydratable } from "../components/hydration.js";
+import { getHostName, getHydrationDiagnostic, } from "../hydration/diagnostics.js";
+import { buildViewBindingTargets, createRangeForNodes, HydrationTargetElementError, targetFactory, } from "../hydration/target-builder.js";
+import { SourceLifetime } from "../observation/observable.js";
+import { makeSerializationNoop } from "../platform.js";
+import { DefaultExecutionContext, removeNodeSequence, } from "./view.js";
+/** @public */
+export const HydrationStage = {
+    unhydrated: "unhydrated",
+    hydrating: "hydrating",
+    hydrated: "hydrated",
+};
+/** @public */
+export class HydrationBindingError extends Error {
+    constructor(
+    /**
+     * The error message
+     */
+    message, 
+    /**
+     * The factory that was unable to be bound
+     */
+    factory, 
+    /**
+     * A DocumentFragment containing a clone of the
+     * view's Nodes.
+     */
+    fragment, 
+    /**
+     * String representation of the HTML in the template that
+     * threw the binding error.
+     */
+    templateString, 
+    /**
+     * Structured description of the binding the hydration walk was
+     * attempting to apply when the mismatch was detected.
+     */
+    expected, 
+    /**
+     * Structured description of the server-rendered DOM that was
+     * encountered at the mismatch point.
+     */
+    received) {
+        super(message);
+        this.factory = factory;
+        this.fragment = fragment;
+        this.templateString = templateString;
+        this.expected = expected;
+        this.received = received;
+    }
+}
+export 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.context = this;
+        this.source = null;
+        this.isBound = false;
+        this.sourceLifetime = SourceLifetime.unknown;
+        this.unbindables = [];
+        this.fragment = null;
+        this.behaviors = null;
+        this._hydrationStage = HydrationStage.unhydrated;
+        this._bindingViewBoundaries = {};
+        this._targets = {};
+        this.factories = sourceTemplate.compile().factories;
+    }
+    /**
+     * no-op. Hydrated views are don't need to be moved from a documentFragment
+     * to the target node.
+     */
+    insertBefore(node) {
+        // No-op in cases where this is called before the view is removed,
+        // because the nodes will already be in the document and just need hydrating.
+        if (this.fragment === null) {
+            return;
+        }
+        if (this.fragment.hasChildNodes()) {
+            node.parentNode.insertBefore(this.fragment, node);
+        }
+        else {
+            const end = this.lastChild;
+            if (node.previousSibling === end)
+                return;
+            const parentNode = node.parentNode;
+            let current = this.firstChild;
+            let next;
+            while (current !== end) {
+                next = current.nextSibling;
+                parentNode.insertBefore(current, node);
+                current = next;
+            }
+            parentNode.insertBefore(end, node);
+        }
+    }
+    /**
+     * Appends the view to a node. In cases where this is called before the
+     * view has been removed, the method will no-op.
+     * @param node - the node to append the view to.
+     */
+    appendTo(node) {
+        if (this.fragment !== null) {
+            node.appendChild(this.fragment);
+        }
+    }
+    remove() {
+        const fragment = this.fragment || (this.fragment = document.createDocumentFragment());
+        const end = this.lastChild;
+        let current = this.firstChild;
+        let next;
+        while (current !== end) {
+            next = current.nextSibling;
+            if (!next) {
+                throw new Error(`Unmatched first/last child inside "${end.getRootNode().host.nodeName}".`);
+            }
+            fragment.appendChild(current);
+            current = next;
+        }
+        fragment.appendChild(end);
+    }
+    bind(source, context = this) {
+        if (this.source === source && this.context === context) {
+            return;
+        }
+        if (this.hydrationStage !== HydrationStage.hydrated) {
+            this._hydrationStage = HydrationStage.hydrating;
+        }
+        let behaviors = this.behaviors;
+        if (behaviors === null) {
+            this.source = source;
+            this.context = context;
+            try {
+                const { targets, boundaries } = buildViewBindingTargets(this.firstChild, this.lastChild, this.factories);
+                this._targets = targets;
+                this._bindingViewBoundaries = boundaries;
+            }
+            catch (error) {
+                if (error instanceof HydrationTargetElementError) {
+                    let templateString = this.sourceTemplate.html;
+                    if (typeof templateString !== "string") {
+                        templateString = templateString.innerHTML;
+                    }
+                    error.templateString = templateString;
+                }
+                throw error;
+            }
+            this.behaviors = behaviors = new Array(this.factories.length);
+            const factories = this.factories;
+            for (let i = 0, ii = factories.length; i < ii; ++i) {
+                const factory = factories[i];
+                if (factory.targetNodeId === "h" && this.hostBindingTarget) {
+                    targetFactory(factory, this.hostBindingTarget, this._targets);
+                }
+                // If the binding has been targeted or it is a host binding and the view has a hostBindingTarget
+                if (factory.targetNodeId in this.targets) {
+                    const behavior = factory.createBehavior();
+                    behavior.bind(this);
+                    behaviors[i] = behavior;
+                }
+                else {
+                    let templateString = this.sourceTemplate.html;
+                    if (typeof templateString !== "string") {
+                        templateString = templateString.innerHTML;
+                    }
+                    const fragment = createRangeForNodes(this.firstChild, this.lastChild).cloneContents();
+                    const result = getHydrationDiagnostic().formatBindingMismatch(factory, this.firstChild, this.lastChild, getHostName(this.firstChild));
+                    throw new HydrationBindingError(result.message, factory, fragment, templateString, result.expected, result.received);
+                }
+            }
+        }
+        else {
+            if (this.source !== null) {
+                this.evaluateUnbindables();
+            }
+            this.isBound = false;
+            this.source = source;
+            this.context = context;
+            for (let i = 0, ii = behaviors.length; i < ii; ++i) {
+                behaviors[i].bind(this);
+            }
+        }
+        this.isBound = true;
+        this._hydrationStage = HydrationStage.hydrated;
+    }
+    unbind() {
+        if (!this.isBound || this.source === null) {
+            return;
+        }
+        this.evaluateUnbindables();
+        this.source = null;
+        this.context = this;
+        this.isBound = false;
+    }
+    /**
+     * Removes the view and unbinds its behaviors, disposing of DOM nodes afterward.
+     * Once a view has been disposed, it cannot be inserted or bound again.
+     */
+    dispose() {
+        removeNodeSequence(this.firstChild, this.lastChild);
+        this.unbind();
+    }
+    onUnbind(behavior) {
+        this.unbindables.push(behavior);
+    }
+    evaluateUnbindables() {
+        const unbindables = this.unbindables;
+        for (let i = 0, ii = unbindables.length; i < ii; ++i) {
+            unbindables[i].unbind(this);
+        }
+        unbindables.length = 0;
+    }
+}
+_a = Hydratable;
+makeSerializationNoop(HydrationView);