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

package/dist/esm/dom-policy.js

@@ -0,0 +1,374 @@
+import { DOMAspect } from "./dom.js";
+import { isString, Message } from "./interfaces.js";
+import { FAST } from "./platform.js";
+const surroundingWhitespaceAndControlChars = /^[\u0000-\u0020\u007F]+|[\u0000-\u0020\u007F]+$/g;
+const whitespaceAndControlChars = /[\u0000-\u0020\u007F]+/g;
+const unsafeURLProtocol = /^(?:javascript|vbscript|data):/;
+function trimURL(value) {
+    return value.replace(surroundingWhitespaceAndControlChars, "");
+}
+function decodeURL(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch (_a) {
+        return value;
+    }
+}
+function hasUnsafeURLProtocol(value) {
+    let normalized = trimURL(value);
+    for (let i = 0; i < 3; ++i) {
+        const decoded = decodeURL(normalized);
+        if (decoded === normalized) {
+            break;
+        }
+        normalized = trimURL(decoded);
+    }
+    normalized = normalized.replace(whitespaceAndControlChars, "").toLowerCase();
+    return unsafeURLProtocol.test(normalized);
+}
+function sanitizeURL(value) {
+    const trimmed = trimURL(value);
+    return hasUnsafeURLProtocol(trimmed) ? "" : trimmed;
+}
+function safeURL(tagName, aspect, aspectName, sink) {
+    return (target, name, value, ...rest) => {
+        if (isString(value)) {
+            value = sanitizeURL(value);
+        }
+        sink(target, name, value, ...rest);
+    };
+}
+function block(tagName, aspect, aspectName, sink) {
+    throw FAST.error(Message.blockedByDOMPolicy, {
+        aspectName,
+        tagName: tagName !== null && tagName !== void 0 ? tagName : "text",
+    });
+}
+const defaultDOMElementGuards = {
+    a: {
+        [DOMAspect.attribute]: {
+            href: safeURL,
+        },
+        [DOMAspect.property]: {
+            href: safeURL,
+        },
+    },
+    area: {
+        [DOMAspect.attribute]: {
+            href: safeURL,
+        },
+        [DOMAspect.property]: {
+            href: safeURL,
+        },
+    },
+    button: {
+        [DOMAspect.attribute]: {
+            formaction: safeURL,
+        },
+        [DOMAspect.property]: {
+            formAction: safeURL,
+        },
+    },
+    embed: {
+        [DOMAspect.attribute]: {
+            src: block,
+        },
+        [DOMAspect.property]: {
+            src: block,
+        },
+    },
+    form: {
+        [DOMAspect.attribute]: {
+            action: safeURL,
+        },
+        [DOMAspect.property]: {
+            action: safeURL,
+        },
+    },
+    frame: {
+        [DOMAspect.attribute]: {
+            src: safeURL,
+        },
+        [DOMAspect.property]: {
+            src: safeURL,
+        },
+    },
+    iframe: {
+        [DOMAspect.attribute]: {
+            src: safeURL,
+        },
+        [DOMAspect.property]: {
+            src: safeURL,
+            srcdoc: block,
+        },
+    },
+    input: {
+        [DOMAspect.attribute]: {
+            formaction: safeURL,
+        },
+        [DOMAspect.property]: {
+            formAction: safeURL,
+        },
+    },
+    link: {
+        [DOMAspect.attribute]: {
+            href: block,
+        },
+        [DOMAspect.property]: {
+            href: block,
+        },
+    },
+    object: {
+        [DOMAspect.attribute]: {
+            codebase: block,
+            data: block,
+        },
+        [DOMAspect.property]: {
+            codeBase: block,
+            data: block,
+        },
+    },
+    script: {
+        [DOMAspect.attribute]: {
+            src: block,
+            text: block,
+        },
+        [DOMAspect.property]: {
+            src: block,
+            text: block,
+            innerText: block,
+            textContent: block,
+        },
+    },
+    style: {
+        [DOMAspect.property]: {
+            innerText: block,
+            textContent: block,
+        },
+    },
+};
+const blockedEvents = {
+    onabort: block,
+    onauxclick: block,
+    onbeforeinput: block,
+    onbeforematch: block,
+    onblur: block,
+    oncancel: block,
+    oncanplay: block,
+    oncanplaythrough: block,
+    onchange: block,
+    onclick: block,
+    onclose: block,
+    oncontextlost: block,
+    oncontextmenu: block,
+    oncontextrestored: block,
+    oncopy: block,
+    oncuechange: block,
+    oncut: block,
+    ondblclick: block,
+    ondrag: block,
+    ondragend: block,
+    ondragenter: block,
+    ondragleave: block,
+    ondragover: block,
+    ondragstart: block,
+    ondrop: block,
+    ondurationchange: block,
+    onemptied: block,
+    onended: block,
+    onerror: block,
+    onfocus: block,
+    onformdata: block,
+    oninput: block,
+    oninvalid: block,
+    onkeydown: block,
+    onkeypress: block,
+    onkeyup: block,
+    onload: block,
+    onloadeddata: block,
+    onloadedmetadata: block,
+    onloadstart: block,
+    onmousedown: block,
+    onmouseenter: block,
+    onmouseleave: block,
+    onmousemove: block,
+    onmouseout: block,
+    onmouseover: block,
+    onmouseup: block,
+    onpaste: block,
+    onpause: block,
+    onplay: block,
+    onplaying: block,
+    onprogress: block,
+    onratechange: block,
+    onreset: block,
+    onresize: block,
+    onscroll: block,
+    onsecuritypolicyviolation: block,
+    onseeked: block,
+    onseeking: block,
+    onselect: block,
+    onslotchange: block,
+    onstalled: block,
+    onsubmit: block,
+    onsuspend: block,
+    ontimeupdate: block,
+    ontoggle: block,
+    onvolumechange: block,
+    onwaiting: block,
+    onwebkitanimationend: block,
+    onwebkitanimationiteration: block,
+    onwebkitanimationstart: block,
+    onwebkittransitionend: block,
+    onwheel: block,
+};
+const defaultDOMGuards = {
+    elements: defaultDOMElementGuards,
+    aspects: {
+        [DOMAspect.attribute]: Object.assign({}, blockedEvents),
+        [DOMAspect.property]: Object.assign({ innerHTML: block }, blockedEvents),
+        [DOMAspect.event]: Object.assign({}, blockedEvents),
+    },
+};
+function createDomSinkGuards(config, defaults) {
+    const result = {};
+    for (const name in defaults) {
+        const overrideValue = config[name];
+        const defaultValue = defaults[name];
+        switch (overrideValue) {
+            case null:
+                // remove the default
+                break;
+            case undefined:
+                // keep the default
+                result[name] = defaultValue;
+                break;
+            default:
+                // override the default
+                result[name] = overrideValue;
+                break;
+        }
+    }
+    // add any new sinks that were not overrides
+    for (const name in config) {
+        if (!(name in result)) {
+            result[name] = config[name];
+        }
+    }
+    return Object.freeze(result);
+}
+function createDOMAspectGuards(config, defaults) {
+    const result = {};
+    for (const aspect in defaults) {
+        const overrideValue = config[aspect];
+        const defaultValue = defaults[aspect];
+        switch (overrideValue) {
+            case null:
+                // remove the default
+                break;
+            case undefined:
+                // keep the default
+                result[aspect] = createDomSinkGuards(defaultValue, {});
+                break;
+            default:
+                // override the default
+                result[aspect] = createDomSinkGuards(overrideValue, defaultValue);
+                break;
+        }
+    }
+    // add any new aspect guards that were not overrides
+    for (const aspect in config) {
+        if (!(aspect in result)) {
+            result[aspect] = createDomSinkGuards(config[aspect], {});
+        }
+    }
+    return Object.freeze(result);
+}
+function createElementGuards(config, defaults) {
+    const result = {};
+    for (const tag in defaults) {
+        const overrideValue = config[tag];
+        const defaultValue = defaults[tag];
+        switch (overrideValue) {
+            case null:
+                // remove the default
+                break;
+            case undefined:
+                // keep the default
+                result[tag] = createDOMAspectGuards(defaultValue, {});
+                break;
+            default:
+                // override the default aspects
+                result[tag] = createDOMAspectGuards(overrideValue, defaultValue);
+                break;
+        }
+    }
+    // Add any new element guards that were not overrides
+    for (const tag in config) {
+        if (!(tag in result)) {
+            result[tag] = createDOMAspectGuards(config[tag], {});
+        }
+    }
+    return Object.freeze(result);
+}
+function createDOMGuards(config, defaults) {
+    return Object.freeze({
+        elements: config.elements
+            ? createElementGuards(config.elements, defaults.elements)
+            : defaults.elements,
+        aspects: config.aspects
+            ? createDOMAspectGuards(config.aspects, defaults.aspects)
+            : defaults.aspects,
+    });
+}
+function createTrustedType() {
+    const createHTML = html => html;
+    return globalThis.trustedTypes
+        ? globalThis.trustedTypes.createPolicy("fast-element", { createHTML })
+        : { createHTML };
+}
+function tryGuard(aspectGuards, tagName, aspect, aspectName, sink) {
+    const sinkGuards = aspectGuards[aspect];
+    if (sinkGuards) {
+        const guard = sinkGuards[aspectName];
+        if (guard) {
+            return guard(tagName, aspect, aspectName, sink);
+        }
+    }
+}
+/**
+ * A helper for creating DOM policies.
+ * @public
+ */
+export const DOMPolicy = Object.freeze({
+    /**
+     * Creates a new DOM Policy object.
+     * @param options - The options to use in creating the policy.
+     * @returns The newly created DOMPolicy.
+     */
+    create(options = {}) {
+        var _a, _b;
+        const trustedType = (_a = options.trustedType) !== null && _a !== void 0 ? _a : createTrustedType();
+        const guards = createDOMGuards((_b = options.guards) !== null && _b !== void 0 ? _b : {}, defaultDOMGuards);
+        return Object.freeze({
+            createHTML(value) {
+                return trustedType.createHTML(value);
+            },
+            protect(tagName, aspect, aspectName, sink) {
+                var _a;
+                // Check for element-specific guards.
+                const key = (tagName !== null && tagName !== void 0 ? tagName : "").toLowerCase();
+                const elementGuards = guards.elements[key];
+                if (elementGuards) {
+                    const guard = tryGuard(elementGuards, tagName, aspect, aspectName, sink);
+                    if (guard) {
+                        return guard;
+                    }
+                }
+                // Check for guards applicable to all nodes.
+                return ((_a = tryGuard(guards.aspects, tagName, aspect, aspectName, sink)) !== null && _a !== void 0 ? _a : sink);
+            },
+        });
+    },
+});

