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

package/dist/esm/templating/repeat.js

@@ -0,0 +1,434 @@
+import { normalizeBinding } from "../binding/normalize.js";
+import { HydrationMarkup, isHydratable } from "../components/hydration.js";
+import { ArrayObserver } from "../observation/arrays.js";
+import { Observable, } from "../observation/observable.js";
+import { emptyArray } from "../platform.js";
+import { HTMLDirective, } from "./html-directive.js";
+import { HydrationStage } from "./hydration-view.js";
+import { Markup } from "./markup.js";
+import { createChildView, HTMLView } from "./view.js";
+const defaultRepeatOptions = Object.freeze({
+    positioning: false,
+    recycle: true,
+});
+function bindWithoutPositioning(view, items, index, controller) {
+    view.context.parent = controller.source;
+    view.context.parentContext = controller.context;
+    view.bind(items[index]);
+}
+function bindWithPositioning(view, items, index, controller) {
+    view.context.parent = controller.source;
+    view.context.parentContext = controller.context;
+    view.context.length = items.length;
+    view.context.index = index;
+    view.bind(items[index]);
+}
+function isCommentNode(node) {
+    return node.nodeType === Node.COMMENT_NODE;
+}
+function removeNodeRange(first, last) {
+    const parentNode = first.parentNode;
+    if (parentNode === null) {
+        return;
+    }
+    let current = first;
+    while (current !== null) {
+        const next = current.nextSibling;
+        parentNode.removeChild(current);
+        if (current === last) {
+            break;
+        }
+        current = next;
+    }
+}
+export class HydrationRepeatError extends Error {
+    constructor(
+    /**
+     * The error message
+     */
+    message, propertyBag) {
+        super(message);
+        this.propertyBag = propertyBag;
+    }
+}
+/**
+ * A behavior that renders a template for each item in an array.
+ * @public
+ */
+export class RepeatBehavior {
+    /**
+     * Creates an instance of RepeatBehavior.
+     * @param location - The location in the DOM to render the repeat.
+     * @param dataBinding - The array to render.
+     * @param isItemsBindingVolatile - Indicates whether the items binding has volatile dependencies.
+     * @param templateBinding - The template to render for each item.
+     * @param isTemplateBindingVolatile - Indicates whether the template binding has volatile dependencies.
+     * @param options - Options used to turn on special repeat features.
+     */
+    constructor(directive) {
+        this.directive = directive;
+        this.isBound = false;
+        this.items = null;
+        this.itemsObserver = null;
+        this.bindView = bindWithoutPositioning;
+        /** @internal */
+        this.views = [];
+        this.itemsBindingObserver = directive.dataBinding.createObserver(this, directive);
+        this.templateBindingObserver = directive.templateBinding.createObserver(this, directive);
+        if (directive.options.positioning) {
+            this.bindView = bindWithPositioning;
+        }
+    }
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    bind(controller) {
+        this.location = controller.targets[this.directive.targetNodeId];
+        this.controller = controller;
+        this.isBound = true;
+        this.items = this.itemsBindingObserver.bind(controller);
+        this.template = this.templateBindingObserver.bind(controller);
+        this.observeItems(true);
+        if (isHydratable(this.template) &&
+            isHydratable(controller) &&
+            controller.hydrationStage !== HydrationStage.hydrated) {
+            this.hydrateViews(this.template);
+        }
+        else {
+            this.refreshAllViews();
+        }
+        controller.onUnbind(this);
+    }
+    /**
+     * Unbinds this behavior.
+     */
+    unbind() {
+        this.isBound = false;
+        if (this.itemsObserver !== null) {
+            this.itemsObserver.unsubscribe(this);
+        }
+        this.unbindAllViews();
+    }
+    /**
+     * Handles changes in the array, its items, and the repeat template.
+     * @param source - The source of the change.
+     * @param args - The details about what was changed.
+     */
+    handleChange(source, args) {
+        // Notifications queued before unbind must not reobserve a cleared view source.
+        if (!this.isBound) {
+            return;
+        }
+        if (args === this.itemsBindingObserver) {
+            this.items = this.itemsBindingObserver.bind(this.controller);
+            this.observeItems();
+            this.refreshAllViews();
+        }
+        else if (args === this.templateBindingObserver) {
+            this.template = this.templateBindingObserver.bind(this.controller);
+            this.refreshAllViews(true);
+        }
+        else if (!args[0]) {
+            return;
+        }
+        else if (args[0].reset) {
+            this.refreshAllViews();
+        }
+        else if (args[0].sorted) {
+            this.updateSortedViews(args);
+        }
+        else {
+            this.updateSplicedViews(args);
+        }
+    }
+    observeItems(force = false) {
+        if (!this.items) {
+            this.items = emptyArray;
+            return;
+        }
+        const oldObserver = this.itemsObserver;
+        const newObserver = (this.itemsObserver = Observable.getNotifier(this.items));
+        const hasNewObserver = oldObserver !== newObserver;
+        if (hasNewObserver && oldObserver !== null) {
+            oldObserver.unsubscribe(this);
+        }
+        if (hasNewObserver || force) {
+            newObserver.subscribe(this);
+        }
+    }
+    updateSortedViews(sorts) {
+        const views = this.views;
+        for (let i = 0, ii = sorts.length; i < ii; ++i) {
+            const sortedItems = sorts[i].sorted.slice();
+            const unsortedItems = sortedItems.slice().sort();
+            for (let j = 0, jj = sortedItems.length; j < jj; ++j) {
+                const sortedIndex = sortedItems.find(value => sortedItems[j] === unsortedItems[value]);
+                if (sortedIndex !== j) {
+                    const removedItems = unsortedItems.splice(sortedIndex, 1);
+                    unsortedItems.splice(j, 0, ...removedItems);
+                    const neighbor = views[j];
+                    const location = neighbor ? neighbor.firstChild : this.location;
+                    views[sortedIndex].remove();
+                    views[sortedIndex].insertBefore(location);
+                    const removedViews = views.splice(sortedIndex, 1);
+                    views.splice(j, 0, ...removedViews);
+                }
+            }
+        }
+    }
+    updateSplicedViews(splices) {
+        const views = this.views;
+        const bindView = this.bindView;
+        const items = this.items;
+        const template = this.template;
+        const controller = this.controller;
+        const recycle = this.directive.options.recycle;
+        const leftoverViews = [];
+        let leftoverIndex = 0;
+        let availableViews = 0;
+        for (let i = 0, ii = splices.length; i < ii; ++i) {
+            const splice = splices[i];
+            const removed = splice.removed;
+            let removeIndex = 0;
+            let addIndex = splice.index;
+            const end = addIndex + splice.addedCount;
+            const removedViews = views.splice(splice.index, removed.length);
+            const totalAvailableViews = (availableViews =
+                leftoverViews.length + removedViews.length);
+            for (; addIndex < end; ++addIndex) {
+                const neighbor = views[addIndex];
+                const location = neighbor ? neighbor.firstChild : this.location;
+                let view;
+                if (recycle && availableViews > 0) {
+                    if (removeIndex <= totalAvailableViews && removedViews.length > 0) {
+                        view = removedViews[removeIndex];
+                        removeIndex++;
+                    }
+                    else {
+                        view = leftoverViews[leftoverIndex];
+                        leftoverIndex++;
+                    }
+                    availableViews--;
+                }
+                else {
+                    view = createChildView(template, controller);
+                }
+                views.splice(addIndex, 0, view);
+                bindView(view, items, addIndex, controller);
+                view.insertBefore(location);
+            }
+            if (removedViews[removeIndex]) {
+                leftoverViews.push(...removedViews.slice(removeIndex));
+            }
+        }
+        for (let i = leftoverIndex, ii = leftoverViews.length; i < ii; ++i) {
+            leftoverViews[i].dispose();
+        }
+        if (this.directive.options.positioning) {
+            for (let i = 0, viewsLength = views.length; i < viewsLength; ++i) {
+                const context = views[i].context;
+                context.length = viewsLength;
+                context.index = i;
+            }
+        }
+    }
+    refreshAllViews(templateChanged = false) {
+        const items = this.items;
+        const template = this.template;
+        const location = this.location;
+        const bindView = this.bindView;
+        const controller = this.controller;
+        let itemsLength = items.length;
+        let views = this.views;
+        let viewsLength = views.length;
+        if (itemsLength === 0 || templateChanged || !this.directive.options.recycle) {
+            // all views need to be removed
+            HTMLView.disposeContiguousBatch(views);
+            viewsLength = 0;
+        }
+        if (viewsLength === 0) {
+            // all views need to be created
+            this.views = views = new Array(itemsLength);
+            for (let i = 0; i < itemsLength; ++i) {
+                const view = createChildView(template, controller);
+                bindView(view, items, i, controller);
+                views[i] = view;
+                view.insertBefore(location);
+            }
+        }
+        else {
+            // attempt to reuse existing views with new data
+            let i = 0;
+            for (; i < itemsLength; ++i) {
+                if (i < viewsLength) {
+                    const view = views[i];
+                    if (!view) {
+                        const serializer = new XMLSerializer();
+                        throw new HydrationRepeatError(`View is null or undefined inside "${this.location.getRootNode().host.nodeName}".`, {
+                            index: i,
+                            hydrationStage: this.controller
+                                .hydrationStage,
+                            itemsLength,
+                            viewsState: views.map(v => (v ? "hydrated" : "empty")),
+                            viewTemplateString: serializer.serializeToString(template.create().fragment),
+                            rootNodeContent: serializer.serializeToString(this.location.getRootNode()),
+                        });
+                    }
+                    bindView(view, items, i, controller);
+                }
+                else {
+                    const view = createChildView(template, controller);
+                    bindView(view, items, i, controller);
+                    views.push(view);
+                    view.insertBefore(location);
+                }
+            }
+            const removed = views.splice(i, viewsLength - i);
+            for (i = 0, itemsLength = removed.length; i < itemsLength; ++i) {
+                removed[i].dispose();
+            }
+        }
+    }
+    unbindAllViews() {
+        const views = this.views;
+        for (let i = 0, ii = views.length; i < ii; ++i) {
+            const view = views[i];
+            if (!view) {
+                const serializer = new XMLSerializer();
+                throw new HydrationRepeatError(`View is null or undefined inside "${this.location.getRootNode().host.nodeName}".`, {
+                    index: i,
+                    hydrationStage: this.controller.hydrationStage,
+                    viewsState: views.map(v => (v ? "hydrated" : "empty")),
+                    rootNodeContent: serializer.serializeToString(this.location.getRootNode()),
+                });
+            }
+            view.unbind();
+        }
+    }
+    hydrateViews(template) {
+        var _a;
+        if (!this.items) {
+            return;
+        }
+        const items = this.items;
+        const itemCount = items.length;
+        const views = (this.views = new Array(itemCount));
+        // First pass: collect all repeat marker pairs by walking backward.
+        // Each entry tracks both the item content range and its SSR markers.
+        const itemRanges = [];
+        let current = this.location.previousSibling;
+        while (current !== null) {
+            if (!isCommentNode(current) ||
+                !HydrationMarkup.isRepeatViewEndMarker(current.data)) {
+                current = current.previousSibling;
+                continue;
+            }
+            const endMarker = current;
+            endMarker.data = "";
+            const end = endMarker.previousSibling;
+            if (!end) {
+                throw new Error(`Error when hydrating inside "${this.location.getRootNode().host.nodeName}": end should never be null.`);
+            }
+            // Find matching start marker via balanced counting
+            let start = end;
+            let depth = 0;
+            while (start !== null) {
+                if (isCommentNode(start)) {
+                    if (HydrationMarkup.isRepeatViewEndMarker(start.data)) {
+                        depth++;
+                    }
+                    else if (HydrationMarkup.isRepeatViewStartMarker(start.data)) {
+                        if (depth === 0) {
+                            const startMarker = start;
+                            startMarker.data = "";
+                            current = startMarker.previousSibling;
+                            const itemStart = (_a = startMarker.nextSibling) !== null && _a !== void 0 ? _a : endMarker;
+                            // Empty item: start and end markers are adjacent.
+                            const itemEnd = end === startMarker ? itemStart : end;
+                            itemRanges.push({
+                                start: itemStart,
+                                end: itemEnd,
+                                startMarker,
+                                endMarker,
+                            });
+                            break;
+                        }
+                        depth--;
+                    }
+                }
+                start = start.previousSibling;
+            }
+            if (!start) {
+                throw new Error(`Error when hydrating inside "${this.location.getRootNode().host.nodeName}": repeat start marker not found.`);
+            }
+        }
+        // Ranges were collected backward (last item first).
+        // Reverse so index 0 = first SSR item.
+        itemRanges.reverse();
+        // Hydrate each SSR item at its correct index (0-based from start).
+        const hydrationCount = Math.min(itemRanges.length, itemCount);
+        for (let i = 0; i < hydrationCount; i++) {
+            const { start, end } = itemRanges[i];
+            const view = template.hydrate(start, end);
+            views[i] = view;
+            this.bindView(view, items, i, this.controller);
+        }
+        for (let i = hydrationCount; i < itemCount; i++) {
+            const view = createChildView(template, this.controller);
+            views[i] = view;
+            this.bindView(view, items, i, this.controller);
+            view.insertBefore(this.location);
+        }
+        for (let i = itemCount, ii = itemRanges.length; i < ii; i++) {
+            const { startMarker, endMarker } = itemRanges[i];
+            removeNodeRange(startMarker, endMarker);
+        }
+    }
+}
+/**
+ * A directive that configures list rendering.
+ * @public
+ */
+export class RepeatDirective {
+    /**
+     * Creates a placeholder string based on the directive's index within the template.
+     * @param index - The index of the directive within the template.
+     */
+    createHTML(add) {
+        return Markup.comment(add(this));
+    }
+    /**
+     * Creates an instance of RepeatDirective.
+     * @param dataBinding - The binding that provides the array to render.
+     * @param templateBinding - The template binding used to obtain a template to render for each item in the array.
+     * @param options - Options used to turn on special repeat features.
+     */
+    constructor(dataBinding, templateBinding, options) {
+        this.dataBinding = dataBinding;
+        this.templateBinding = templateBinding;
+        this.options = options;
+        ArrayObserver.enable();
+    }
+    /**
+     * Creates a behavior for the provided target node.
+     * @param target - The node instance to create the behavior for.
+     */
+    createBehavior() {
+        return new RepeatBehavior(this);
+    }
+}
+HTMLDirective.define(RepeatDirective);
+/**
+ * A directive that enables list rendering.
+ * @param items - The array to render.
+ * @param template - The template or a template binding used obtain a template
+ * to render for each item in the array.
+ * @param options - Options used to turn on special repeat features.
+ * @public
+ */
+export function repeat(items, template, options = defaultRepeatOptions) {
+    const dataBinding = normalizeBinding(items);
+    const templateBinding = normalizeBinding(template);
+    return new RepeatDirective(dataBinding, templateBinding, Object.assign(Object.assign({}, defaultRepeatOptions), options));
+}

