@mgdis/mg-components 5.19.2 → 5.19.3

package/dist/esm/{components.utils-0f76010d.js → components.utils-6cf27db1.js}

@@ -285,7 +285,7 @@ const createID = (prefix = '', length = 10) => {
   const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
   const charsLength = chars.length;
   let ID = '';
-  let now = Date.now();
+  let now = Math.floor(globalThis.crypto.getRandomValues(new Uint32Array(1))[0] * Date.now());
   while (length > 0) {
     now += Math.pow(10, 6); // Add 1 millisecond to the timestamp
     const index = now % charsLength;
@@ -422,4 +422,4 @@ const cleanString = (text) => typeof text === 'string' &&
 
 export { ClassList as C, Direction as D, isValidString as a, isTagName as b, createID as c, cleanString as d, dateRegExp as e, localeCurrency as f, localeNumber as g, allItemsAreString as h, initLocales as i, focusableElements as j, getWindows as k, localeDate as l, sizes as s };
 
-//# sourceMappingURL=components.utils-0f76010d.js.map
+//# sourceMappingURL=components.utils-6cf27db1.js.map

package/dist/esm/components.utils-6cf27db1.js.map

@@ -0,0 +1 @@
+{"file":"components.utils-6cf27db1.js","mappings":"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","names":[],"sources":["src/utils/locale.utils.ts","src/locales/index.ts","src/components/molecules/menu/mg-menu/mg-menu.conf.ts","src/utils/components.utils.ts"],"sourcesContent":["/**\n * Format number to the locale currency\n * @param number - number to format\n * @param locale - locale to apply\n * @param currency - currency to apply\n * @returns formatted currency\n */\nexport const localeCurrency = (number: number, locale: string, currency: string): string => {\n  return new Intl.NumberFormat(locale, { style: 'currency', currency }).format(number);\n};\n\n/**\n * Format number to locale\n * @param number - number to format\n * @param locale - locale to apply\n * @returns formatted number\n */\nexport const localeNumber = (number: number, locale: string): string => {\n  return new Intl.NumberFormat(locale).format(number);\n};\n\n/**\n * Date RegExp\n */\nexport const dateRegExp = /^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$/;\n\n/**\n * Locale date format\n * @param date - date to format\n * @param locale - locale to apply\n * @returns formatted date\n */\nexport const localeDate = (date: string, locale: string): string => {\n  if (typeof date !== 'string' || date === '' || !dateRegExp.test(date)) {\n    return '';\n  }\n  return new Intl.DateTimeFormat(locale).format(new Date(date));\n};\n\n/**\n * Get locale and messages\n * We load the defined locale but for now we only support the first subtag for messages\n * @param element - element we need to get the language\n * @param messages - messages to use\n * @param defaultLocale - default messages locale\n * @returns messages object\n */\nexport const getLocaleMessages = (element: HTMLElement, messages: unknown, defaultLocale: string): { locale: string; messages: Record<string, unknown> } => {\n  // Get local\n  const closestLangAttribute: HTMLElement = element.closest('[lang]');\n  const closestLang: string[] = Intl.NumberFormat.supportedLocalesOf(closestLangAttribute?.lang);\n  const locale = closestLang.length > 0 ? closestLang[0] : navigator.language || defaultLocale;\n  // Only keep first subtag\n  const localeSubtag = locale.split('-').shift();\n  // Return\n  return {\n    locale,\n    messages: messages[localeSubtag] || messages[defaultLocale],\n  };\n};\n","import en from './en/messages.json';\nimport fr from './fr/messages.json';\nimport { getLocaleMessages } from '../utils/locale.utils';\n\nconst defaultLocale = 'en';\nconst messages = { en, fr };\n\n/**\n * Get Intl object\n * @param element - element we need to get the language\n * @returns messages object\n */\nexport const initLocales = (element: HTMLElement): { locale: string; messages: Record<string, unknown> } => getLocaleMessages(element, messages, defaultLocale);\n","import { MgItemMore } from '../../mg-item-more/mg-item-more';\n\n/**\n * Menu direction type\n */\nexport enum Direction {\n  VERTICAL = 'vertical',\n  HORIZONTAL = 'horizontal',\n}\n\n/**\n * ItemMore prop type\n */\nexport type ItemMoreType = Pick<MgItemMore, 'icon' | 'slotlabel' | 'size'>;\n\n/**\n * List of all possibles sizes\n */\nexport const sizes = ['regular', 'medium', 'large'] as const;\n\n/**\n * item Size from sizes\n */\nexport type MenuSizeType = (typeof sizes)[number];\n","/**\n * Create random ID\n * @param prefix - add prefix to created ID\n * @param length - ID length\n * @returns ID\n */\nexport const createID = (prefix = '', length = 10): string => {\n  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';\n  const charsLength = chars.length;\n\n  let ID = '';\n  let now = Math.floor(globalThis.crypto.getRandomValues(new Uint32Array(1))[0] * Date.now());\n  while (length > 0) {\n    now += Math.pow(10, 6); // Add 1 millisecond to the timestamp\n    const index = now % charsLength;\n    ID += chars.charAt(index);\n    length--;\n  }\n  return (prefix !== '' ? `${prefix}-` : '') + ID;\n};\n\n/**\n * Class to manage component classlist\n * Set() are not working when imported in project\n */\nexport class ClassList {\n  /**\n   * Available classes\n   */\n  classes: string[];\n\n  constructor(classlist: string[] = []) {\n    this.classes = classlist;\n  }\n\n  /**\n   * Add class\n   * @param className - class name to add\n   */\n  add = (className: string): void => {\n    if (!this.has(className)) {\n      this.classes.push(className);\n    }\n  };\n\n  /**\n   * Delete class\n   * @param className - class name to delete\n   */\n  delete = (className: string): void => {\n    const index = this.classes.indexOf(className);\n    if (index > -1) {\n      this.classes.splice(index, 1);\n    }\n  };\n\n  /**\n   * Check if class exist in list\n   * @param className - class name to check\n   * @returns class name is in the list\n   */\n  has = (className: string): boolean => {\n    return this.classes.includes(className);\n  };\n\n  /**\n   * Join classes seperated by spaces\n   * @returns joined values\n   */\n  join = (): string => {\n    return this.classes.join(' ');\n  };\n}\n\n/**\n * Check if all items are string\n * @param items - items to check\n * @returns all items are string\n */\nexport const allItemsAreString = (items: unknown): items is string[] => Array.isArray(items) && items.every(item => typeof item === 'string');\n\n/**\n * Check if element is a heading\n * @param element - slotted element\n * @param tagNames - allowed tag names list\n * @returns element is a heading\n */\nexport const isTagName = (element: Element, tagNames: string[]): boolean => {\n  return tagNames.includes(element?.tagName.toLowerCase());\n};\n\n/**\n * Focusable elements query selector\n */\nexport const focusableElements = 'a[href], button, input, textarea, select, details, [tabindex]:not([tabindex=\"-1\"]), [identifier]';\n\n/**\n * Get windows\n * @param localWindow - the window we are lookink for other windows\n * @returns The list of windows found\n */\nexport const getWindows = (localWindow: Window): Window[] => {\n  const parentWindows = getParentWindows(localWindow);\n  const childWindows = getChildWindows(localWindow);\n  return [localWindow, ...parentWindows, ...childWindows];\n};\n\n/**\n * Get parent windows\n * @param localWindow - the window we are lookink for parents\n * @param windows - The list of allready found windows\n * @returns The list of windows found\n */\nexport const getParentWindows = (localWindow: Window, windows: Window[] = []): Window[] => {\n  // Check if is in iframe\n  if (localWindow.self !== localWindow.top) {\n    // Check if we have permission to access parent\n    try {\n      const parentWindow: Window = localWindow.parent;\n      windows.push(parentWindow);\n      return getParentWindows(parentWindow, windows);\n    } catch (err) {\n      console.error('Different hosts between iframes:', err);\n      return windows;\n    }\n  }\n  return windows;\n};\n\n/**\n * Get child windows\n * @param localWindow - the window we are lookink for children\n * @param windows - The list of allready found windows\n * @returns The list of windows found\n */\nconst getChildWindows = (localWindow: Window, windows: Window[] = []): Window[] => {\n  if (localWindow.frames.length > 0) {\n    for (const childWindow of Array.from(localWindow.frames)) {\n      windows.push(childWindow);\n      getChildWindows(childWindow, windows);\n    }\n  }\n  return windows;\n};\n\n/**\n * Validate string\n * @param value - value to check\n * @returns if string is valid\n */\nexport const isValidString = (value: unknown): boolean => typeof value === 'string' && value.trim() !== '';\n\n/**\n * Clean string caraters\n * @param text - text to cliean\n * @returns cleanded string\n */\nexport const cleanString = (text: string): string =>\n  typeof text === 'string' &&\n  text\n    .toLocaleLowerCase()\n    .normalize('NFD')\n    .replaceAll(/[\\u0300-\\u036f]/g, '');\n"],"version":3}

package/dist/esm/{index-ce01e63b.js → index-0f833068.js}

@@ -667,7 +667,7 @@ const putBackInOriginalLocation = (parentElm, recursive) => {
             parentReferenceNode(childNode).insertBefore(childNode, referenceNode(childNode));
             // remove the old original location comment entirely
             // later on the patch function will know what to do
-            // and move this to the correct spot in need be
+            // and move this to the correct spot if need be
             childNode['s-ol'].remove();
             childNode['s-ol'] = undefined;
             checkSlotRelocate = true;
@@ -1085,30 +1085,37 @@ const patch = (oldVNode, newVNode) => {
         elm.data = text;
     }
 };
+/**
+ * Adjust the `.hidden` property as-needed on any nodes in a DOM subtree which
+ * are slot fallbacks nodes.
+ *
+ * A slot fallback node should be visible by default. Then, it should be
+ * conditionally hidden if:
+ *
+ * - it has a sibling with a `slot` property set to its slot name or if
+ * - it is a default fallback slot node, in which case we hide if it has any
+ *   content
+ *
+ * @param elm the element of interest
+ */
 const updateFallbackSlotVisibility = (elm) => {
-    // tslint:disable-next-line: prefer-const
     const childNodes = elm.childNodes;
-    let childNode;
-    let i;
-    let ilen;
-    let j;
-    let slotNameAttr;
-    let nodeType;
-    for (i = 0, ilen = childNodes.length; i < ilen; i++) {
-        childNode = childNodes[i];
+    for (const childNode of childNodes) {
         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
-                slotNameAttr = childNode['s-sn'];
+                const slotName = childNode['s-sn'];
                 // by default always show a fallback slot node
                 // then hide it if there are other slots in the light dom
                 childNode.hidden = false;
-                for (j = 0; j < ilen; j++) {
-                    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 /* NODE_TYPE.ElementNode */ && slotNameAttr === childNodes[j].getAttribute('slot')) {
+                // we need to check all of its sibling nodes in order to see if
+                // `childNode` should be hidden
+                for (const siblingNode of childNodes) {
+                    if (siblingNode['s-hn'] !== childNode['s-hn'] || slotName !== '') {
+                        // this sibling node is from a different component OR is a named
+                        // fallback slot node
+                        if (siblingNode.nodeType === 1 /* NODE_TYPE.ElementNode */ && slotName === siblingNode.getAttribute('slot')) {
                             childNode.hidden = true;
                             break;
                         }
@@ -1117,8 +1124,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 /* NODE_TYPE.ElementNode */ ||
-                            (nodeType === 3 /* NODE_TYPE.TextNode */ && childNodes[j].textContent.trim() !== '')) {
+                        if (siblingNode.nodeType === 1 /* NODE_TYPE.ElementNode */ ||
+                            (siblingNode.nodeType === 3 /* NODE_TYPE.TextNode */ && siblingNode.textContent.trim() !== '')) {
                             childNode.hidden = true;
                             break;
                         }
@@ -1130,42 +1137,55 @@ const updateFallbackSlotVisibility = (elm) => {
         }
     }
 };
+/**
+ * Component-global information about nodes which are either currently being
+ * relocated or will be shortly.
+ */
 const relocateNodes = [];
-const relocateSlotContent = (elm) => {
+/**
+ * Mark the contents of a slot for relocation via adding references to them to
+ * the {@link relocateNodes} data structure. The actual work of relocating them
+ * will then be handled in {@link renderVdom}.
+ *
+ * @param elm a render node whose child nodes need to be relocated
+ */
+const markSlotContentForRelocation = (elm) => {
     // tslint:disable-next-line: prefer-const
-    let childNode;
     let node;
     let hostContentNodes;
-    let slotNameAttr;
-    let relocateNodeData;
     let j;
-    let i = 0;
-    const childNodes = elm.childNodes;
-    const ilen = childNodes.length;
-    for (; i < ilen; i++) {
-        childNode = childNodes[i];
+    for (const childNode of elm.childNodes) {
+        // we need to find child nodes which are slot references so we can then try
+        // to match them up with nodes that need to be relocated
         if (childNode['s-sr'] && (node = childNode['s-cr']) && node.parentNode) {
-            // first got the content reference comment node
-            // then we got it's parent, which is where all the host content is in now
+            // first get the content reference comment node ('s-cr'), then we get
+            // its parent, which is where all the host content is now
             hostContentNodes = node.parentNode.childNodes;
-            slotNameAttr = childNode['s-sn'];
+            const slotName = childNode['s-sn'];
+            // iterate through all the nodes under the location where the host was
+            // originally rendered
             for (j = hostContentNodes.length - 1; j >= 0; j--) {
                 node = hostContentNodes[j];
+                // check that the node is not a content reference node or a node
+                // reference and then check that the host name does not match that of
+                // childNode
                 if (!node['s-cn'] && !node['s-nr'] && node['s-hn'] !== childNode['s-hn']) {
-                    // let's do some relocating to its new home
-                    // but never relocate a content reference node
-                    // that is suppose to always represent the original content location
-                    if (isNodeLocatedInSlot(node, slotNameAttr)) {
+                    // if `node` is located in the slot that `childNode` refers to (via the
+                    // `'s-sn'` property) then we need to relocate it from it's current spot
+                    // (under the host element parent) to the right slot location
+                    if (isNodeLocatedInSlot(node, slotName)) {
                         // it's possible we've already decided to relocate this node
-                        relocateNodeData = relocateNodes.find((r) => r.$nodeToRelocate$ === node);
+                        let relocateNodeData = relocateNodes.find((r) => r.$nodeToRelocate$ === node);
                         // made some changes to slots
                         // let's make sure we also double check
                         // fallbacks are correctly hidden or shown
                         checkSlotFallbackVisibility = true;
-                        node['s-sn'] = node['s-sn'] || slotNameAttr;
+                        // ensure that the slot-name attr is correct
+                        node['s-sn'] = node['s-sn'] || slotName;
                         if (relocateNodeData) {
-                            // previously we never found a slot home for this node
-                            // but turns out we did, so let's remember it now
+                            // we marked this node for relocation previously but didn't find
+                            // out the slot reference node to which it needs to be relocated
+                            // so write it down now!
                             relocateNodeData.$slotRefNode$ = childNode;
                         }
                         else {
@@ -1187,8 +1207,10 @@ const relocateSlotContent = (elm) => {
                         }
                     }
                     else if (!relocateNodes.some((r) => r.$nodeToRelocate$ === node)) {
-                        // so far this element does not have a slot home, not setting slotRefNode on purpose
-                        // if we never find a home for this element then we'll need to hide it
+                        // the node is not found within the slot (`childNode`) that we're
+                        // currently looking at, so we stick it into `relocateNodes` to
+                        // handle later. If we never find a home for this element then
+                        // we'll need to hide it
                         relocateNodes.push({
                             $nodeToRelocate$: node,
                         });
@@ -1196,30 +1218,41 @@ const relocateSlotContent = (elm) => {
                 }
             }
         }
+        // if we're dealing with any type of element (capable of itself being a
+        // slot reference or containing one) then we recur
         if (childNode.nodeType === 1 /* NODE_TYPE.ElementNode */) {
-            relocateSlotContent(childNode);
+            markSlotContentForRelocation(childNode);
         }
     }
 };
-const isNodeLocatedInSlot = (nodeToRelocate, slotNameAttr) => {
+/**
+ * Check whether a node is located in a given named slot.
+ *
+ * @param nodeToRelocate the node of interest
+ * @param slotName the slot name to check
+ * @returns whether the node is located in the slot or not
+ */
+const isNodeLocatedInSlot = (nodeToRelocate, slotName) => {
     if (nodeToRelocate.nodeType === 1 /* NODE_TYPE.ElementNode */) {
-        if (nodeToRelocate.getAttribute('slot') === null && slotNameAttr === '') {
+        if (nodeToRelocate.getAttribute('slot') === null && slotName === '') {
+            // if the node doesn't have a slot attribute, and the slot we're checking
+            // is not a named slot, then we assume the node should be within the slot
             return true;
         }
-        if (nodeToRelocate.getAttribute('slot') === slotNameAttr) {
+        if (nodeToRelocate.getAttribute('slot') === slotName) {
             return true;
         }
         return false;
     }
-    if (nodeToRelocate['s-sn'] === slotNameAttr) {
+    if (nodeToRelocate['s-sn'] === slotName) {
         return true;
     }
-    return slotNameAttr === '';
+    return slotName === '';
 };
 /**
- * '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.
+ * '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
  */
@@ -1298,7 +1331,7 @@ const renderVdom = (hostRef, renderFnResults, isInitialLoad = false) => {
         // the disconnectCallback from working
         plt.$flags$ |= 1 /* PLATFORM_FLAGS.isTmpDisconnected */;
         if (checkSlotRelocate) {
-            relocateSlotContent(rootVnode.$elm$);
+            markSlotContentForRelocation(rootVnode.$elm$);
             let relocateData;
             let nodeToRelocate;
             let orgLocationNode;
@@ -1534,6 +1567,10 @@ const updateComponent = async (hostRef, instance, isInitialLoad) => {
  */
 const callRender = (hostRef, instance, elm, isInitialLoad) => {
     try {
+        /**
+         * minification optimization: `allRenderFn` is `true` if all components have a `render`
+         * method, so we can call the method immediately. If not, check before calling it.
+         */
         instance = instance.render && instance.render();
         {
             hostRef.$flags$ &= ~16 /* HOST_FLAGS.isQueuedForUpdate */;
@@ -1616,6 +1653,16 @@ const appDidLoad = (who) => {
     }
     nextTick(() => emitEvent(win, 'appload', { detail: { namespace: NAMESPACE } }));
 };
+/**
+ * Allows to safely call a method, e.g. `componentDidLoad`, on an instance,
+ * e.g. custom element node. If a build figures out that e.g. no component
+ * has a `componentDidLoad` method, the instance method gets removed from the
+ * output bundle and this function returns `undefined`.
+ * @param instance any object that may or may not contain methods
+ * @param method method name
+ * @param arg single arbitrary argument
+ * @returns result of method call if it exists, otherwise `undefined`
+ */
 const safeCall = (instance, method, arg) => {
     if (instance && instance[method]) {
         try {
@@ -1816,7 +1863,18 @@ const proxyComponent = (Cstr, cmpMeta, flags) => {
     }
     return Cstr;
 };
-const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId, Cstr) => {
+/**
+ * Initialize a Stencil component given a reference to its host element, its
+ * runtime bookkeeping data structure, runtime metadata about the component,
+ * and (optionally) an HMR version ID.
+ *
+ * @param elm a host element
+ * @param hostRef the element's runtime bookkeeping object
+ * @param cmpMeta runtime metadata for the Stencil component
+ * @param hmrVersionId an (optional) HMR version ID
+ */
+const initializeComponent = async (elm, hostRef, cmpMeta, hmrVersionId) => {
+    let Cstr;
     // initializeComponent
     if ((hostRef.$flags$ & 32 /* HOST_FLAGS.hasInitializedComponent */) === 0) {
         // Let the runtime know that the component has been initialized
@@ -2137,13 +2195,40 @@ const hostListenerOpts = (flags) => (flags & 2 /* LISTENER_FLAGS.Capture */) !==
  * @returns void
  */
 const setNonce = (nonce) => (plt.$nonce$ = nonce);
+/**
+ * A WeakMap mapping runtime component references to their corresponding host reference
+ * instances.
+ */
 const hostRefs = /*@__PURE__*/ new WeakMap();
+/**
+ * Given a {@link d.RuntimeRef} retrieve the corresponding {@link d.HostRef}
+ *
+ * @param ref the runtime ref of interest
+ * @returns the Host reference (if found) or undefined
+ */
 const getHostRef = (ref) => hostRefs.get(ref);
+/**
+ * Register a lazy instance with the {@link hostRefs} object so it's
+ * corresponding {@link d.HostRef} can be retrieved later.
+ *
+ * @param lazyInstance the lazy instance of interest
+ * @param hostRef that instances `HostRef` object
+ * @returns a reference to the host ref WeakMap
+ */
 const registerInstance = (lazyInstance, hostRef) => hostRefs.set((hostRef.$lazyInstance$ = lazyInstance), hostRef);
-const registerHost = (elm, cmpMeta) => {
+/**
+ * Register a host element for a Stencil component, setting up various metadata
+ * and callbacks based on {@link BUILD} flags as well as the component's runtime
+ * metadata.
+ *
+ * @param hostElement the host element to register
+ * @param cmpMeta runtime metadata for that component
+ * @returns a reference to the host ref WeakMap
+ */
+const registerHost = (hostElement, cmpMeta) => {
     const hostRef = {
         $flags$: 0,
-        $hostElement$: elm,
+        $hostElement$: hostElement,
         $cmpMeta$: cmpMeta,
         $instanceValues$: new Map(),
     };
@@ -2152,11 +2237,11 @@ const registerHost = (elm, cmpMeta) => {
     }
     {
         hostRef.$onReadyPromise$ = new Promise((r) => (hostRef.$onReadyResolve$ = r));
-        elm['s-p'] = [];
-        elm['s-rc'] = [];
+        hostElement['s-p'] = [];
+        hostElement['s-rc'] = [];
     }
-    addHostEventListeners(elm, hostRef, cmpMeta.$listeners$);
-    return hostRefs.set(elm, hostRef);
+    addHostEventListeners(hostElement, hostRef, cmpMeta.$listeners$);
+    return hostRefs.set(hostElement, hostRef);
 };
 const isMemberInElement = (elm, memberName) => memberName in elm;
 const consoleError = (e, el) => (0, console.error)(e, el);
@@ -2266,4 +2351,4 @@ const writeTask = /*@__PURE__*/ queueTask(queueDomWrites, true);
 
 export { Host as H, bootstrapLazy as b, createEvent as c, getElement as g, h, promiseResolve as p, registerInstance as r, setNonce as s };
 
-//# sourceMappingURL=index-ce01e63b.js.map
+//# sourceMappingURL=index-0f833068.js.map