@dso-toolkit/core 54.2.1 → 55.0.0

package/dist/esm/{index-ac5a22a3.js → index-898d8443.js}

@@ -47,11 +47,30 @@ const EMPTY_OBJ = {};
 const SVG_NS = 'http://www.w3.org/2000/svg';
 const HTML_NS = 'http://www.w3.org/1999/xhtml';
 const isDef = (v) => v != null;
+/**
+ * Check whether a value is a 'complex type', defined here as an object or a
+ * function.
+ *
+ * @param o the value to check
+ * @returns whether it's a complex type or not
+ */
 const isComplexType = (o) => {
     // https://jsperf.com/typeof-fn-object/5
     o = typeof o;
     return o === 'object' || o === 'function';
 };
+/**
+ * Helper method for querying a `meta` tag that contains a nonce value
+ * out of a DOM's head.
+ *
+ * @param doc The DOM containing the `head` to query against
+ * @returns The content of the meta tag representing the nonce value, or `undefined` if no tag
+ * exists or the tag has no content.
+ */
+function queryNonceMetaTagContent(doc) {
+    var _a, _b, _c;
+    return (_c = (_b = (_a = doc.head) === null || _a === void 0 ? void 0 : _a.querySelector('meta[name="csp-nonce"]')) === null || _b === void 0 ? void 0 : _b.getAttribute('content')) !== null && _c !== void 0 ? _c : undefined;
+}
 /**
  * Production h() function based on Preact by
  * Jason Miller (@developit)
@@ -60,7 +79,6 @@ const isComplexType = (o) => {
  *
  * Modified for Stencil's compiler and vdom
  */
-// const stack: any[] = [];
 // export function h(nodeName: string | d.FunctionalComponent, vnodeData: d.PropsType, child?: d.ChildType): d.VNode;
 // export function h(nodeName: string | d.FunctionalComponent, vnodeData: d.PropsType, ...children: d.ChildType[]): d.VNode;
 const h = (nodeName, vnodeData, ...children) => {
@@ -130,6 +148,14 @@ const h = (nodeName, vnodeData, ...children) => {
     }
     return vnode;
 };
