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

package/dist/esm/styles/css-directive.js

@@ -0,0 +1,36 @@
+import { createTypeRegistry } from "../platform.js";
+const registry = createTypeRegistry();
+/**
+ * Instructs the css engine to provide styles during CSS template composition.
+ * @public
+ */
+export const CSSDirective = 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 a CSSDirective.
+     * @param type - The type to define as a directive.
+     */
+    define(type) {
+        registry.register({ type });
+        return type;
+    },
+});
+/**
+ * Decorator: Defines a CSSDirective.
+ * @public
+ */
+export function cssDirective() {
+    /* eslint-disable-next-line @typescript-eslint/explicit-function-return-type */
+    return function (type) {
+        CSSDirective.define(type);
+    };
+}

package/dist/esm/styles/css.js

@@ -0,0 +1,56 @@
+import { CSSDirective } from "./css-directive.js";
+import { ElementStyles } from "./element-styles.js";
+function collectStyles(strings, values) {
+    const styles = [];
+    let cssString = "";
+    for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
+        cssString += strings[i];
+        let value = values[i];
+        if (CSSDirective.getForInstance(value) !== void 0) {
+            value = value.createCSS();
+        }
+        if (value instanceof ElementStyles || value instanceof CSSStyleSheet) {
+            if (cssString.trim() !== "") {
+                styles.push(cssString);
+                cssString = "";
+            }
+            styles.push(value);
+        }
+        else {
+            cssString += value;
+        }
+    }
+    cssString += strings[strings.length - 1];
+    if (cssString.trim() !== "") {
+        styles.push(cssString);
+    }
+    return styles;
+}
+/**
+ * Transforms a template literal string into styles.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The css helper supports interpolation of static composable styles and CSS directives.
+ * @public
+ */
+export const css = ((strings, ...values) => {
+    return new ElementStyles(collectStyles(strings, values));
+});
+class CSSPartial {
+    constructor(styles) {
+        this.value =
+            styles.length === 0
+                ? ""
+                : styles.length === 1
+                    ? styles[0]
+                    : new ElementStyles(styles);
+    }
+    createCSS() {
+        return this.value;
+    }
+}
+CSSDirective.define(CSSPartial);
+css.partial = (strings, ...values) => {
+    return new CSSPartial(collectStyles(strings, values));
+};

package/dist/esm/styles/element-styles.js

