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

package/dist/esm/templating/view.js

@@ -0,0 +1,298 @@
+import { ExecutionContext, Observable, SourceLifetime, } from "../observation/observable.js";
+import { makeSerializationNoop } from "../platform.js";
+/**
+ * Creates a child view from a template on behalf of a directive, carrying over the
+ * scoped custom element registry scope of the parent view (if it has one).
+ * For views without a scope this is exactly `template.create()`.
+ * @internal
+ */
+export function createChildView(template, controller) {
+    const scope = controller._scope;
+    return scope === void 0
+        ? template.create()
+        : template.create(void 0, scope);
+}
+export function removeNodeSequence(firstNode, lastNode) {
+    const parent = firstNode.parentNode;
+    let current = firstNode;
+    let next;
+    while (current !== lastNode) {
+        next = current.nextSibling;
+        if (!next) {
+            throw new Error(`Unmatched first/last child inside "${lastNode.getRootNode().host.nodeName}".`);
+        }
+        parent.removeChild(current);
+        current = next;
+    }
+    parent.removeChild(lastNode);
+}
+/**
+ * The default execution context for template views.
+ * @public
+ */
+export class DefaultExecutionContext {
+    constructor() {
+        /**
+         * The index of the current item within a repeat context.
+         */
+        this.index = 0;
+        /**
+         * The length of the current collection within a repeat context.
+         */
+        this.length = 0;
+    }
+    /**
+     * The current event within an event handler.
+     */
+    get event() {
+        return ExecutionContext.getEvent();
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an even index.
+     */
+    get isEven() {
+        return this.index % 2 === 0;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * has an odd index.
+     */
+    get isOdd() {
+        return this.index % 2 !== 0;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the first item in the collection.
+     */
+    get isFirst() {
+        return this.index === 0;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * is somewhere in the middle of the collection.
+     */
+    get isInMiddle() {
+        return !this.isFirst && !this.isLast;
+    }
+    /**
+     * Indicates whether the current item within a repeat context
+     * is the last item in the collection.
+     */
+    get isLast() {
+        return this.index === this.length - 1;
+    }
+    /**
+     * Returns the typed event detail of a custom event.
+     */
+    eventDetail() {
+        return this.event.detail;
+    }
+    /**
+     * Returns the typed event target of the event.
+     */
+    eventTarget() {
+        return this.event.target;
+    }
+}
+/**
+ * The standard View implementation, which also implements ElementView and SyntheticView.
+ * @public
+ */
+export class HTMLView extends DefaultExecutionContext {
+    /**
+     * Constructs an instance of HTMLView.
+     * @param fragment - The html fragment that contains the nodes for this view.
+     * @param behaviors - The behaviors to be applied to this view.
+     */
+    constructor(fragment, factories, targets, 
+    /**
+     * The shadow root whose scoped custom element registry this view's
+     * elements were created against, if any. Child views inherit it.
+     * @internal
+     */
+    _scope) {
+        super();
+        this.fragment = fragment;
+        this.factories = factories;
+        this.targets = targets;
+        this._scope = _scope;
+        this.behaviors = null;
+        this.unbindables = [];
+        /**
+         * The data that the view is bound to.
+         */
+        this.source = null;
+        /**
+         * Indicates whether the controller is bound.
+         */
+        this.isBound = false;
+        /**
+         * Indicates how the source's lifetime relates to the controller's lifetime.
+         */
+        this.sourceLifetime = SourceLifetime.unknown;
+        /**
+         * When true, directives skip attribute/booleanAttribute DOM
+         * updates during bind(). Set only during the prerendered bind
+         * window and cleared immediately after.
+         * @internal
+         */
+        this._skipAttrUpdates = false;
+        /**
+         * A promise that resolves with `true` after prerendered content
+         * has been hydrated, or `false` when the view is client-side
+         * rendered. Resolves once the first bind completes.
+         */
+        this.isPrerendered = Promise.resolve(false);
+        /**
+         * Resolves `true` after prerendered content has been hydrated,
+         * `false` when client-side rendered or hydration not enabled.
+         */
+        this.isHydrated = Promise.resolve(false);
+        /**
+         * The execution context the view is running within.
+         */
+        this.context = this;
+        this.firstChild = fragment.firstChild;
+        this.lastChild = fragment.lastChild;
+    }
+    /**
+     * Appends the view's DOM nodes to the referenced node.
+     * @param node - The parent node to append the view's DOM nodes to.
+     */
+    appendTo(node) {
+        node.appendChild(this.fragment);
+    }
+    /**
+     * Inserts the view's DOM nodes before the referenced node.
+     * @param node - The node to insert the view's DOM before.
+     */
+    insertBefore(node) {
+        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);
+        }
+    }
+    /**
+     * Removes the view's DOM nodes.
+     * The nodes are not disposed and the view can later be re-inserted.
+     */
+    remove() {
+        const fragment = this.fragment;
+        const end = this.lastChild;
+        let current = this.firstChild;
+        let next;
+        while (current !== end) {
+            next = current.nextSibling;
+            fragment.appendChild(current);
+            current = next;
+        }
+        fragment.appendChild(end);
+    }
+    /**
+     * 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);
+    }
+    /**
+     * 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.
+     */
+    bind(source, context = this) {
+        if (this.source === source && this.context === context) {
+            return;
+        }
+        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);
+            const factories = this.factories;
+            for (let i = 0, ii = factories.length; i < ii; ++i) {
+                const behavior = factories[i].createBehavior();
+                behavior.bind(this);
+                behaviors[i] = behavior;
+            }
+        }
+        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;
+    }
+    /**
+     * Unbinds a view's behaviors from its binding source.
+     */
+    unbind() {
+        if (!this.isBound || this.source === null) {
+            return;
+        }
+        this.evaluateUnbindables();
+        this.source = null;
+        this.context = this;
+        this.isBound = false;
+    }
+    evaluateUnbindables() {
+        const unbindables = this.unbindables;
+        for (let i = 0, ii = unbindables.length; i < ii; ++i) {
+            unbindables[i].unbind(this);
+        }
+        unbindables.length = 0;
+    }
+    /**
+     * Efficiently disposes of a contiguous range of synthetic view instances.
+     * @param views - A contiguous range of views to be disposed.
+     */
+    static disposeContiguousBatch(views) {
+        if (views.length === 0) {
+            return;
+        }
+        removeNodeSequence(views[0].firstChild, views[views.length - 1].lastChild);
+        for (let i = 0, ii = views.length; i < ii; ++i) {
+            views[i].unbind();
+        }
+    }
+}
+makeSerializationNoop(HTMLView);
+Observable.defineProperty(HTMLView.prototype, "index");
+Observable.defineProperty(HTMLView.prototype, "length");