package/dist/esm/templating/slotted.js

@@ -0,0 +1,49 @@
+import { isString } from "../interfaces.js";
+import { HTMLDirective } from "./html-directive.js";
+import { NodeObservationDirective, } from "./node-observation.js";
+const slotEvent = "slotchange";
+/**
+ * The runtime behavior for slotted node observation.
+ * @public
+ */
+export class SlottedDirective extends NodeObservationDirective {
+    /**
+     * Begins observation of the nodes.
+     * @param target - The target to observe.
+     */
+    observe(target) {
+        target.addEventListener(slotEvent, this);
+    }
+    /**
+     * Disconnects observation of the nodes.
+     * @param target - The target to unobserve.
+     */
+    disconnect(target) {
+        target.removeEventListener(slotEvent, this);
+    }
+    /**
+     * Retrieves the raw nodes that should be assigned to the source property.
+     * @param target - The target to get the node to.
+     */
+    getNodes(target) {
+        return target.assignedNodes(this.options);
+    }
+    /** @internal */
+    handleEvent(event) {
+        const target = event.currentTarget;
+        this.updateTarget(this.getSource(target), this.computeNodes(target));
+    }
+}
+HTMLDirective.define(SlottedDirective);
+/**
+ * A directive that observes the `assignedNodes()` of a slot and updates a property
+ * whenever they change.
+ * @param propertyOrOptions - The options used to configure slotted node observation.
+ * @public
+ */
+export function slotted(propertyOrOptions) {
+    if (isString(propertyOrOptions)) {
+        propertyOrOptions = { property: propertyOrOptions };
+    }
+    return new SlottedDirective(propertyOrOptions);
+}