@@ -0,0 +1,144 @@
+let DefaultStyleStrategy;
+function reduceStyles(styles) {
+    return styles.reduce((reduced, current) => {
+        if (current instanceof ElementStyles) {
+            reduced.push(...reduceStyles(current.styles));
+        }
+        else {
+            reduced.push(current);
+        }
+        return reduced;
+    }, []);
+}
+/**
+ * Represents styles that can be applied to a custom element.
+ * @public
+ */
+export class ElementStyles {
+    /**
+     * Gets the StyleStrategy associated with these element styles.
+     */
+    get strategy() {
+        if (this._strategy === null) {
+            if (!DefaultStyleStrategy) {
+                ElementStyles.setDefaultStrategy(ElementStyles.supportsAdoptedStyleSheets
+                    ? createAdoptedSheetsStrategy()
+                    : createStyleElementStrategy());
+            }
+            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;
+    }
+    /** @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);
+    }
+    /**
+     * 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;
+// Fallback strategy factories used when no strategy has been explicitly set
+// via ElementStyles.setDefaultStrategy (e.g. when importing only from the
+// styles.js subpath without loading element-controller.ts).
+function createAdoptedSheetsStrategy() {
+    const cache = new Map();
+    return class FallbackAdoptedSheetsStrategy {
+        constructor(styles) {
+            this.sheets = styles.map(x => {
+                if (x instanceof CSSStyleSheet) {
+                    return x;
+                }
+                let sheet = cache.get(x);
+                if (sheet === void 0) {
+                    sheet = new CSSStyleSheet();
+                    sheet.replaceSync(x);
+                    cache.set(x, sheet);
+                }
+                return sheet;
+            });
+        }
+        addStylesTo(target) {
+            const t = target;
+            t.adoptedStyleSheets = [...t.adoptedStyleSheets, ...this.sheets];
+        }
+        removeStylesFrom(target) {
+            const t = target;
+            t.adoptedStyleSheets = t.adoptedStyleSheets.filter((x) => this.sheets.indexOf(x) === -1);
+        }
+    };
+}
+let fallbackStyleId = 0;
+function createStyleElementStrategy() {
+    return class FallbackStyleElementStrategy {
+        constructor(styles) {
+            this.styles = styles;
+            this.styleClass = `fast-${++fallbackStyleId}`;
+        }
+        addStylesTo(target) {
+            const t = target === document ? document.body : target;
+            for (let i = 0; i < this.styles.length; i++) {
+                const element = document.createElement("style");
+                element.innerHTML = this.styles[i];
+                element.className = this.styleClass;
+                t.append(element);
+            }
+        }
+        removeStylesFrom(target) {
+            const t = target === document ? document.body : target;
+            const styles = t.querySelectorAll(`.${this.styleClass}`);
+            for (let i = 0, ii = styles.length; i < ii; ++i) {
+                t.removeChild(styles[i]);
+            }
+        }
+    };
+}

package/dist/esm/styles/host.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/styles/style-strategy.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/templating/children.js

@@ -0,0 +1,67 @@
+import { isString, noop } from "../interfaces.js";
+import { HTMLDirective } from "./html-directive.js";
+import { NodeObservationDirective, } from "./node-observation.js";
+/**
+ * The runtime behavior for child node observation.
+ * @public
+ */
+export class ChildrenDirective extends NodeObservationDirective {
+    /**
+     * Creates an instance of ChildrenDirective.
+     * @param options - The options to use in configuring the child observation behavior.
+     */
+    constructor(options) {
+        super(options);
+        this.observerProperty = Symbol();
+        options.childList = true;
+    }
+    /**
+     * Begins observation of the nodes.
+     * @param target - The target to observe.
+     */
+    observe(target) {
+        let observer = target[this.observerProperty];
+        if (!observer) {
+            const handleEvent = (mutations, observer) => {
+                this.updateTarget(this.getSource(target), this.computeNodes(target));
+            };
+            observer = new MutationObserver(handleEvent);
+            observer.toJSON = noop;
+            target[this.observerProperty] = observer;
+        }
+        observer.observe(target, this.options);
+    }
+    /**
+     * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
+     */
+    disconnect(target) {
+        const observer = target[this.observerProperty];
+        observer.disconnect();
+    }
+    /**
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
+     */
+    getNodes(target) {
+        if ("selector" in this.options) {
+            return Array.from(target.querySelectorAll(this.options.selector));
+        }
+        return Array.from(target.childNodes);
+    }
+}
+HTMLDirective.define(ChildrenDirective);
+/**
+ * A directive that observes the `childNodes` of an element and updates a property
+ * whenever they change.
+ * @param propertyOrOptions - The options used to configure child node observation.
+ * @public
+ */
+export function children(propertyOrOptions) {
+    if (isString(propertyOrOptions)) {
+        propertyOrOptions = {
+            property: propertyOrOptions,
+        };
+    }
+    return new ChildrenDirective(propertyOrOptions);
+}

package/dist/esm/templating/compiler.js

@@ -0,0 +1,359 @@
+import { oneTime } from "../binding/one-time.js";
+import { oneWay } from "../binding/one-way.js";
+import { DOM } from "../dom.js";
+import { isFunction, isString, Message } from "../interfaces.js";
+import { FAST } from "../platform.js";
+import { HTMLBindingDirective } from "./html-binding-directive.js";
+import { HTMLDirective, } from "./html-directive.js";
+import { nextId, Parser } from "./markup.js";
+import { HTMLView } from "./view.js";
+/**
+ * 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
+const next = {
+    index: 0,
+    node: null,
+};
+function tryWarn(name) {
+    if (!name.startsWith("fast-")) {
+        FAST.warn(Message.hostBindingWithoutHost, { name });
+    }
+}
+const warningHost = new Proxy(document.createElement("div"), {
+    get(target, property) {
+        tryWarn(property);
+        const value = Reflect.get(target, property);
+        return isFunction(value) ? value.bind(target) : value;
+    },
+    set(target, property, value) {
+        tryWarn(property);
+        return Reflect.set(target, property, value);
+    },
+});
+class CompilationContext {
+    constructor(fragment, directives, policy) {
+        this.fragment = fragment;
+        this.directives = directives;
+        this.policy = policy;
+        this.proto = null;
+        this.nodeIds = new Set();
+        this.descriptors = {};
+        this.factories = [];
+    }
+    addFactory(factory, parentId, nodeId, targetIndex, tagName) {
+        var _a, _b;
+        if (!this.nodeIds.has(nodeId)) {
+            this.nodeIds.add(nodeId);
+            this.addTargetDescriptor(parentId, nodeId, targetIndex);
+        }
+        factory.id = (_a = factory.id) !== null && _a !== void 0 ? _a : nextId();
+        factory.targetNodeId = nodeId;
+        factory.targetTagName = tagName;
+        factory.policy = (_b = factory.policy) !== null && _b !== void 0 ? _b : this.policy;
+        this.factories.push(factory);
+    }
+    freeze() {
+        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
+            targetId === "h" || // host
+            descriptors[targetId]) {
+            return;
+        }
+        if (!descriptors[parentId]) {
+            const index = parentId.lastIndexOf(".");
+            const grandparentId = parentId.substring(0, index);
+            const childIndex = parseInt(parentId.substring(index + 1), 10);
+            this.addTargetDescriptor(grandparentId, parentId, childIndex);
+        }
+        let descriptor = descriptorCache[targetId];
+        if (!descriptor) {
+            const field = `_${targetId}`;
+            descriptorCache[targetId] = descriptor = {
+                get() {
+                    var _a;
+                    return ((_a = this[field]) !== null && _a !== void 0 ? _a : (this[field] = this[parentId].childNodes[targetIndex]));
+                },
+            };
+        }
+        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, scope) {
+        const fragment = scope === void 0
+            ? this.fragment.cloneNode(true)
+            : cloneIntoScope(this.fragment, scope);
+        const targets = Object.create(this.proto);
+        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) {
+            Reflect.get(targets, id); // trigger lazy getter to resolve and cache the DOM node
+        }
+        return new HTMLView(fragment, this.factories, targets, scope);
+    }
+}
+let inertDocument;
+const registryFreeSources = new WeakMap();
+/**
+ * Returns a copy of a compiled fragment whose elements have no custom element
+ * registry. Elements that already have one (all elements of the fragment that was
+ * adopted into the main document have the global registry) keep it when cloned, so
+ * a registry can only be chosen for clones of a registry-free source.
+ */
+function getRegistryFreeSource(fragment) {
+    let source = registryFreeSources.get(fragment);
+    if (source === void 0) {
+        inertDocument !== null && inertDocument !== void 0 ? inertDocument : (inertDocument = document.implementation.createHTMLDocument(""));
+        source = fragment.cloneNode(true);
+        inertDocument.adoptNode(source);
+        registryFreeSources.set(fragment, source);
+    }
+    return source;
+}
+/**
+ * Clones a compiled fragment so that custom elements inside it are created against
+ * the scoped custom element registry of `scope`.
+ *
+ * @remarks
+ * The compiled fragment is adopted into the main document, so a plain `cloneNode`
+ * creates its children against the *global* registry and a tag that is only defined
+ * in a scoped registry is never upgraded. Only views for hosts that were given a
+ * registry take this path (see `ElementController`); every other view keeps using
+ * `cloneNode(true)`.
+ *
+ * - Native scoped registries: `document.importNode` with a `customElementRegistry`,
+ *   from a registry-free copy of the fragment (created once per template).
+ * - `@webcomponents/scoped-custom-element-registry` (0.0.x): `ShadowRoot.importNode`,
+ *   which the polyfill patches to resolve the scope from the shadow root.
+ * - Otherwise: a plain clone.
+ */
+function cloneIntoScope(fragment, scope) {
+    var _a;
+    const scoped = scope;
+    const registry = (_a = scoped.customElementRegistry) !== null && _a !== void 0 ? _a : scoped.registry;
+    if (registry) {
+        // A registry that can `initialize` is the native (or spec-aligned) API.
+        if (registry !== globalThis.customElements &&
+            typeof registry.initialize === "function") {
+            return document.importNode(getRegistryFreeSource(fragment), {
+                selfOnly: false,
+                customElementRegistry: registry,
+            });
+        }
+        if (typeof scoped.importNode === "function") {
+            return scoped.importNode(fragment, true);
+        }
+    }
+    return fragment.cloneNode(true);
+}
+function compileAttributes(context, parentId, node, nodeId, nodeIndex, includeBasicValues = false) {
+    const attributes = node.attributes;
+    const directives = context.directives;
+    for (let i = 0, ii = attributes.length; i < ii; ++i) {
+        const attr = attributes[i];
+        const attrValue = attr.value;
+        const parseResult = Parser.parse(attrValue, directives);
+        let result = null;
+        if (parseResult === null) {
+            if (includeBasicValues) {
+                result = new HTMLBindingDirective(oneTime(() => attrValue, context.policy));
+                HTMLDirective.assignAspect(result, attr.name);
+            }
+        }
+        else {
+            result = Compiler.aggregate(parseResult, context.policy);
+        }
+        if (result !== null) {
+            node.removeAttributeNode(attr);
+            i--;
+            ii--;
+            context.addFactory(result, parentId, nodeId, nodeIndex, node.tagName);
+        }
+    }
+}
+function compileContent(context, node, parentId, nodeId, nodeIndex) {
+    const parseResult = Parser.parse(node.textContent, context.directives);
+    if (parseResult === null) {
+        next.node = node.nextSibling;
+        next.index = nodeIndex + 1;
+        return next;
+    }
+    let currentNode;
+    let lastNode = (currentNode = node);
+    for (let i = 0, ii = parseResult.length; i < ii; ++i) {
+        const currentPart = parseResult[i];
+        if (i !== 0) {
+            nodeIndex++;
+            nodeId = targetIdFrom(parentId, nodeIndex);
+            currentNode = lastNode.parentNode.insertBefore(document.createTextNode(""), lastNode.nextSibling);
+        }
+        if (isString(currentPart)) {
+            currentNode.textContent = currentPart;
+        }
+        else {
+            currentNode.textContent = " ";
+            HTMLDirective.assignAspect(currentPart);
+            context.addFactory(currentPart, parentId, nodeId, nodeIndex, null);
+        }
+        lastNode = currentNode;
+    }
+    next.index = nodeIndex + 1;
+    next.node = lastNode.nextSibling;
+    return next;
+}
+function compileChildren(context, parent, parentId) {
+    let nodeIndex = 0;
+    let childNode = parent.firstChild;
+    while (childNode) {
+        const result = compileNode(context, parentId, childNode, nodeIndex);
+        childNode = result.node;
+        nodeIndex = result.index;
+    }
+}
+function compileNode(context, parentId, node, nodeIndex) {
+    const nodeId = targetIdFrom(parentId, nodeIndex);
+    switch (node.nodeType) {
+        case 1: // element node
+            compileAttributes(context, parentId, node, nodeId, nodeIndex);
+            compileChildren(context, node, nodeId);
+            break;
+        case 3: // text node
+            return compileContent(context, node, parentId, nodeId, nodeIndex);
+        case 8: {
+            // comment
+            const parts = Parser.parse(node.data, context.directives);
+            if (parts !== null) {
+                context.addFactory(Compiler.aggregate(parts), parentId, nodeId, nodeIndex, null);
+            }
+            break;
+        }
+    }
+    next.index = nodeIndex + 1;
+    next.node = node.nextSibling;
+    return next;
+}
+function isMarker(node, directives) {
+    return (node &&
+        node.nodeType === 8 &&
+        Parser.parse(node.data, directives) !== null);
+}
+const templateTag = "TEMPLATE";
+/**
+ * Common APIs related to compilation.
+ * @public
+ */
+export const Compiler = {
+    /**
+     * Compiles a template and associated directives into a compilation
+     * result which can be used to create views.
+     * @param html - The html string or template element to compile.
+     * @param factories - The behavior factories referenced by the template.
+     * @param policy - The security policy to compile the html with.
+     * @remarks
+     * The template that is provided for compilation is altered in-place
+     * and cannot be compiled again. If the original template must be preserved,
+     * it is recommended that you clone the original and pass the clone to this API.
+     * @public
+     */
+    compile(html, factories, policy = DOM.policy) {
+        let template;
+        if (isString(html)) {
+            template = document.createElement(templateTag);
+            template.innerHTML = policy.createHTML(html);
+            const fec = template.content.firstElementChild;
+            if (fec !== null && fec.tagName === templateTag) {
+                template = fec;
+            }
+        }
+        else {
+            template = html;
+        }
+        if (!template.content.firstChild && !template.content.lastChild) {
+            template.content.appendChild(document.createComment(""));
+        }
+        // https://bugs.chromium.org/p/chromium/issues/detail?id=1111864
+        const fragment = document.adoptNode(template.content);
+        const context = new CompilationContext(fragment, factories, policy);
+        compileAttributes(context, "", template, /* host */ "h", 0, true);
+        if (
+        // If the first node in a fragment is a marker, that means it's an unstable first node,
+        // because something like a when, repeat, etc. could add nodes before the marker.
+        // To mitigate this, we insert a stable first node. However, if we insert a node,
+        // that will alter the result of the TreeWalker. So, we also need to offset the target index.
+        isMarker(fragment.firstChild, factories) ||
+            // Or if there is only one node and a directive, it means the template's content
+            // is *only* the directive. In that case, HTMLView.dispose() misses any nodes inserted by
+            // the directive. Inserting a new node ensures proper disposal of nodes added by the directive.
+            (fragment.childNodes.length === 1 && Object.keys(factories).length > 0)) {
+            fragment.insertBefore(document.createComment(""), fragment.firstChild);
+        }
+        compileChildren(context, fragment, /* root */ "r");
+        next.node = null; // prevent leaks
+        return context.freeze();
+    },
+    /**
+     * Sets the default compilation strategy that will be used by the ViewTemplate whenever
+     * it needs to compile a view preprocessed with the html template function.
+     * @param strategy - The compilation strategy to use when compiling templates.
+     */
+    setDefaultStrategy(strategy) {
+        this.compile = strategy;
+    },
+    /**
+     * Aggregates an array of strings and directives into a single directive.
+     * @param parts - A heterogeneous array of static strings interspersed with
+     * directives.
+     * @param policy - The security policy to use with the aggregated bindings.
+     * @returns A single inline directive that aggregates the behavior of all the parts.
+     */
+    aggregate(parts, policy = DOM.policy) {
+        if (parts.length === 1) {
+            return parts[0];
+        }
+        let sourceAspect;
+        let isVolatile = false;
+        let bindingPolicy = void 0;
+        const partCount = parts.length;
+        const finalParts = parts.map((x) => {
+            if (isString(x)) {
+                return () => x;
+            }
+            sourceAspect = x.sourceAspect || sourceAspect;
+            isVolatile = isVolatile || x.dataBinding.isVolatile;
+            bindingPolicy = bindingPolicy || x.dataBinding.policy;
+            return x.dataBinding.evaluate;
+        });
+        const expression = (scope, context) => {
+            let output = "";
+            for (let i = 0; i < partCount; ++i) {
+                output += finalParts[i](scope, context);
+            }
+            return output;
+        };
+        const directive = new HTMLBindingDirective(oneWay(expression, bindingPolicy !== null && bindingPolicy !== void 0 ? bindingPolicy : policy, isVolatile));
+        HTMLDirective.assignAspect(directive, sourceAspect);
+        return directive;
+    },
+};