package/dist/esm/dom.js

@@ -0,0 +1,101 @@
+import { Message } from "./interfaces.js";
+import { FAST } from "./platform.js";
+/**
+ * The type of HTML aspect to target.
+ * @public
+ */
+export const DOMAspect = Object.freeze({
+    /**
+     * Not aspected.
+     */
+    none: 0,
+    /**
+     * An attribute.
+     */
+    attribute: 1,
+    /**
+     * A boolean attribute.
+     */
+    booleanAttribute: 2,
+    /**
+     * A property.
+     */
+    property: 3,
+    /**
+     * Content
+     */
+    content: 4,
+    /**
+     * A token list.
+     */
+    tokenList: 5,
+    /**
+     * An event.
+     */
+    event: 6,
+});
+const createHTML = html => html;
+const fastTrustedType = globalThis.trustedTypes
+    ? globalThis.trustedTypes.createPolicy("fast-element", { createHTML })
+    : { createHTML };
+let defaultPolicy = Object.freeze({
+    createHTML(value) {
+        return fastTrustedType.createHTML(value);
+    },
+    protect(tagName, aspect, aspectName, sink) {
+        return sink;
+    },
+});
+const fastPolicy = defaultPolicy;
+/**
+ * Common DOM APIs.
+ * @public
+ */
+export const DOM = Object.freeze({
+    /**
+     * Gets the dom policy used by the templating system.
+     */
+    get policy() {
+        return defaultPolicy;
+    },
+    /**
+     * Sets the dom policy used by the templating system.
+     * @param policy - The policy to set.
+     * @remarks
+     * This API can only be called once, for security reasons. It should be
+     * called by the application developer at the start of their program.
+     */
+    setPolicy(value) {
+        if (defaultPolicy !== fastPolicy) {
+            throw FAST.error(Message.onlySetDOMPolicyOnce);
+        }
+        defaultPolicy = value;
+    },
+    /**
+     * Sets an attribute value on an element.
+     * @param element - The element to set the attribute value on.
+     * @param attributeName - The attribute name to set.
+     * @param value - The value of the attribute to set.
+     * @remarks
+     * If the value is `null` or `undefined`, the attribute is removed, otherwise
+     * it is set to the provided value using the standard `setAttribute` API.
+     */
+    setAttribute(element, attributeName, value) {
+        value === null || value === undefined
+            ? element.removeAttribute(attributeName)
+            : element.setAttribute(attributeName, value);
+    },
+    /**
+     * Sets a boolean attribute value.
+     * @param element - The element to set the boolean attribute value on.
+     * @param attributeName - The attribute name to set.
+     * @param value - The value of the attribute to set.
+     * @remarks
+     * If the value is true, the attribute is added; otherwise it is removed.
+     */
+    setBooleanAttribute(element, attributeName, value) {
+        value
+            ? element.setAttribute(attributeName, "")
+            : element.removeAttribute(attributeName);
+    },
+});