package/dist/esm/templating/template.js

@@ -0,0 +1,206 @@
+import { Binding } from "../binding/binding.js";
+import { oneTime } from "../binding/one-time.js";
+import { oneWay } from "../binding/one-way.js";
+import { isFunction, isString, Message } from "../interfaces.js";
+import { FAST, makeSerializationNoop } from "../platform.js";
+import { Compiler } from "./compiler.js";
+import { HTMLBindingDirective } from "./html-binding-directive.js";
+import { HTMLDirective, } from "./html-directive.js";
+import { nextId } from "./markup.js";
+// Much thanks to LitHTML for working this out!
+const lastAttributeNameRegex = 
+/* eslint-disable-next-line no-control-regex, max-len */
+/([ \x09\x0a\x0c\x0d])([^\0-\x1F\x7F-\x9F "'>=/]+)([ \x09\x0a\x0c\x0d]*=[ \x09\x0a\x0c\x0d]*(?:[^ \x09\x0a\x0c\x0d"'`<>=]*|"[^"]*|'[^']*))$/;
+const noFactories = Object.create(null);
+/**
+ * Inlines a template into another template.
+ * @public
+ */
+export class InlineTemplateDirective {
+    /**
+     * Creates an instance of InlineTemplateDirective.
+     * @param template - The template to inline.
+     */
+    constructor(html, factories = noFactories) {
+        this.html = html;
+        this.factories = factories;
+    }
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add) {
+        const factories = this.factories;
+        for (const key in factories) {
+            add(factories[key]);
+        }
+        return this.html;
+    }
+}
+/**
+ * An empty template partial.
+ */
+InlineTemplateDirective.empty = new InlineTemplateDirective("");
+HTMLDirective.define(InlineTemplateDirective);
+function createHTML(value, prevString, add, definition = HTMLDirective.getForInstance(value)) {
+    if (definition.aspected) {
+        const match = lastAttributeNameRegex.exec(prevString);
+        if (match !== null) {
+            HTMLDirective.assignAspect(value, match[2]);
+        }
+    }
+    return value.createHTML(add);
+}
+/**
+ * A template capable of creating HTMLView instances or rendering directly to DOM.
+ * @public
+ */
+export class ViewTemplate {
+    /**
+     * Creates an instance of ViewTemplate.
+     * @param html - The html representing what this template will instantiate, including placeholders for directives.
+     * @param factories - The directives that will be connected to placeholders in the html.
+     * @param policy - The security policy to use when compiling this template.
+     */
+    constructor(html, factories = {}, policy) {
+        this.policy = policy;
+        this.result = null;
+        this.html = html;
+        this.factories = factories;
+    }
+    /**
+     * @internal
+     */
+    compile() {
+        if (this.result === null) {
+            this.result = Compiler.compile(this.html, this.factories, this.policy);
+        }
+        return this.result;
+    }
+    /**
+     * Returns a directive that can inline the template.
+     */
+    inline() {
+        return new InlineTemplateDirective(isString(this.html) ? this.html : this.html.innerHTML, this.factories);
+    }
+    /**
+     * Sets the DOMPolicy for this template.
+     * @param policy - The policy to associated with this template.
+     * @returns The modified template instance.
+     * @remarks
+     * The DOMPolicy can only be set once for a template and cannot be
+     * set after the template is compiled.
+     */
+    withPolicy(policy) {
+        if (this.result) {
+            throw FAST.error(Message.cannotSetTemplatePolicyAfterCompilation);
+        }
+        if (this.policy) {
+            throw FAST.error(Message.onlySetTemplatePolicyOnce);
+        }
+        this.policy = policy;
+        return this;
+    }
+    /**
+     * Creates an HTMLView from this template, binds it to the source, and then appends it to the host.
+     * @param source - The data source to bind the template to.
+     * @param host - The Element where the template will be rendered.
+     * @param hostBindingTarget - An HTML element to target the host bindings at if different from the
+     * host that the template is being attached to.
+     * @param scope - The shadow root whose scoped custom element registry child
+     * elements should be created against, when it has one.
+     */
+    render(source, host, hostBindingTarget, scope) {
+        const view = this.create(hostBindingTarget, scope);
+        view.bind(source);
+        view.appendTo(host);
+        return view;
+    }
+    /**
+     * Creates an HTMLView instance based on this template definition.
+     * @param hostBindingTarget - The element that host behaviors will be bound to.
+     * @param scope - The shadow root whose scoped custom element registry child
+     * elements should be created against, when it has one.
+     */
+    create(hostBindingTarget, scope) {
+        return this.compile().createView(hostBindingTarget, scope);
+    }
+    /**
+     * Processes the tagged template literal's static strings and interpolated values and
+     * creates a ViewTemplate.
+     *
+     * For each interpolated value:
+     * 1. Functions (binding expressions, e.g., `x => x.name`) → wrapped in a one-way HTMLBindingDirective
+     * 2. Binding instances → wrapped in an HTMLBindingDirective
+     * 3. HTMLDirective instances → used as-is
+     * 4. Static values (strings, numbers) → wrapped in a one-time HTMLBindingDirective
+     *
+     * Each directive's createHTML() is called with an `add` callback that registers
+     * the factory in the factories record under a unique ID and returns that ID.
+     * The directive inserts a placeholder marker (e.g., `fast-abc123{0}fast-abc123`) into
+     * the HTML string so the compiler can later find and associate it with the factory.
+     *
+     * Aspect detection happens here too: the `lastAttributeNameRegex` checks whether
+     * the placeholder appears inside an attribute value, and if so, assignAspect()
+     * sets the correct DOMAspect (attribute, property, event, etc.) based on the
+     * attribute name prefix.
+     *
+     * @param strings - The static strings to create the template with.
+     * @param values - The dynamic values to create the template with.
+     * @param policy - The DOMPolicy to associated with the template.
+     * @returns A ViewTemplate.
+     * @remarks
+     * This API should not be used directly under normal circumstances because constructing
+     * a template in this way, if not done properly, can open up the application to XSS
+     * attacks. When using this API, provide a strong DOMPolicy that can properly sanitize
+     * and also be sure to manually sanitize all static strings particularly if they can
+     * come from user input.
+     */
+    static create(strings, values, policy) {
+        let html = "";
+        const factories = Object.create(null);
+        const add = (factory) => {
+            var _a;
+            const id = (_a = factory.id) !== null && _a !== void 0 ? _a : (factory.id = nextId());
+            factories[id] = factory;
+            return id;
+        };
+        for (let i = 0, ii = strings.length - 1; i < ii; ++i) {
+            const currentString = strings[i];
+            let currentValue = values[i];
+            let definition;
+            html += currentString;
+            if (isFunction(currentValue)) {
+                currentValue = new HTMLBindingDirective(oneWay(currentValue));
+            }
+            else if (currentValue instanceof Binding) {
+                currentValue = new HTMLBindingDirective(currentValue);
+            }
+            else if (!(definition = HTMLDirective.getForInstance(currentValue))) {
+                const staticValue = currentValue;
+                currentValue = new HTMLBindingDirective(oneTime(() => staticValue));
+            }
+            html += createHTML(currentValue, currentString, add, definition);
+        }
+        return new ViewTemplate(html + strings[strings.length - 1], factories, policy);
+    }
+}
+makeSerializationNoop(ViewTemplate);
+/**
+ * Transforms a template literal string into a ViewTemplate.
+ * @param strings - The string fragments that are interpolated with the values.
+ * @param values - The values that are interpolated with the string fragments.
+ * @remarks
+ * The html helper supports interpolation of strings, numbers, binding expressions,
+ * other template instances, and Directive instances.
+ * @public
+ */
+export const html = ((strings, ...values) => {
+    if (Array.isArray(strings) && Array.isArray(strings.raw)) {
+        return ViewTemplate.create(strings, values);
+    }
+    throw FAST.error(Message.directCallToHTMLTagNotAllowed);
+});
+html.partial = (html) => {
+    return new InlineTemplateDirective(html);
+};