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

package/dist/esm/templating/markup.js

@@ -0,0 +1,83 @@
+/**
+ * A unique per-session random marker string used to create placeholder tokens in HTML.
+ * Bindings embedded in template literals are replaced with interpolation markers
+ * of the form `fast-xxxxxx{id}fast-xxxxxx` so the compiler can later locate them in the
+ * parsed DOM and associate each marker with its ViewBehaviorFactory.
+ */
+const marker = `fast-${Math.random().toString(36).substring(2, 8)}`;
+const interpolationStart = `${marker}{`;
+const interpolationEnd = `}${marker}`;
+const interpolationEndLength = interpolationEnd.length;
+let id = 0;
+/** @internal */
+export const nextId = () => `${marker}-${++id}`;
+/**
+ * Common APIs related to markup generation.
+ * @public
+ */
+export const Markup = Object.freeze({
+    /**
+     * Creates a placeholder string suitable for marking out a location *within*
+     * an attribute value or HTML content.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by binding directives.
+     */
+    interpolation: (id) => `${interpolationStart}${id}${interpolationEnd}`,
+    /**
+     * Creates a placeholder that manifests itself as an attribute on an
+     * element.
+     * @param attributeName - The name of the custom attribute.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by attribute directives such as `ref`, `slotted`, and `children`.
+     */
+    attribute: (id) => `${nextId()}="${interpolationStart}${id}${interpolationEnd}"`,
+    /**
+     * Creates a placeholder that manifests itself as a marker within the DOM structure.
+     * @param index - The directive index to create the placeholder for.
+     * @remarks
+     * Used internally by structural directives such as `repeat`.
+     */
+    comment: (id) => `<!--${interpolationStart}${id}${interpolationEnd}-->`,
+});
+/**
+ * Common APIs related to content parsing.
+ * @public
+ */
+export const Parser = Object.freeze({
+    /**
+     * Parses text content or HTML attribute content, separating out the static strings
+     * from the directives.
+     * @param value - The content or attribute string to parse.
+     * @param factories - A list of directives to search for in the string.
+     * @returns A heterogeneous array of static strings interspersed with
+     * directives or null if no directives are found in the string.
+     */
+    parse(value, factories) {
+        // Split on the interpolation start marker. If there's only one part,
+        // no placeholders exist and we return null to signal "no directives here."
+        const parts = value.split(interpolationStart);
+        if (parts.length === 1) {
+            return null;
+        }
+        const result = [];
+        for (let i = 0, ii = parts.length; i < ii; ++i) {
+            const current = parts[i];
+            const index = current.indexOf(interpolationEnd);
+            let literal;
+            if (index === -1) {
+                literal = current;
+            }
+            else {
+                const factoryId = current.substring(0, index);
+                result.push(factories[factoryId]);
+                literal = current.substring(index + interpolationEndLength);
+            }
+            if (literal !== "") {
+                result.push(literal);
+            }
+        }
+        return result;
+    },
+});

package/dist/esm/templating/node-observation.js

@@ -0,0 +1,84 @@
+import { emptyArray } from "../platform.js";
+import { StatelessAttachedAttributeDirective, } from "./html-directive.js";
+const selectElements = (value) => value.nodeType === 1;
+/**
+ * Creates a function that can be used to filter a Node array, selecting only elements.
+ * @param selector - An optional selector to restrict the filter to.
+ * @public
+ */
+export const elements = (selector) => selector
+    ? value => value.nodeType === 1 && value.matches(selector)
+    : selectElements;
+/**
+ * A base class for node observation.
+ * @public
+ * @remarks
+ * Internally used by the SlottedDirective and the ChildrenDirective.
+ */
+export class NodeObservationDirective extends StatelessAttachedAttributeDirective {
+    /**
+     * The unique id of the factory.
+     */
+    get id() {
+        return this._id;
+    }
+    set id(value) {
+        this._id = value;
+        this._controllerProperty = `${value}-c`;
+    }
+    /**
+     * Bind this behavior to the source.
+     * @param source - The source to bind to.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    bind(controller) {
+        const target = controller.targets[this.targetNodeId];
+        target[this._controllerProperty] = controller;
+        this.updateTarget(controller.source, this.computeNodes(target));
+        this.observe(target);
+        controller.onUnbind(this);
+    }
+    /**
+     * Unbinds this behavior from the source.
+     * @param source - The source to unbind from.
+     * @param context - The execution context that the binding is operating within.
+     * @param targets - The targets that behaviors in a view can attach to.
+     */
+    unbind(controller) {
+        const target = controller.targets[this.targetNodeId];
+        this.updateTarget(controller.source, emptyArray);
+        this.disconnect(target);
+        target[this._controllerProperty] = null;
+    }
+    /**
+     * Gets the data source for the target.
+     * @param target - The target to get the source for.
+     * @returns The source.
+     */
+    getSource(target) {
+        return target[this._controllerProperty].source;
+    }
+    /**
+     * Updates the source property with the computed nodes.
+     * @param source - The source object to assign the nodes property to.
+     * @param value - The nodes to assign to the source object property.
+     */
+    updateTarget(source, value) {
+        source[this.options.property] = value;
+    }
+    /**
+     * Computes the set of nodes that should be assigned to the source property.
+     * @param target - The target to compute the nodes for.
+     * @returns The computed nodes.
+     * @remarks
+     * Applies filters if provided.
+     */
+    computeNodes(target) {
+        let nodes = this.getNodes(target);
+        if ("filter" in this.options) {
+            nodes = nodes.filter(this.options.filter);
+        }
+        return nodes;
+    }
+}