package/dist/esm/templating/when.js

@@ -0,0 +1,22 @@
+import { isFunction } from "../interfaces.js";
+const noTemplate = () => null;
+function normalizeBinding(value) {
+    return value === undefined ? noTemplate : isFunction(value) ? value : () => value;
+}
+/**
+ * A directive that enables basic conditional rendering in a template.
+ * @param condition - The condition to test for rendering.
+ * @param templateOrTemplateBinding - The template or a binding that gets
+ * the template to render when the condition is true.
+ * @param elseTemplateOrTemplateBinding - Optional template or binding that that
+ * gets the template to render when the conditional is false.
+ * @public
+ */
+export function when(condition, templateOrTemplateBinding, elseTemplateOrTemplateBinding) {
+    const dataBinding = isFunction(condition) ? condition : () => condition;
+    const templateBinding = normalizeBinding(templateOrTemplateBinding);
+    const elseBinding = normalizeBinding(elseTemplateOrTemplateBinding);
+    return (source, context) => dataBinding(source, context)
+        ? templateBinding(source, context)
+        : elseBinding(source, context);
+}

package/dist/esm/testing/exports.js

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

package/dist/esm/testing/fakes.js

@@ -0,0 +1,107 @@
+import { noop } from "../interfaces.js";
+import { ExecutionContext } from "../observation/observable.js";
+export const Fake = Object.freeze({
+    executionContext(parent, parentContext) {
+        return {
+            /**
+             * The index of the current item within a repeat context.
+             */
+            index: 0,
+            /**
+             * The length of the current collection within a repeat context.
+             */
+            length: 0,
+            /**
+             * The parent data source within a nested context.
+             */
+            parent: parent,
+            /**
+             * The parent execution context when in nested context scenarios.
+             */
+            parentContext: parentContext,
+            /**
+             * The current event within an event handler.
+             */
+            get event() {
+                return ExecutionContext.getEvent();
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * has an even index.
+             */
+            get isEven() {
+                return this.index % 2 === 0;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * has an odd index.
+             */
+            get isOdd() {
+                return this.index % 2 !== 0;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * is the first item in the collection.
+             */
+            get isFirst() {
+                return this.index === 0;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * is somewhere in the middle of the collection.
+             */
+            get isInMiddle() {
+                return !this.isFirst && !this.isLast;
+            },
+            /**
+             * Indicates whether the current item within a repeat context
+             * is the last item in the collection.
+             */
+            get isLast() {
+                return this.index === this.length - 1;
+            },
+            /**
+             * Returns the typed event detail of a custom event.
+             */
+            eventDetail() {
+                return this.event.detail;
+            },
+            /**
+             * Returns the typed event target of the event.
+             */
+            eventTarget() {
+                return this.event.target;
+            },
+        };
+    },
+    viewController(targets = {}, ...behaviors) {
+        const unbindables = new Set();
+        return {
+            isBound: false,
+            context: null,
+            onUnbind(object) {
+                unbindables.add(object);
+            },
+            source: null,
+            targets,
+            toJSON: noop,
+            bind(source, context = Fake.executionContext()) {
+                if (this.isBound) {
+                    return;
+                }
+                this.source = source;
+                this.context = context;
+                behaviors.forEach(x => x.bind(this));
+                this.isBound = true;
+            },
+            unbind() {
+                if (this.isBound) {
+                    unbindables.forEach(x => x.unbind(this));
+                    this.source = null;
+                    this.context = null;
+                    this.isBound = false;
+                }
+            },
+        };
+    },
+});

package/dist/esm/testing/fixture.js

@@ -0,0 +1,86 @@
+var __awaiter = (this && this.__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());
+    });
+};
+import { FASTElementDefinition } from "../components/fast-definitions.js";
+import { ViewTemplate } from "../templating/template.js";
+function findElement(view) {
+    let current = view.firstChild;
+    while (current !== null && current.nodeType !== 1) {
+        current = current.nextSibling;
+    }
+    return current;
+}
+/**
+ * Creates a random, unique name suitable for use as a Custom Element name.
+ * @public
+ */
+export function uniqueElementName(prefix = "fast-unique") {
+    return `${prefix}-${Math.random().toString(36).substring(7)}`;
+}
+/**
+ * Creates a test fixture suitable for testing custom elements, templates, and bindings.
+ * @param templateNameOrType An HTML template or single element name to create the fixture for.
+ * @param options Enables customizing fixture creation behavior.
+ * @remarks
+ * Yields control to the caller one Microtask later, in order to
+ * ensure that the DOM has settled.
+ * @public
+ */
+export function fixture(templateNameOrType_1) {
+    return __awaiter(this, arguments, void 0, function* (templateNameOrType, options = {}) {
+        const document = options.document || globalThis.document;
+        const parent = options.parent || document.createElement("div");
+        const source = options.source || {};
+        if (typeof templateNameOrType === "function") {
+            const def = FASTElementDefinition.getByType(templateNameOrType);
+            if (!def) {
+                throw new Error("Missing FASTElement definition.");
+            }
+            templateNameOrType = def.name;
+        }
+        if (typeof templateNameOrType === "string") {
+            const html = `<${templateNameOrType}></${templateNameOrType}>`;
+            templateNameOrType = new ViewTemplate(html);
+        }
+        const view = templateNameOrType.create();
+        const element = findElement(view);
+        let isConnected = false;
+        view.bind(source);
+        view.appendTo(parent);
+        customElements.upgrade(parent);
+        // Hook into the Microtask Queue to ensure the DOM is settled
+        // before yielding control to the caller.
+        yield Promise.resolve();
+        const connect = () => __awaiter(this, void 0, void 0, function* () {
+            if (isConnected) {
+                return;
+            }
+            isConnected = true;
+            document.body.appendChild(parent);
+            yield Promise.resolve();
+        });
+        const disconnect = () => __awaiter(this, void 0, void 0, function* () {
+            if (!isConnected) {
+                return;
+            }
+            isConnected = false;
+            document.body.removeChild(parent);
+            yield Promise.resolve();
+        });
+        return {
+            document,
+            template: templateNameOrType,
+            view,
+            parent,
+            element,
+            connect,
+            disconnect,
+        };
+    });
+}

package/dist/esm/testing/models.js

@@ -0,0 +1,58 @@
+import { Observable, observable } from "../observation/observable.js";
+class ChildModel {
+}
+observable(ChildModel.prototype, "value");
+ChildModel.prototype.value = "value";
+class Model {
+    constructor() {
+        this.childChangedCalled = false;
+    }
+    childChanged() {
+        this.childChangedCalled = true;
+    }
+    incrementTrigger() {
+        this.trigger++;
+    }
+    decrementTrigger() {
+        this.trigger--;
+    }
+    get ifConditional() {
+        Observable.trackVolatile();
+        if (this.trigger < 1) {
+            return 42;
+        }
+        return this.value;
+    }
+}
+observable(Model.prototype, "child");
+Model.prototype.child = new ChildModel();
+observable(Model.prototype, "child2");
+Model.prototype.child2 = new ChildModel();
+observable(Model.prototype, "trigger");
+Model.prototype.trigger = 0;
+observable(Model.prototype, "value");
+Model.prototype.value = 10;
+Object.defineProperty(Model.prototype, "ternaryConditional", {
+    get() {
+        Observable.trackVolatile();
+        return this.trigger < 1 ? 42 : this.value;
+    },
+});
+Object.defineProperty(Model.prototype, "andCondition", {
+    get() {
+        Observable.trackVolatile();
+        return this.trigger && this.value;
+    },
+});
+class DerivedModel extends Model {
+    constructor() {
+        super(...arguments);
+        this.child2ChangedCalled = false;
+    }
+    child2Changed() {
+        this.child2ChangedCalled = true;
+    }
+}
+observable(DerivedModel.prototype, "derivedChild");
+DerivedModel.prototype.derivedChild = new ChildModel();
+export { ChildModel, DerivedModel, Model };

package/dist/esm/testing/timeout.js

@@ -0,0 +1,24 @@
+var __awaiter = (this && this.__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());
+    });
+};
+/**
+ * A timeout helper for use in tests.
+ * @param timeout The length of the timeout.
+ * @returns A promise that resolves once the configured time has elapsed.
+ * @public
+ */
+export function timeout() {
+    return __awaiter(this, arguments, void 0, function* (timeout = 0) {
+        return new Promise((resolve, reject) => {
+            window.setTimeout(() => {
+                resolve(void 0);
+            }, timeout);
+        });
+    });
+}

package/dist/esm/trust/index.js

@@ -0,0 +1,7 @@
+/**
+ * Trust Events - AFD trust signals for component events.
+ *
+ * @packageDocumentation
+ */
+export { TRUST_KEY } from "./types.js";
+export { getTrustSignals, hasTrustSignals } from "./utils.js";

package/dist/esm/trust/types.js

@@ -0,0 +1,6 @@
+/**
+ * Property key (the string `"__trust"`) under which trust metadata is stored in
+ * event detail.
+ * @public
+ */
+export const TRUST_KEY = "__trust";