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

package/dist/esm/observation/notifier.js

@@ -0,0 +1,162 @@
+/**
+ * An implementation of {@link Notifier} that efficiently keeps track of
+ * subscribers interested in a specific change notification on an
+ * observable subject.
+ *
+ * @remarks
+ * This set is optimized for the most common scenario of 1 or 2 subscribers.
+ * With this in mind, it can store a subscriber in an internal field, allowing it to avoid Array#push operations.
+ * If the set ever exceeds two subscribers, it upgrades to an array automatically.
+ * @public
+ */
+export class SubscriberSet {
+    /**
+     * Creates an instance of SubscriberSet for the specified subject.
+     * @param subject - The subject that subscribers will receive notifications from.
+     * @param initialSubscriber - An initial subscriber to changes.
+     */
+    constructor(subject, initialSubscriber) {
+        this.sub1 = void 0;
+        this.sub2 = void 0;
+        this.spillover = void 0;
+        this.subject = subject;
+        this.sub1 = initialSubscriber;
+    }
+    /**
+     * Checks whether the provided subscriber has been added to this set.
+     * @param subscriber - The subscriber to test for inclusion in this set.
+     */
+    has(subscriber) {
+        return this.spillover === void 0
+            ? this.sub1 === subscriber || this.sub2 === subscriber
+            : this.spillover.indexOf(subscriber) !== -1;
+    }
+    /**
+     * Subscribes to notification of changes in an object's state.
+     * @param subscriber - The object that is subscribing for change notification.
+     */
+    subscribe(subscriber) {
+        const spillover = this.spillover;
+        if (spillover === void 0) {
+            if (this.has(subscriber)) {
+                return;
+            }
+            if (this.sub1 === void 0) {
+                this.sub1 = subscriber;
+                return;
+            }
+            if (this.sub2 === void 0) {
+                this.sub2 = subscriber;
+                return;
+            }
+            this.spillover = [this.sub1, this.sub2, subscriber];
+            this.sub1 = void 0;
+            this.sub2 = void 0;
+        }
+        else {
+            const index = spillover.indexOf(subscriber);
+            if (index === -1) {
+                spillover.push(subscriber);
+            }
+        }
+    }
+    /**
+     * Unsubscribes from notification of changes in an object's state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     */
+    unsubscribe(subscriber) {
+        const spillover = this.spillover;
+        if (spillover === void 0) {
+            if (this.sub1 === subscriber) {
+                this.sub1 = void 0;
+            }
+            else if (this.sub2 === subscriber) {
+                this.sub2 = void 0;
+            }
+        }
+        else {
+            const index = spillover.indexOf(subscriber);
+            if (index !== -1) {
+                spillover.splice(index, 1);
+            }
+        }
+    }
+    /**
+     * Notifies all subscribers.
+     * @param args - Data passed along to subscribers during notification.
+     */
+    notify(args) {
+        const spillover = this.spillover;
+        const subject = this.subject;
+        if (spillover === void 0) {
+            const sub1 = this.sub1;
+            const sub2 = this.sub2;
+            if (sub1 !== void 0) {
+                sub1.handleChange(subject, args);
+            }
+            if (sub2 !== void 0) {
+                sub2.handleChange(subject, args);
+            }
+        }
+        else {
+            for (let i = 0, ii = spillover.length; i < ii; ++i) {
+                spillover[i].handleChange(subject, args);
+            }
+        }
+    }
+}
+/**
+ * An implementation of Notifier that allows subscribers to be notified
+ * of individual property changes on an object.
+ * @public
+ */
+export class PropertyChangeNotifier {
+    /**
+     * Creates an instance of PropertyChangeNotifier for the specified subject.
+     * @param subject - The object that subscribers will receive notifications for.
+     */
+    constructor(subject) {
+        this.subscribers = {};
+        this.subjectSubscribers = null;
+        this.subject = subject;
+    }
+    /**
+     * Notifies all subscribers, based on the specified property.
+     * @param propertyName - The property name, passed along to subscribers during notification.
+     */
+    notify(propertyName) {
+        var _a, _b;
+        (_a = this.subscribers[propertyName]) === null || _a === void 0 ? void 0 : _a.notify(propertyName);
+        (_b = this.subjectSubscribers) === null || _b === void 0 ? void 0 : _b.notify(propertyName);
+    }
+    /**
+     * Subscribes to notification of changes in an object's state.
+     * @param subscriber - The object that is subscribing for change notification.
+     * @param propertyToWatch - The name of the property that the subscriber is interested in watching for changes.
+     */
+    subscribe(subscriber, propertyToWatch) {
+        var _a, _b;
+        let subscribers;
+        if (propertyToWatch) {
+            subscribers = (_a = this.subscribers[propertyToWatch]) !== null && _a !== void 0 ? _a : (this.subscribers[propertyToWatch] = new SubscriberSet(this.subject));
+        }
+        else {
+            subscribers = (_b = this.subjectSubscribers) !== null && _b !== void 0 ? _b : (this.subjectSubscribers = new SubscriberSet(this.subject));
+        }
+        subscribers.subscribe(subscriber);
+    }
+    /**
+     * Unsubscribes from notification of changes in an object's state.
+     * @param subscriber - The object that is unsubscribing from change notification.
+     * @param propertyToUnwatch - The name of the property that the subscriber is no longer interested in watching.
+     */
+    unsubscribe(subscriber, propertyToUnwatch) {
+        var _a, _b;
+        if (propertyToUnwatch) {
+            (_a = this.subscribers[propertyToUnwatch]) === null || _a === void 0 ? void 0 : _a.unsubscribe(subscriber);
+        }
+        else {
+            (_b = this.subjectSubscribers) === null || _b === void 0 ? void 0 : _b.unsubscribe(subscriber);
+        }
+    }
+}