package/dist/esm/templating/ref.js

@@ -0,0 +1,21 @@
+import { HTMLDirective, StatelessAttachedAttributeDirective, } from "./html-directive.js";
+/**
+ * The runtime behavior for template references.
+ * @public
+ */
+export class RefDirective extends StatelessAttachedAttributeDirective {
+    /**
+     * Bind this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    bind(controller) {
+        controller.source[this.options] = controller.targets[this.targetNodeId];
+    }
+}
+HTMLDirective.define(RefDirective);
+/**
+ * A directive that observes the updates a property with a reference to the element.
+ * @param propertyName - The name of the property to assign the reference to.
+ * @public
+ */
+export const ref = (propertyName) => new RefDirective(propertyName);

package/dist/esm/templating/render.js

@@ -0,0 +1,468 @@
+import { Binding } from "../binding/binding.js";
+import { normalizeBinding } from "../binding/normalize.js";
+import { oneTime } from "../binding/one-time.js";
+import { oneWay } from "../binding/one-way.js";
+import { FASTElementDefinition } from "../components/fast-definitions.js";
+import { isHydratable } from "../components/hydration.js";
+import { isFunction, isString, Message } from "../interfaces.js";
+import { FAST } from "../platform.js";
+import { HTMLDirective, } from "./html-directive.js";
+import { HydrationStage } from "./hydration-view.js";
+import { Markup } from "./markup.js";
+import { html, ViewTemplate, } from "./template.js";
+import { createChildView } from "./view.js";
+/**
+ * A Behavior that enables advanced rendering.
+ * @public
+ */
+export class RenderBehavior {
+    /**
+     * Creates an instance of RenderBehavior.
+     * @param directive - The render directive that created this behavior.
+     */
+    constructor(directive) {
+        this.directive = directive;
+        this.location = null;
+        this.controller = null;
+        this.view = null;
+        this.data = null;
+        this.dataBindingObserver = directive.dataBinding.createObserver(this, directive);
+        this.templateBindingObserver = directive.templateBinding.createObserver(this, directive);
+    }
+    /**
+     * 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.data = this.dataBindingObserver.bind(controller);
+        this.template = this.templateBindingObserver.bind(controller);
+        controller.onUnbind(this);
+        if (isHydratable(this.template) &&
+            isHydratable(controller) &&
+            controller.hydrationStage !== HydrationStage.hydrated &&
+            !this.view) {
+            const viewNodes = controller.bindingViewBoundaries[this.directive.targetNodeId];
+            if (viewNodes) {
+                this.view = this.template.hydrate(viewNodes.first, viewNodes.last);
+                this.bindView(this.view);
+                return;
+            }
+        }
+        this.refreshView();
+    }
+    /**
+     * Unbinds this behavior.
+     * @param controller - The view controller that manages the lifecycle of this behavior.
+     */
+    unbind(controller) {
+        const view = this.view;
+        if (view !== null && view.isComposed) {
+            view.unbind();
+            view.needsBindOnly = true;
+        }
+    }
+    /**
+     * Handles changes from data or template binding observers.
+     * Guards against stale notifications that may arrive after the
+     * controller's view has been unbound (e.g., when a parent `when`
+     * directive tears down and later recreates a child element).
+     * @internal
+     */
+    handleChange(source, observer) {
+        // https://github.com/microsoft/fast/issues/7444
+        // This guard will be reconsidered in the next major version.
+        if (!this.controller.isBound) {
+            return;
+        }
+        if (observer === this.dataBindingObserver) {
+            this.data = this.dataBindingObserver.bind(this.controller);
+        }
+        if (this.directive.templateBindingDependsOnData ||
+            observer === this.templateBindingObserver) {
+            this.template = this.templateBindingObserver.bind(this.controller);
+        }
+        this.refreshView();
+    }
+    bindView(view) {
+        // It's possible that the value is the same as the previous template
+        // and that there's actually no need to compose it.
+        if (!view.isComposed) {
+            view.isComposed = true;
+            view.bind(this.data);
+            view.insertBefore(this.location);
+            view.$fastTemplate = this.template;
+        }
+        else if (view.needsBindOnly) {
+            view.needsBindOnly = false;
+            view.bind(this.data);
+        }
+    }
+    refreshView() {
+        let view = this.view;
+        const template = this.template;
+        if (view === null) {
+            this.view = view = createChildView(template, this.controller);
+            this.view.context.parent = this.controller.source;
+            this.view.context.parentContext = this.controller.context;
+        }
+        else {
+            // If there is a previous view, but it wasn't created
+            // from the same template as the new value, then we
+            // need to remove the old view if it's still in the DOM
+            // and create a new view from the template.
+            if (view.$fastTemplate !== template) {
+                if (view.isComposed) {
+                    view.remove();
+                    view.unbind();
+                }
+                this.view = view = createChildView(template, this.controller);
+                this.view.context.parent = this.controller.source;
+                this.view.context.parentContext = this.controller.context;
+            }
+        }
+        this.bindView(view);
+    }
+}
+/**
+ * A Directive that enables use of the RenderBehavior.
+ * @public
+ */
+export class RenderDirective {
+    /**
+     * Creates an instance of RenderDirective.
+     * @param dataBinding - A binding expression that returns the data to render.
+     * @param templateBinding - A binding expression that returns the template to use to render the data.
+     */
+    constructor(dataBinding, templateBinding, templateBindingDependsOnData) {
+        this.dataBinding = dataBinding;
+        this.templateBinding = templateBinding;
+        this.templateBindingDependsOnData = templateBindingDependsOnData;
+    }
+    /**
+     * Creates HTML to be used within a template.
+     * @param add - Can be used to add  behavior factories to a template.
+     */
+    createHTML(add) {
+        return Markup.comment(add(this));
+    }
+    /**
+     * Creates a behavior.
+     * @param targets - The targets available for behaviors to be attached to.
+     */
+    createBehavior() {
+        return new RenderBehavior(this);
+    }
+}
+HTMLDirective.define(RenderDirective);
+function isElementRenderOptions(object) {
+    return !!object.element || !!object.tagName;
+}
+const typeToInstructionLookup = new Map();
+/* eslint @typescript-eslint/naming-convention: "off"*/
+const defaultAttributes = { ":model": (x) => x };
+const brand = Symbol("RenderInstruction");
+const defaultViewName = "default-view";
+const nullTemplate = html `
+     
+`;
+function instructionToTemplate(def) {
+    if (def === void 0) {
+        return nullTemplate;
+    }
+    return def.template;
+}
+function resolveTemplateBindingValue(result, dataBinding, source, context) {
+    var _a;
+    if (isString(result)) {
+        return instructionToTemplate(getForInstance(dataBinding.evaluate(source, context), result));
+    }
+    if (result instanceof Node) {
+        return (_a = result.$fastTemplate) !== null && _a !== void 0 ? _a : new NodeTemplate(result);
+    }
+    return result;
+}
+function adaptTemplateBinding(binding, dataBinding) {
+    const evaluateTemplate = binding.evaluate;
+    const adapter = Object.create(Object.getPrototypeOf(binding));
+    for (const propertyName of Object.getOwnPropertyNames(binding)) {
+        if (propertyName !== "evaluate") {
+            Object.defineProperty(adapter, propertyName, Object.getOwnPropertyDescriptor(binding, propertyName));
+        }
+    }
+    Object.defineProperty(adapter, "evaluate", {
+        configurable: true,
+        enumerable: true,
+        value: (source, context) => resolveTemplateBindingValue(evaluateTemplate(source, context), dataBinding, source, context),
+        writable: true,
+    });
+    return adapter;
+}
+function createElementTemplate(tagName, options) {
+    const markup = [];
+    const values = [];
+    const { attributes, directives, content, policy } = options !== null && options !== void 0 ? options : {};
+    markup.push(`<${tagName}`);
+    if (attributes) {
+        const attrNames = Object.getOwnPropertyNames(attributes);
+        for (let i = 0, ii = attrNames.length; i < ii; ++i) {
+            const name = attrNames[i];
+            if (i === 0) {
+                markup[0] = `${markup[0]} ${name}="`;
+            }
+            else {
+                markup.push(`" ${name}="`);
+            }
+            values.push(attributes[name]);
+        }
+        markup.push(`"`);
+    }
+    if (directives) {
+        markup[markup.length - 1] += " ";
+        for (let i = 0, ii = directives.length; i < ii; ++i) {
+            const directive = directives[i];
+            markup.push(i > 0 ? "" : " ");
+            values.push(directive);
+        }
+    }
+    markup[markup.length - 1] += ">";
+    if (content && isFunction(content.create)) {
+        values.push(content);
+        markup.push(`</${tagName}>`);
+    }
+    else {
+        const lastIndex = markup.length - 1;
+        markup[lastIndex] = `${markup[lastIndex]}${content !== null && content !== void 0 ? content : ""}</${tagName}>`;
+    }
+    return ViewTemplate.create(markup, values, policy);
+}
+function create(options) {
+    var _a;
+    const name = (_a = options.name) !== null && _a !== void 0 ? _a : defaultViewName;
+    let template;
+    if (isElementRenderOptions(options)) {
+        let tagName = options.tagName;
+        if (!tagName) {
+            const def = FASTElementDefinition.getByType(options.element);
+            if (def) {
+                tagName = def.name;
+            }
+            else {
+                throw new Error("Invalid element for model rendering.");
+            }
+        }
+        if (!options.attributes) {
+            options.attributes = defaultAttributes;
+        }
+        template = createElementTemplate(tagName, options);
+    }
+    else {
+        template = options.template;
+    }
+    return {
+        brand,
+        type: options.type,
+        name,
+        template,
+    };
+}
+function instanceOf(object) {
+    return object && object.brand === brand;
+}
+function register(optionsOrInstruction) {
+    let lookup = typeToInstructionLookup.get(optionsOrInstruction.type);
+    if (lookup === void 0) {
+        typeToInstructionLookup.set(optionsOrInstruction.type, (lookup = Object.create(null)));
+    }
+    const instruction = instanceOf(optionsOrInstruction)
+        ? optionsOrInstruction
+        : create(optionsOrInstruction);
+    if (lookup[instruction.name] !== void 0) {
+        const typeName = instruction.type.name || "(anonymous)";
+        FAST.warn(Message.duplicateRenderInstruction, {
+            type: typeName,
+            name: instruction.name,
+        });
+    }
+    return (lookup[instruction.name] = instruction);
+}
+function getByType(type, name) {
+    const entries = typeToInstructionLookup.get(type);
+    if (entries === void 0) {
+        return void 0;
+    }
+    return entries[name !== null && name !== void 0 ? name : defaultViewName];
+}
+function getForInstance(object, name) {
+    if (object) {
+        return getByType(object.constructor, name);
+    }
+    return void 0;
+}
+/**
+ * Provides APIs for creating and interacting with render instructions.
+ * @public
+ */
+export const RenderInstruction = Object.freeze({
+    /**
+     * Checks whether the provided object is a RenderInstruction.
+     * @param object - The object to check.
+     * @returns true if the object is a RenderInstruction; false otherwise
+     */
+    instanceOf,
+    /**
+     * Creates a RenderInstruction for a set of options.
+     * @param options - The options to use when creating the RenderInstruction.
+     * @remarks
+     * This API should be used with caution. When providing attributes or content,
+     * if not done properly, you 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
+     * content and attribute values particularly if they can come from user input.
+     */
+    create,
+    /**
+     * Creates a template based on a tag name.
+     * @param tagName - The tag name to use when creating the template.
+     * @param attributes - The attributes to apply to the element.
+     * @param content - The content to insert into the element.
+     * @param policy - The DOMPolicy to create the template with.
+     * @returns A template based on the provided specifications.
+     * @remarks
+     * This API should be used with caution. When providing attributes or content,
+     * if not done properly, you 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
+     * content and attribute values particularly if they can come from user input.
+     */
+    createElementTemplate,
+    /**
+     * Creates and registers an instruction.
+     * @param options The options to use when creating the RenderInstruction.
+     * @remarks
+     * A previously created RenderInstruction can also be registered.
+     */
+    register,
+    /**
+     * Finds a previously registered RenderInstruction by type and optionally by name.
+     * @param type - The type to retrieve the RenderInstruction for.
+     * @param name - An optional name used in differentiating between multiple registered instructions.
+     * @returns The located RenderInstruction that matches the criteria or undefined if none is found.
+     */
+    getByType,
+    /**
+     * Finds a previously registered RenderInstruction for the instance's type and optionally by name.
+     * @param object - The instance to retrieve the RenderInstruction for.
+     * @param name - An optional name used in differentiating between multiple registered instructions.
+     * @returns The located RenderInstruction that matches the criteria or undefined if none is found.
+     */
+    getForInstance,
+});
+export function renderWith(value, name) {
+    return function (type) {
+        if (isFunction(value)) {
+            register({ type, element: value, name });
+        }
+        else if (isFunction(value.create)) {
+            register({ type, template: value, name });
+        }
+        else {
+            register(Object.assign({ type }, value));
+        }
+    };
+}
+/**
+ * @internal
+ */
+export class NodeTemplate {
+    constructor(node) {
+        this.node = node;
+        node.$fastTemplate = this;
+    }
+    get context() {
+        // HACK
+        return this;
+    }
+    bind(source) { }
+    unbind() { }
+    insertBefore(refNode) {
+        refNode.parentNode.insertBefore(this.node, refNode);
+    }
+    remove() {
+        this.node.parentNode.removeChild(this.node);
+    }
+    create() {
+        return this;
+    }
+    hydrate(first, last) {
+        return this;
+    }
+}
+/**
+ * Creates a RenderDirective for use in advanced rendering scenarios.
+ * @param value - The binding expression that returns the data to be rendered. The expression
+ * can also return a Node to render directly.
+ * @param template - A template to render the data with
+ * or a string to indicate which RenderInstruction to use when looking up a RenderInstruction.
+ * Expressions can also be provided to dynamically determine either the template or the name.
+ * @returns A RenderDirective suitable for use in a template.
+ * @remarks
+ * If no binding is provided, then a default binding that returns the source is created.
+ * If no template is provided, then a binding is created that will use registered
+ * RenderInstructions to determine the view.
+ * If the template binding returns a string, then it will be used to look up a
+ * RenderInstruction to determine the view.
+ * @public
+ */
+export function render(value, template) {
+    let dataBinding;
+    if (value === void 0) {
+        dataBinding = oneTime((source) => source);
+    }
+    else {
+        dataBinding = normalizeBinding(value);
+    }
+    let templateBinding;
+    let templateBindingDependsOnData = false;
+    if (template === void 0) {
+        templateBindingDependsOnData = true;
+        templateBinding = oneTime((s, c) => {
+            var _a;
+            const data = dataBinding.evaluate(s, c);
+            if (data instanceof Node) {
+                return (_a = data.$fastTemplate) !== null && _a !== void 0 ? _a : new NodeTemplate(data);
+            }
+            return instructionToTemplate(getForInstance(data));
+        });
+    }
+    else if (isFunction(template)) {
+        templateBinding = oneWay((s, c) => {
+            var _a;
+            let result = template(s, c);
+            if (isString(result)) {
+                result = instructionToTemplate(getForInstance(dataBinding.evaluate(s, c), result));
+            }
+            else if (result instanceof Node) {
+                result = (_a = result.$fastTemplate) !== null && _a !== void 0 ? _a : new NodeTemplate(result);
+            }
+            return result;
+        }, void 0, true);
+    }
+    else if (isString(template)) {
+        templateBindingDependsOnData = true;
+        templateBinding = oneTime((s, c) => {
+            var _a;
+            const data = dataBinding.evaluate(s, c);
+            if (data instanceof Node) {
+                return (_a = data.$fastTemplate) !== null && _a !== void 0 ? _a : new NodeTemplate(data);
+            }
+            return instructionToTemplate(getForInstance(data, template));
+        });
+    }
+    else if (template instanceof Binding) {
+        templateBinding = adaptTemplateBinding(template, dataBinding);
+    }
+    else {
+        templateBinding = oneTime((s, c) => template);
+    }
+    return new RenderDirective(dataBinding, templateBinding, templateBindingDependsOnData);
+}