package/dist/esm/hydration/diagnostics.js

@@ -0,0 +1,50 @@
+import { formatDefaultMismatchMessage, unknownHostName } from "./messages.js";
+function formatMinimalMessage(hostName, detail) {
+    const host = (hostName !== null && hostName !== void 0 ? hostName : unknownHostName).toLowerCase();
+    return formatDefaultMismatchMessage(host, detail);
+}
+const defaultDiagnostic = {
+    formatBindingMismatch(_factory, _firstChild, _lastChild, hostName) {
+        return {
+            message: formatMinimalMessage(hostName, undefined),
+        };
+    },
+    formatStructuralError(_node, hostName, expectedDescription) {
+        return {
+            message: formatMinimalMessage(hostName, expectedDescription),
+        };
+    },
+};
+let activeDiagnostic = defaultDiagnostic;
+/**
+ * Installs a {@link HydrationDiagnostic} as the active formatter for
+ * hydration mismatch errors. Called by `enableHydration()` when an opt-in
+ * debugger configuration is supplied; not exposed as `@public` because
+ * library consumers should always go through `enableHydration` to install
+ * a debugger.
+ * @internal
+ */
+export function installHydrationDiagnostic(diagnostic) {
+    activeDiagnostic = diagnostic;
+}
+/**
+ * Returns the currently active {@link HydrationDiagnostic} — either the
+ * minimal default or one installed by an opt-in debugger.
+ * @internal
+ */
+export function getHydrationDiagnostic() {
+    return activeDiagnostic;
+}
+/**
+ * Reads the host element's tag name from any node inside a hydration view.
+ * Returns `undefined` when the node is not inside a shadow root.
+ * @internal
+ */
+export function getHostName(node) {
+    var _a;
+    if (!node) {
+        return undefined;
+    }
+    const root = node.getRootNode();
+    return (_a = root.host) === null || _a === void 0 ? void 0 : _a.nodeName;
+}