package/dist/esm/observation/observable.js

@@ -0,0 +1,324 @@
+import { isFunction, isString, Message } from "../interfaces.js";
+import { createMetadataLocator, FAST, makeSerializationNoop } from "../platform.js";
+import { PropertyChangeNotifier, SubscriberSet } from "./notifier.js";
+import { Updates } from "./update-queue.js";
+/**
+ * Describes how the source's lifetime relates to its controller's lifetime.
+ * @public
+ */
+export const SourceLifetime = Object.freeze({
+    /**
+     * The source to controller lifetime relationship is unknown.
+     */
+    unknown: void 0,
+    /**
+     * The source and controller lifetimes are coupled to one another.
+     * They can/will be GC'd together.
+     */
+    coupled: 1,
+});
+/**
+ * Common Observable APIs.
+ * @public
+ */
+export const Observable = (() => {
+    const queueUpdate = Updates.enqueue;
+    const volatileRegex = /(:|&&|\|\||if|\?\.)/;
+    const notifierLookup = new WeakMap();
+    let watcher = void 0;
+    let createArrayObserver = (array) => {
+        throw FAST.error(Message.needsArrayObservation);
+    };
+    function getNotifier(source) {
+        var _a;
+        let found = (_a = source.$fastController) !== null && _a !== void 0 ? _a : notifierLookup.get(source);
+        if (found === void 0) {
+            Array.isArray(source)
+                ? (found = createArrayObserver(source))
+                : notifierLookup.set(source, (found = new PropertyChangeNotifier(source)));
+        }
+        return found;
+    }
+    const getAccessors = createMetadataLocator();
+    class DefaultObservableAccessor {
+        constructor(name) {
+            this.name = name;
+            this.field = `_${name}`;
+            this.callback = `${name}Changed`;
+        }
+        getValue(source) {
+            if (watcher !== void 0) {
+                watcher.watch(source, this.name);
+            }
+            return source[this.field];
+        }
+        setValue(source, newValue) {
+            const field = this.field;
+            const oldValue = source[field];
+            if (oldValue !== newValue) {
+                source[field] = newValue;
+                const callback = source[this.callback];
+                if (isFunction(callback)) {
+                    callback.call(source, oldValue, newValue);
+                }
+                getNotifier(source).notify(this.name);
+            }
+        }
+    }
+    class ExpressionNotifierImplementation extends SubscriberSet {
+        constructor(expression, initialSubscriber, isVolatileBinding = false) {
+            super(expression, initialSubscriber);
+            this.expression = expression;
+            this.isVolatileBinding = isVolatileBinding;
+            this.needsRefresh = true;
+            this.needsQueue = true;
+            this.isAsync = true;
+            this.first = this;
+            this.last = null;
+            this.propertySource = void 0;
+            this.propertyName = void 0;
+            this.notifier = void 0;
+            this.next = void 0;
+        }
+        setMode(isAsync) {
+            this.isAsync = this.needsQueue = isAsync;
+        }
+        bind(controller) {
+            const value = this.observe(controller.source, controller.context);
+            if (!controller.isBound && this.requiresUnbind(controller)) {
+                controller.onUnbind(this);
+            }
+            return value;
+        }
+        requiresUnbind(controller) {
+            return (controller.sourceLifetime !== SourceLifetime.coupled ||
+                this.first !== this.last ||
+                this.first.propertySource !== controller.source);
+        }
+        unbind(controller) {
+            this.dispose();
+        }
+        observe(source, context) {
+            if (this.needsRefresh && this.last !== null) {
+                this.dispose();
+            }
+            const previousWatcher = watcher;
+            watcher = this.needsRefresh ? this : void 0;
+            this.needsRefresh = this.isVolatileBinding;
+            let result;
+            try {
+                result = this.expression(source, context);
+            }
+            finally {
+                watcher = previousWatcher;
+            }
+            return result;
+        }
+        // backwards compat with v1 kernel
+        disconnect() {
+            this.dispose();
+        }
+        dispose() {
+            if (this.last !== null) {
+                let current = this.first;
+                while (current !== void 0) {
+                    current.notifier.unsubscribe(this, current.propertyName);
+                    current = current.next;
+                }
+                this.last = null;
+                // A disposed graph has no subscriptions, so the next observe()
+                // must always re-track, regardless of sync/async mode.
+                this.needsRefresh = true;
+                this.needsQueue = this.isAsync;
+            }
+        }
+        watch(propertySource, propertyName) {
+            const prev = this.last;
+            const notifier = getNotifier(propertySource);
+            const current = prev === null ? this.first : {};
+            current.propertySource = propertySource;
+            current.propertyName = propertyName;
+            current.notifier = notifier;
+            notifier.subscribe(this, propertyName);
+            if (prev !== null) {
+                if (!this.needsRefresh) {
+                    // Declaring the variable prior to assignment below circumvents
+                    // a bug in Angular's optimization process causing infinite recursion
+                    // of this watch() method. Details https://github.com/microsoft/fast/issues/4969
+                    // biome-ignore lint/style/useConst: see above
+                    let prevValue;
+                    watcher = void 0;
+                    prevValue = prev.propertySource[prev.propertyName];
+                    watcher = this;
+                    if (propertySource === prevValue) {
+                        this.needsRefresh = true;
+                    }
+                }
+                prev.next = current;
+            }
+            this.last = current;
+        }
+        handleChange() {
+            if (this.needsQueue) {
+                this.needsQueue = false;
+                queueUpdate(this);
+            }
+            else if (!this.isAsync) {
+                this.call();
+            }
+        }
+        call() {
+            if (this.last !== null) {
+                this.needsQueue = this.isAsync;
+                this.notify(this);
+            }
+        }
+        *records() {
+            let next = this.first;
+            while (next !== void 0) {
+                yield next;
+                next = next.next;
+            }
+        }
+    }
+    makeSerializationNoop(ExpressionNotifierImplementation);
+    return Object.freeze({
+        /**
+         * @internal
+         * @param factory - The factory used to create array observers.
+         */
+        setArrayObserverFactory(factory) {
+            createArrayObserver = factory;
+        },
+        /**
+         * Gets a notifier for an object or Array.
+         * @param source - The object or Array to get the notifier for.
+         */
+        getNotifier,
+        /**
+         * Records a property change for a source object.
+         * @param source - The object to record the change against.
+         * @param propertyName - The property to track as changed.
+         */
+        track(source, propertyName) {
+            watcher && watcher.watch(source, propertyName);
+        },
+        /**
+         * Notifies watchers that the currently executing property getter or function is volatile
+         * with respect to its observable dependencies.
+         */
+        trackVolatile() {
+            watcher && (watcher.needsRefresh = true);
+        },
+        /**
+         * Notifies subscribers of a source object of changes.
+         * @param source - the object to notify of changes.
+         * @param args - The change args to pass to subscribers.
+         */
+        notify(source, args) {
+            /* eslint-disable-next-line @typescript-eslint/no-use-before-define */
+            getNotifier(source).notify(args);
+        },
+        /**
+         * Defines an observable property on an object or prototype.
+         * @param target - The target object to define the observable on.
+         * @param nameOrAccessor - The name of the property to define as observable;
+         * or a custom accessor that specifies the property name and accessor implementation.
+         */
+        defineProperty(target, nameOrAccessor) {
+            if (isString(nameOrAccessor)) {
+                nameOrAccessor = new DefaultObservableAccessor(nameOrAccessor);
+            }
+            getAccessors(target).push(nameOrAccessor);
+            Reflect.defineProperty(target, nameOrAccessor.name, {
+                enumerable: true,
+                get() {
+                    return nameOrAccessor.getValue(this);
+                },
+                set(newValue) {
+                    nameOrAccessor.setValue(this, newValue);
+                },
+            });
+        },
+        /**
+         * Finds all the observable accessors defined on the target,
+         * including its prototype chain.
+         * @param target - The target object to search for accessor on.
+         */
+        getAccessors,
+        /**
+         * Creates a {@link ExpressionNotifier} that can watch the
+         * provided {@link Expression} for changes.
+         * @param expression - The binding to observe.
+         * @param initialSubscriber - An initial subscriber to changes in the binding value.
+         * @param isVolatileBinding - Indicates whether the binding's dependency list must be re-evaluated on every value evaluation.
+         */
+        binding(expression, initialSubscriber, isVolatileBinding = this.isVolatileBinding(expression)) {
+            return new ExpressionNotifierImplementation(expression, initialSubscriber, isVolatileBinding);
+        },
+        /**
+         * Determines whether a binding expression is volatile and needs to have its dependency list re-evaluated
+         * on every evaluation of the value.
+         * @param expression - The binding to inspect.
+         */
+        isVolatileBinding(expression) {
+            return volatileRegex.test(expression.toString());
+        },
+    });
+})();
+/**
+ * Decorator: Defines an observable property on the target.
+ * @param target - The target to define the observable on.
+ * @param nameOrAccessor - The property name or accessor to define the observable as.
+ * @public
+ */
+export function observable(target, nameOrAccessor) {
+    Observable.defineProperty(target, nameOrAccessor);
+}
+const contextEvent = (() => {
+    let current = null;
+    return {
+        get() {
+            return current;
+        },
+        set(event) {
+            current = event;
+        },
+    };
+})();
+/**
+ * Provides additional contextual information available to behaviors and expressions.
+ * @public
+ */
+export const ExecutionContext = Object.freeze({
+    /**
+     * A default execution context.
+     */
+    default: {
+        index: 0,
+        length: 0,
+        get event() {
+            return ExecutionContext.getEvent();
+        },
+        eventDetail() {
+            return this.event.detail;
+        },
+        eventTarget() {
+            return this.event.target;
+        },
+    },
+    /**
+     * Gets the current event.
+     * @returns An event object.
+     */
+    getEvent() {
+        return contextEvent.get();
+    },
+    /**
+     * Sets the current event.
+     * @param event - An event object.
+     */
+    setEvent(event) {
+        contextEvent.set(event);
+    },
+});