+/**
+ * A utility function for creating a virtual DOM node from a tag and some
+ * possible text content.
+ *
+ * @param tag the tag for this element
+ * @param text possible text content for the node
+ * @returns a newly-minted virtual DOM node
+ */
 const newVNode = (tag, text) => {
     const vnode = {
         $flags$: 0,
@@ -150,11 +176,31 @@ const newVNode = (tag, text) => {
     return vnode;
 };
 const Host = {};
+/**
+ * Check whether a given node is a Host node or not
+ *
+ * @param node the virtual DOM node to check
+ * @returns whether it's a Host node or not
+ */
 const isHost = (node) => node && node.$tag$ === Host;
+/**
+ * Implementation of {@link d.FunctionalUtilities} for Stencil's VDom.
+ *
+ * Note that these functions convert from {@link d.VNode} to
+ * {@link d.ChildNode} to give functional component developers a friendly
+ * interface.
+ */
 const vdomFnUtils = {
     forEach: (children, cb) => children.map(convertToPublic).forEach(cb),
     map: (children, cb) => children.map(convertToPublic).map(cb).map(convertToPrivate),
 };
+/**
+ * Convert a {@link d.VNode} to a {@link d.ChildNode} in order to present a
+ * friendlier public interface (hence, 'convertToPublic').
+ *
+ * @param node the virtual DOM node to convert
+ * @returns a converted child node
+ */
 const convertToPublic = (node) => ({
     vattrs: node.$attrs$,
     vchildren: node.$children$,
@@ -163,6 +209,15 @@ const convertToPublic = (node) => ({
     vtag: node.$tag$,
     vtext: node.$text$,
 });
+/**
+ * Convert a {@link d.ChildNode} back to an equivalent {@link d.VNode} in
+ * order to use the resulting object in the virtual DOM. The initial object was
+ * likely created as part of presenting a public API, so converting it back
+ * involved making it 'private' again (hence, `convertToPrivate`).
+ *
+ * @param node the child node to convert
+ * @returns a converted virtual DOM node
+ */
 const convertToPrivate = (node) => {
     if (typeof node.vtag === 'function') {
         const vnodeData = Object.assign({}, node.vattrs);
@@ -272,6 +327,7 @@ const registerStyle = (scopeId, cssText, allowCS) => {
     styles.set(scopeId, style);
 };
 const addStyle = (styleContainerNode, cmpMeta, mode, hostElm) => {
+    var _a;
     let scopeId = getScopeId(cmpMeta);
     const style = styles.get(scopeId);
     // if an element is NOT connected then getRootNode() will return the wrong root node
@@ -287,10 +343,16 @@ const addStyle = (styleContainerNode, cmpMeta, mode, hostElm) => {
             }
             if (!appliedStyles.has(scopeId)) {
                 {
+                    // TODO(STENCIL-659): Remove code implementing the CSS variable shim
                     {
                         styleElm = doc.createElement('style');
                         styleElm.innerHTML = style;
                     }
+                    // Apply CSP nonce to the style tag if it exists
+                    const nonce = (_a = plt.$nonce$) !== null && _a !== void 0 ? _a : queryNonceMetaTagContent(doc);
+                    if (nonce != null) {
+                        styleElm.setAttribute('nonce', nonce);
+                    }
                     styleContainerNode.insertBefore(styleElm, styleContainerNode.querySelector('link'));
                 }
                 if (appliedStyles) {
@@ -310,6 +372,7 @@ const attachStyles = (hostRef) => {
     const flags = cmpMeta.$flags$;
     const endAttachStyles = createTime('attachStyles', cmpMeta.$tagName$);
     const scopeId = addStyle(elm.shadowRoot ? elm.shadowRoot : elm.getRootNode(), cmpMeta);
+    // TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
     if (flags & 10 /* CMP_FLAGS.needsScopedEncapsulation */) {
         // only required when we're NOT using native shadow dom (slot)
         // or this browser doesn't support native shadow dom
@@ -627,6 +690,21 @@ const putBackInOriginalLocation = (parentElm, recursive) => {
     }
     plt.$flags$ &= ~1 /* PLATFORM_FLAGS.isTmpDisconnected */;
 };
+/**
+ * Create DOM nodes corresponding to a list of {@link d.Vnode} objects and
+ * add them to the DOM in the appropriate place.
+ *
+ * @param parentElm the DOM node which should be used as a parent for the new
+ * DOM nodes
+ * @param before a child of the `parentElm` which the new children should be
+ * inserted before (optional)
+ * @param parentVNode the parent virtual DOM node
+ * @param vnodes the new child virtual DOM nodes to produce DOM nodes for
+ * @param startIdx the index in the child virtual DOM nodes at which to start
+ * creating DOM nodes (inclusive)
+ * @param endIdx the index in the child virtual DOM nodes at which to stop
+ * creating DOM nodes (inclusive)
+ */
 const addVnodes = (parentElm, before, parentVNode, vnodes, startIdx, endIdx) => {
     let containerElm = ((parentElm['s-cr'] && parentElm['s-cr'].parentNode) || parentElm);
     let childNode;
@@ -643,27 +721,41 @@ const addVnodes = (parentElm, before, parentVNode, vnodes, startIdx, endIdx) =>
         }
     }
 };
-const removeVnodes = (vnodes, startIdx, endIdx, vnode, elm) => {
-    for (; startIdx <= endIdx; ++startIdx) {
-        if ((vnode = vnodes[startIdx])) {
-            elm = vnode.$elm$;
-            callNodeRefs(vnode);
-            {
-                // we're removing this element
-                // so it's possible we need to show slot fallback content now
-                checkSlotFallbackVisibility = true;
-                if (elm['s-ol']) {
-                    // remove the original location comment
-                    elm['s-ol'].remove();
-                }
-                else {
-                    // it's possible that child nodes of the node
-                    // that's being removed are slot nodes
-                    putBackInOriginalLocation(elm, true);
+/**
+ * Remove the DOM elements corresponding to a list of {@link d.VNode} objects.
+ * This can be used to, for instance, clean up after a list of children which
+ * should no longer be shown.
+ *
+ * This function also handles some of Stencil's slot relocation logic.
+ *
+ * @param vnodes a list of virtual DOM nodes to remove
+ * @param startIdx the index at which to start removing nodes (inclusive)
+ * @param endIdx the index at which to stop removing nodes (inclusive)
+ */
+const removeVnodes = (vnodes, startIdx, endIdx) => {
+    for (let index = startIdx; index <= endIdx; ++index) {
+        const vnode = vnodes[index];
+        if (vnode) {
+            const elm = vnode.$elm$;
+            nullifyVNodeRefs(vnode);
+            if (elm) {
+                {
+                    // we're removing this element
+                    // so it's possible we need to show slot fallback content now
+                    checkSlotFallbackVisibility = true;
+                    if (elm['s-ol']) {
+                        // remove the original location comment
+                        elm['s-ol'].remove();
+                    }
+                    else {
+                        // it's possible that child nodes of the node
+                        // that's being removed are slot nodes
+                        putBackInOriginalLocation(elm, true);
+                    }
                 }
+                // remove the vnode's element from the dom
+                elm.remove();
             }
-            // remove the vnode's element from the dom
-            elm.remove();
         }
     }
 };
@@ -921,7 +1013,8 @@ const updateChildren = (parentElm, oldCh, newVNode, newCh) => {
  *
  * So, in other words, if `key` attrs are not set on VNodes which may be
  * changing order within a `children` array or something along those lines then
- * we could obtain a false positive and then have to do needless re-rendering.
+ * we could obtain a false negative and then have to do needless re-rendering
+ * (i.e. we'd say two VNodes aren't equal when in fact they should be).
  *
  * @param leftVNode the first VNode to check
  * @param rightVNode the second VNode to check
@@ -1143,12 +1236,31 @@ const isNodeLocatedInSlot = (nodeToRelocate, slotNameAttr) => {
     }
     return slotNameAttr === '';
 };
-const callNodeRefs = (vNode) => {
+/**
+ * 'Nullify' any VDom `ref` callbacks on a VDom node or its children by
+ * calling them with `null`. This signals that the DOM element corresponding to
+ * the VDom node has been removed from the DOM.
+ *
+ * @param vNode a virtual DOM node
+ */
+const nullifyVNodeRefs = (vNode) => {
     {
         vNode.$attrs$ && vNode.$attrs$.ref && vNode.$attrs$.ref(null);
-        vNode.$children$ && vNode.$children$.map(callNodeRefs);
+        vNode.$children$ && vNode.$children$.map(nullifyVNodeRefs);
     }
 };
+/**
+ * The main entry point for Stencil's virtual DOM-based rendering engine
+ *
+ * Given a {@link d.HostRef} container and some virtual DOM nodes, this
+ * function will handle creating a virtual DOM tree with a single root, patching
+ * the current virtual DOM tree onto an old one (if any), dealing with slot
+ * relocation, and reflecting attributes.
+ *
+ * @param hostRef data needed to root and render the virtual DOM tree, such as
+ * the DOM node into which it should be rendered.
+ * @param renderFnResults the virtual DOM nodes to be rendered
+ */
 const renderVdom = (hostRef, renderFnResults) => {
     const hostElm = hostRef.$hostElement$;
     const cmpMeta = hostRef.$cmpMeta$;
@@ -1271,27 +1383,83 @@ const scheduleUpdate = (hostRef, isInitialLoad) => {
     const dispatch = () => dispatchHooks(hostRef, isInitialLoad);
     return writeTask(dispatch) ;
 };
+/**
+ * Dispatch initial-render and update lifecycle hooks, enqueuing calls to
+ * component lifecycle methods like `componentWillLoad` as well as
+ * {@link updateComponent}, which will kick off the virtual DOM re-render.
+ *
+ * @param hostRef a reference to a host DOM node
+ * @param isInitialLoad whether we're on the initial load or not
+ * @returns an empty Promise which is used to enqueue a series of operations for
+ * the component
+ */
 const dispatchHooks = (hostRef, isInitialLoad) => {
     const endSchedule = createTime('scheduleUpdate', hostRef.$cmpMeta$.$tagName$);
     const instance = hostRef.$lazyInstance$ ;
-    let promise;
+    // We're going to use this variable together with `enqueue` to implement a
+    // little promise-based queue. We start out with it `undefined`. When we add
+    // the first function to the queue we'll set this variable to be that
+    // function's return value. When we attempt to add subsequent values to the
+    // queue we'll check that value and, if it was a `Promise`, we'll then chain
+    // the new function off of that `Promise` using `.then()`. This will give our
+    // queue two nice properties:
+    //
+    // 1. If all functions added to the queue are synchronous they'll be called
+    //    synchronously right away.
+    // 2. If all functions added to the queue are asynchronous they'll all be
+    //    called in order after `dispatchHooks` exits.
+    let maybePromise;
     if (isInitialLoad) {
         {
             hostRef.$flags$ |= 256 /* HOST_FLAGS.isListenReady */;
             if (hostRef.$queuedListeners$) {
                 hostRef.$queuedListeners$.map(([methodName, event]) => safeCall(instance, methodName, event));
-                hostRef.$queuedListeners$ = null;
+                hostRef.$queuedListeners$ = undefined;
             }
         }
         {
-            promise = safeCall(instance, 'componentWillLoad');
+            // If `componentWillLoad` returns a `Promise` then we want to wait on
+            // whatever's going on in that `Promise` before we launch into
+            // rendering the component, doing other lifecycle stuff, etc. So
+            // in that case we assign the returned promise to the variable we
+            // declared above to hold a possible 'queueing' Promise
+            maybePromise = safeCall(instance, 'componentWillLoad');
         }
     }
     endSchedule();
-    return then(promise, () => updateComponent(hostRef, instance, isInitialLoad));
+    return enqueue(maybePromise, () => updateComponent(hostRef, instance, isInitialLoad));
 };
+/**
+ * This function uses a Promise to implement a simple first-in, first-out queue
+ * of functions to be called.
+ *
+ * The queue is ordered on the basis of the first argument. If it's
+ * `undefined`, then nothing is on the queue yet, so the provided function can
+ * be called synchronously (although note that this function may return a
+ * `Promise`). The idea is that then the return value of that enqueueing
+ * operation is kept around, so that if it was a `Promise` then subsequent
+ * functions can be enqueued by calling this function again with that `Promise`
+ * as the first argument.
+ *
+ * @param maybePromise either a `Promise` which should resolve before the next function is called or an 'empty' sentinel
+ * @param fn a function to enqueue
+ * @returns either a `Promise` or the return value of the provided function
+ */
+const enqueue = (maybePromise, fn) => isPromisey(maybePromise) ? maybePromise.then(fn) : fn();
+/**
+ * Check that a value is a `Promise`. To check, we first see if the value is an
+ * instance of the `Promise` global. In a few circumstances, in particular if
+ * the global has been overwritten, this is could be misleading, so we also do
+ * a little 'duck typing' check to see if the `.then` property of the value is
+ * defined and a function.
+ *
+ * @param maybePromise it might be a promise!
+ * @returns whether it is or not
+ */
+const isPromisey = (maybePromise) => maybePromise instanceof Promise ||
+    (maybePromise && maybePromise.then && typeof maybePromise.then === 'function');
 const updateComponent = async (hostRef, instance, isInitialLoad) => {
-    // updateComponent
+    var _a;
     const elm = hostRef.$hostElement$;
     const endUpdate = createTime('update', hostRef.$cmpMeta$.$tagName$);
     const rc = elm['s-rc'];
@@ -1313,7 +1481,7 @@ const updateComponent = async (hostRef, instance, isInitialLoad) => {
     endRender();
     endUpdate();
     {
-        const childrenPromises = elm['s-p'];
+        const childrenPromises = (_a = elm['s-p']) !== null && _a !== void 0 ? _a : [];
         const postUpdate = () => postUpdateComponent(hostRef);
         if (childrenPromises.length === 0) {
             postUpdate();
@@ -1435,9 +1603,6 @@ const safeCall = (instance, method, arg) => {
     }
     return undefined;
 };
-const then = (promise, thenFn) => {
-    return promise && promise.then ? promise.then(thenFn) : thenFn();
-};
 const addHydratedFlag = (elm) => elm.classList.add('hydrated')
     ;
 const getValue = (ref, propName) => getHostRef(ref).$instanceValues$.get(propName);
@@ -1601,9 +1766,9 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
 const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) => {
     // initializeComponent
     if ((hostRef.$flags$ & 32 /* HOST_FLAGS.hasInitializedComponent */) === 0) {
+        // Let the runtime know that the component has been initialized
+        hostRef.$flags$ |= 32 /* HOST_FLAGS.hasInitializedComponent */;
         {
-            // we haven't initialized this element yet
-            hostRef.$flags$ |= 32 /* HOST_FLAGS.hasInitializedComponent */;
             // lazy loaded components
             // request the component's implementation to be
             // wired up with the host element
@@ -1695,7 +1860,8 @@ const connectedCallback = (elm) => {
                 // if the slot polyfill is required we'll need to put some nodes
                 // in here to act as original content anchors as we move nodes around
                 // host element has been connected to the DOM
-                if ((cmpMeta.$flags$ & (4 /* CMP_FLAGS.hasSlotRelocation */ | 8 /* CMP_FLAGS.needsShadowDomShim */))) {
+                if ((// TODO(STENCIL-662): Remove code related to deprecated shadowDomShim field
+                        cmpMeta.$flags$ & (4 /* CMP_FLAGS.hasSlotRelocation */ | 8 /* CMP_FLAGS.needsShadowDomShim */))) {
                     setContentReference(elm);
                 }
             }
@@ -1767,6 +1933,7 @@ const disconnectedCallback = (elm) => {
     }
 };
 const bootstrapLazy = (lazyBundles, options = {}) => {
+    var _a;
     const endBootstrap = createTime();
     const cmpTags = [];
     const exclude = options.exclude || [];
@@ -1849,6 +2016,11 @@ const bootstrapLazy = (lazyBundles, options = {}) => {
     {
         visibilityStyle.innerHTML = cmpTags + HYDRATED_CSS;
         visibilityStyle.setAttribute('data-styles', '');
+        // Apply CSP nonce to the style tag if it exists
+        const nonce = (_a = plt.$nonce$) !== null && _a !== void 0 ? _a : queryNonceMetaTagContent(doc);
+        if (nonce != null) {
+            visibilityStyle.setAttribute('nonce', nonce);
+        }
         head.insertBefore(visibilityStyle, metaCharset ? metaCharset.nextSibling : head.firstChild);
     }
     // Process deferred connectedCallbacks now all components have been registered
@@ -1901,6 +2073,13 @@ const getHostListenerTarget = (elm, flags) => {
 };
 // prettier-ignore
 const hostListenerOpts = (flags) => (flags & 2 /* LISTENER_FLAGS.Capture */) !== 0;
+/**
+ * Assigns the given value to the nonce property on the runtime platform object.
+ * During runtime, this value is used to set the nonce attribute on all dynamically created script and style tags.
+ * @param nonce The value to be assigned to the platform nonce property.
+ * @returns void
+ */
+const setNonce = (nonce) => (plt.$nonce$ = nonce);
 const hostRefs = /*@__PURE__*/ new WeakMap();
 const getHostRef = (ref) => hostRefs.get(ref);
 const registerInstance = (lazyInstance, hostRef) => hostRefs.set((hostRef.$lazyInstance$ = lazyInstance), hostRef);
@@ -2011,4 +2190,6 @@ const flush = () => {
 const nextTick = /*@__PURE__*/ (cb) => promiseResolve().then(cb);
 const writeTask = /*@__PURE__*/ queueTask(queueDomWrites, true);
 
-export { Fragment as F, Host as H, getRenderingRef as a, bootstrapLazy as b, createEvent as c, forceUpdate as f, getElement as g, h, promiseResolve as p, registerInstance as r };
+export { Fragment as F, Host as H, getRenderingRef as a, bootstrapLazy as b, createEvent as c, forceUpdate as f, getElement as g, h, promiseResolve as p, registerInstance as r, setNonce as s };
+
+//# sourceMappingURL=index-898d8443.js.map