package/dist/esm/hydration/exports.js

@@ -0,0 +1,6 @@
+export { deferHydrationAttribute, enableHydration, StopHydration, } from "../components/enable-hydration.js";
+export { isHydratable } from "../components/hydration.js";
+export { HydrationTracker } from "../components/hydration-tracker.js";
+export { DOMPolicy, } from "../dom-policy.js";
+export { HydrationBindingError, HydrationStage, } from "../templating/hydration-view.js";
+export { hydrationDebugger } from "./hydration-debugger.js";

package/dist/esm/hydration/hydration-debugger.js

@@ -0,0 +1,112 @@
+import { DOMAspect } from "../dom.js";
+import { aspectLabelAttribute, aspectLabelBooleanAttribute, aspectLabelContent, aspectLabelEvent, aspectLabelProperty, aspectLabelTokenList, aspectLabelUnknown, formatAspect, formatExpectedTarget, formatRichMismatchMessage, unknownHostName, } from "./messages.js";
+const aspectLabelsByCode = Object.freeze({
+    [DOMAspect.attribute]: aspectLabelAttribute,
+    [DOMAspect.booleanAttribute]: aspectLabelBooleanAttribute,
+    [DOMAspect.property]: aspectLabelProperty,
+    [DOMAspect.content]: aspectLabelContent,
+    [DOMAspect.tokenList]: aspectLabelTokenList,
+    [DOMAspect.event]: aspectLabelEvent,
+});
+const defaultSnippetLength = 500;
+function describeAspect(aspectType, sourceAspect) {
+    var _a;
+    const base = aspectType !== undefined
+        ? ((_a = aspectLabelsByCode[aspectType]) !== null && _a !== void 0 ? _a : aspectLabelUnknown)
+        : aspectLabelUnknown;
+    return formatAspect(base, sourceAspect);
+}
+function describeExpectedTarget(factory) {
+    var _a;
+    const aspectType = factory.aspectType;
+    const sourceAspect = factory.sourceAspect;
+    return {
+        tagName: (_a = factory.targetTagName) !== null && _a !== void 0 ? _a : null,
+        aspect: describeAspect(aspectType, sourceAspect),
+    };
+}
+function stripEmptyComments(root) {
+    var _a;
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+    const empties = [];
+    let current;
+    while ((current = walker.nextNode()) !== null) {
+        if (current.data === "") {
+            empties.push(current);
+        }
+    }
+    for (const comment of empties) {
+        (_a = comment.parentNode) === null || _a === void 0 ? void 0 : _a.removeChild(comment);
+    }
+}
+function truncate(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength)}…` : value;
+}
+function serializeNodeForError(node, maxLength = defaultSnippetLength) {
+    const wrapper = document.createElement("div");
+    wrapper.appendChild(node.cloneNode(true));
+    stripEmptyComments(wrapper);
+    return truncate(wrapper.innerHTML.trim(), maxLength);
+}
+function serializeRangeForError(first, last, maxLength = defaultSnippetLength) {
+    const wrapper = document.createElement("div");
+    let current = first;
+    while (current !== null) {
+        wrapper.appendChild(current.cloneNode(true));
+        if (current === last) {
+            break;
+        }
+        current = current.nextSibling;
+    }
+    stripEmptyComments(wrapper);
+    return truncate(wrapper.innerHTML.trim(), maxLength);
+}
+function formatMismatchMessage(hostName, expected, received) {
+    const host = (hostName !== null && hostName !== void 0 ? hostName : unknownHostName).toLowerCase();
+    const expectedText = typeof expected === "string"
+        ? expected
+        : formatExpectedTarget(expected.tagName, expected.aspect);
+    return formatRichMismatchMessage(host, expectedText, received.html);
+}
+const richDiagnostic = {
+    formatBindingMismatch(factory, firstChild, lastChild, hostName) {
+        const expected = describeExpectedTarget(factory);
+        const received = {
+            html: serializeRangeForError(firstChild, lastChild),
+        };
+        const result = {
+            message: formatMismatchMessage(hostName, expected, received),
+            expected,
+            received,
+        };
+        return result;
+    },
+    formatStructuralError(node, hostName, expectedDescription) {
+        const received = {
+            html: serializeNodeForError(node),
+        };
+        const result = {
+            message: formatMismatchMessage(hostName, expectedDescription, received),
+            expected: expectedDescription,
+            received,
+        };
+        return result;
+    },
+};
+/**
+ * Returns a {@link HydrationDebugger} that, when supplied to
+ * `enableHydration({ debugger })`, installs the rich hydration mismatch
+ * formatter: a single-line "Expected … / Received …" message plus an HTML
+ * snippet of the SSR DOM and structured `expected`/`received` fields on
+ * the thrown error (both `HydrationBindingError` and
+ * `HydrationTargetElementError`).
+ *
+ * Without the debugger, hydration errors emit only a minimal one-line
+ * message pointing at this function — keeping the runtime hydration cost
+ * small for production bundles that do not need rich diagnostics.
+ *
+ * @public
+ */
+export function hydrationDebugger() {
+    return { diagnostic: richDiagnostic };
+}