@revolist/revogrid 3.6.6 → 3.6.8

package/dist/esm/{index-6f753b3c.js → index-f21f8a13.js}

@@ -3,6 +3,14 @@
  */
 const NAMESPACE = 'revo-grid';
 
+/**
+ * Virtual DOM patching algorithm based on Snabbdom by
+ * Simon Friis Vindum (@paldepind)
+ * Licensed under the MIT License
+ * https://github.com/snabbdom/snabbdom/blob/master/LICENSE
+ *
+ * Modified for Stencil's renderer and slot projection
+ */
 let contentRef;
 let hostTagName;
 let useNativeShadowDom = false;
@@ -11,64 +19,6 @@ let checkSlotRelocate = false;
 let isSvgMode = false;
 let renderingRef = null;
 let queuePending = false;
-const win = typeof window !== 'undefined' ? window : {};
-const CSS = win.CSS ;
-const doc = win.document || { head: {} };
-const plt = {
-    $flags$: 0,
-    $resourcesUrl$: '',
-    jmp: (h) => h(),
-    raf: (h) => requestAnimationFrame(h),
-    ael: (el, eventName, listener, opts) => el.addEventListener(eventName, listener, opts),
-    rel: (el, eventName, listener, opts) => el.removeEventListener(eventName, listener, opts),
-    ce: (eventName, opts) => new CustomEvent(eventName, opts),
-};
-const promiseResolve = (v) => Promise.resolve(v);
-const supportsConstructableStylesheets = /*@__PURE__*/ (() => {
-        try {
-            new CSSStyleSheet();
-            return typeof new CSSStyleSheet().replaceSync === 'function';
-        }
-        catch (e) { }
-        return false;
-    })()
-    ;
-const addHostEventListeners = (elm, hostRef, listeners, attachParentListeners) => {
-    if (listeners) {
-        listeners.map(([flags, name, method]) => {
-            const target = getHostListenerTarget(elm, flags) ;
-            const handler = hostListenerProxy(hostRef, method);
-            const opts = hostListenerOpts(flags);
-            plt.ael(target, name, handler, opts);
-            (hostRef.$rmListeners$ = hostRef.$rmListeners$ || []).push(() => plt.rel(target, name, handler, opts));
-        });
-    }
-};
-const hostListenerProxy = (hostRef, methodName) => (ev) => {
-    try {
-        {
-            if (hostRef.$flags$ & 256 /* isListenReady */) {
-                // instance is ready, let's call it's member method for this event
-                hostRef.$lazyInstance$[methodName](ev);
-            }
-            else {
-                (hostRef.$queuedListeners$ = hostRef.$queuedListeners$ || []).push([methodName, ev]);
-            }
-        }
-    }
-    catch (e) {
-        consoleError(e);
-    }
-};
-const getHostListenerTarget = (elm, flags) => {
-    if (flags & 4 /* TargetDocument */)
-        return doc;
-    return elm;
-};
-// prettier-ignore
-const hostListenerOpts = (flags) => (flags & 2 /* Capture */) !== 0;
-const HYDRATED_CSS = '{visibility:hidden}.hydrated{visibility:inherit}';
-const XLINK_NS = 'http://www.w3.org/1999/xlink';
 const createTime = (fnName, tagName = '') => {
     {
         return () => {
@@ -83,75 +33,8 @@ const uniqueTime = (key, measureText) => {
         };
     }
 };
-const rootAppliedStyles = new WeakMap();
-const registerStyle = (scopeId, cssText, allowCS) => {
-    let style = styles.get(scopeId);
-    if (supportsConstructableStylesheets && allowCS) {
-        style = (style || new CSSStyleSheet());
-        if (typeof style === 'string') {
-            style = cssText;
-        }
-        else {
-            style.replaceSync(cssText);
-        }
-    }
-    else {
-        style = cssText;
-    }
-    styles.set(scopeId, style);
-};
-const addStyle = (styleContainerNode, cmpMeta, mode, hostElm) => {
-    let scopeId = getScopeId(cmpMeta);
-    const style = styles.get(scopeId);
-    // if an element is NOT connected then getRootNode() will return the wrong root node
-    // so the fallback is to always use the document for the root node in those cases
-    styleContainerNode = styleContainerNode.nodeType === 11 /* DocumentFragment */ ? styleContainerNode : doc;
-    if (style) {
-        if (typeof style === 'string') {
-            styleContainerNode = styleContainerNode.head || styleContainerNode;
-            let appliedStyles = rootAppliedStyles.get(styleContainerNode);
-            let styleElm;
-            if (!appliedStyles) {
-                rootAppliedStyles.set(styleContainerNode, (appliedStyles = new Set()));
-            }
-            if (!appliedStyles.has(scopeId)) {
-                {
-                    if (plt.$cssShim$) {
-                        styleElm = plt.$cssShim$.createHostStyle(hostElm, scopeId, style, !!(cmpMeta.$flags$ & 10 /* needsScopedEncapsulation */));
-                        const newScopeId = styleElm['s-sc'];
-                        if (newScopeId) {
-                            scopeId = newScopeId;
-                            // we don't want to add this styleID to the appliedStyles Set
-                            // since the cssVarShim might need to apply several different
-                            // stylesheets for the same component
-                            appliedStyles = null;
-                        }
-                    }
-                    else {
-                        styleElm = doc.createElement('style');
-                        styleElm.innerHTML = style;
-                    }
-                    styleContainerNode.insertBefore(styleElm, styleContainerNode.querySelector('link'));
-                }
-                if (appliedStyles) {
-                    appliedStyles.add(scopeId);
-                }
-            }
-        }
-        else if (!styleContainerNode.adoptedStyleSheets.includes(style)) {
-            styleContainerNode.adoptedStyleSheets = [...styleContainerNode.adoptedStyleSheets, style];
-        }
-    }
-    return scopeId;
-};
-const attachStyles = (hostRef) => {
-    const cmpMeta = hostRef.$cmpMeta$;
-    const elm = hostRef.$hostElement$;
-    const endAttachStyles = createTime('attachStyles', cmpMeta.$tagName$);
-    addStyle(elm.getRootNode(), cmpMeta, hostRef.$modeName$, elm);
-    endAttachStyles();
-};
-const getScopeId = (cmp, mode) => 'sc-' + (cmp.$tagName$);
+const HYDRATED_CSS = '{visibility:hidden}.hydrated{visibility:inherit}';
+const XLINK_NS = 'http://www.w3.org/1999/xlink';
 /**
  * Default style mode id
  */
@@ -165,11 +48,30 @@ const EMPTY_OBJ = {};
  */
 const SVG_NS = 'http://www.w3.org/2000/svg';
 const HTML_NS = 'http://www.w3.org/1999/xhtml';
+/**
+ * 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)
@@ -178,7 +80,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) => {
@@ -248,6 +149,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,
@@ -268,11 +177,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$,
@@ -281,6 +210,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);
@@ -299,6 +237,141 @@ const convertToPrivate = (node) => {
     vnode.$name$ = node.vname;
     return vnode;
 };
+/**
+ * Parse a new property value for a given property type.
+ *
+ * While the prop value can reasonably be expected to be of `any` type as far as TypeScript's type checker is concerned,
+ * it is not safe to assume that the string returned by evaluating `typeof propValue` matches:
+ *   1. `any`, the type given to `propValue` in the function signature
+ *   2. the type stored from `propType`.
+ *
+ * This function provides the capability to parse/coerce a property's value to potentially any other JavaScript type.
+ *
+ * Property values represented in TSX preserve their type information. In the example below, the number 0 is passed to
+ * a component. This `propValue` will preserve its type information (`typeof propValue === 'number'`). Note that is
+ * based on the type of the value being passed in, not the type declared of the class member decorated with `@Prop`.
+ * ```tsx
+ * <my-cmp prop-val={0}></my-cmp>
+ * ```
+ *
+ * HTML prop values on the other hand, will always a string
+ *
+ * @param propValue the new value to coerce to some type
+ * @param propType the type of the prop, expressed as a binary number
+ * @returns the parsed/coerced value
+ */
+const parsePropertyValue = (propValue, propType) => {
+    // ensure this value is of the correct prop type
+    if (propValue != null && !isComplexType(propValue)) {
+        if (propType & 4 /* MEMBER_FLAGS.Boolean */) {
+            // per the HTML spec, any string value means it is a boolean true value
+            // but we'll cheat here and say that the string "false" is the boolean false
+            return propValue === 'false' ? false : propValue === '' || !!propValue;
+        }
+        if (propType & 2 /* MEMBER_FLAGS.Number */) {
+            // force it to be a number
+            return parseFloat(propValue);
+        }
+        if (propType & 1 /* MEMBER_FLAGS.String */) {
+            // could have been passed as a number or boolean
+            // but we still want it as a string
+            return String(propValue);
+        }
+        // redundant return here for better minification
+        return propValue;
+    }
+    // not sure exactly what type we want
+    // so no need to change to a different type
+    return propValue;
+};
+const getElement = (ref) => (getHostRef(ref).$hostElement$ );
+const createEvent = (ref, name, flags) => {
+    const elm = getElement(ref);
+    return {
+        emit: (detail) => {
+            return emitEvent(elm, name, {
+                bubbles: !!(flags & 4 /* EVENT_FLAGS.Bubbles */),
+                composed: !!(flags & 2 /* EVENT_FLAGS.Composed */),
+                cancelable: !!(flags & 1 /* EVENT_FLAGS.Cancellable */),
+                detail,
+            });
+        },
+    };
+};
+/**
+ * Helper function to create & dispatch a custom Event on a provided target
+ * @param elm the target of the Event
+ * @param name the name to give the custom Event
+ * @param opts options for configuring a custom Event
+ * @returns the custom Event
+ */
+const emitEvent = (elm, name, opts) => {
+    const ev = plt.ce(name, opts);
+    elm.dispatchEvent(ev);
+    return ev;
+};
+const rootAppliedStyles = /*@__PURE__*/ new WeakMap();
+const registerStyle = (scopeId, cssText, allowCS) => {
+    let style = styles.get(scopeId);
+    if (supportsConstructableStylesheets && allowCS) {
+        style = (style || new CSSStyleSheet());
+        if (typeof style === 'string') {
+            style = cssText;
+        }
+        else {
+            style.replaceSync(cssText);
+        }
+    }
+    else {
+        style = cssText;
+    }
+    styles.set(scopeId, style);
+};
+const addStyle = (styleContainerNode, cmpMeta, mode) => {
+    var _a;
+    const scopeId = getScopeId(cmpMeta);
+    const style = styles.get(scopeId);
+    // if an element is NOT connected then getRootNode() will return the wrong root node
+    // so the fallback is to always use the document for the root node in those cases
+    styleContainerNode = styleContainerNode.nodeType === 11 /* NODE_TYPE.DocumentFragment */ ? styleContainerNode : doc;
+    if (style) {
+        if (typeof style === 'string') {
+            styleContainerNode = styleContainerNode.head || styleContainerNode;
+            let appliedStyles = rootAppliedStyles.get(styleContainerNode);
+            let styleElm;
+            if (!appliedStyles) {
+                rootAppliedStyles.set(styleContainerNode, (appliedStyles = new Set()));
+            }
+            if (!appliedStyles.has(scopeId)) {
+                {
+                    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) {
+                    appliedStyles.add(scopeId);
+                }
+            }
+        }
+        else if (!styleContainerNode.adoptedStyleSheets.includes(style)) {
+            styleContainerNode.adoptedStyleSheets = [...styleContainerNode.adoptedStyleSheets, style];
+        }
+    }
+    return scopeId;
+};
+const attachStyles = (hostRef) => {
+    const cmpMeta = hostRef.$cmpMeta$;
+    const elm = hostRef.$hostElement$;
+    const endAttachStyles = createTime('attachStyles', cmpMeta.$tagName$);
+    addStyle(elm.getRootNode(), cmpMeta);
+    endAttachStyles();
+};
+const getScopeId = (cmp, mode) => 'sc-' + (cmp.$tagName$);
 /**
  * Production setAccessor() function based on Preact by
  * Jason Miller (@developit)
@@ -435,7 +508,7 @@ const setAccessor = (elm, memberName, oldValue, newValue, isSvg, flags) => {
                     }
                 }
             }
-            else if ((!isProp || flags & 4 /* isHost */ || isSvg) && !isComplex) {
+            else if ((!isProp || flags & 4 /* VNODE_FLAGS.isHost */ || isSvg) && !isComplex) {
                 newValue = newValue === true ? '' : newValue;
                 if (xlink) {
                     elm.setAttributeNS(XLINK_NS, memberName, newValue);
@@ -453,7 +526,7 @@ const updateElement = (oldVnode, newVnode, isSvgMode, memberName) => {
     // if the element passed in is a shadow root, which is a document fragment
     // then we want to be adding attrs/props to the shadow root's "host" element
     // if it's not a shadow root, then we add attrs/props to the same element
-    const elm = newVnode.$elm$.nodeType === 11 /* DocumentFragment */ && newVnode.$elm$.host
+    const elm = newVnode.$elm$.nodeType === 11 /* NODE_TYPE.DocumentFragment */ && newVnode.$elm$.host
         ? newVnode.$elm$.host
         : newVnode.$elm$;
     const oldVnodeAttrs = (oldVnode && oldVnode.$attrs$) || EMPTY_OBJ;
@@ -471,6 +544,16 @@ const updateElement = (oldVnode, newVnode, isSvgMode, memberName) => {
         setAccessor(elm, memberName, oldVnodeAttrs[memberName], newVnodeAttrs[memberName], isSvgMode, newVnode.$flags$);
     }
 };
+/**
+ * Create a DOM Node corresponding to one of the children of a given VNode.
+ *
+ * @param oldParentVNode the parent VNode from the previous render
+ * @param newParentVNode the parent VNode from the current render
+ * @param childIndex the index of the VNode, in the _new_ parent node's
+ * children, for which we will create a new DOM node
+ * @param parentElm the parent DOM node which our new node will be a child of
+ * @returns the newly created node
+ */
 const createElm = (oldParentVNode, newParentVNode, childIndex, parentElm) => {
     // tslint:disable-next-line: prefer-const
     const newVNode = newParentVNode.$children$[childIndex];
@@ -484,16 +567,16 @@ const createElm = (oldParentVNode, newParentVNode, childIndex, parentElm) => {
         if (newVNode.$tag$ === 'slot') {
             newVNode.$flags$ |= newVNode.$children$
                 ? // slot element has fallback content
-                    2 /* isSlotFallback */
+                    2 /* VNODE_FLAGS.isSlotFallback */
                 : // slot element does not have fallback content
-                    1 /* isSlotReference */;
+                    1 /* VNODE_FLAGS.isSlotReference */;
         }
     }
     if (newVNode.$text$ !== null) {
         // create text node
         elm = newVNode.$elm$ = doc.createTextNode(newVNode.$text$);
     }
-    else if (newVNode.$flags$ & 1 /* isSlotReference */) {
+    else if (newVNode.$flags$ & 1 /* VNODE_FLAGS.isSlotReference */) {
         // create a slot reference node
         elm = newVNode.$elm$ =
             doc.createTextNode('');
@@ -503,7 +586,7 @@ const createElm = (oldParentVNode, newParentVNode, childIndex, parentElm) => {
             isSvgMode = newVNode.$tag$ === 'svg';
         }
         // create element
-        elm = newVNode.$elm$ = (doc.createElementNS(isSvgMode ? SVG_NS : HTML_NS, newVNode.$flags$ & 2 /* isSlotFallback */
+        elm = newVNode.$elm$ = (doc.createElementNS(isSvgMode ? SVG_NS : HTML_NS, newVNode.$flags$ & 2 /* VNODE_FLAGS.isSlotFallback */
                 ? 'slot-fb'
                 : newVNode.$tag$)
             );
@@ -538,7 +621,7 @@ const createElm = (oldParentVNode, newParentVNode, childIndex, parentElm) => {
     }
     {
         elm['s-hn'] = hostTagName;
-        if (newVNode.$flags$ & (2 /* isSlotFallback */ | 1 /* isSlotReference */)) {
+        if (newVNode.$flags$ & (2 /* VNODE_FLAGS.isSlotFallback */ | 1 /* VNODE_FLAGS.isSlotReference */)) {
             // remember the content reference comment
             elm['s-sr'] = true;
             // remember the content reference comment
@@ -557,7 +640,7 @@ const createElm = (oldParentVNode, newParentVNode, childIndex, parentElm) => {
     return elm;
 };
 const putBackInOriginalLocation = (parentElm, recursive) => {
-    plt.$flags$ |= 1 /* isTmpDisconnected */;
+    plt.$flags$ |= 1 /* PLATFORM_FLAGS.isTmpDisconnected */;
     const oldSlotChildNodes = parentElm.childNodes;
     for (let i = oldSlotChildNodes.length - 1; i >= 0; i--) {
         const childNode = oldSlotChildNodes[i];
@@ -578,8 +661,23 @@ const putBackInOriginalLocation = (parentElm, recursive) => {
             putBackInOriginalLocation(childNode, recursive);
         }
     }
-    plt.$flags$ &= ~1 /* isTmpDisconnected */;
+    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;
@@ -593,30 +691,112 @@ 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();
         }
     }
 };
+/**
+ * Reconcile the children of a new VNode with the children of an old VNode by
+ * traversing the two collections of children, identifying nodes that are
+ * conserved or changed, calling out to `patch` to make any necessary
+ * updates to the DOM, and rearranging DOM nodes as needed.
+ *
+ * The algorithm for reconciling children works by analyzing two 'windows' onto
+ * the two arrays of children (`oldCh` and `newCh`). We keep track of the
+ * 'windows' by storing start and end indices and references to the
+ * corresponding array entries. Initially the two 'windows' are basically equal
+ * to the entire array, but we progressively narrow the windows until there are
+ * no children left to update by doing the following:
+ *
+ * 1. Skip any `null` entries at the beginning or end of the two arrays, so
+ *    that if we have an initial array like the following we'll end up dealing
+ *    only with a window bounded by the highlighted elements:
+ *
+ *    [null, null, VNode1 , ... , VNode2, null, null]
+ *                 ^^^^^^         ^^^^^^
+ *
+ * 2. Check to see if the elements at the head and tail positions are equal
+ *    across the windows. This will basically detect elements which haven't
+ *    been added, removed, or changed position, i.e. if you had the following
+ *    VNode elements (represented as HTML):
+ *
+ *    oldVNode: `<div><p><span>HEY</span></p></div>`
+ *    newVNode: `<div><p><span>THERE</span></p></div>`
+ *
+ *    Then when comparing the children of the `<div>` tag we check the equality
+ *    of the VNodes corresponding to the `<p>` tags and, since they are the
+ *    same tag in the same position, we'd be able to avoid completely
+ *    re-rendering the subtree under them with a new DOM element and would just
+ *    call out to `patch` to handle reconciling their children and so on.
+ *
+ * 3. Check, for both windows, to see if the element at the beginning of the
+ *    window corresponds to the element at the end of the other window. This is
+ *    a heuristic which will let us identify _some_ situations in which
+ *    elements have changed position, for instance it _should_ detect that the
+ *    children nodes themselves have not changed but merely moved in the
+ *    following example:
+ *
+ *    oldVNode: `<div><element-one /><element-two /></div>`
+ *    newVNode: `<div><element-two /><element-one /></div>`
+ *
+ *    If we find cases like this then we also need to move the concrete DOM
+ *    elements corresponding to the moved children to write the re-order to the
+ *    DOM.
+ *
+ * 4. Finally, if VNodes have the `key` attribute set on them we check for any
+ *    nodes in the old children which have the same key as the first element in
+ *    our window on the new children. If we find such a node we handle calling
+ *    out to `patch`, moving relevant DOM nodes, and so on, in accordance with
+ *    what we find.
+ *
+ * Finally, once we've narrowed our 'windows' to the point that either of them
+ * collapse (i.e. they have length 0) we then handle any remaining VNode
+ * insertion or deletion that needs to happen to get a DOM state that correctly
+ * reflects the new child VNodes. If, for instance, after our window on the old
+ * children has collapsed we still have more nodes on the new children that
+ * we haven't dealt with yet then we need to add them, or if the new children
+ * collapse but we still have unhandled _old_ children then we need to make
+ * sure the corresponding DOM nodes are removed.
+ *
+ * @param parentElm the node into which the parent VNode is rendered
+ * @param oldCh the old children of the parent node
+ * @param newVNode the new VNode which will replace the parent
+ * @param newCh the new children of the parent node
+ */
 const updateChildren = (parentElm, oldCh, newVNode, newCh) => {
     let oldStartIdx = 0;
     let newStartIdx = 0;
@@ -632,7 +812,7 @@ const updateChildren = (parentElm, oldCh, newVNode, newCh) => {
     let elmToMove;
     while (oldStartIdx <= oldEndIdx && newStartIdx <= newEndIdx) {
         if (oldStartVnode == null) {
-            // Vnode might have been moved left
+            // VNode might have been moved left
             oldStartVnode = oldCh[++oldStartIdx];
         }
         else if (oldEndVnode == null) {
@@ -645,37 +825,100 @@ const updateChildren = (parentElm, oldCh, newVNode, newCh) => {
             newEndVnode = newCh[--newEndIdx];
         }
         else if (isSameVnode(oldStartVnode, newStartVnode)) {
+            // if the start nodes are the same then we should patch the new VNode
+            // onto the old one, and increment our `newStartIdx` and `oldStartIdx`
+            // indices to reflect that. We don't need to move any DOM Nodes around
+            // since things are matched up in order.
             patch(oldStartVnode, newStartVnode);
             oldStartVnode = oldCh[++oldStartIdx];
             newStartVnode = newCh[++newStartIdx];
         }
         else if (isSameVnode(oldEndVnode, newEndVnode)) {
+            // likewise, if the end nodes are the same we patch new onto old and
+            // decrement our end indices, and also likewise in this case we don't
+            // need to move any DOM Nodes.
             patch(oldEndVnode, newEndVnode);
             oldEndVnode = oldCh[--oldEndIdx];
             newEndVnode = newCh[--newEndIdx];
         }
         else if (isSameVnode(oldStartVnode, newEndVnode)) {
-            // Vnode moved right
+            // case: "Vnode moved right"
+            //
+            // We've found that the last node in our window on the new children is
+            // the same VNode as the _first_ node in our window on the old children
+            // we're dealing with now. Visually, this is the layout of these two
+            // nodes:
+            //
+            // newCh: [..., newStartVnode , ... , newEndVnode , ...]
+            //                                    ^^^^^^^^^^^
+            // oldCh: [..., oldStartVnode , ... , oldEndVnode , ...]
+            //              ^^^^^^^^^^^^^
+            //
+            // In this situation we need to patch `newEndVnode` onto `oldStartVnode`
+            // and move the DOM element for `oldStartVnode`.
             if ((oldStartVnode.$tag$ === 'slot' || newEndVnode.$tag$ === 'slot')) {
                 putBackInOriginalLocation(oldStartVnode.$elm$.parentNode, false);
             }
             patch(oldStartVnode, newEndVnode);
+            // We need to move the element for `oldStartVnode` into a position which
+            // will be appropriate for `newEndVnode`. For this we can use
+            // `.insertBefore` and `oldEndVnode.$elm$.nextSibling`. If there is a
+            // sibling for `oldEndVnode.$elm$` then we want to move the DOM node for
+            // `oldStartVnode` between `oldEndVnode` and it's sibling, like so:
+            //
+            // <old-start-node />
+            // <some-intervening-node />
+            // <old-end-node />
+            // <!-- ->              <-- `oldStartVnode.$elm$` should be inserted here
+            // <next-sibling />
+            //
+            // If instead `oldEndVnode.$elm$` has no sibling then we just want to put
+            // the node for `oldStartVnode` at the end of the children of
+            // `parentElm`. Luckily, `Node.nextSibling` will return `null` if there
+            // aren't any siblings, and passing `null` to `Node.insertBefore` will
+            // append it to the children of the parent element.
             parentElm.insertBefore(oldStartVnode.$elm$, oldEndVnode.$elm$.nextSibling);
             oldStartVnode = oldCh[++oldStartIdx];
             newEndVnode = newCh[--newEndIdx];
         }
         else if (isSameVnode(oldEndVnode, newStartVnode)) {
-            // Vnode moved left
+            // case: "Vnode moved left"
+            //
+            // We've found that the first node in our window on the new children is
+            // the same VNode as the _last_ node in our window on the old children.
+            // Visually, this is the layout of these two nodes:
+            //
+            // newCh: [..., newStartVnode , ... , newEndVnode , ...]
+            //              ^^^^^^^^^^^^^
+            // oldCh: [..., oldStartVnode , ... , oldEndVnode , ...]
+            //                                    ^^^^^^^^^^^
+            //
+            // In this situation we need to patch `newStartVnode` onto `oldEndVnode`
+            // (which will handle updating any changed attributes, reconciling their
+            // children etc) but we also need to move the DOM node to which
+            // `oldEndVnode` corresponds.
             if ((oldStartVnode.$tag$ === 'slot' || newEndVnode.$tag$ === 'slot')) {
                 putBackInOriginalLocation(oldEndVnode.$elm$.parentNode, false);
             }
             patch(oldEndVnode, newStartVnode);
+            // We've already checked above if `oldStartVnode` and `newStartVnode` are
+            // the same node, so since we're here we know that they are not. Thus we
+            // can move the element for `oldEndVnode` _before_ the element for
+            // `oldStartVnode`, leaving `oldStartVnode` to be reconciled in the
+            // future.
             parentElm.insertBefore(oldEndVnode.$elm$, oldStartVnode.$elm$);
             oldEndVnode = oldCh[--oldEndIdx];
             newStartVnode = newCh[++newStartIdx];
         }
         else {
-            // createKeyToOldIdx
+            // Here we do some checks to match up old and new nodes based on the
+            // `$key$` attribute, which is set by putting a `key="my-key"` attribute
+            // in the JSX for a DOM element in the implementation of a Stencil
+            // component.
+            //
+            // First we check to see if there are any nodes in the array of old
+            // children which have the same key as the first node in the new
+            // children.
             idxInOld = -1;
             {
                 for (i = oldStartIdx; i <= oldEndIdx; ++i) {
@@ -686,23 +929,32 @@ const updateChildren = (parentElm, oldCh, newVNode, newCh) => {
                 }
             }
             if (idxInOld >= 0) {
+                // We found a node in the old children which matches up with the first
+                // node in the new children! So let's deal with that
                 elmToMove = oldCh[idxInOld];
                 if (elmToMove.$tag$ !== newStartVnode.$tag$) {
+                    // the tag doesn't match so we'll need a new DOM element
                     node = createElm(oldCh && oldCh[newStartIdx], newVNode, idxInOld);
                 }
                 else {
                     patch(elmToMove, newStartVnode);
+                    // invalidate the matching old node so that we won't try to update it
+                    // again later on
                     oldCh[idxInOld] = undefined;
                     node = elmToMove.$elm$;
                 }
                 newStartVnode = newCh[++newStartIdx];
             }
             else {
-                // new element
+                // We either didn't find an element in the old children that matches
+                // the key of the first new child OR the build is not using `key`
+                // attributes at all. In either case we need to create a new element
+                // for the new node.
                 node = createElm(oldCh && oldCh[newStartIdx], newVNode, newStartIdx);
                 newStartVnode = newCh[++newStartIdx];
             }
             if (node) {
+                // if we created a new node then handle inserting it to the DOM
                 {
                     parentReferenceNode(oldStartVnode.$elm$).insertBefore(node, referenceNode(oldStartVnode.$elm$));
                 }
@@ -710,21 +962,44 @@ const updateChildren = (parentElm, oldCh, newVNode, newCh) => {
         }
     }
     if (oldStartIdx > oldEndIdx) {
+        // we have some more new nodes to add which don't match up with old nodes
         addVnodes(parentElm, newCh[newEndIdx + 1] == null ? null : newCh[newEndIdx + 1].$elm$, newVNode, newCh, newStartIdx, newEndIdx);
     }
     else if (newStartIdx > newEndIdx) {
+        // there are nodes in the `oldCh` array which no longer correspond to nodes
+        // in the new array, so lets remove them (which entails cleaning up the
+        // relevant DOM nodes)
         removeVnodes(oldCh, oldStartIdx, oldEndIdx);
     }
 };
-const isSameVnode = (vnode1, vnode2) => {
+/**
+ * Compare two VNodes to determine if they are the same
+ *
+ * **NB**: This function is an equality _heuristic_ based on the available
+ * information set on the two VNodes and can be misleading under certain
+ * circumstances. In particular, if the two nodes do not have `key` attrs
+ * (available under `$key$` on VNodes) then the function falls back on merely
+ * checking that they have the same tag.
+ *
+ * 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 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
+ * @returns whether they're equal or not
+ */
+const isSameVnode = (leftVNode, rightVNode) => {
     // compare if two vnode to see if they're "technically" the same
     // need to have the same element tag, and same key to be the same
-    if (vnode1.$tag$ === vnode2.$tag$) {
-        if (vnode1.$tag$ === 'slot') {
-            return vnode1.$name$ === vnode2.$name$;
+    if (leftVNode.$tag$ === rightVNode.$tag$) {
+        if (leftVNode.$tag$ === 'slot') {
+            return leftVNode.$name$ === rightVNode.$name$;
         }
+        // this will be set if components in the build have `key` attrs set on them
         {
-            return vnode1.$key$ === vnode2.$key$;
+            return leftVNode.$key$ === rightVNode.$key$;
         }
     }
     return false;
@@ -737,6 +1012,14 @@ const referenceNode = (node) => {
     return (node && node['s-ol']) || node;
 };
 const parentReferenceNode = (node) => (node['s-ol'] ? node['s-ol'] : node).parentNode;
+/**
+ * Handle reconciling an outdated VNode with a new one which corresponds to
+ * it. This function handles flushing updates to the DOM and reconciling the
+ * children of the two nodes (if any).
+ *
+ * @param oldVNode an old VNode whose DOM element and children we want to update
+ * @param newVNode a new VNode representing an updated version of the old one
+ */
 const patch = (oldVNode, newVNode) => {
     const elm = (newVNode.$elm$ = oldVNode.$elm$);
     const oldChildren = oldVNode.$children$;
@@ -750,7 +1033,6 @@ const patch = (oldVNode, newVNode) => {
             // only add this to the when the compiler sees we're using an svg somewhere
             isSvgMode = tag === 'svg' ? true : tag === 'foreignObject' ? false : isSvgMode;
         }
-        // element node
         {
             if (tag === 'slot')
                 ;
@@ -763,6 +1045,7 @@ const patch = (oldVNode, newVNode) => {
         }
         if (oldChildren !== null && newChildren !== null) {
             // looks like there's child vnodes for both the old and new vnodes
+            // so we need to call `updateChildren` to reconcile them
             updateChildren(elm, oldChildren, newVNode, newChildren);
         }
         else if (newChildren !== null) {
@@ -803,7 +1086,7 @@ const updateFallbackSlotVisibility = (elm) => {
     let nodeType;
     for (i = 0, ilen = childNodes.length; i < ilen; i++) {
         childNode = childNodes[i];
-        if (childNode.nodeType === 1 /* ElementNode */) {
+        if (childNode.nodeType === 1 /* NODE_TYPE.ElementNode */) {
             if (childNode['s-sr']) {
                 // this is a slot fallback node
                 // get the slot name for this slot reference node
@@ -815,7 +1098,7 @@ const updateFallbackSlotVisibility = (elm) => {
                     nodeType = childNodes[j].nodeType;
                     if (childNodes[j]['s-hn'] !== childNode['s-hn'] || slotNameAttr !== '') {
                         // this sibling node is from a different component OR is a named fallback slot node
-                        if (nodeType === 1 /* ElementNode */ && slotNameAttr === childNodes[j].getAttribute('slot')) {
+                        if (nodeType === 1 /* NODE_TYPE.ElementNode */ && slotNameAttr === childNodes[j].getAttribute('slot')) {
                             childNode.hidden = true;
                             break;
                         }
@@ -824,8 +1107,8 @@ const updateFallbackSlotVisibility = (elm) => {
                         // this is a default fallback slot node
                         // any element or text node (with content)
                         // should hide the default fallback slot node
-                        if (nodeType === 1 /* ElementNode */ ||
-                            (nodeType === 3 /* TextNode */ && childNodes[j].textContent.trim() !== '')) {
+                        if (nodeType === 1 /* NODE_TYPE.ElementNode */ ||
+                            (nodeType === 3 /* NODE_TYPE.TextNode */ && childNodes[j].textContent.trim() !== '')) {
                             childNode.hidden = true;
                             break;
                         }
@@ -903,13 +1186,13 @@ const relocateSlotContent = (elm) => {
                 }
             }
         }
-        if (childNode.nodeType === 1 /* ElementNode */) {
+        if (childNode.nodeType === 1 /* NODE_TYPE.ElementNode */) {
             relocateSlotContent(childNode);
         }
     }
 };
 const isNodeLocatedInSlot = (nodeToRelocate, slotNameAttr) => {
-    if (nodeToRelocate.nodeType === 1 /* ElementNode */) {
+    if (nodeToRelocate.nodeType === 1 /* NODE_TYPE.ElementNode */) {
         if (nodeToRelocate.getAttribute('slot') === null && slotNameAttr === '') {
             return true;
         }
@@ -923,12 +1206,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$;
@@ -940,12 +1242,12 @@ const renderVdom = (hostRef, renderFnResults) => {
         cmpMeta.$attrsToReflect$.map(([propName, attribute]) => (rootVnode.$attrs$[attribute] = hostElm[propName]));
     }
     rootVnode.$tag$ = null;
-    rootVnode.$flags$ |= 4 /* isHost */;
+    rootVnode.$flags$ |= 4 /* VNODE_FLAGS.isHost */;
     hostRef.$vnode$ = rootVnode;
     rootVnode.$elm$ = oldVNode.$elm$ = (hostElm);
     {
         contentRef = hostElm['s-cr'];
-        useNativeShadowDom = (cmpMeta.$flags$ & 1 /* shadowDomEncapsulation */) !== 0;
+        useNativeShadowDom = (cmpMeta.$flags$ & 1 /* CMP_FLAGS.shadowDomEncapsulation */) !== 0;
         // always reset
         checkSlotFallbackVisibility = false;
     }
@@ -954,7 +1256,7 @@ const renderVdom = (hostRef, renderFnResults) => {
     {
         // while we're moving nodes around existing nodes, temporarily disable
         // the disconnectCallback from working
-        plt.$flags$ |= 1 /* isTmpDisconnected */;
+        plt.$flags$ |= 1 /* PLATFORM_FLAGS.isTmpDisconnected */;
         if (checkSlotRelocate) {
             relocateSlotContent(rootVnode.$elm$);
             let relocateData;
@@ -1012,7 +1314,7 @@ const renderVdom = (hostRef, renderFnResults) => {
                 }
                 else {
                     // this node doesn't have a slot home to go to, so let's hide it
-                    if (nodeToRelocate.nodeType === 1 /* ElementNode */) {
+                    if (nodeToRelocate.nodeType === 1 /* NODE_TYPE.ElementNode */) {
                         nodeToRelocate.hidden = true;
                     }
                 }
@@ -1023,37 +1325,11 @@ const renderVdom = (hostRef, renderFnResults) => {
         }
         // done moving nodes around
         // allow the disconnect callback to work again
-        plt.$flags$ &= ~1 /* isTmpDisconnected */;
+        plt.$flags$ &= ~1 /* PLATFORM_FLAGS.isTmpDisconnected */;
         // always reset
         relocateNodes.length = 0;
     }
 };
-const getElement = (ref) => (getHostRef(ref).$hostElement$ );
-const createEvent = (ref, name, flags) => {
-    const elm = getElement(ref);
-    return {
-        emit: (detail) => {
-            return emitEvent(elm, name, {
-                bubbles: !!(flags & 4 /* Bubbles */),
-                composed: !!(flags & 2 /* Composed */),
-                cancelable: !!(flags & 1 /* Cancellable */),
-                detail,
-            });
-        },
-    };
-};
-/**
- * Helper function to create & dispatch a custom Event on a provided target
- * @param elm the target of the Event
- * @param name the name to give the custom Event
- * @param opts options for configuring a custom Event
- * @returns the custom Event
- */
-const emitEvent = (elm, name, opts) => {
-    const ev = plt.ce(name, opts);
-    elm.dispatchEvent(ev);
-    return ev;
-};
 const attachToAncestor = (hostRef, ancestorComponent) => {
     if (ancestorComponent && !hostRef.$onRenderResolve$ && ancestorComponent['s-p']) {
         ancestorComponent['s-p'].push(new Promise((r) => (hostRef.$onRenderResolve$ = r)));
@@ -1061,10 +1337,10 @@ const attachToAncestor = (hostRef, ancestorComponent) => {
 };
 const scheduleUpdate = (hostRef, isInitialLoad) => {
     {
-        hostRef.$flags$ |= 16 /* isQueuedForUpdate */;
+        hostRef.$flags$ |= 16 /* HOST_FLAGS.isQueuedForUpdate */;
     }
-    if (hostRef.$flags$ & 4 /* isWaitingForChildren */) {
-        hostRef.$flags$ |= 512 /* needsRerender */;
+    if (hostRef.$flags$ & 4 /* HOST_FLAGS.isWaitingForChildren */) {
+        hostRef.$flags$ |= 512 /* HOST_FLAGS.needsRerender */;
         return;
     }
     attachToAncestor(hostRef, hostRef.$ancestorComponent$);
@@ -1074,30 +1350,86 @@ 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 /* isListenReady */;
+            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');
         }
     }
     {
-        promise = then(promise, () => safeCall(instance, 'componentWillRender'));
+        maybePromise = enqueue(maybePromise, () => safeCall(instance, 'componentWillRender'));
     }
     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'];
@@ -1109,9 +1441,6 @@ const updateComponent = async (hostRef, instance, isInitialLoad) => {
     {
         callRender(hostRef, instance);
     }
-    if (plt.$cssShim$) {
-        plt.$cssShim$.updateHost(elm);
-    }
     if (rc) {
         // ok, so turns out there are some child host elements
         // waiting on this parent element to load
@@ -1122,14 +1451,14 @@ 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();
         }
         else {
             Promise.all(childrenPromises).then(postUpdate);
-            hostRef.$flags$ |= 4 /* isWaitingForChildren */;
+            hostRef.$flags$ |= 4 /* HOST_FLAGS.isWaitingForChildren */;
             childrenPromises.length = 0;
         }
     }
@@ -1139,10 +1468,10 @@ const callRender = (hostRef, instance, elm) => {
         renderingRef = instance;
         instance = instance.render && instance.render();
         {
-            hostRef.$flags$ &= ~16 /* isQueuedForUpdate */;
+            hostRef.$flags$ &= ~16 /* HOST_FLAGS.isQueuedForUpdate */;
         }
         {
-            hostRef.$flags$ |= 2 /* hasRendered */;
+            hostRef.$flags$ |= 2 /* HOST_FLAGS.hasRendered */;
         }
         {
             {
@@ -1171,8 +1500,8 @@ const postUpdateComponent = (hostRef) => {
     {
         safeCall(instance, 'componentDidRender');
     }
-    if (!(hostRef.$flags$ & 64 /* hasLoadedComponent */)) {
-        hostRef.$flags$ |= 64 /* hasLoadedComponent */;
+    if (!(hostRef.$flags$ & 64 /* HOST_FLAGS.hasLoadedComponent */)) {
+        hostRef.$flags$ |= 64 /* HOST_FLAGS.hasLoadedComponent */;
         {
             // DOM WRITE!
             addHydratedFlag(elm);
@@ -1201,10 +1530,10 @@ const postUpdateComponent = (hostRef) => {
             hostRef.$onRenderResolve$();
             hostRef.$onRenderResolve$ = undefined;
         }
-        if (hostRef.$flags$ & 512 /* needsRerender */) {
+        if (hostRef.$flags$ & 512 /* HOST_FLAGS.needsRerender */) {
             nextTick(() => scheduleUpdate(hostRef, false));
         }
-        hostRef.$flags$ &= ~(4 /* isWaitingForChildren */ | 512 /* needsRerender */);
+        hostRef.$flags$ &= ~(4 /* HOST_FLAGS.isWaitingForChildren */ | 512 /* HOST_FLAGS.needsRerender */);
     }
     // ( •_•)
     // ( •_•)>⌐■-■
@@ -1215,7 +1544,7 @@ const forceUpdate = (ref) => {
         const hostRef = getHostRef(ref);
         const isConnected = hostRef.$hostElement$.isConnected;
         if (isConnected &&
-            (hostRef.$flags$ & (2 /* hasRendered */ | 16 /* isQueuedForUpdate */)) === 2 /* hasRendered */) {
+            (hostRef.$flags$ & (2 /* HOST_FLAGS.hasRendered */ | 16 /* HOST_FLAGS.isQueuedForUpdate */)) === 2 /* HOST_FLAGS.hasRendered */) {
             scheduleUpdate(hostRef, false);
         }
         // Returns "true" when the forced update was successfully scheduled
@@ -1241,58 +1570,8 @@ 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')
     ;
-/**
- * Parse a new property value for a given property type.
- *
- * While the prop value can reasonably be expected to be of `any` type as far as TypeScript's type checker is concerned,
- * it is not safe to assume that the string returned by evaluating `typeof propValue` matches:
- *   1. `any`, the type given to `propValue` in the function signature
- *   2. the type stored from `propType`.
- *
- * This function provides the capability to parse/coerce a property's value to potentially any other JavaScript type.
- *
- * Property values represented in TSX preserve their type information. In the example below, the number 0 is passed to
- * a component. This `propValue` will preserve its type information (`typeof propValue === 'number'`). Note that is
- * based on the type of the value being passed in, not the type declared of the class member decorated with `@Prop`.
- * ```tsx
- * <my-cmp prop-val={0}></my-cmp>
- * ```
- *
- * HTML prop values on the other hand, will always a string
- *
- * @param propValue the new value to coerce to some type
- * @param propType the type of the prop, expressed as a binary number
- * @returns the parsed/coerced value
- */
-const parsePropertyValue = (propValue, propType) => {
-    // ensure this value is of the correct prop type
-    if (propValue != null && !isComplexType(propValue)) {
-        if (propType & 4 /* Boolean */) {
-            // per the HTML spec, any string value means it is a boolean true value
-            // but we'll cheat here and say that the string "false" is the boolean false
-            return propValue === 'false' ? false : propValue === '' || !!propValue;
-        }
-        if (propType & 2 /* Number */) {
-            // force it to be a number
-            return parseFloat(propValue);
-        }
-        if (propType & 1 /* String */) {
-            // could have been passed as a number or boolean
-            // but we still want it as a string
-            return String(propValue);
-        }
-        // redundant return here for better minification
-        return propValue;
-    }
-    // not sure exactly what type we want
-    // so no need to change to a different type
-    return propValue;
-};
 const getValue = (ref, propName) => getHostRef(ref).$instanceValues$.get(propName);
 const setValue = (ref, propName, newVal, cmpMeta) => {
     // check our new property value against our internal value
@@ -1305,13 +1584,13 @@ const setValue = (ref, propName, newVal, cmpMeta) => {
     // explicitly check for NaN on both sides, as `NaN === NaN` is always false
     const areBothNaN = Number.isNaN(oldVal) && Number.isNaN(newVal);
     const didValueChange = newVal !== oldVal && !areBothNaN;
-    if ((!(flags & 8 /* isConstructingInstance */) || oldVal === undefined) && didValueChange) {
+    if ((!(flags & 8 /* HOST_FLAGS.isConstructingInstance */) || oldVal === undefined) && didValueChange) {
         // gadzooks! the property's value has changed!!
         // set our new value!
         hostRef.$instanceValues$.set(propName, newVal);
         if (instance) {
             // get an array of method names of watch functions to call
-            if (cmpMeta.$watchers$ && flags & 128 /* isWatchReady */) {
+            if (cmpMeta.$watchers$ && flags & 128 /* HOST_FLAGS.isWatchReady */) {
                 const watchMethods = cmpMeta.$watchers$[propName];
                 if (watchMethods) {
                     // this instance is watching for when this property changed
@@ -1326,7 +1605,7 @@ const setValue = (ref, propName, newVal, cmpMeta) => {
                     });
                 }
             }
-            if ((flags & (2 /* hasRendered */ | 16 /* isQueuedForUpdate */)) === 2 /* hasRendered */) {
+            if ((flags & (2 /* HOST_FLAGS.hasRendered */ | 16 /* HOST_FLAGS.isQueuedForUpdate */)) === 2 /* HOST_FLAGS.hasRendered */) {
                 // looks like this value actually changed, so we've got work to do!
                 // but only if we've already rendered, otherwise just chill out
                 // queue that we need to do an update, but don't worry about queuing
@@ -1336,6 +1615,16 @@ const setValue = (ref, propName, newVal, cmpMeta) => {
         }
     }
 };
+/**
+ * Attach a series of runtime constructs to a compiled Stencil component
+ * constructor, including getters and setters for the `@Prop` and `@State`
+ * decorators, callbacks for when attributes change, and so on.
+ *
+ * @param Cstr the constructor for a component that we need to process
+ * @param cmpMeta metadata collected previously about the component
+ * @param flags a number used to store a series of bit flags
+ * @returns a reference to the same constructor passed in (but now mutated)
+ */
 const proxyComponent = (Cstr, cmpMeta, flags) => {
     if (cmpMeta.$members$) {
         if (Cstr.watchers) {
@@ -1345,8 +1634,8 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
         const members = Object.entries(cmpMeta.$members$);
         const prototype = Cstr.prototype;
         members.map(([memberName, [memberFlags]]) => {
-            if ((memberFlags & 31 /* Prop */ ||
-                    ((flags & 2 /* proxyState */) && memberFlags & 32 /* State */))) {
+            if ((memberFlags & 31 /* MEMBER_FLAGS.Prop */ ||
+                    ((flags & 2 /* PROXY_FLAGS.proxyState */) && memberFlags & 32 /* MEMBER_FLAGS.State */))) {
                 // proxyComponent - prop
                 Object.defineProperty(prototype, memberName, {
                     get() {
@@ -1361,8 +1650,8 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
                     enumerable: true,
                 });
             }
-            else if (flags & 1 /* isElementConstructor */ &&
-                memberFlags & 64 /* Method */) {
+            else if (flags & 1 /* PROXY_FLAGS.isElementConstructor */ &&
+                memberFlags & 64 /* MEMBER_FLAGS.Method */) {
                 // proxyComponent - method
                 Object.defineProperty(prototype, memberName, {
                     value(...args) {
@@ -1372,7 +1661,7 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
                 });
             }
         });
-        if ((flags & 1 /* isElementConstructor */)) {
+        if ((flags & 1 /* PROXY_FLAGS.isElementConstructor */)) {
             const attrNameToPropName = new Map();
             prototype.attributeChangedCallback = function (attrName, _oldValue, newValue) {
                 plt.jmp(() => {
@@ -1428,11 +1717,11 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
             // create an array of attributes to observe
             // and also create a map of html attribute name to js property name
             Cstr.observedAttributes = members
-                .filter(([_, m]) => m[0] & 15 /* HasAttribute */) // filter to only keep props that should match attributes
+                .filter(([_, m]) => m[0] & 15 /* MEMBER_FLAGS.HasAttribute */) // filter to only keep props that should match attributes
                 .map(([propName, m]) => {
                 const attrName = m[1] || propName;
                 attrNameToPropName.set(attrName, propName);
-                if (m[0] & 512 /* ReflectAttr */) {
+                if (m[0] & 512 /* MEMBER_FLAGS.ReflectAttr */) {
                     cmpMeta.$attrsToReflect$.push([propName, attrName]);
                 }
                 return attrName;
@@ -1443,10 +1732,10 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
 };
 const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) => {
     // initializeComponent
-    if ((hostRef.$flags$ & 32 /* hasInitializedComponent */) === 0) {
+    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 /* hasInitializedComponent */;
             // lazy loaded components
             // request the component's implementation to be
             // wired up with the host element
@@ -1464,7 +1753,7 @@ const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) =>
                 {
                     cmpMeta.$watchers$ = Cstr.watchers;
                 }
-                proxyComponent(Cstr, cmpMeta, 2 /* proxyState */);
+                proxyComponent(Cstr, cmpMeta, 2 /* PROXY_FLAGS.proxyState */);
                 Cstr.isProxied = true;
             }
             const endNewInstance = createTime('createInstance', cmpMeta.$tagName$);
@@ -1472,7 +1761,7 @@ const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) =>
             // but let's keep track of when we start and stop
             // so that the getters/setters don't incorrectly step on data
             {
-                hostRef.$flags$ |= 8 /* isConstructingInstance */;
+                hostRef.$flags$ |= 8 /* HOST_FLAGS.isConstructingInstance */;
             }
             // construct the lazy-loaded component implementation
             // passing the hostRef is very important during
@@ -1485,10 +1774,10 @@ const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) =>
                 consoleError(e);
             }
             {
-                hostRef.$flags$ &= ~8 /* isConstructingInstance */;
+                hostRef.$flags$ &= ~8 /* HOST_FLAGS.isConstructingInstance */;
             }
             {
-                hostRef.$flags$ |= 128 /* isWatchReady */;
+                hostRef.$flags$ |= 128 /* HOST_FLAGS.isWatchReady */;
             }
             endNewInstance();
             fireConnectedCallback(hostRef.$lazyInstance$);
@@ -1499,7 +1788,7 @@ const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) =>
             const scopeId = getScopeId(cmpMeta);
             if (!styles.has(scopeId)) {
                 const endRegisterStyles = createTime('registerStyles', cmpMeta.$tagName$);
-                registerStyle(scopeId, style, !!(cmpMeta.$flags$ & 1 /* shadowDomEncapsulation */));
+                registerStyle(scopeId, style, !!(cmpMeta.$flags$ & 1 /* CMP_FLAGS.shadowDomEncapsulation */));
                 endRegisterStyles();
             }
         }
@@ -1526,19 +1815,20 @@ const fireConnectedCallback = (instance) => {
     }
 };
 const connectedCallback = (elm) => {
-    if ((plt.$flags$ & 1 /* isTmpDisconnected */) === 0) {
+    if ((plt.$flags$ & 1 /* PLATFORM_FLAGS.isTmpDisconnected */) === 0) {
         const hostRef = getHostRef(elm);
         const cmpMeta = hostRef.$cmpMeta$;
         const endConnected = createTime('connectedCallback', cmpMeta.$tagName$);
-        if (!(hostRef.$flags$ & 1 /* hasConnected */)) {
+        if (!(hostRef.$flags$ & 1 /* HOST_FLAGS.hasConnected */)) {
             // first time this component has connected
-            hostRef.$flags$ |= 1 /* hasConnected */;
+            hostRef.$flags$ |= 1 /* HOST_FLAGS.hasConnected */;
             {
                 // initUpdate
                 // 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 /* hasSlotRelocation */ | 8 /* needsShadowDomShim */))) {
+                if ((// TODO(STENCIL-854): Remove code related to legacy shadowDomShim field
+                        cmpMeta.$flags$ & (4 /* CMP_FLAGS.hasSlotRelocation */ | 8 /* CMP_FLAGS.needsShadowDomShim */))) {
                     setContentReference(elm);
                 }
             }
@@ -1561,7 +1851,7 @@ const connectedCallback = (elm) => {
             // https://developers.google.com/web/fundamentals/web-components/best-practices#lazy-properties
             if (cmpMeta.$members$) {
                 Object.entries(cmpMeta.$members$).map(([memberName, [memberFlags]]) => {
-                    if (memberFlags & 31 /* Prop */ && elm.hasOwnProperty(memberName)) {
+                    if (memberFlags & 31 /* MEMBER_FLAGS.Prop */ && elm.hasOwnProperty(memberName)) {
                         const value = elm[memberName];
                         delete elm[memberName];
                         elm[memberName] = value;
@@ -1599,7 +1889,7 @@ const setContentReference = (elm) => {
     elm.insertBefore(contentRefElm, elm.firstChild);
 };
 const disconnectedCallback = (elm) => {
-    if ((plt.$flags$ & 1 /* isTmpDisconnected */) === 0) {
+    if ((plt.$flags$ & 1 /* PLATFORM_FLAGS.isTmpDisconnected */) === 0) {
         const hostRef = getHostRef(elm);
         const instance = hostRef.$lazyInstance$ ;
         {
@@ -1608,16 +1898,13 @@ const disconnectedCallback = (elm) => {
                 hostRef.$rmListeners$ = undefined;
             }
         }
-        // clear CSS var-shim tracking
-        if (plt.$cssShim$) {
-            plt.$cssShim$.removeHost(elm);
-        }
         {
             safeCall(instance, 'disconnectedCallback');
         }
     }
 };
 const bootstrapLazy = (lazyBundles, options = {}) => {
+    var _a;
     const endBootstrap = createTime();
     const cmpTags = [];
     const exclude = options.exclude || [];
@@ -1682,13 +1969,18 @@ const bootstrapLazy = (lazyBundles, options = {}) => {
             cmpMeta.$lazyBundleId$ = lazyBundle[0];
             if (!exclude.includes(tagName) && !customElements.get(tagName)) {
                 cmpTags.push(tagName);
-                customElements.define(tagName, proxyComponent(HostElement, cmpMeta, 1 /* isElementConstructor */));
+                customElements.define(tagName, proxyComponent(HostElement, cmpMeta, 1 /* PROXY_FLAGS.isElementConstructor */));
             }
         });
     });
     {
         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
@@ -1704,7 +1996,48 @@ const bootstrapLazy = (lazyBundles, options = {}) => {
     // Fallback appLoad event
     endBootstrap();
 };
-const hostRefs = new WeakMap();
+const addHostEventListeners = (elm, hostRef, listeners, attachParentListeners) => {
+    if (listeners) {
+        listeners.map(([flags, name, method]) => {
+            const target = getHostListenerTarget(elm, flags) ;
+            const handler = hostListenerProxy(hostRef, method);
+            const opts = hostListenerOpts(flags);
+            plt.ael(target, name, handler, opts);
+            (hostRef.$rmListeners$ = hostRef.$rmListeners$ || []).push(() => plt.rel(target, name, handler, opts));
+        });
+    }
+};
+const hostListenerProxy = (hostRef, methodName) => (ev) => {
+    try {
+        {
+            if (hostRef.$flags$ & 256 /* HOST_FLAGS.isListenReady */) {
+                // instance is ready, let's call it's member method for this event
+                hostRef.$lazyInstance$[methodName](ev);
+            }
+            else {
+                (hostRef.$queuedListeners$ = hostRef.$queuedListeners$ || []).push([methodName, ev]);
+            }
+        }
+    }
+    catch (e) {
+        consoleError(e);
+    }
+};
+const getHostListenerTarget = (elm, flags) => {
+    if (flags & 4 /* LISTENER_FLAGS.TargetDocument */)
+        return doc;
+    return elm;
+};
+// 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);
 const registerHost = (elm, cmpMeta) => {
@@ -1770,14 +2103,35 @@ const loadModule = (cmpMeta, hostRef, hmrVersionId) => {
         return importedModule[exportName];
     }, consoleError);
 };
-const styles = new Map();
+const styles = /*@__PURE__*/ new Map();
+const win = typeof window !== 'undefined' ? window : {};
+const doc = win.document || { head: {} };
+const plt = {
+    $flags$: 0,
+    $resourcesUrl$: '',
+    jmp: (h) => h(),
+    raf: (h) => requestAnimationFrame(h),
+    ael: (el, eventName, listener, opts) => el.addEventListener(eventName, listener, opts),
+    rel: (el, eventName, listener, opts) => el.removeEventListener(eventName, listener, opts),
+    ce: (eventName, opts) => new CustomEvent(eventName, opts),
+};
+const promiseResolve = (v) => Promise.resolve(v);
+const supportsConstructableStylesheets = /*@__PURE__*/ (() => {
+        try {
+            new CSSStyleSheet();
+            return typeof new CSSStyleSheet().replaceSync === 'function';
+        }
+        catch (e) { }
+        return false;
+    })()
+    ;
 const queueDomReads = [];
 const queueDomWrites = [];
 const queueTask = (queue, write) => (cb) => {
     queue.push(cb);
     if (!queuePending) {
         queuePending = true;
-        if (write && plt.$flags$ & 4 /* queueSync */) {
+        if (write && plt.$flags$ & 4 /* PLATFORM_FLAGS.queueSync */) {
             nextTick(flush);
         }
         else {
@@ -1814,4 +2168,6 @@ const flush = () => {
 const nextTick = /*@__PURE__*/ (cb) => promiseResolve().then(cb);
 const writeTask = /*@__PURE__*/ queueTask(queueDomWrites, true);
 
-export { CSS as C, Host as H, NAMESPACE as N, promiseResolve as a, bootstrapLazy as b, createEvent as c, doc as d, getElement as e, forceUpdate as f, getRenderingRef as g, h, plt as p, registerInstance as r, win as w };
+export { Host as H, getElement as a, bootstrapLazy as b, createEvent as c, forceUpdate as f, getRenderingRef as g, h, promiseResolve as p, registerInstance as r, setNonce as s };
+
+//# sourceMappingURL=index-f21f8a13.js.map