package/dist/esm/observation/update-queue.js

@@ -0,0 +1,56 @@
+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++;
+        if (index > capacity) {
+            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();
+    }
+}
+/**
+ * The default UpdateQueue.
+ * @public
+ */
+export const Updates = Object.freeze({
+    enqueue,
+    next: () => new Promise(enqueue),
+    process,
+    setMode: (isAsync) => (updateAsync = isAsync),
+});

package/dist/esm/observation/volatile.js

@@ -0,0 +1,16 @@
+import { Observable } from "./observable.js";
+/**
+ * Decorator: Marks a property getter as having volatile observable dependencies.
+ * @param target - The target that the property is defined on.
+ * @param name - The property name.
+ * @param descriptor - The existing descriptor.
+ * @public
+ */
+export function volatile(target, name, descriptor) {
+    return Object.assign({}, descriptor, {
+        get() {
+            Observable.trackVolatile();
+            return descriptor.get.apply(this);
+        },
+    });
+}

package/dist/esm/platform.js

@@ -0,0 +1,98 @@
+import { noop } from "./interfaces.js";
+const debugMessages = Object.create(null);
+/**
+ * The FAST messaging API for warnings and errors.
+ * @public
+ */
+export const FAST = {
+    /**
+     * Sends a warning to the developer.
+     * @param code - The warning code to send.
+     * @param values - Values relevant for the warning message.
+     */
+    warn(_code, _values) { },
+    /**
+     * Creates an error from a code.
+     * @param code - The error code.
+     * @param values - Values relevant for the error message.
+     */
+    error(code, _values) {
+        return new Error(`Error ${code}`);
+    },
+    /**
+     * Adds debug messages for errors and warnings.
+     * @param messages - The message dictionary to add.
+     */
+    addMessages(messages) {
+        Object.assign(debugMessages, messages);
+    },
+};
+/**
+ * Gets the shared debug message lookup.
+ * @internal
+ */
+export function getDebugMessageLookup() {
+    return debugMessages;
+}
+/**
+ * A readonly, empty array.
+ * @remarks
+ * Typically returned by APIs that return arrays when there are
+ * no actual items to return.
+ * @public
+ */
+export const emptyArray = Object.freeze([]);
+/**
+ * Do not change. Part of shared kernel contract.
+ * @internal
+ */
+export function createTypeRegistry() {
+    const typeToDefinition = new Map();
+    return Object.freeze({
+        register(definition) {
+            if (typeToDefinition.has(definition.type)) {
+                return false;
+            }
+            typeToDefinition.set(definition.type, definition);
+            return true;
+        },
+        getByType(key) {
+            return typeToDefinition.get(key);
+        },
+        getForInstance(object) {
+            if (object === null || object === void 0) {
+                return void 0;
+            }
+            return typeToDefinition.get(object.constructor);
+        },
+    });
+}
+/**
+ * Creates a function capable of locating metadata associated with a type.
+ * @returns A metadata locator function.
+ * @internal
+ */
+export function createMetadataLocator() {
+    const metadataLookup = new WeakMap();
+    return function (target) {
+        let metadata = metadataLookup.get(target);
+        if (metadata === void 0) {
+            let currentTarget = Reflect.getPrototypeOf(target);
+            while (metadata === void 0 && currentTarget !== null) {
+                metadata = metadataLookup.get(currentTarget);
+                currentTarget = Reflect.getPrototypeOf(currentTarget);
+            }
+            metadata = metadata === void 0 ? [] : metadata.slice(0);
+            metadataLookup.set(target, metadata);
+        }
+        return metadata;
+    };
+}
+/**
+ * Makes a type noop for JSON serialization.
+ * @param type - The type to make noop for JSON serialization.
+ * @internal
+ */
+export function makeSerializationNoop(type) {
+    type.prototype.toJSON = noop;
+}

package/dist/esm/registry.js

@@ -0,0 +1,2 @@
+export { FASTElementDefinition, } from "./components/fast-definitions.js";
+export { fastElementRegistry, } from "./components/fast-element-registry.js";

package/dist/esm/render.js

@@ -0,0 +1 @@
+export { RenderBehavior, RenderDirective, render } from "./templating/render.js";

package/dist/esm/schema.js

@@ -0,0 +1 @@
+export { Schema, schemaRegistry, } from "./components/schema.js";