@mgdis/mg-components 5.19.2 → 5.19.3

package/dist/cjs/{components.utils-dc9c8a53.js → components.utils-69435877.js}

@@ -287,7 +287,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;
@@ -437,4 +437,4 @@ exports.localeDate = localeDate;
 exports.localeNumber = localeNumber;
 exports.sizes = sizes;
 
-//# sourceMappingURL=components.utils-dc9c8a53.js.map
+//# sourceMappingURL=components.utils-69435877.js.map

package/dist/cjs/components.utils-69435877.js.map

@@ -0,0 +1 @@
+{"file":"components.utils-69435877.js","mappings":"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","names":["Direction"],"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/cjs/{index-c042e24b.js → index-60dd0c56.js}

@@ -689,7 +689,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;
@@ -1107,30 +1107,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;
                         }
@@ -1139,8 +1146,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;
                         }
@@ -1152,42 +1159,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 {
@@ -1209,8 +1229,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,
                         });
@@ -1218,30 +1240,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
  */
@@ -1320,7 +1353,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;
@@ -1556,6 +1589,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 */;
@@ -1638,6 +1675,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 {
@@ -1838,7 +1885,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
@@ -2159,13 +2217,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(),
     };
@@ -2174,11 +2259,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);
@@ -2295,4 +2380,4 @@ exports.promiseResolve = promiseResolve;
 exports.registerInstance = registerInstance;
 exports.setNonce = setNonce;
 
-//# sourceMappingURL=index-c042e24b.js.map
+//# sourceMappingURL=index-60dd0c56.js.map